logtide 1.0.0

data/lib/logtide/scope.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require_relative "breadcrumb"
+
+module Logtide
+  # Per-request/per-task context merged into every entry captured while active
+  # (spec 004 section 4). Cloned per request so concurrent work never shares
+  # mutable state.
+  class Scope
+    attr_reader :tags, :user, :session_id, :extra, :trace_id, :span_id, :breadcrumbs, :span
+
+    def initialize(max_breadcrumbs: 100)
+      @tags = {}
+      @user = nil
+      @session_id = nil
+      @extra = {}
+      @trace_id = nil
+      @span_id = nil
+      @span = nil
+      @breadcrumbs = BreadcrumbBuffer.new(max_breadcrumbs)
+      @event_processors = []
+    end
+
+    def set_span(span)
+      @span = span
+      self
+    end
+
+    def set_tag(key, value)
+      @tags[key.to_s] = value.to_s
+      self
+    end
+
+    def remove_tag(key)
+      @tags.delete(key.to_s)
+      self
+    end
+
+    def set_user(user)
+      @user = user.nil? ? nil : stringify(user)
+      self
+    end
+
+    def set_session_id(session_id)
+      @session_id = session_id
+      self
+    end
+
+    def set_extra(key, value)
+      @extra[key.to_s] = value
+      self
+    end
+
+    def set_trace_context(trace_id, span_id)
+      @trace_id = trace_id
+      @span_id = span_id
+      self
+    end
+
+    def add_breadcrumb(breadcrumb)
+      @breadcrumbs.add(breadcrumb)
+      self
+    end
+
+    def clear_breadcrumbs
+      @breadcrumbs.clear
+      self
+    end
+
+    def add_event_processor(processor)
+      @event_processors << processor
+      self
+    end
+
+    def event_processors
+      @event_processors.dup
+    end
+
+    def initialize_copy(other)
+      super
+      @tags = other.tags.dup
+      @extra = other.extra.dup
+      @user = other.user&.dup
+      @breadcrumbs = other.breadcrumbs.dup
+      @event_processors = other.event_processors
+    end
+
+    private
+
+    def stringify(hash)
+      hash.each_with_object({}) { |(k, v), out| out[k.to_s] = v }
+    end
+  end
+end

data/lib/logtide/structured_exception.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+
+module Logtide
+  # Serialises a Ruby exception into the StructuredException wire shape
+  # (spec 003 section 4): type, message, language, stacktrace (outermost first),
+  # the cause chain (capped at 10, cycle-safe) and an optional raw trace.
+  module StructuredException
+    LANGUAGE = "ruby"
+    MAX_CAUSE_DEPTH = 10
+    MAX_FRAMES = 100
+
+    module_function
+
+    def serialize(exception, include_stacktrace: true)
+      build(exception, 0, {}.compare_by_identity, include_stacktrace)
+    end
+
+    def build(exception, depth, seen, include_stacktrace)
+      seen[exception] = true
+      result = {
+        "type" => type_of(exception),
+        "message" => message_of(exception),
+        "language" => LANGUAGE
+      }
+
+      if include_stacktrace
+        frames = stacktrace(exception)
+        result["stacktrace"] = frames unless frames.empty?
+        raw = raw_text(exception)
+        result["raw"] = raw if raw
+      end
+
+      cause = safe_cause(exception)
+      result["cause"] = build(cause, depth + 1, seen, include_stacktrace) if follow_cause?(cause, depth, seen)
+
+      result
+    end
+
+    def type_of(exception)
+      name = exception.class.name
+      name.nil? || name.empty? ? "Exception" : name
+    end
+
+    def message_of(exception)
+      message = exception.message.to_s
+      message.empty? ? type_of(exception) : message
+    end
+
+    def stacktrace(exception)
+      locations = exception.backtrace_locations
+      return [] unless locations
+
+      # Ruby backtraces are innermost-first; the wire format wants outermost
+      # first, and truncation keeps the outermost frames (003 section 4).
+      locations.reverse.first(MAX_FRAMES).map { |location| frame(location) }
+    end
+
+    def frame(location)
+      path = location.absolute_path || location.path
+      {
+        "file" => path,
+        "function" => location.label,
+        "line" => location.lineno,
+        "metadata" => { "in_app" => in_app?(path) }
+      }
+    end
+
+    def in_app?(path)
+      return false unless path
+
+      !(path.include?("/gems/") || path.start_with?(RbConfig::CONFIG["rubylibdir"].to_s))
+    end
+
+    def raw_text(exception)
+      backtrace = exception.backtrace
+      return nil unless backtrace
+
+      (["#{type_of(exception)}: #{message_of(exception)}"] + backtrace).join("\n")
+    end
+
+    def follow_cause?(cause, depth, seen)
+      cause && depth < MAX_CAUSE_DEPTH && !seen.key?(cause)
+    end
+
+    def safe_cause(exception)
+      cause = exception.cause
+      cause if cause.is_a?(Exception)
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/logtide/tracing/span.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Logtide
+  module Tracing
+    # A span in the SDK tracing API, exported as OTLP/JSON (spec 005 section 3).
+    class Span
+      KINDS = { internal: 1, server: 2, client: 3, producer: 4, consumer: 5 }.freeze
+      STATUS = { unset: 0, ok: 1, error: 2 }.freeze
+
+      attr_reader :name, :trace_id, :span_id, :parent_span_id, :kind
+
+      def initialize(name:, trace_id:, span_id:, parent_span_id: nil,
+                     kind: :internal, sampled: true, start_time: nil, reporter: nil)
+        @name = name
+        @trace_id = trace_id
+        @span_id = span_id
+        @parent_span_id = parent_span_id
+        @kind = kind
+        @sampled = sampled
+        @start_time = start_time || now_nano
+        @reporter = reporter
+        @attributes = {}
+        @events = []
+        @status = :unset
+        @end_time = nil
+        @finished = false
+      end
+
+      def sampled? = @sampled
+      def recording? = @sampled
+
+      def set_attribute(key, value)
+        @attributes[key.to_s] = value
+        self
+      end
+
+      def add_event(name)
+        @events << { name: name, time: now_nano }
+        self
+      end
+
+      def finish(status = :ok)
+        return self if @finished
+
+        @finished = true
+        @end_time = now_nano
+        @status = status
+        # Unsampled spans are no-ops: cheap, never exported (spec 005 section 5).
+        @reporter.call(self) if @sampled && @reporter
+        self
+      end
+
+      def to_otlp
+        otlp = {
+          "traceId" => @trace_id,
+          "spanId" => @span_id,
+          "name" => @name,
+          "kind" => KINDS.fetch(@kind, 1),
+          "startTimeUnixNano" => @start_time.to_s,
+          "endTimeUnixNano" => (@end_time || @start_time).to_s,
+          "attributes" => @attributes.map { |key, value| otlp_attribute(key, value) },
+          "events" => @events.map { |event| { "name" => event[:name], "timeUnixNano" => event[:time].to_s } },
+          "status" => { "code" => STATUS.fetch(@status, 0) }
+        }
+        otlp["parentSpanId"] = @parent_span_id if @parent_span_id
+        otlp
+      end
+
+      private
+
+      def otlp_attribute(key, value)
+        { "key" => key, "value" => otlp_value(value) }
+      end
+
+      def otlp_value(value)
+        case value
+        when Integer then { "intValue" => value }
+        when Float then { "doubleValue" => value }
+        when true, false then { "boolValue" => value }
+        else { "stringValue" => value.to_s }
+        end
+      end
+
+      def now_nano
+        Process.clock_gettime(Process::CLOCK_REALTIME, :nanosecond)
+      end
+    end
+  end
+end

data/lib/logtide/tracing.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Logtide
+  # W3C trace context: identifier generation and traceparent parsing/formatting
+  # (spec 005 sections 1-2).
+  module Tracing
+    module_function
+
+    def generate_trace_id
+      loop do
+        id = SecureRandom.hex(16)
+        return id unless id.match?(/\A0+\z/)
+      end
+    end
+
+    def generate_span_id
+      loop do
+        id = SecureRandom.hex(8)
+        return id unless id.match?(/\A0+\z/)
+      end
+    end
+
+    # Parsing and building of the `traceparent` header (00-trace-span-flags).
+    module Propagation
+      Parsed = Struct.new(:trace_id, :parent_span_id, :sampled, keyword_init: true)
+
+      TRACE_ID = /\A[a-f0-9]{32}\z/
+      SPAN_ID = /\A[a-f0-9]{16}\z/
+
+      module_function
+
+      def parse_traceparent(header)
+        return nil unless header
+
+        version, trace_id, parent_span_id, flags = header.split("-")
+        return nil unless version == "00"
+        return nil unless valid_id?(trace_id, TRACE_ID)
+        return nil unless valid_id?(parent_span_id, SPAN_ID)
+        return nil unless flags&.match?(/\A[a-f0-9]{2}\z/)
+
+        Parsed.new(
+          trace_id: trace_id,
+          parent_span_id: parent_span_id,
+          sampled: Integer(flags, 16).allbits?(0x01)
+        )
+      end
+
+      def format_traceparent(trace_id:, span_id:, sampled: true)
+        "00-#{trace_id}-#{span_id}-#{sampled ? "01" : "00"}"
+      end
+
+      def valid_id?(value, pattern)
+        return false unless value&.match?(pattern)
+
+        !value.match?(/\A0+\z/)
+      end
+    end
+  end
+end

data/lib/logtide/transport/batcher.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+require_relative "buffer"
+
+module Logtide
+  module Transport
+    # Owns the buffer and the background dispatcher (spec 002 sections 5-8).
+    # Capture appends to a bounded buffer and returns immediately; a worker
+    # thread flushes on batch size or interval, applying the retry policy and
+    # circuit breaker. flush/close are best-effort and never raise.
+    class Batcher
+      def initialize(sender:, metrics:, circuit_breaker:, retry_policy:,
+                     batch_size: 100, max_buffer_size: 10_000,
+                     flush_interval: 5, flush_timeout: 10,
+                     sleeper: ->(seconds) { sleep(seconds) }, logger: nil)
+        @sender = sender
+        @metrics = metrics
+        @circuit_breaker = circuit_breaker
+        @retry_policy = retry_policy
+        @batch_size = batch_size
+        @flush_interval = flush_interval
+        @flush_timeout = flush_timeout
+        @sleeper = sleeper
+        @logger = logger
+
+        @buffer = Buffer.new(max_size: max_buffer_size)
+        @mutex = Mutex.new
+        @work = ConditionVariable.new
+        @flushed = ConditionVariable.new
+        @stop = false
+        @closed = false
+        @delivering = false
+        @auth_warned = false
+        @worker = Thread.new { run }
+      end
+
+      def enqueue(entry)
+        return if stopped?
+
+        if @buffer.push(entry)
+          signal_worker if @buffer.size >= @batch_size
+        else
+          @metrics.increment(:logs_dropped)
+          log("buffer full, dropping entry")
+        end
+      end
+
+      def flush(timeout = @flush_timeout)
+        deadline = monotonic + timeout
+        @mutex.synchronize do
+          @work.signal
+          until drained?
+            remaining = deadline - monotonic
+            break if remaining <= 0
+
+            @flushed.wait(@mutex, remaining)
+          end
+          drained?
+        end
+      end
+
+      def close(timeout = @flush_timeout)
+        return if @closed
+
+        flush(timeout)
+        @mutex.synchronize do
+          @stop = true
+          @work.broadcast
+        end
+        @worker.join(timeout)
+        @closed = true
+      end
+
+      private
+
+      def stopped?
+        @mutex.synchronize { @stop }
+      end
+
+      def signal_worker
+        @mutex.synchronize { @work.signal }
+      end
+
+      # Must hold the mutex.
+      def drained?
+        @buffer.empty? && !@delivering
+      end
+
+      def run
+        loop do
+          batch = wait_for_batch
+          break if batch.nil?
+
+          deliver(batch)
+          finish_delivery
+        end
+      end
+
+      def wait_for_batch
+        @mutex.synchronize do
+          loop do
+            unless @buffer.empty?
+              @delivering = true
+              return @buffer.drain(@batch_size)
+            end
+
+            @flushed.broadcast
+            return nil if @stop
+
+            @work.wait(@mutex, @flush_interval)
+          end
+        end
+      end
+
+      def finish_delivery
+        @mutex.synchronize do
+          @delivering = false
+          @flushed.broadcast
+        end
+      end
+
+      def deliver(batch)
+        return drop_open_circuit(batch) unless @circuit_breaker.allow?
+
+        attempt = 0
+        loop do
+          response = attempt_delivery(batch)
+          return on_success(batch) if response && success?(response.status)
+          return handle_oversized(batch) if response&.status == 413
+          return on_non_retryable(batch, response.status) if non_retryable?(response)
+          return on_exhausted(batch, attempt) unless attempt < @retry_policy.max_retries
+
+          @metrics.increment(:retries)
+          @sleeper.call(@retry_policy.delay_for(attempt, retry_after: response&.retry_after))
+          attempt += 1
+        end
+      end
+
+      def attempt_delivery(batch)
+        @sender.deliver(batch)
+      rescue NetworkError => e
+        log("network error: #{e.message}")
+        nil
+      end
+
+      def on_success(batch)
+        @metrics.increment(:logs_sent, batch.size)
+        @circuit_breaker.record_success
+      end
+
+      def on_non_retryable(batch, status)
+        warn_auth_once(status)
+        @metrics.increment(:errors)
+        log("non-retryable status #{status}, dropping #{batch.size} entries")
+      end
+
+      def on_exhausted(batch, attempt)
+        @metrics.increment(:errors)
+        @circuit_breaker.record_failure
+        log("delivery failed after #{attempt + 1} attempts, dropping #{batch.size} entries")
+      end
+
+      def drop_open_circuit(batch)
+        @metrics.increment(:logs_dropped, batch.size)
+        @metrics.increment(:circuit_breaker_trips)
+        log("circuit open, dropping #{batch.size} entries")
+      end
+
+      # On 413 the server rejected an oversized batch: split in half and retry
+      # each half once (spec 002 section 10).
+      def handle_oversized(batch)
+        return @metrics.increment(:errors) if batch.size <= 1
+
+        batch.each_slice((batch.size / 2.0).ceil) do |half|
+          response = attempt_delivery(half)
+          if response && success?(response.status)
+            @metrics.increment(:logs_sent, half.size)
+          else
+            @metrics.increment(:errors)
+          end
+        end
+      end
+
+      def warn_auth_once(status)
+        return unless [401, 403].include?(status)
+        return if @auth_warned
+
+        @auth_warned = true
+        log("authentication failed (#{status}); check the api key")
+      end
+
+      def success?(status)
+        status.between?(200, 299)
+      end
+
+      def non_retryable?(response)
+        response && !@retry_policy.retryable_status?(response.status)
+      end
+
+      def log(message)
+        @logger&.call("[logtide] #{message}")
+      end
+
+      def monotonic
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end

data/lib/logtide/transport/buffer.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Logtide
+  module Transport
+    # A bounded FIFO buffer (spec 002 section 5). When full it rejects the new
+    # entry (drop-newest); the caller records the drop. Thread-safe.
+    class Buffer
+      def initialize(max_size:)
+        @max_size = max_size
+        @entries = []
+        @mutex = Mutex.new
+      end
+
+      # Returns false when the buffer is full and the entry was dropped.
+      def push(entry)
+        @mutex.synchronize do
+          return false if @entries.size >= @max_size
+
+          @entries << entry
+          true
+        end
+      end
+
+      def drain(limit)
+        @mutex.synchronize { @entries.shift(limit) }
+      end
+
+      def size
+        @mutex.synchronize { @entries.size }
+      end
+
+      def empty?
+        @mutex.synchronize { @entries.empty? }
+      end
+    end
+  end
+end

data/lib/logtide/transport/http.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+require "zlib"
+require "stringio"
+require "time"
+require "timeout"
+require_relative "../error"
+require_relative "../version"
+
+module Logtide
+  module Transport
+    # Raised when a batch cannot be delivered due to a network/transport problem.
+    # These failures are retryable (spec 002 section 6).
+    class NetworkError < Logtide::Error; end
+
+    # The outcome of a single delivery attempt.
+    Response = Struct.new(:status, :retry_after, keyword_init: true)
+
+    # Stateless HTTP sender: one POST per batch to the ingest endpoint
+    # (spec 002 sections 1-4). Buffering, batching and retries live in the
+    # Batcher; this class just speaks HTTP and never raises for HTTP status codes.
+    class HTTP
+      GZIP_THRESHOLD = 1024 * 1024
+      USER_AGENT = "logtide-ruby/#{Logtide::VERSION}".freeze
+
+      NETWORK_ERRORS = [
+        Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::EHOSTUNREACH,
+        Errno::ENETUNREACH, Errno::ETIMEDOUT, Errno::EPIPE,
+        SocketError, Timeout::Error, EOFError, IOError
+      ].freeze
+
+      def initialize(url:, api_key:, timeout: 10)
+        @uri = URI.parse(url)
+        @api_key = api_key
+        @timeout = timeout
+      end
+
+      # Delivers the batch and returns a Response, or raises NetworkError.
+      def deliver(logs)
+        body = JSON.generate("logs" => logs)
+        response = client.request(build_request(body))
+        Response.new(status: response.code.to_i, retry_after: parse_retry_after(response["retry-after"]))
+      rescue *NETWORK_ERRORS => e
+        raise NetworkError, e.message
+      end
+
+      private
+
+      def client
+        http = Net::HTTP.new(@uri.host, @uri.port)
+        http.use_ssl = @uri.scheme == "https"
+        http.open_timeout = @timeout
+        http.read_timeout = @timeout
+        http.write_timeout = @timeout if http.respond_to?(:write_timeout=)
+        http
+      end
+
+      def build_request(body)
+        request = Net::HTTP::Post.new(@uri.request_uri)
+        request["X-API-Key"] = @api_key
+        request["Content-Type"] = "application/json"
+        request["User-Agent"] = USER_AGENT
+        if body.bytesize > GZIP_THRESHOLD
+          request["Content-Encoding"] = "gzip"
+          request.body = gzip(body)
+        else
+          request.body = body
+        end
+        request
+      end
+
+      def gzip(data)
+        io = StringIO.new
+        writer = Zlib::GzipWriter.new(io)
+        writer.write(data)
+        writer.close
+        io.string
+      end
+
+      def parse_retry_after(value)
+        return nil if value.nil? || value.empty?
+        return value.to_i if value.match?(/\A\d+\z/)
+
+        seconds = (Time.httpdate(value) - Time.now).ceil
+        seconds.positive? ? seconds : 0
+      rescue ArgumentError
+        nil
+      end
+    end
+  end
+end