logbrew-sdk 0.1.0 → 0.1.2

data/lib/logbrew/event_batcher.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module LogBrew
+  class EventBatcher
+    DEFAULT_MAX_SIZE = 100
+    DEFAULT_MAX_BYTES = 262_144
+    BATCH_SUFFIX = "]}"
+
+    Batch = Struct.new(:body, :event_count, :event_bytes)
+    private_constant :Batch
+
+    attr_reader :max_event_bytes
+
+    def initialize(sdk:, max_size:, max_bytes:)
+      validate_positive_integer("max_batch_size", max_size)
+      validate_positive_integer("max_batch_bytes", max_bytes)
+
+      @max_size = max_size
+      @max_bytes = max_bytes
+      @batch_prefix = "{\"sdk\":#{JSON.generate(sdk)},\"events\":["
+      @base_bytes = @batch_prefix.bytesize + BATCH_SUFFIX.bytesize
+      if @base_bytes >= @max_bytes
+        raise SdkError.new("validation_error", "max_batch_bytes must fit the SDK envelope")
+      end
+
+      @max_event_bytes = @max_bytes - @base_bytes
+    rescue JSON::GeneratorError, EncodingError
+      raise SdkError.new("validation_error", "sdk identity must be JSON serializable")
+    end
+
+    def next_batch(serialized_events, limit:)
+      event_json = []
+      event_bytes = 0
+      body_bytes = @base_bytes
+      maximum = [serialized_events.length, limit, @max_size].min
+
+      maximum.times do |index|
+        serialized = serialized_events.fetch(index)
+        next_body_bytes = body_bytes + (event_json.empty? ? 0 : 1) + serialized.bytesize
+        break if next_body_bytes > @max_bytes
+
+        event_json << serialized
+        event_bytes += serialized.bytesize
+        body_bytes = next_body_bytes
+      end
+
+      if event_json.empty?
+        raise SdkError.new("transport_error", "queued event cannot fit the configured batch byte limit")
+      end
+
+      Batch.new(
+        (@batch_prefix + event_json.join(",") + BATCH_SUFFIX).freeze,
+        event_json.length,
+        event_bytes
+      ).freeze
+    end
+
+    private
+
+    def validate_positive_integer(label, value)
+      return if value.is_a?(Integer) && value.positive?
+
+      raise SdkError.new("validation_error", "#{label} must be a positive integer")
+    end
+  end
+  private_constant :EventBatcher
+end

data/lib/logbrew/faraday_tracing.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "faraday"
+require_relative "../logbrew"
+
+module LogBrew
+  class FaradayTracingMiddleware < ::Faraday::Middleware
+    def initialize(app, client:, on_capture_error: nil)
+      super(app)
+      @client = client
+      @on_capture_error = on_capture_error
+    end
+
+    def call(env)
+      prepared = HttpClientTracing.prepare(
+        client: @client,
+        source: "faraday",
+        on_capture_error: @on_capture_error
+      ) do
+        url = env.url
+        [env.method, url && url.host, HttpClientTracing::FaradayHeaderSnapshot.new(env.request_headers)]
+      end
+      return @app.call(env) unless prepared
+
+      operation, header = prepared
+      begin
+        header.inject(operation.traceparent)
+      rescue StandardError => error
+        operation.capture_error(error)
+        HttpClientTracing.reset_header(header, operation)
+        return @app.call(env)
+      end
+
+      response = nil
+      begin
+        response = operation.around { @app.call(env) }
+      rescue StandardError => error
+        operation.finish(error: error)
+        raise
+      ensure
+        HttpClientTracing.reset_header(header, operation)
+      end
+
+      begin
+        response.on_complete do |completed|
+          operation.finish(status_code: HttpClientTracing.read_status(completed, :status, operation))
+        end
+      rescue StandardError => error
+        operation.capture_error(error)
+        operation.finish(status_code: HttpClientTracing.read_status(response, :status, operation))
+      end
+      response
+    end
+  end
+end

data/lib/logbrew/http_client_tracing.rb

@@ -0,0 +1,282 @@
+# frozen_string_literal: true
+
+require "ipaddr"
+
+module LogBrew
+  class HttpClientTraceOperation
+    attr_reader :context, :traceparent
+
+    def initialize(client:, parent:, source:, method:, host:, on_capture_error:)
+      @client = client
+      @context = Trace.create(
+        trace_id: parent.trace_id,
+        span_id: Trace.generate_span_id,
+        parent_span_id: parent.span_id,
+        trace_flags: parent.trace_flags
+      )
+      @traceparent = Trace.create_headers(@context).fetch("traceparent")
+      @source = source
+      @method = HttpClientTracing.normalize_method(method)
+      @host = HttpClientTracing.normalize_host(host)
+      @on_capture_error = on_capture_error
+      @started_at = HttpClientTracing.monotonic_time
+      @mutex = Mutex.new
+      @finished = false
+    end
+
+    def around
+      HttpClientTracing.with_operation(self) { yield }
+    end
+
+    def finish(status_code: nil, error: nil)
+      should_capture = @mutex.synchronize do
+        next false if @finished
+
+        @finished = true
+        true
+      end
+      return unless should_capture
+
+      capture(status_code, error)
+    end
+
+    def capture_error(error)
+      HttpClientTracing.report_capture_error(@on_capture_error, error)
+    end
+
+    private
+
+    def capture(status_code, error)
+      normalized_status = HttpClientTracing.normalize_status_code(status_code)
+      metadata = {
+        method: @method,
+        source: @source,
+        sampled: @context.sampled
+      }
+      metadata[:host] = @host if @host
+      metadata[:statusCode] = normalized_status if normalized_status
+      metadata[:exceptionType] = error.class.name if error
+      status = error || (normalized_status && normalized_status >= 400) ? "error" : "ok"
+
+      @client.span(
+        "ruby_http_span_#{@context.span_id}",
+        Time.now.utc.iso8601,
+        {
+          name: "http.client:#{@method}",
+          traceId: @context.trace_id,
+          spanId: @context.span_id,
+          parentSpanId: @context.parent_span_id,
+          status: status,
+          durationMs: ((HttpClientTracing.monotonic_time - @started_at) * 1000.0).round(3),
+          metadata: metadata
+        }
+      )
+    rescue StandardError => capture_error
+      HttpClientTracing.report_capture_error(@on_capture_error, capture_error)
+    end
+  end
+
+  class NetHttpTracingClient
+    attr_reader :http
+
+    def initialize(http, client:, on_capture_error: nil)
+      @http = http
+      @client = client
+      @on_capture_error = on_capture_error
+    end
+
+    def request(request, body = nil, &block)
+      prepared = HttpClientTracing.prepare(
+        client: @client,
+        source: "net_http",
+        on_capture_error: @on_capture_error
+      ) do
+        [request.method, address, HttpClientTracing::NetHttpHeaderSnapshot.new(request)]
+      end
+      return @http.request(request, body, &block) unless prepared
+
+      operation, header = prepared
+      begin
+        header.inject(operation.traceparent)
+      rescue StandardError => error
+        operation.capture_error(error)
+        HttpClientTracing.reset_header(header, operation)
+        return @http.request(request, body, &block)
+      end
+
+      response = nil
+      begin
+        response = operation.around { @http.request(request, body, &block) }
+      rescue StandardError => error
+        operation.finish(error: error)
+        raise
+      ensure
+        HttpClientTracing.reset_header(header, operation)
+      end
+      operation.finish(status_code: HttpClientTracing.read_status(response, :code, operation))
+      response
+    end
+
+    def start(*arguments)
+      unless block_given?
+        started = @http.start(*arguments)
+        return started.equal?(@http) ? self : started
+      end
+
+      @http.start(*arguments) { yield self }
+    end
+
+    def method_missing(name, *arguments, &block)
+      return super unless @http.respond_to?(name)
+
+      @http.public_send(name, *arguments, &block)
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      @http.respond_to?(name, include_private) || super
+    end
+  end
+
+  module HttpClientTracing
+    ACTIVE_OPERATION_KEY = :logbrew_http_client_operation
+    SUPPRESSION_KEY = :logbrew_http_client_suppression
+    SOURCES = %w[net_http faraday].freeze
+    private_constant :ACTIVE_OPERATION_KEY, :SUPPRESSION_KEY, :SOURCES
+
+    class NetHttpHeaderSnapshot
+      def initialize(request)
+        @request = request
+        @values = request.get_fields("traceparent")
+      end
+
+      def inject(traceparent)
+        @request["traceparent"] = traceparent
+      end
+
+      def reset
+        @request.delete("traceparent")
+        Array(@values).each { |value| @request.add_field("traceparent", value) }
+      end
+    end
+
+    class FaradayHeaderSnapshot
+      def initialize(headers)
+        @headers = headers
+        @present = headers.key?("traceparent")
+        @value = headers["traceparent"]
+      end
+
+      def inject(traceparent)
+        @headers["traceparent"] = traceparent
+      end
+
+      def reset
+        if @present
+          @headers["traceparent"] = @value
+        else
+          @headers.delete("traceparent")
+        end
+      end
+    end
+
+    module_function
+
+    def wrap_net_http(http, client:, on_capture_error: nil)
+      return http if http.is_a?(NetHttpTracingClient)
+
+      NetHttpTracingClient.new(http, client: client, on_capture_error: on_capture_error)
+    end
+
+    def prepare(client:, source:, on_capture_error: nil)
+      parent = Trace.current
+      return nil unless parent
+      return nil if suppressed? || active_operation?
+      return nil unless SOURCES.include?(source)
+
+      method, host, header = yield
+      operation = HttpClientTraceOperation.new(
+        client: client,
+        parent: parent,
+        source: source,
+        method: method,
+        host: host,
+        on_capture_error: on_capture_error
+      )
+      [operation, header]
+    rescue StandardError => error
+      report_capture_error(on_capture_error, error)
+      nil
+    end
+
+    def with_operation(operation)
+      previous = Thread.current[ACTIVE_OPERATION_KEY]
+      Thread.current[ACTIVE_OPERATION_KEY] = operation
+      Trace.with_context(operation.context) { yield }
+    ensure
+      Thread.current[ACTIVE_OPERATION_KEY] = previous
+    end
+
+    def suppress
+      previous = Thread.current[SUPPRESSION_KEY]
+      Thread.current[SUPPRESSION_KEY] = true
+      yield
+    ensure
+      Thread.current[SUPPRESSION_KEY] = previous
+    end
+
+    def active_operation?
+      !Thread.current[ACTIVE_OPERATION_KEY].nil?
+    end
+
+    def suppressed?
+      Thread.current[SUPPRESSION_KEY] == true
+    end
+
+    def normalize_method(method)
+      value = method.to_s.strip.upcase
+      value.empty? ? "HTTP" : value[0, 32]
+    end
+
+    def normalize_host(host)
+      value = host.to_s.strip.downcase.sub(/\.+\z/, "")
+      return nil if value.empty? || value.bytesize > 253
+      return nil if value.match?(/\A[0-9.]+\z/)
+      return nil unless value.match?(/\A[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?\z/)
+
+      begin
+        IPAddr.new(value)
+        nil
+      rescue IPAddr::InvalidAddressError
+        value
+      end
+    end
+
+    def normalize_status_code(status_code)
+      value = status_code.to_i
+      value.positive? && value <= 999 ? value : nil
+    end
+
+    def read_status(response, method, operation)
+      response.public_send(method)
+    rescue StandardError => error
+      operation.capture_error(error)
+      nil
+    end
+
+    def reset_header(header, operation)
+      header.reset
+    rescue StandardError => error
+      operation.capture_error(error)
+    end
+
+    def monotonic_time
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def report_capture_error(callback, error)
+      callback.call(error) if callback.respond_to?(:call)
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/logbrew/operation_tracing.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+module LogBrew
+  # Explicit dependency spans for app-owned database, cache, and queue work.
+  module OperationTracing
+    UNSAFE_METADATA_PATTERNS = [
+      /authorization/i,
+      /body/i,
+      /broker/i,
+      /cache.?key/i,
+      /command/i,
+      /connection/i,
+      /cookie/i,
+      /dsn/i,
+      /header/i,
+      /host/i,
+      /\bjid\z/i,
+      /job.?id/i,
+      /key/i,
+      /message/i,
+      /param/i,
+      /pass#{'word'}/i,
+      /payload/i,
+      /query/i,
+      /sec#{'ret'}/i,
+      /sql/i,
+      /statement/i,
+      /to#{'ken'}/i,
+      /url/i,
+      /username/i,
+      /value/i
+    ].freeze
+    private_constant :UNSAFE_METADATA_PATTERNS
+
+    module_function
+
+    def database_operation(client, name, **options, &block)
+      capture_operation(client, "database", name, options, &block)
+    end
+
+    def cache_operation(client, name, **options, &block)
+      capture_operation(client, "cache", name, options, &block)
+    end
+
+    def queue_operation(client, name, **options, &block)
+      capture_operation(client, "queue", name, options, &block)
+    end
+
+    def capture_operation(client, kind, name, options)
+      raise SdkError.new("validation_error", "#{kind} operation block is required") unless block_given?
+
+      Validation.require_non_empty("#{kind} operation name", name)
+      started_at = monotonic_time
+      context = child_context
+      error = nil
+      result = nil
+
+      Trace.with_context(context) do
+        begin
+          result = yield context
+        rescue StandardError => captured
+          error = captured
+        end
+      end
+
+      capture_span(client, kind, name, context, started_at, options, error)
+      raise error if error
+
+      result
+    end
+
+    def capture_span(client, kind, name, context, started_at, options, error)
+      client.span(
+        event_id(kind, context, options),
+        timestamp(options),
+        {
+          name: "#{kind}.operation:#{name}",
+          traceId: context.trace_id,
+          spanId: context.span_id,
+          parentSpanId: context.parent_span_id,
+          status: error ? "error" : "ok",
+          durationMs: duration_ms(started_at, options),
+          metadata: span_metadata(kind, options, error),
+          events: span_events(error)
+        }
+      )
+    rescue StandardError => capture_error
+      on_error = read_option(options, :on_error)
+      begin
+        on_error.call(capture_error) if on_error.respond_to?(:call)
+      rescue StandardError
+        nil
+      end
+    end
+
+    def child_context
+      parent = Trace.current
+      return Trace.create_root unless parent
+
+      Trace.create(
+        trace_id: parent.trace_id,
+        span_id: generate_span_id,
+        parent_span_id: parent.span_id,
+        trace_flags: parent.trace_flags
+      )
+    end
+
+    def span_metadata(kind, options, error)
+      sanitized_metadata(read_option(options, :metadata)).tap do |metadata|
+        metadata["source"] = "#{kind}.operation"
+        add_option(metadata, "#{kind}.system", read_option(options, :system))
+        add_option(metadata, "#{kind}.operation", read_option(options, :operation))
+        add_option(metadata, "#{kind}.target", read_option(options, :target))
+        metadata["exceptionType"] = error.class.name if error
+      end
+    end
+
+    def span_events(error)
+      return nil unless error
+
+      [
+        {
+          name: "exception",
+          metadata: {
+            exceptionType: error.class.name,
+            exceptionEscaped: true
+          }
+        }
+      ]
+    end
+
+    def sanitized_metadata(metadata)
+      return {} if metadata.nil?
+      raise SdkError.new("validation_error", "operation metadata must be an object") unless metadata.is_a?(Hash)
+
+      metadata.each_with_object({}) do |(key, value), copied|
+        normalized_key = key.to_s
+        next if normalized_key.strip.empty?
+        next if unsafe_metadata_key?(normalized_key)
+        next unless primitive_metadata_value?(value)
+
+        copied[normalized_key] = value
+      end
+    end
+
+    def unsafe_metadata_key?(key)
+      UNSAFE_METADATA_PATTERNS.any? { |pattern| key.match?(pattern) }
+    end
+
+    def primitive_metadata_value?(value)
+      return true if value.nil? || value == true || value == false
+      return true if value.is_a?(String) || value.is_a?(Integer)
+
+      value.is_a?(Float) && value.finite?
+    end
+
+    def add_option(metadata, key, value)
+      metadata[key] = value if primitive_metadata_value?(value) && !(value.is_a?(String) && value.strip.empty?)
+    end
+
+    def read_option(options, key)
+      options[key] || options[key.to_s]
+    end
+
+    def event_id(kind, context, options)
+      read_option(options, :event_id) || "ruby_#{kind}_span_#{context.span_id}"
+    end
+
+    def timestamp(options)
+      value = read_option(options, :timestamp)
+      return value unless value.nil?
+
+      Time.now.utc.iso8601
+    end
+
+    def duration_ms(started_at, options)
+      configured = read_option(options, :duration_ms)
+      return configured unless configured.nil?
+
+      ((monotonic_time - started_at) * 1000.0).round(3)
+    end
+
+    def monotonic_time
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def generate_span_id
+      loop do
+        value = SecureRandom.hex(8)
+        return value unless value.delete("0").empty?
+      end
+    end
+  end
+end