logbrew-sdk 0.1.3 → 0.1.5

data/lib/logbrew/product_timeline.rb

@@ -3,6 +3,9 @@
 module LogBrew
   # Builders for app-owned product and network timeline action events.
   class ProductTimeline
+    PRODUCT_ANALYTICS_SCHEMA_VERSION = 1
+    MAX_PRODUCT_ANALYTICS_SURFACE_LENGTH = 256
+
     private_class_method :new
 
     def self.product_action(
@@ -17,12 +20,18 @@ module LogBrew
       metadata: nil
     )
       action_metadata = timeline_metadata("product_timeline", metadata)
-      put_if_present(action_metadata, "routeTemplate", sanitize_optional_route_template("product route_template", route_template))
+      sanitized_route = sanitize_optional_route_template("product route_template", route_template)
+      sanitized_screen = optional_label("screen", screen)
+      put_if_present(action_metadata, "routeTemplate", sanitized_route)
       put_if_present(action_metadata, "sessionId", optional_label("session_id", session_id))
       put_if_present(action_metadata, "traceId", optional_label("trace_id", trace_id))
-      put_if_present(action_metadata, "screen", optional_label("screen", screen))
+      put_if_present(action_metadata, "screen", sanitized_screen)
       put_if_present(action_metadata, "funnel", optional_label("funnel", funnel))
       put_if_present(action_metadata, "step", optional_label("step", step))
+      action_metadata["analyticsSchemaVersion"] = PRODUCT_ANALYTICS_SCHEMA_VERSION
+      action_metadata["analyticsKind"] = "interaction"
+      surface = bounded_product_analytics_surface(sanitized_route || sanitized_screen)
+      surface.nil? ? action_metadata.delete("analyticsSurface") : action_metadata["analyticsSurface"] = surface
 
       {
         "name" => required_label("product action name", name),
@@ -146,8 +155,20 @@ module LogBrew
       [first, second].min
     end
 
+    def self.bounded_product_analytics_surface(surface)
+      return nil if surface.nil?
+
+      normalized = surface.to_s.strip
+      characters = normalized.each_codepoint.take(MAX_PRODUCT_ANALYTICS_SURFACE_LENGTH + 1)
+      return nil if normalized.empty? || characters.length > MAX_PRODUCT_ANALYTICS_SURFACE_LENGTH
+      return nil if characters.any? { |codepoint| codepoint <= 31 || (codepoint >= 127 && codepoint <= 159) }
+
+      normalized
+    end
+
     private_class_method :timeline_metadata, :required_label, :optional_label, :normalize_status,
                          :sanitize_optional_route_template, :sanitize_route_template, :normalize_method,
-                         :validate_status_code, :validate_duration_ms, :put_if_present, :first_present_index
+                         :validate_status_code, :validate_duration_ms, :put_if_present, :first_present_index,
+                         :bounded_product_analytics_surface
   end
 end

data/lib/logbrew/rails_integration.rb

@@ -353,10 +353,23 @@ module LogBrew
           sdk_version: LogBrew::VERSION,
           transport: transport,
           flush_interval: configuration.flush_interval,
-          flush_threshold: configuration.flush_threshold
+          flush_threshold: configuration.flush_threshold,
+          context: client_context(configuration)
         )
       end
 
+      def client_context(configuration)
+        resource = LogBrew::TelemetryResource.create
+          .with_service(name: configuration.service_name)
+          .with_deployment(
+            environment: configuration.app_environment,
+            release: configuration.release
+          )
+          .with_framework(name: "rails", version: configuration.rails_version)
+          .build
+        LogBrew::TelemetryContext.create.with_resource(resource).build
+      end
+
       def record_process_context(created)
         timestamp = logbrew_timestamp
         metadata = base_metadata
@@ -398,6 +411,14 @@ module LogBrew
     class RailsRackMiddleware < LogBrew::RackMiddleware
       private
 
+      def exception_mechanism_type
+        "rails.middleware"
+      end
+
+      def exception_grouping_prefix
+        "rails-exception"
+      end
+
       def request_name(env)
         "#{request_method(env)} #{route_template(env)}"
       end

data/lib/logbrew/telemetry.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module LogBrew
+  # Idempotent owner for one active shared-context scope.
+  class TelemetryScope
+    def initialize(activation_id)
+      @activation_id = activation_id
+      @closed = false
+    end
+
+    def close
+      return if @closed
+
+      Telemetry.close_scope(@activation_id)
+      @closed = true
+    end
+  end
+
+  # Fiber/thread-local shared context for request, job, and operation boundaries.
+  module Telemetry
+    STACK_KEY = :logbrew_telemetry_context_stack
+    private_constant :STACK_KEY
+
+    module_function
+
+    def current_context
+      entry = stack.last
+      entry && entry[:context]
+    end
+
+    def activate_context(context)
+      unless context.is_a?(TelemetryContext)
+        raise TelemetryContextValue.invalid("context must be a LogBrew::TelemetryContext")
+      end
+
+      merged = TelemetryContext.merge(current_context, context)
+      activation_id = Object.new
+      stack << { id: activation_id, context: merged }
+      TelemetryScope.new(activation_id)
+    end
+
+    def with_context(context)
+      scope = activate_context(context)
+      yield context
+    ensure
+      scope.close if scope
+    end
+
+    def close_scope(activation_id)
+      entries = stack
+      index = entries.rindex { |entry| entry[:id].equal?(activation_id) }
+      entries.delete_at(index) unless index.nil?
+    end
+
+    def stack
+      Thread.current[STACK_KEY] ||= []
+    end
+    private_class_method :stack
+  end
+end

data/lib/logbrew/telemetry_context.rb

@@ -0,0 +1,306 @@
+# frozen_string_literal: true
+
+require "etc"
+require "rbconfig"
+
+module LogBrew
+  # Immutable schema-v1 resource, trace, session, subject, and tag context.
+  class TelemetryContext
+    SCHEMA_VERSION = 1
+    ROOT_FIELDS = %w[schemaVersion resource trace session subject tags].freeze
+    TRACE_FIELDS = %w[traceId spanId parentSpanId sampled].freeze
+    SESSION_FIELDS = %w[id previousId].freeze
+    SUBJECT_FIELDS = %w[id kind].freeze
+
+    def self.create
+      TelemetryContextBuilder.new
+    end
+
+    def self.from_hash(value = nil, **keywords)
+      if value.nil?
+        value = keywords
+      elsif !keywords.empty?
+        raise TelemetryContextValue.invalid("telemetry context must be one object")
+      end
+      object = TelemetryContextValue.object(value, "telemetry context")
+      TelemetryContextValue.reject_unknown_fields(object, ROOT_FIELDS, "telemetry context")
+      unless object["schemaVersion"] == SCHEMA_VERSION
+        raise TelemetryContextValue.invalid("telemetry context schemaVersion must be 1")
+      end
+
+      normalized = { "schemaVersion" => SCHEMA_VERSION }
+      if object.key?("resource")
+        normalized["resource"] = TelemetryResource.from_hash(object.fetch("resource")).to_h
+      end
+      normalized["trace"] = normalize_trace(object.fetch("trace")) if object.key?("trace")
+      normalized["session"] = normalize_session(object.fetch("session")) if object.key?("session")
+      normalized["subject"] = normalize_subject(object.fetch("subject")) if object.key?("subject")
+      normalized["tags"] = normalize_tags(object.fetch("tags")) if object.key?("tags")
+      if normalized.length == 1
+        raise TelemetryContextValue.invalid(
+          "telemetry context must include resource, trace, session, subject, or tags"
+        )
+      end
+
+      new(normalized)
+    end
+
+    # Resource fields and tags merge by field. Trace, session, and subject are replaced.
+    def self.merge(base, override)
+      require_context_or_nil(base, "base telemetry context")
+      require_context_or_nil(override, "override telemetry context")
+      return nil if base.nil? && override.nil?
+      return from_hash(override.to_h) if base.nil?
+      return from_hash(base.to_h) if override.nil?
+
+      base_value = base.to_h
+      override_value = override.to_h
+      merged = { "schemaVersion" => SCHEMA_VERSION }
+
+      base_resource = resource_from_value(base_value["resource"])
+      override_resource = resource_from_value(override_value["resource"])
+      resource = TelemetryResource.merge(base_resource, override_resource)
+      merged["resource"] = resource.to_h unless resource.nil?
+
+      %w[trace session subject].each do |section|
+        value = override_value[section] || base_value[section]
+        merged[section] = value unless value.nil?
+      end
+
+      base_tags = base_value["tags"] || {}
+      override_tags = override_value["tags"] || {}
+      unless base_tags.empty? && override_tags.empty?
+        tags = base_tags.merge(override_tags)
+        TelemetryContextValue.require_tag_count(tags.length)
+        merged["tags"] = tags.keys.sort.each_with_object({}) { |key, sorted| sorted[key] = tags.fetch(key) }
+      end
+
+      from_hash(merged)
+    end
+
+    # Add exact active trace correlation over any existing context.
+    def self.with_trace(context, trace)
+      require_context_or_nil(context, "telemetry context")
+      unless defined?(LogBrew::TraceContext) && trace.is_a?(LogBrew::TraceContext)
+        raise TelemetryContextValue.invalid("trace must be a LogBrew::TraceContext")
+      end
+
+      trace_context = create.with_trace(trace).build
+      merge(context, trace_context)
+    end
+
+    # Conservative Ruby runtime, OS-family/release, and architecture identity.
+    def self.runtime_defaults
+      runtime_name = defined?(RUBY_ENGINE) ? RUBY_ENGINE : "ruby"
+      resource = TelemetryResource.create.with_runtime(name: runtime_name, version: RUBY_VERSION)
+      uname = safe_uname
+      operating_system = normalize_os_name(
+        safe_runtime_value(uname && uname[:sysname]) ||
+          safe_runtime_value(RbConfig::CONFIG["host_os"])
+      )
+      operating_system_version = safe_runtime_value(uname && uname[:release])
+      architecture = safe_runtime_value(uname && uname[:machine]) ||
+                     safe_runtime_value(RbConfig::CONFIG["host_cpu"])
+      unless operating_system.nil?
+        resource.with_operating_system(name: operating_system, version: operating_system_version)
+      end
+      resource.with_device(architecture: architecture) unless architecture.nil?
+      create.with_resource(resource.build).build
+    end
+
+    def to_h
+      TelemetryContextValue.deep_copy(@value)
+    end
+
+    class << self
+      private
+
+      def normalize_trace(value)
+        object = TelemetryContextValue.object(value, "telemetry context trace")
+        TelemetryContextValue.reject_unknown_fields(object, TRACE_FIELDS, "telemetry context trace")
+        unless object.key?("traceId")
+          raise TelemetryContextValue.invalid("traceId must be 32 non-zero hex characters")
+        end
+
+        normalized = {
+          "traceId" => TelemetryContextValue.trace_id(object.fetch("traceId"))
+        }
+        if object.key?("spanId")
+          normalized["spanId"] = TelemetryContextValue.span_id(object.fetch("spanId"), "spanId")
+        end
+        if object.key?("parentSpanId")
+          normalized["parentSpanId"] = TelemetryContextValue.span_id(
+            object.fetch("parentSpanId"),
+            "parentSpanId"
+          )
+        end
+        if object.key?("sampled")
+          sampled = object.fetch("sampled")
+          unless sampled == true || sampled == false
+            raise TelemetryContextValue.invalid("sampled must be a boolean")
+          end
+          normalized["sampled"] = sampled
+        end
+        normalized
+      end
+
+      def normalize_session(value)
+        object = TelemetryContextValue.object(value, "telemetry context session")
+        TelemetryContextValue.reject_unknown_fields(object, SESSION_FIELDS, "telemetry context session")
+        unless object.key?("id")
+          raise TelemetryContextValue.invalid("session id must be a string")
+        end
+        id = TelemetryContextValue.required_id(object.fetch("id"), "session id")
+        normalized = { "id" => id }
+        if object.key?("previousId")
+          previous_id = TelemetryContextValue.required_id(
+            object.fetch("previousId"),
+            "session previousId"
+          )
+          if previous_id == id
+            raise TelemetryContextValue.invalid("session previousId must differ from id")
+          end
+          normalized["previousId"] = previous_id
+        end
+        normalized
+      end
+
+      def normalize_subject(value)
+        object = TelemetryContextValue.object(value, "telemetry context subject")
+        TelemetryContextValue.reject_unknown_fields(object, SUBJECT_FIELDS, "telemetry context subject")
+        unless object.key?("id")
+          raise TelemetryContextValue.invalid("subject id must be a string")
+        end
+        kind = object["kind"]
+        unless %w[anonymous user].include?(kind)
+          raise TelemetryContextValue.invalid("subject kind must be anonymous or user")
+        end
+        {
+          "id" => TelemetryContextValue.required_id(object.fetch("id"), "subject id"),
+          "kind" => kind
+        }
+      end
+
+      def normalize_tags(value)
+        object = TelemetryContextValue.object(value, "telemetry context tags")
+        TelemetryContextValue.require_tag_count(object.length)
+        object.keys.sort.each_with_object({}) do |key, normalized|
+          normalized_key = TelemetryContextValue.tag_key(key)
+          normalized[normalized_key] = TelemetryContextValue.required_string(
+            object.fetch(key),
+            "tag value for #{normalized_key}"
+          )
+        end
+      end
+
+      def resource_from_value(value)
+        value.nil? ? nil : TelemetryResource.from_hash(value)
+      end
+
+      def require_context_or_nil(value, label)
+        return if value.nil? || value.is_a?(TelemetryContext)
+
+        raise TelemetryContextValue.invalid("#{label} must be a LogBrew::TelemetryContext")
+      end
+
+      def safe_uname
+        Etc.uname
+      rescue StandardError
+        nil
+      end
+
+      def safe_runtime_value(value)
+        return nil if value.nil?
+
+        TelemetryContextValue.required_string(value.to_s, "runtime context value")
+      rescue StandardError
+        nil
+      end
+
+      def normalize_os_name(value)
+        return nil if value.nil?
+
+        normalized = value.downcase
+        return "darwin" if normalized.include?("darwin") || normalized.include?("mac os")
+        return "linux" if normalized.include?("linux")
+        return "windows" if normalized.match?(/windows|mswin|mingw|cygwin/)
+
+        normalized
+      end
+    end
+
+    private
+
+    def initialize(value)
+      @value = TelemetryContextValue.deep_freeze(TelemetryContextValue.deep_copy(value))
+      freeze
+    end
+  end
+
+  # Builder for one immutable, privacy-bounded shared telemetry context.
+  class TelemetryContextBuilder
+    def initialize
+      @value = { "schemaVersion" => TelemetryContext::SCHEMA_VERSION }
+    end
+
+    def with_resource(resource)
+      unless resource.is_a?(TelemetryResource)
+        raise TelemetryContextValue.invalid("resource must be a LogBrew::TelemetryResource")
+      end
+      @value["resource"] = resource.to_h
+      self
+    end
+
+    def with_trace(trace)
+      unless defined?(LogBrew::TraceContext) && trace.is_a?(LogBrew::TraceContext)
+        raise TelemetryContextValue.invalid("trace must be a LogBrew::TraceContext")
+      end
+      with_trace_ids(
+        trace_id: trace.trace_id,
+        span_id: trace.span_id,
+        parent_span_id: trace.parent_span_id,
+        sampled: trace.sampled
+      )
+    end
+
+    def with_trace_ids(trace_id:, span_id: nil, parent_span_id: nil, sampled: nil)
+      trace = { "traceId" => trace_id }
+      trace["spanId"] = span_id unless span_id.nil?
+      trace["parentSpanId"] = parent_span_id unless parent_span_id.nil?
+      trace["sampled"] = sampled unless sampled.nil?
+      @value["trace"] = trace
+      self
+    end
+
+    def with_session(id:, previous_id: nil)
+      session = { "id" => id }
+      session["previousId"] = previous_id unless previous_id.nil?
+      @value["session"] = session
+      self
+    end
+
+    def with_subject(id:, kind:)
+      @value["subject"] = { "id" => id, "kind" => kind }
+      self
+    end
+
+    def with_tag(key, value)
+      normalized_key = TelemetryContextValue.tag_key(key.to_s)
+      normalized_value = TelemetryContextValue.required_string(value, "tag value for #{normalized_key}")
+      tags = (@value["tags"] ||= {})
+      tags[normalized_key] = normalized_value
+      TelemetryContextValue.require_tag_count(tags.length)
+      self
+    end
+
+    def with_tags(tags)
+      object = TelemetryContextValue.object(tags, "telemetry context tags")
+      object.each { |key, value| with_tag(key, value) }
+      self
+    end
+
+    def build
+      TelemetryContext.from_hash(@value)
+    end
+  end
+end

data/lib/logbrew/telemetry_context_value.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module LogBrew
+  # Shared validation and detachment rules for schema-v1 telemetry context.
+  module TelemetryContextValue
+    MAX_CONTEXT_STRING = 256
+    MAX_CONTEXT_ID = 200
+    MAX_TAGS = 32
+    MAX_TAG_KEY = 64
+    TAG_KEY = /\A[A-Za-z][A-Za-z0-9_.-]*\z/.freeze
+    CONTROL_CHARACTERS = /[\u0000-\u001f\u007f-\u009f]/.freeze
+    LOWER_HEX = /\A[0-9a-f]+\z/.freeze
+
+    module_function
+
+    def object(value, label)
+      raise invalid("#{label} must be an object") unless value.is_a?(Hash)
+
+      value.each_with_object({}) do |(key, item), normalized|
+        unless key.is_a?(String) || key.is_a?(Symbol)
+          raise invalid("#{label} keys must be strings")
+        end
+
+        normalized_key = key.to_s
+        if normalized.key?(normalized_key)
+          raise invalid("#{label} contains duplicate field #{normalized_key}")
+        end
+        normalized[normalized_key] = item
+      end
+    end
+
+    def reject_unknown_fields(value, allowed, label)
+      unknown = value.keys - allowed
+      return if unknown.empty?
+
+      raise invalid("#{label} has unknown field #{unknown.sort.first}")
+    end
+
+    def required_string(value, label, maximum = MAX_CONTEXT_STRING)
+      raise invalid("#{label} must be a string") unless value.is_a?(String)
+
+      normalized = utf8_string(value, label).strip
+      raise invalid("#{label} must not be empty") if normalized.empty? || !normalized.match?(/\S/)
+      if normalized.length > maximum
+        raise invalid("#{label} must contain at most #{maximum} characters")
+      end
+      if normalized.match?(CONTROL_CHARACTERS)
+        raise invalid("#{label} must not contain control characters")
+      end
+
+      normalized
+    end
+
+    def optional_string(value, label, maximum = MAX_CONTEXT_STRING)
+      return nil if value.nil?
+
+      required_string(value, label, maximum)
+    end
+
+    def required_id(value, label)
+      required_string(value, label, MAX_CONTEXT_ID)
+    end
+
+    def optional_id(value, label)
+      return nil if value.nil?
+
+      required_id(value, label)
+    end
+
+    def trace_id(value, label = "traceId")
+      normalized_hex_id(value, 32, "0" * 32, label)
+    end
+
+    def span_id(value, label)
+      normalized_hex_id(value, 16, "0" * 16, label)
+    end
+
+    def optional_span_id(value, label)
+      return nil if value.nil?
+
+      span_id(value, label)
+    end
+
+    def tag_key(value)
+      raise invalid("tag key must be a string") unless value.is_a?(String)
+
+      normalized = utf8_string(value, "tag key")
+      unless normalized.length <= MAX_TAG_KEY && normalized.match?(TAG_KEY)
+        raise invalid("tag key #{normalized} must start with a letter and contain only letters, numbers, _, ., or -")
+      end
+
+      normalized
+    end
+
+    def require_tag_count(count)
+      unless count.between?(1, MAX_TAGS)
+        raise invalid("telemetry context must contain 1 to at most #{MAX_TAGS} tags")
+      end
+    end
+
+    def deep_copy(value)
+      case value
+      when Hash
+        value.each_with_object({}) { |(key, item), copy| copy[key.dup] = deep_copy(item) }
+      when Array
+        value.map { |item| deep_copy(item) }
+      when String
+        value.dup
+      else
+        value
+      end
+    end
+
+    def deep_freeze(value)
+      case value
+      when Hash
+        value.each do |key, item|
+          key.freeze
+          deep_freeze(item)
+        end
+      when Array
+        value.each { |item| deep_freeze(item) }
+      end
+      value.freeze
+    end
+
+    def invalid(message)
+      SdkError.new("validation_error", message)
+    end
+
+    def normalized_hex_id(value, width, all_zero, label)
+      raise invalid("#{label} must be #{width} non-zero hex characters") unless value.is_a?(String)
+
+      normalized = utf8_string(value, label).downcase
+      unless normalized.length == width && normalized.match?(LOWER_HEX) && normalized != all_zero
+        raise invalid("#{label} must be #{width} non-zero hex characters")
+      end
+      normalized
+    end
+    private_class_method :normalized_hex_id
+
+    def utf8_string(value, label)
+      normalized = value.encode(Encoding::UTF_8)
+      raise EncodingError unless normalized.valid_encoding?
+
+      normalized.dup
+    rescue EncodingError
+      raise invalid("#{label} must be valid UTF-8")
+    end
+    private_class_method :utf8_string
+  end
+end