logbrew-sdk 0.1.0 → 0.1.1

data/lib/logbrew/trace.rb

@@ -0,0 +1,298 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module LogBrew
+  TraceContext = Struct.new(:trace_id, :span_id, :parent_span_id, :trace_flags, :sampled, keyword_init: true)
+
+  class TraceScope
+    def initialize(scope_id)
+      @scope_id = scope_id
+      @closed = false
+    end
+
+    def close
+      return if @closed
+
+      LogBrew::Trace.close_scope(@scope_id)
+      @closed = true
+    end
+  end
+
+  # Request-local trace context for app-owned logs, errors, actions, and metrics.
+  module Trace
+    STACK_KEY = :logbrew_trace_stack
+    private_constant :STACK_KEY
+
+    module_function
+
+    def current
+      entry = stack.last
+      entry && entry[:context]
+    end
+
+    def activate(context)
+      unless context.is_a?(TraceContext)
+        raise SdkError.new("validation_error", "trace context must be a LogBrew::TraceContext")
+      end
+
+      scope_id = Object.new.object_id
+      stack << { id: scope_id, context: context }
+      TraceScope.new(scope_id)
+    end
+
+    def with_context(context)
+      scope = activate(context)
+      yield context
+    ensure
+      scope.close if scope
+    end
+
+    def close_scope(scope_id)
+      entries = stack
+      index = entries.rindex { |entry| entry[:id] == scope_id }
+      entries.delete_at(index) unless index.nil?
+    end
+
+    def continue_or_create(traceparent)
+      text = traceparent.to_s.strip
+      return create_root if text.empty?
+
+      from_traceparent(text)
+    rescue SdkError
+      create_root
+    end
+
+    def from_traceparent(traceparent)
+      context = Traceparent.parse(traceparent)
+      create(
+        trace_id: context.trace_id,
+        span_id: generate_span_id,
+        parent_span_id: context.parent_span_id,
+        trace_flags: context.trace_flags
+      )
+    end
+
+    def create_root
+      create(trace_id: generate_trace_id, span_id: generate_span_id, trace_flags: "01")
+    end
+
+    def create(trace_id:, span_id:, trace_flags: "01", parent_span_id: nil)
+      normalized_traceparent = Traceparent.create(trace_id: trace_id, span_id: span_id, trace_flags: trace_flags)
+      _version, normalized_trace_id, normalized_span_id, normalized_flags = normalized_traceparent.split("-")
+      normalized_parent_span_id = nil
+      unless parent_span_id.nil?
+        parent_traceparent = Traceparent.create(
+          trace_id: normalized_trace_id,
+          span_id: parent_span_id,
+          trace_flags: normalized_flags
+        )
+        normalized_parent_span_id = parent_traceparent.split("-")[2]
+      end
+
+      TraceContext.new(
+        trace_id: normalized_trace_id,
+        span_id: normalized_span_id,
+        parent_span_id: normalized_parent_span_id,
+        trace_flags: normalized_flags,
+        sampled: (normalized_flags.to_i(16) & 1) == 1
+      )
+    end
+
+    def create_headers(context = current)
+      return {} unless context
+
+      Traceparent.create_headers(
+        trace_id: context.trace_id,
+        span_id: context.span_id,
+        trace_flags: context.trace_flags
+      )
+    end
+
+    def metadata(context = current)
+      return {} unless context
+
+      {
+        "traceId" => context.trace_id,
+        "spanId" => context.span_id,
+        "traceFlags" => context.trace_flags,
+        "traceSampled" => context.sampled
+      }.tap do |payload|
+        payload["parentSpanId"] = context.parent_span_id unless context.parent_span_id.nil?
+      end
+    end
+
+    def add_metadata(target, context = current)
+      return target unless context
+
+      metadata(context).each do |key, value|
+        target[key] = value unless target.key?(key) || target.key?(key.to_sym)
+      end
+      target
+    end
+
+    def merge_attributes(attributes, context = current)
+      return attributes unless context && attributes.is_a?(Hash)
+
+      metadata_value = attributes.key?("metadata") ? attributes["metadata"] : attributes[:metadata]
+      return attributes unless metadata_value.nil? || metadata_value.is_a?(Hash)
+
+      copied = attributes.dup
+      merged_metadata = metadata_value.nil? ? {} : metadata_value.dup
+      add_metadata(merged_metadata, context)
+      if copied.key?(:metadata) && !copied.key?("metadata")
+        copied[:metadata] = merged_metadata
+      else
+        copied["metadata"] = merged_metadata
+      end
+      copied
+    end
+
+    def from_rack_env(env)
+      existing = env_value(env, "logbrew.trace")
+      return existing if existing.is_a?(TraceContext)
+
+      traceparent = env_value(env, "HTTP_TRACEPARENT") || env_value(env, "traceparent") || env_value(env, "logbrew.traceparent")
+      return continue_or_create(traceparent) unless traceparent.nil? || traceparent.empty?
+
+      trace_id = env_value(env, "logbrew.trace_id")
+      span_id = env_value(env, "logbrew.span_id")
+      if trace_id && span_id
+        begin
+          return create(
+            trace_id: trace_id,
+            span_id: span_id,
+            parent_span_id: env_value(env, "logbrew.parent_span_id"),
+            trace_flags: env_value(env, "logbrew.trace_flags") || "01"
+          )
+        rescue SdkError
+          nil
+        end
+      end
+
+      create_root
+    end
+
+    def generate_trace_id
+      loop do
+        value = SecureRandom.hex(16)
+        return value unless value.delete("0").empty?
+      end
+    end
+
+    def generate_span_id
+      loop do
+        value = SecureRandom.hex(8)
+        return value unless value.delete("0").empty?
+      end
+    end
+
+    def stack
+      Thread.current[STACK_KEY] ||= []
+    end
+    private_class_method :stack
+
+    def env_value(env, key)
+      return nil unless env.respond_to?(:[])
+
+      value = env[key]
+      return value if value.is_a?(TraceContext)
+      return nil if value.nil?
+
+      text = value.to_s
+      text.empty? ? nil : text
+    end
+    private_class_method :env_value
+  end
+
+  module TraceClientMethods
+    def issue(id, timestamp, attributes)
+      super(id, timestamp, Trace.merge_attributes(attributes))
+    end
+
+    def log(id, timestamp, attributes)
+      super(id, timestamp, Trace.merge_attributes(attributes))
+    end
+
+    def metric(id, timestamp, attributes)
+      super(id, timestamp, Trace.merge_attributes(attributes))
+    end
+
+    def action(id, timestamp, attributes)
+      super(id, timestamp, Trace.merge_attributes(attributes))
+    end
+  end
+
+  module TraceLoggerMethods
+    private
+
+    def logbrew_metadata(severity, message, progname)
+      Trace.add_metadata(super)
+    end
+  end
+
+  module TraceRackMiddlewareMethods
+    def call(env)
+      trace_context = Trace.from_rack_env(env)
+      env["logbrew.trace"] = trace_context if env.respond_to?(:[]=)
+      Trace.with_context(trace_context) { super(env) }
+    end
+
+    private
+
+    def capture_request_span(env, status_code, elapsed_ms, status)
+      context = rack_trace_context(env)
+      attributes = {
+        name: request_name(env),
+        traceId: context ? context.trace_id : trace_id(env),
+        spanId: context ? context.span_id : span_id(env),
+        status: status,
+        durationMs: elapsed_ms,
+        metadata: request_metadata(env, status_code)
+      }
+      attributes[:parentSpanId] = context.parent_span_id if context && context.parent_span_id
+
+      @client.span(next_event_id("span"), logbrew_timestamp, attributes)
+    end
+
+    def trace_id(env)
+      context = rack_trace_context(env)
+      return context.trace_id if context
+
+      super
+    end
+
+    def span_id(env)
+      context = rack_trace_context(env)
+      return context.span_id if context
+
+      super
+    end
+
+    def request_metadata(env, status_code)
+      Trace.add_metadata(super, rack_trace_context(env))
+    end
+
+    def exception_metadata(env, error)
+      Trace.add_metadata(super, rack_trace_context(env))
+    end
+
+    def rack_trace_context(env)
+      trace = env["logbrew.trace"] if env.respond_to?(:[])
+      trace.is_a?(TraceContext) ? trace : Trace.current
+    end
+  end
+
+  module TraceRailsErrorSubscriberMethods
+    private
+
+    def rails_metadata(error, handled, severity, context, source)
+      Trace.add_metadata(super)
+    end
+  end
+
+  Client.prepend(TraceClientMethods)
+  Logger.prepend(TraceLoggerMethods)
+  RackMiddleware.prepend(TraceRackMiddlewareMethods)
+  RailsErrorSubscriber.prepend(TraceRailsErrorSubscriberMethods)
+end

data/lib/logbrew/traceparent.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+module LogBrew
+  TraceparentContext = Struct.new(:version, :trace_id, :parent_span_id, :trace_flags, :sampled, keyword_init: true)
+  TraceparentSpanInput = Struct.new(:name, :span_id, :status, :duration_ms, :metadata, keyword_init: true) do
+    def initialize(name:, span_id:, status: "ok", duration_ms: nil, metadata: nil)
+      super(
+        name: name,
+        span_id: span_id,
+        status: status,
+        duration_ms: duration_ms,
+        metadata: metadata
+      )
+    end
+  end
+
+  # Dependency-free W3C traceparent helpers for explicit app-owned propagation.
+  module Traceparent
+    VERSION = "00"
+    private_constant :VERSION
+
+    module_function
+
+    def parse(traceparent)
+      Validation.require_non_empty("traceparent", traceparent)
+      parts = traceparent.to_s.strip.downcase.split("-")
+      raise SdkError.new("validation_error", "traceparent must have four fields") unless parts.length == 4
+
+      version, trace_id, parent_span_id, trace_flags = parts
+      require_version(version)
+      require_trace_id(trace_id)
+      require_span_id("traceparent parent span id", parent_span_id)
+      flags = normalize_trace_flags(trace_flags)
+
+      TraceparentContext.new(
+        version: version,
+        trace_id: trace_id,
+        parent_span_id: parent_span_id,
+        trace_flags: flags,
+        sampled: (flags.to_i(16) & 1) == 1
+      )
+    end
+
+    def create(trace_id:, span_id:, trace_flags: "01")
+      normalized_trace_id = normalize_trace_id(trace_id)
+      normalized_span_id = normalize_span_id("traceparent span id", span_id)
+      flags = normalize_trace_flags(trace_flags)
+
+      "#{VERSION}-#{normalized_trace_id}-#{normalized_span_id}-#{flags}"
+    end
+
+    def create_headers(trace_id:, span_id:, trace_flags: "01")
+      { "traceparent" => create(trace_id: trace_id, span_id: span_id, trace_flags: trace_flags) }
+    end
+
+    def span_attributes_from_traceparent(traceparent, input)
+      context = traceparent.is_a?(TraceparentContext) ? traceparent : parse(traceparent)
+      attributes = {
+        "name" => required_name(input.name),
+        "traceId" => context.trace_id,
+        "spanId" => normalize_span_id("span spanId", input.span_id),
+        "parentSpanId" => context.parent_span_id,
+        "status" => normalize_status(input.status)
+      }
+
+      unless input.duration_ms.nil?
+        duration_ms = Validation.require_finite_number("span durationMs", input.duration_ms)
+        raise SdkError.new("validation_error", "span durationMs must be non-negative") if duration_ms.negative?
+
+        attributes["durationMs"] = duration_ms
+      end
+
+      metadata = Validation.require_metadata(input.metadata)
+      attributes["metadata"] = metadata unless metadata.nil?
+      attributes
+    end
+
+    def require_version(version)
+      unless version.length == 2 && lower_hex?(version) && version != "ff"
+        raise SdkError.new("validation_error", "traceparent version must be two hex characters and not ff")
+      end
+    end
+    private_class_method :require_version
+
+    def normalize_trace_id(trace_id)
+      normalized = trace_id.to_s.strip.downcase
+      require_trace_id(normalized)
+      normalized
+    end
+    private_class_method :normalize_trace_id
+
+    def require_trace_id(trace_id)
+      unless trace_id.length == 32 && lower_hex?(trace_id) && !all_zero?(trace_id)
+        raise SdkError.new("validation_error", "traceparent trace id must be 32 non-zero hex characters")
+      end
+    end
+    private_class_method :require_trace_id
+
+    def normalize_span_id(label, span_id)
+      normalized = span_id.to_s.strip.downcase
+      require_span_id(label, normalized)
+      normalized
+    end
+    private_class_method :normalize_span_id
+
+    def require_span_id(label, span_id)
+      unless span_id.length == 16 && lower_hex?(span_id) && !all_zero?(span_id)
+        raise SdkError.new("validation_error", "#{label} must be 16 non-zero hex characters")
+      end
+    end
+    private_class_method :require_span_id
+
+    def normalize_trace_flags(trace_flags)
+      normalized = trace_flags.to_s.strip.downcase
+      unless normalized.length == 2 && lower_hex?(normalized)
+        raise SdkError.new("validation_error", "traceparent flags must be two hex characters")
+      end
+
+      normalized
+    end
+    private_class_method :normalize_trace_flags
+
+    def required_name(name)
+      Validation.require_non_empty("span name", name)
+      name.to_s.strip
+    end
+    private_class_method :required_name
+
+    def normalize_status(status)
+      Validation.require_allowed_value("span status", status, LogBrew::SPAN_STATUSES)
+      status
+    end
+    private_class_method :normalize_status
+
+    def lower_hex?(value)
+      value.match?(/\A[0-9a-f]+\z/)
+    end
+    private_class_method :lower_hex?
+
+    def all_zero?(value)
+      value.delete("0").empty?
+    end
+    private_class_method :all_zero?
+  end
+end

data/lib/logbrew.rb

@@ -9,10 +9,26 @@ require "timeout"
 require "uri"
 
 module LogBrew
-  ISSUE_LEVELS = %w[info warning error critical].freeze
-  LOG_LEVELS = %w[debug info warning error].freeze
+  SEVERITY_VALUES = %w[trace debug info warn warning error fatal critical].freeze
+  SEVERITY_ALIASES = {
+    "trace" => "info",
+    "debug" => "info",
+    "info" => "info",
+    "warn" => "warning",
+    "warning" => "warning",
+    "error" => "error",
+    "fatal" => "critical",
+    "critical" => "critical"
+  }.freeze
   SPAN_STATUSES = %w[ok error].freeze
   ACTION_STATUSES = %w[queued running success failure].freeze
+  METRIC_TEMPORALITIES_BY_KIND = {
+    "counter" => %w[delta cumulative].freeze,
+    "gauge" => %w[instant].freeze,
+    "histogram" => %w[delta cumulative].freeze
+  }.freeze
+  METRIC_KINDS = METRIC_TEMPORALITIES_BY_KIND.keys.freeze
+  NON_NEGATIVE_METRIC_KINDS = %w[counter histogram].freeze
 
   class SdkError < StandardError
     attr_reader :code
@@ -158,11 +174,11 @@ module LogBrew
   class Logger < ::Logger
     DEFAULT_LOGGER_NAME = "ruby-logger"
     SEVERITY_TO_LOGBREW_LEVEL = {
-      ::Logger::DEBUG => "debug",
+      ::Logger::DEBUG => "info",
       ::Logger::INFO => "info",
       ::Logger::WARN => "warning",
       ::Logger::ERROR => "error",
-      ::Logger::FATAL => "error",
+      ::Logger::FATAL => "critical",
       ::Logger::UNKNOWN => "error"
     }.freeze
 
@@ -275,7 +291,7 @@ module LogBrew
     end
 
     def logbrew_level(severity)
-      SEVERITY_TO_LOGBREW_LEVEL.fetch(severity.to_i, severity.to_i >= ::Logger::WARN ? "error" : "info")
+      SEVERITY_TO_LOGBREW_LEVEL.fetch(severity.to_i, severity.to_i >= ::Logger::FATAL ? "critical" : "info")
     end
 
     def event_logger_name(progname)
@@ -314,7 +330,6 @@ module LogBrew
       value.is_a?(Float) && value.finite?
     end
   end
-
   # Rack-compatible middleware for Rails, Sinatra, and other Rack-based Ruby apps.
   #
   # The middleware captures completed requests as span events and unhandled app
@@ -699,6 +714,15 @@ module LogBrew
       end
     end
 
+    def require_finite_number(label, value)
+      unless value.is_a?(Integer) || value.is_a?(Float)
+        raise SdkError.new("validation_error", "#{label} must be a finite number")
+      end
+      raise SdkError.new("validation_error", "#{label} must be a finite number") if numeric_nan?(value)
+
+      value
+    end
+
     def read(attributes, key)
       return nil unless attributes.is_a?(Hash)
 
@@ -764,6 +788,10 @@ module LogBrew
       push_event("span", id, timestamp, validate_span(attributes))
     end
 
+    def metric(id, timestamp, attributes)
+      push_event("metric", id, timestamp, validate_metric(attributes))
+    end
+
     def action(id, timestamp, attributes)
       push_event("action", id, timestamp, validate_action(attributes))
     end
@@ -858,7 +886,7 @@ module LogBrew
       title = Validation.read(attributes, "title")
       level = Validation.read(attributes, "level")
       Validation.require_non_empty("issue title", title)
-      Validation.require_allowed_value("issue level", level, ISSUE_LEVELS)
+      level = normalize_severity("issue level", level)
       with_metadata(
         {
           "title" => title,
@@ -875,7 +903,7 @@ module LogBrew
       message = Validation.read(attributes, "message")
       level = Validation.read(attributes, "level")
       Validation.require_non_empty("log message", message)
-      Validation.require_allowed_value("log level", level, LOG_LEVELS)
+      level = normalize_severity("log level", level)
       with_metadata(
         {
           "message" => message,
@@ -888,6 +916,11 @@ module LogBrew
       )
     end
 
+    def normalize_severity(label, level)
+      Validation.require_allowed_value(label, level, SEVERITY_VALUES)
+      SEVERITY_ALIASES.fetch(level)
+    end
+
     def validate_span(attributes)
       name = Validation.read(attributes, "name")
       trace_id = Validation.read(attributes, "traceId")
@@ -919,6 +952,32 @@ module LogBrew
       )
     end
 
+    def validate_metric(attributes)
+      name = Validation.read(attributes, "name")
+      kind = Validation.read(attributes, "kind")
+      unit = Validation.read(attributes, "unit")
+      temporality = Validation.read(attributes, "temporality")
+      Validation.require_non_empty("metric name", name)
+      Validation.require_allowed_value("metric kind", kind, METRIC_KINDS)
+      value = Validation.require_finite_number("metric value", Validation.read(attributes, "value"))
+      Validation.require_non_empty("metric unit", unit)
+      Validation.require_allowed_value("metric temporality for #{kind}", temporality, METRIC_TEMPORALITIES_BY_KIND[kind])
+      if NON_NEGATIVE_METRIC_KINDS.include?(kind) && value.negative?
+        raise SdkError.new("validation_error", "metric #{kind} value must be non-negative")
+      end
+
+      with_metadata(
+        {
+          "name" => name,
+          "kind" => kind,
+          "value" => value,
+          "unit" => unit,
+          "temporality" => temporality
+        },
+        attributes
+      )
+    end
+
     def validate_action(attributes)
       name = Validation.read(attributes, "name")
       status = Validation.read(attributes, "status")
@@ -934,3 +993,7 @@ module LogBrew
     end
   end
 end
+
+%w[product_timeline traceparent trace operation_tracing support_ticket].each do |path|
+  require_relative "logbrew/#{path}"
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: logbrew-sdk
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - LogBrew
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-05 00:00:00.000000000 Z
+date: 2026-07-01 00:00:00.000000000 Z
 dependencies: []
 description: Public LogBrew Ruby SDK for building, validating, and flushing event
   batches.
@@ -19,9 +19,16 @@ extra_rdoc_files: []
 files:
 - README.md
 - examples/Makefile
+- examples/first_useful_telemetry.rb
+- examples/http_trace_correlation.rb
 - examples/readme_example.rb
 - examples/real_user_smoke.rb
 - lib/logbrew.rb
+- lib/logbrew/operation_tracing.rb
+- lib/logbrew/product_timeline.rb
+- lib/logbrew/support_ticket.rb
+- lib/logbrew/trace.rb
+- lib/logbrew/traceparent.rb
 homepage: https://github.com/LogBrewCo/sdk
 licenses:
 - MIT