logtide 1.0.0

data/lib/logtide/configuration.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "socket"
+require_relative "error"
+require_relative "dsn"
+
+module Logtide
+  # Holds the SDK configuration and the exact spec defaults (004 section 2).
+  #
+  # Durations are expressed in seconds (Ruby has no duration type; seconds with
+  # an optional fractional part is the idiomatic choice and matches sleep,
+  # Net::HTTP timeouts, etc.).
+  class Configuration
+    INGEST_SUFFIX = "/api/v1/ingest"
+    OTLP_TRACES_SUFFIX = "/v1/otlp/traces"
+
+    attr_reader :api_url, :api_key, :service, :environment, :release, :server_name,
+                :batch_size, :flush_interval, :max_buffer_size, :max_retries,
+                :retry_delay, :max_backoff, :circuit_breaker_threshold,
+                :circuit_breaker_reset, :flush_timeout, :max_breadcrumbs,
+                :sample_rate, :traces_sample_rate, :global_metadata,
+                :attach_stacktrace, :send_default_pii, :debug,
+                :before_send, :before_breadcrumb
+
+    def initialize(dsn: nil, api_url: nil, api_key: nil, service: nil,
+                   environment: "production", release: nil, server_name: nil,
+                   batch_size: 100, flush_interval: 5, max_buffer_size: 10_000,
+                   max_retries: 3, retry_delay: 1, max_backoff: 60,
+                   circuit_breaker_threshold: 5, circuit_breaker_reset: 30,
+                   flush_timeout: 10, max_breadcrumbs: 100,
+                   sample_rate: 1.0, traces_sample_rate: 1.0,
+                   global_metadata: nil, attach_stacktrace: true,
+                   send_default_pii: false, debug: false,
+                   before_send: nil, before_breadcrumb: nil)
+      resolve_endpoint(dsn, api_url, api_key)
+      @service = require_service(service)
+      @environment = environment
+      @release = release
+      @server_name = server_name || Socket.gethostname
+
+      @batch_size = batch_size
+      @flush_interval = flush_interval
+      @max_buffer_size = max_buffer_size
+      @max_retries = max_retries
+      @retry_delay = retry_delay
+      @max_backoff = max_backoff
+      @circuit_breaker_threshold = circuit_breaker_threshold
+      @circuit_breaker_reset = circuit_breaker_reset
+      @flush_timeout = flush_timeout
+      @max_breadcrumbs = max_breadcrumbs
+      @sample_rate = sample_rate
+      @traces_sample_rate = traces_sample_rate
+      @global_metadata = global_metadata || {}
+      @attach_stacktrace = attach_stacktrace
+      @send_default_pii = send_default_pii
+      @debug = debug
+      @before_send = before_send
+      @before_breadcrumb = before_breadcrumb
+    end
+
+    def ingest_url
+      "#{@api_url}#{INGEST_SUFFIX}"
+    end
+
+    def otlp_traces_url
+      "#{@api_url}#{OTLP_TRACES_SUFFIX}"
+    end
+
+    private
+
+    def resolve_endpoint(dsn, api_url, api_key)
+      if dsn
+        parsed = DSN.parse(dsn)
+        @api_url = parsed.base_url
+        @api_key = parsed.api_key
+      elsif api_url && api_key
+        @api_url = normalize_base_url(api_url)
+        @api_key = api_key
+      else
+        raise ConfigurationError, "either dsn or both api_url and api_key are required"
+      end
+    end
+
+    def normalize_base_url(url)
+      url.to_s.delete_suffix("/").delete_suffix(INGEST_SUFFIX)
+    end
+
+    def require_service(service)
+      raise ConfigurationError, "service is required" if service.nil? || service.to_s.empty?
+
+      service.to_s
+    end
+  end
+end

data/lib/logtide/dsn.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "uri"
+require_relative "error"
+
+module Logtide
+  # A parsed DSN: scheme://apiKey@host[:port][/base-path] (spec 002 section 3).
+  # The base path prefix is preserved; the ingest/OTLP suffixes are appended by
+  # the configuration, never carried here.
+  class DSN
+    INGEST_SUFFIX = "/api/v1/ingest"
+
+    attr_reader :api_key, :base_url
+
+    def self.parse(dsn)
+      new(dsn)
+    end
+
+    def initialize(dsn)
+      uri = parse_uri(dsn)
+      validate!(uri)
+      @api_key = uri.userinfo
+      @base_url = build_base_url(uri)
+    end
+
+    private
+
+    def parse_uri(dsn)
+      URI.parse(dsn.to_s)
+    rescue URI::InvalidURIError => e
+      raise ConfigurationError, "invalid DSN: #{e.message}"
+    end
+
+    def validate!(uri)
+      raise ConfigurationError, "invalid DSN: scheme must be http or https" unless %w[http https].include?(uri.scheme)
+      raise ConfigurationError, "invalid DSN: missing host" if uri.host.nil? || uri.host.empty?
+      raise ConfigurationError, "invalid DSN: missing api key" if uri.userinfo.nil? || uri.userinfo.empty?
+    end
+
+    def build_base_url(uri)
+      authority = uri.host
+      authority = "#{authority}:#{uri.port}" if uri.port && !default_port?(uri)
+      path = normalize_path(uri.path)
+      "#{uri.scheme}://#{authority}#{path}"
+    end
+
+    def default_port?(uri)
+      (uri.scheme == "https" && uri.port == 443) || (uri.scheme == "http" && uri.port == 80)
+    end
+
+    def normalize_path(path)
+      path = path.to_s.delete_suffix("/")
+      path.delete_suffix(INGEST_SUFFIX)
+    end
+  end
+end

data/lib/logtide/error.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Logtide
+  # Base class for errors raised by the SDK itself.
+  class Error < StandardError; end
+
+  # Raised at init time for invalid configuration. This is the one place where
+  # the SDK fails loudly rather than swallowing the problem (spec 002 section 3).
+  class ConfigurationError < Error; end
+end

data/lib/logtide/event.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Logtide
+  # A single log entry in the LogTide wire format (spec 003).
+  #
+  # The wire format is strict: the backend keeps only the top-level fields
+  # time|service|level|message|metadata|trace_id|span_id|session_id and silently
+  # strips everything else, so all extra data is nested under metadata.
+  class Event
+    SDK_NAME = "logtide-ruby"
+
+    # Reserved metadata keys the SDK populates from structured inputs (003 section 3).
+    # `sdk` is handled separately: a caller-provided value wins, so it is never
+    # namespaced.
+    RESERVED_KEYS = %w[exception breadcrumbs tags user event_id release environment server_name].freeze
+
+    attr_reader :service, :level, :message, :time, :metadata,
+                :trace_id, :span_id, :session_id
+
+    def initialize(service:, level:, message:, metadata: nil, time: nil,
+                   tags: nil, user: nil, breadcrumbs: nil, exception: nil,
+                   event_id: nil, release: nil, environment: nil, server_name: nil,
+                   trace_id: nil, span_id: nil, session_id: nil)
+      @service = service
+      @level = level.to_s
+      @message = message
+      @time = time || Time.now.utc
+      @metadata = metadata || {}
+      @reserved = {
+        "tags" => tags, "user" => user, "breadcrumbs" => breadcrumbs,
+        "exception" => exception, "event_id" => event_id, "release" => release,
+        "environment" => environment, "server_name" => server_name
+      }.compact
+      @trace_id = trace_id
+      @span_id = span_id
+      @session_id = session_id
+    end
+
+    # Build the JSON-ready Hash sent on the wire.
+    def to_wire
+      wire = {
+        "time" => format_time(@time),
+        "service" => @service,
+        "level" => @level,
+        "message" => @message,
+        "metadata" => build_metadata
+      }
+      wire["trace_id"] = @trace_id if @trace_id
+      wire["span_id"] = @span_id if @span_id
+      wire["session_id"] = @session_id if @session_id
+      wire
+    end
+
+    private
+
+    def build_metadata
+      metadata = sanitize(@metadata)
+      reserved = sanitize(@reserved)
+
+      # The SDK owns the reserved keys; a colliding user value is namespaced
+      # rather than dropped or allowed to overwrite the SDK value.
+      reserved.each_key do |key|
+        metadata["user_data_#{key}"] = metadata.delete(key) if metadata.key?(key)
+      end
+      metadata.merge!(reserved)
+
+      # `sdk`: caller value wins, default stamp otherwise.
+      metadata["sdk"] ||= { "name" => SDK_NAME, "version" => Logtide::VERSION }
+      metadata
+    end
+
+    def format_time(time)
+      time.utc.strftime("%Y-%m-%dT%H:%M:%S.%LZ")
+    end
+
+    # Produce a JSON-safe deep copy: stringify keys, break cycles, replace
+    # binary/unserialisable values rather than raising (003 section 8, C17).
+    def sanitize(value, seen = nil)
+      case value
+      when Hash
+        seen = guard_cycle(value, seen) or return "[Circular]"
+        value.each_with_object({}) { |(k, v), out| out[k.to_s] = sanitize(v, seen) }
+      when Array
+        seen = guard_cycle(value, seen) or return "[Circular]"
+        value.map { |v| sanitize(v, seen) }
+      when String
+        printable_string(value)
+      when Integer, Float, true, false, nil
+        value
+      when Symbol
+        value.to_s
+      when Time
+        format_time(value)
+      else
+        safe_to_s(value)
+      end
+    end
+
+    def guard_cycle(value, seen)
+      seen ||= {}.compare_by_identity
+      return nil if seen.key?(value)
+
+      seen.dup.tap { |copy| copy[value] = true }
+    end
+
+    def printable_string(value)
+      if value.encoding == Encoding::BINARY || !value.valid_encoding?
+        "[binary #{value.bytesize} bytes]"
+      else
+        value
+      end
+    end
+
+    def safe_to_s(obj)
+      obj.to_s
+    rescue StandardError
+      obj.class.name
+    end
+  end
+end

data/lib/logtide/hub.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require_relative "scope"
+require_relative "tracing"
+
+module Logtide
+  # Binds a Client to a stack of Scopes (spec 001 terminology, 004 section 4).
+  # Captures merge the current scope; with_scope/clone provide isolation.
+  class Hub
+    def initialize(client, scope = Scope.new)
+      @client = client
+      @scope_stack = [scope]
+    end
+
+    attr_reader :client
+
+    def current_scope
+      @scope_stack.last
+    end
+
+    def push_scope
+      @scope_stack.push(current_scope.clone)
+      current_scope
+    end
+
+    def pop_scope
+      @scope_stack.pop if @scope_stack.size > 1
+    end
+
+    def with_scope
+      push_scope
+      yield current_scope
+    ensure
+      pop_scope
+    end
+
+    def configure_scope
+      yield current_scope
+      self
+    end
+
+    def clone
+      Hub.new(@client, current_scope.clone)
+    end
+
+    def capture_log(level, message, metadata = nil, **opts)
+      return unless @client
+
+      @client.capture_log(level, message, metadata, scope: current_scope, **opts)
+    end
+
+    def capture_exception(exception, **opts)
+      return unless @client
+
+      @client.capture_exception(exception, scope: current_scope, **opts)
+    end
+
+    def add_breadcrumb(breadcrumb)
+      current_scope.add_breadcrumb(breadcrumb)
+    end
+
+    # Start a span and make it the active span. With a block, the span is
+    # finished and the previous active span restored automatically.
+    def start_span(name, **opts)
+      return block_given? ? yield(nil) : nil unless @client
+
+      span = @client.start_span(name, scope: current_scope, **opts)
+      previous = current_scope.span
+      current_scope.set_span(span)
+      return span unless block_given?
+
+      begin
+        yield span
+      ensure
+        span.finish
+        current_scope.set_span(previous)
+      end
+    end
+
+    # Headers to inject into an outbound HTTP request so the trace continues
+    # across services (spec 005 section 2). Empty when there is no trace context.
+    # Never emits X-Trace-ID.
+    def trace_propagation_headers
+      scope = current_scope
+      trace_id = scope.span&.trace_id || scope.trace_id
+      span_id = scope.span&.span_id || scope.span_id
+      return {} unless trace_id && span_id
+
+      sampled = scope.span ? scope.span.sampled? : true
+      { "traceparent" => Tracing::Propagation.format_traceparent(trace_id: trace_id, span_id: span_id, sampled: sampled) }
+    end
+
+    def flush(timeout = nil)
+      @client&.flush(*[timeout].compact)
+    end
+
+    def close(timeout = nil)
+      @client&.close(*[timeout].compact)
+    end
+  end
+end

data/lib/logtide/logger_bridge.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "logger"
+
+module Logtide
+  # A drop-in stdlib Logger that routes records through LogTide (spec 004
+  # section 7). Severities are mapped to the five LogTide levels and entries are
+  # enriched with the current scope.
+  #
+  #   logger = Logtide::LoggerBridge.new
+  #   logger.warn("disk almost full")
+  class LoggerBridge < ::Logger
+    SEVERITY_MAP = {
+      ::Logger::DEBUG => "debug",
+      ::Logger::INFO => "info",
+      ::Logger::WARN => "warn",
+      ::Logger::ERROR => "error",
+      ::Logger::FATAL => "critical",
+      ::Logger::UNKNOWN => "error"
+    }.freeze
+
+    def initialize(hub: nil, level: ::Logger::DEBUG)
+      super(nil)
+      self.level = level
+      @hub = hub
+    end
+
+    def add(severity, message = nil, progname = nil) # rubocop:disable Naming/PredicateMethod
+      severity ||= ::Logger::UNKNOWN
+      return true if severity < level
+
+      if message.nil?
+        if block_given?
+          message = yield
+        else
+          message = progname
+          progname = @progname
+        end
+      end
+
+      metadata = progname ? { "logger" => progname.to_s } : nil
+      hub.capture_log(SEVERITY_MAP.fetch(severity, "info"), message.to_s, metadata)
+      true
+    end
+
+    private
+
+    def hub
+      @hub || Logtide.current_hub
+    end
+  end
+end

data/lib/logtide/metrics.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Logtide
+  # Thread-safe self-metrics counters (spec 002 section 9).
+  class Metrics
+    COUNTERS = %i[logs_sent logs_dropped errors retries circuit_breaker_trips].freeze
+
+    def initialize
+      @mutex = Mutex.new
+      @counters = COUNTERS.to_h { |name| [name, 0] }
+    end
+
+    def increment(name, amount = 1)
+      @mutex.synchronize { @counters[name] += amount }
+    end
+
+    def snapshot
+      @mutex.synchronize { @counters.dup }
+    end
+
+    def reset
+      @mutex.synchronize { COUNTERS.each { |name| @counters[name] = 0 } }
+    end
+  end
+end

data/lib/logtide/rack/middleware.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Logtide
+  module Rack
+    # Rack middleware (spec 004 section 6). Per request it clones the hub for
+    # isolation, reads the inbound traceparent, tags the scope, records request
+    # and response breadcrumbs, emits a request log, and captures unhandled
+    # exceptions before re-raising them (it never swallows errors).
+    class Middleware
+      DEFAULT_SKIP_PATHS = %w[/health /healthz].freeze
+
+      # Redacted by default so secrets never reach captured data (spec 004 section 6).
+      SENSITIVE_HEADERS = %w[
+        authorization cookie set-cookie x-api-key x-auth-token proxy-authorization
+      ].freeze
+
+      def initialize(app, skip_paths: DEFAULT_SKIP_PATHS, capture_request_logs: true)
+        @app = app
+        @skip_paths = skip_paths
+        @capture_request_logs = capture_request_logs
+      end
+
+      def call(env)
+        path = env["PATH_INFO"].to_s
+        return @app.call(env) if @skip_paths.include?(path)
+
+        Logtide.with_request_hub do |hub|
+          start = monotonic
+          setup_scope(hub, env)
+          handle(hub, env, start)
+        end
+      end
+
+      private
+
+      def handle(hub, env, start)
+        status, headers, body = @app.call(env)
+        finish(hub, env, status, duration_ms(start))
+        [status, headers, body]
+      rescue Exception => e # rubocop:disable Lint/RescueException
+        on_error(hub, e, duration_ms(start))
+        raise
+      end
+
+      def setup_scope(hub, env)
+        method = request_method(env)
+        path = env["PATH_INFO"].to_s
+        hub.configure_scope do |scope|
+          apply_trace_context(scope, env)
+          scope.set_tag("http.method", method)
+          scope.set_tag("http.route", route(env))
+        end
+        hub.add_breadcrumb(breadcrumb("request", "#{method} #{path}", { "method" => method }))
+      end
+
+      def apply_trace_context(scope, env)
+        parsed = Tracing::Propagation.parse_traceparent(env["HTTP_TRACEPARENT"])
+        if parsed
+          scope.set_trace_context(parsed.trace_id, Tracing.generate_span_id)
+        elsif (legacy = env["HTTP_X_TRACE_ID"])
+          scope.set_trace_context(legacy, Tracing.generate_span_id)
+        else
+          scope.set_trace_context(Tracing.generate_trace_id, Tracing.generate_span_id)
+        end
+      end
+
+      def finish(hub, env, status, duration)
+        hub.configure_scope do |scope|
+          scope.set_tag("http.status_code", status.to_s)
+          scope.set_tag("duration_ms", duration.to_s)
+        end
+        hub.add_breadcrumb(breadcrumb("response", "#{status} #{env["PATH_INFO"]}",
+                                      { "status_code" => status, "duration_ms" => duration }))
+        return unless @capture_request_logs
+
+        hub.capture_log("info", "#{request_method(env)} #{route(env)}",
+                        { "http.status_code" => status, "duration_ms" => duration })
+      end
+
+      def on_error(hub, error, duration)
+        hub.configure_scope do |scope|
+          scope.set_tag("http.status_code", "500")
+          scope.set_tag("duration_ms", duration.to_s)
+        end
+        hub.capture_exception(error)
+      end
+
+      def breadcrumb(category, message, data)
+        Breadcrumb.new(type: "http", category: category, message: message, data: data)
+      end
+
+      def request_method(env)
+        env["REQUEST_METHOD"].to_s
+      end
+
+      # Plain Rack only knows the raw path; framework integrations supply the
+      # route pattern via env (e.g. Rails sets the matched route).
+      def route(env)
+        env["logtide.route"] || env["sinatra.route"] || env["PATH_INFO"].to_s
+      end
+
+      def duration_ms(start)
+        ((monotonic - start) * 1000).round
+      end
+
+      def monotonic
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end

data/lib/logtide/rails/railtie.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+require_relative "../rack/middleware"
+
+module Logtide
+  module Rails
+    # Wires the Rack middleware into the Rails stack. Placed after
+    # ActionDispatch::ShowExceptions so unhandled exceptions are captured and
+    # then re-raised to Rails' own error handling (spec 004 section 6).
+    #
+    # Call Logtide.init(...) from an initializer; this railtie only installs the
+    # middleware.
+    class Railtie < ::Rails::Railtie
+      initializer "logtide.middleware" do |app|
+        app.middleware.insert_after(
+          ActionDispatch::ShowExceptions,
+          Logtide::Rack::Middleware
+        )
+      end
+    end
+  end
+end

data/lib/logtide/retry_policy.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Logtide
+  # Decides whether a delivery failure is retryable and how long to wait
+  # (spec 002 section 6). Retryable: network errors and 408/429/5xx; never any
+  # other 4xx. Backoff is exponential with full jitter, never below the base.
+  class RetryPolicy
+    RETRYABLE_STATUSES = [408, 429, 500, 502, 503, 504].freeze
+
+    attr_reader :max_retries
+
+    def initialize(base:, max_backoff:, max_retries:, rng: -> { rand })
+      @base = base
+      @max_backoff = max_backoff
+      @max_retries = max_retries
+      @rng = rng
+    end
+
+    def retryable_status?(status)
+      RETRYABLE_STATUSES.include?(status)
+    end
+
+    # Seconds to wait before the next attempt. A server-provided Retry-After wins.
+    def delay_for(attempt, retry_after: nil)
+      return retry_after if retry_after
+
+      capped = [@base * (2**attempt), @max_backoff].min
+      low = [@base, capped].min
+      low + (@rng.call * (capped - low))
+    end
+  end
+end