strongmind-platform-sdk 3.27.5 → 3.28.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 10d6f1421ebf925d2fabec136b4afc8c4c98e93007858365f5232f2345e8082f
-  data.tar.gz: e8b7b866bc67d307abde2fbaf2b8c1c6c2c3e55dddfc95bd67e5df197da9e1cb
+  metadata.gz: 97b493cd879ebbc714026b5d819ddfe8366453b0fb3d4e037ccf653dd6bf852e
+  data.tar.gz: bf03370e3b62cdc6732dcb9d1a0966782afa45722ac6f2bf15e121978c0d1fce
 SHA512:
-  metadata.gz: cc9a23c8b4d71f2aa8effcd0e0c62e7e3eed2b2b09c03b0313e1eb4ec71f6fc6d1a19b1cddee0829265d265ce9b03115f7752bae073e7157bf05e306e577f927
-  data.tar.gz: 766fea6294b2dde18c78d008741a8e80d0bf9610b9eb476422cdd0ccde51e367a2ba51da952358a752483071e35005f92988f184c529bb75d8f95072b61c7f9b
+  metadata.gz: 37074d6a5591e41ae57301530ffaed72b49bb21d07298ebd2c2434fcfe50cbd623f24b1fc6db4ee991b7b19c3eaa503014568a8e7b2548766265c8c90589dd0e
+  data.tar.gz: a539e7cad181064b9d617c020241a356dafb96102bfb2d1a63398476885c400b6736dfad46ab0b941e314654f6181960a46552bde1a3556ab0ea281b6a97e347

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 ## [Unreleased]
 
+## [3.28.0] - 2026-05-05
+
+- Add `PlatformSdk::Observability::Langfuse` module providing OpenTelemetry-based tracing exported to Langfuse Cloud via OTLP.
+- `TracerProvider` is isolated (not installed globally) and coexists safely with `ddtrace`.
+- Add `Traceable` Sidekiq concern (`include PlatformSdk::Observability::Langfuse::Traceable`) that wraps `perform` in a parent span.
+- Add `record_generation` module method emitting `gen_ai.*` child spans inside an active trace.
+- Add `NullSpanExporter` for use in tests (no network calls).
+- Sidekiq shutdown flush hook is installed automatically when `configure` is called with valid keys.
+- Add runtime dependencies: `opentelemetry-sdk`, `opentelemetry-exporter-otlp`.
+
 ## [0.1.0] - 2022-05-13
 
 - Initial release

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    strongmind-platform-sdk (3.27.0)
+    strongmind-platform-sdk (3.28.0)
       asset_sync
       aws-sdk-cloudwatch
       aws-sdk-secretsmanager (~> 1.66)
@@ -11,6 +11,8 @@ PATH
       jwt
       learnosity-sdk (~> 0.2.2)
       multi_json
+      opentelemetry-exporter-otlp (~> 0.27)
+      opentelemetry-sdk (~> 1.10)
       rails (>= 7.1)
       sentry-ruby
       sidekiq
@@ -97,8 +99,9 @@ GEM
       tzinfo (~> 2.0)
     addressable (2.8.7)
       public_suffix (>= 2.0.2, < 7.0)
-    asset_sync (2.19.2)
+    asset_sync (2.19.3)
       activemodel (>= 4.1.0)
+      cgi
       fog-core
       mime-types (>= 2.99)
       unf
@@ -121,6 +124,7 @@ GEM
     base64 (0.2.0)
     bigdecimal (3.1.8)
     builder (3.3.0)
+    cgi (0.5.1)
     coderay (1.1.3)
     concurrent-ruby (1.3.3)
     connection_pool (2.4.1)
@@ -134,7 +138,7 @@ GEM
     erubi (1.13.0)
     ethon (0.16.0)
       ffi (>= 1.15.0)
-    excon (1.3.0)
+    excon (1.4.2)
       logger
     factory_bot (6.4.6)
       activesupport (>= 5.0.0)
@@ -150,7 +154,7 @@ GEM
     ffi (1.17.0)
     ffi (1.17.0-x86_64-darwin)
     ffi (1.17.0-x86_64-linux-gnu)
-    fog-aws (3.33.0)
+    fog-aws (3.33.1)
       base64 (>= 0.2, < 0.4)
       fog-core (~> 2.6)
       fog-json (~> 1.1)
@@ -166,10 +170,21 @@ GEM
     fog-xml (0.1.5)
       fog-core
       nokogiri (>= 1.5.11, < 2.0.0)
-    formatador (1.2.2)
+    formatador (1.2.3)
       reline
     globalid (1.3.0)
       activesupport (>= 6.1)
+    google-protobuf (4.33.6)
+      bigdecimal
+      rake (>= 13)
+    google-protobuf (4.33.6-x86_64-darwin)
+      bigdecimal
+      rake (>= 13)
+    google-protobuf (4.33.6-x86_64-linux-gnu)
+      bigdecimal
+      rake (>= 13)
+    googleapis-common-protos-types (1.22.0)
+      google-protobuf (~> 4.26)
     hashdiff (1.1.0)
     i18n (1.14.5)
       concurrent-ruby (~> 1.0)
@@ -198,7 +213,7 @@ GEM
     mime-types (3.7.0)
       logger
       mime-types-data (~> 3.2025, >= 3.2025.0507)
-    mime-types-data (3.2025.0924)
+    mime-types-data (3.2026.0317)
     mini_mime (1.1.5)
     mini_portile2 (2.8.7)
     minitest (5.24.1)
@@ -206,7 +221,7 @@ GEM
     mutex_m (0.2.0)
     net-http (0.4.1)
       uri
-    net-imap (0.5.12)
+    net-imap (0.6.3)
       date
       net-protocol
     net-pop (0.1.2)
@@ -223,6 +238,26 @@ GEM
       racc (~> 1.4)
     nokogiri (1.16.7-x86_64-linux)
       racc (~> 1.4)
+    opentelemetry-api (1.8.0)
+      logger
+    opentelemetry-common (0.23.0)
+      opentelemetry-api (~> 1.0)
+    opentelemetry-exporter-otlp (0.32.0)
+      google-protobuf (>= 3.18)
+      googleapis-common-protos-types (~> 1.3)
+      opentelemetry-api (~> 1.1)
+      opentelemetry-common (~> 0.20)
+      opentelemetry-sdk (~> 1.10)
+      opentelemetry-semantic_conventions
+    opentelemetry-registry (0.4.0)
+      opentelemetry-api (~> 1.1)
+    opentelemetry-sdk (1.10.0)
+      opentelemetry-api (~> 1.1)
+      opentelemetry-common (~> 0.20)
+      opentelemetry-registry (~> 0.2)
+      opentelemetry-semantic_conventions
+    opentelemetry-semantic_conventions (1.36.0)
+      opentelemetry-api (~> 1.0)
     parallel (1.25.1)
     parser (3.3.4.0)
       ast (~> 2.4.1)
@@ -342,7 +377,7 @@ GEM
       ffi (~> 1.1)
     thor (1.3.1)
     timecop (0.9.10)
-    timeout (0.4.4)
+    timeout (0.6.1)
     typhoeus (1.4.1)
       ethon (>= 0.9.0)
     tzinfo (2.0.6)

data/lib/platform_sdk/observability/langfuse/coercions.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module PlatformSdk
+  module Observability
+    module Langfuse
+      # Shared coercion helpers used by Configuration, Recorder, and the
+      # Traceable PerformWrapper. Extracted to a single home so the
+      # OpenTelemetry attribute-validator workaround (`String.new` to
+      # produce a plain String rather than a subclass) lives in one place.
+      module Coercions
+        module_function
+
+        # Returns `nil` for nil; otherwise a plain `String` (not a
+        # subclass). OTel's attribute validator uses `instance_of?(String)`
+        # — subclasses like `ActiveSupport::SafeBuffer` fail validation and
+        # crash `Resource.create`.
+        def coerce_string(value)
+          return nil if value.nil?
+
+          String.new(value.to_s)
+        end
+      end
+    end
+  end
+end

data/lib/platform_sdk/observability/langfuse/configuration.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require 'opentelemetry/sdk'
+require 'opentelemetry/exporter/otlp'
+require 'base64'
+require 'uri'
+
+module PlatformSdk
+  module Observability
+    module Langfuse
+      class Configuration
+        DEFAULT_BASE_URL = 'https://us.cloud.langfuse.com' # US region; set LANGFUSE_BASE_URL for eu.cloud.langfuse.com, jp.cloud.langfuse.com, etc.
+        DEFAULT_PROMPT_LABEL = 'latest'
+        DEFAULT_BATCH_INTERVAL_MS = 5_000
+        OTLP_TRACES_PATH = '/api/public/otel/v1/traces'
+
+        attr_reader :app_name, :environment, :prompt_label, :exporter
+
+        def initialize(app_name:, environment: nil, prompt_label: nil, exporter: nil)
+          @app_name = coerce_string(app_name)
+          @environment = coerce_string(environment || ENV.fetch('RAILS_ENV', 'development'))
+          @prompt_label = coerce_string(prompt_label || ENV.fetch('LANGFUSE_PROMPT_LABEL', DEFAULT_PROMPT_LABEL))
+          @exporter = exporter
+          @enabled = compute_enabled
+        end
+
+        def enabled?
+          @enabled
+        end
+
+        def otlp_endpoint
+          "#{base_url}#{OTLP_TRACES_PATH}"
+        end
+
+        def default_resource_attributes
+          {
+            'service.name' => app_name,
+            'deployment.environment' => environment
+          }
+        end
+
+        def tracer
+          @tracer ||= tracer_provider.tracer('platform_sdk.observability.langfuse', PlatformSdk::VERSION)
+        end
+
+        def tracer_provider
+          @tracer_provider ||= build_tracer_provider
+        end
+
+        def force_flush_and_shutdown
+          return if @shut_down
+          return unless @tracer_provider
+
+          @tracer_provider.force_flush(timeout: 5)
+          @tracer_provider.shutdown(timeout: 5)
+          @shut_down = true
+        end
+
+        private
+
+        # Snapshot the enabled state at construction time so credentials
+        # mutated in ENV after `configure` don't silently flip behavior
+        # mid-process. Callers who need to roll keys must re-`configure`.
+        def compute_enabled
+          return false if ENV['LANGFUSE_ENABLED'] == 'false'
+
+          public_key.to_s != '' && secret_key.to_s != ''
+        end
+
+        def coerce_string(value)
+          Coercions.coerce_string(value)
+        end
+
+        def public_key
+          ENV['LANGFUSE_PUBLIC_KEY']
+        end
+
+        def secret_key
+          ENV['LANGFUSE_SECRET_KEY']
+        end
+
+        def base_url
+          @base_url ||= validated_base_url
+        end
+
+        def validated_base_url
+          url = ENV.fetch('LANGFUSE_BASE_URL', DEFAULT_BASE_URL)
+          uri = URI.parse(url)
+          unless %w[http https].include?(uri.scheme) && !uri.host.nil?
+            raise ConfigurationError, "LANGFUSE_BASE_URL must be an http(s) URL with a host (got: #{url.inspect})"
+          end
+
+          url
+        rescue URI::InvalidURIError => e
+          raise ConfigurationError, "LANGFUSE_BASE_URL is not a valid URI: #{e.message}"
+        end
+
+        def batch_interval_ms
+          ENV.fetch('LANGFUSE_BATCH_INTERVAL_MS', DEFAULT_BATCH_INTERVAL_MS).to_i
+        end
+
+        # Builds an isolated TracerProvider that is intentionally NOT installed
+        # as the OpenTelemetry global (no `OpenTelemetry.tracer_provider =`,
+        # no `OpenTelemetry::SDK.configure`). Datadog APM (ddtrace) hooks the
+        # global tracer provider via `require 'datadog/opentelemetry'`; keeping
+        # this provider isolated lets Langfuse and ddtrace coexist without
+        # fighting over the same global state. See:
+        # https://github.com/DataDog/dd-trace-rb/blob/master/docs/OpenTelemetry.md
+        def build_tracer_provider
+          provider = OpenTelemetry::SDK::Trace::TracerProvider.new(
+            resource: OpenTelemetry::SDK::Resources::Resource.create(default_resource_attributes),
+            span_limits: span_limits
+          )
+          provider.add_span_processor(span_processor)
+          provider
+        end
+
+        def span_limits
+          OpenTelemetry::SDK::Trace::SpanLimits.new(
+            attribute_length_limit: Recorder::MAX_ATTRIBUTE_BYTES
+          )
+        end
+
+        def span_processor
+          OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(
+            exporter || build_otlp_exporter,
+            schedule_delay: batch_interval_ms,
+            max_queue_size: 2048,
+            max_export_batch_size: 512
+          )
+        end
+
+        def build_otlp_exporter
+          OpenTelemetry::Exporter::OTLP::Exporter.new(
+            endpoint: otlp_endpoint,
+            headers: {
+              'Authorization' => basic_auth_header,
+              'x-langfuse-ingestion-version' => '4'
+            }
+          )
+        end
+
+        def basic_auth_header
+          token = Base64.strict_encode64("#{public_key}:#{secret_key}")
+          "Basic #{token}"
+        end
+      end
+    end
+  end
+end

data/lib/platform_sdk/observability/langfuse/null_span_exporter.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require 'opentelemetry/sdk'
+
+module PlatformSdk
+  module Observability
+    module Langfuse
+      # Span exporter for tests and dev. Wraps OTel's `InMemorySpanExporter`
+      # with two minor adjustments:
+      #
+      #   1. `shutdown` is a no-op (the base class clears `@finished_spans`
+      #      on shutdown). Our tests pervasively call
+      #      `configuration.force_flush_and_shutdown` and then assert on
+      #      exported spans — preserving the buffer across shutdown is
+      #      what makes that ergonomics work.
+      #   2. `exported_spans` / `clear` aliases for `finished_spans` /
+      #      `reset` so the names line up with how we talk about this
+      #      thing elsewhere in the SDK (and don't change call sites in
+      #      consumer apps).
+      class NullSpanExporter < OpenTelemetry::SDK::Trace::Export::InMemorySpanExporter
+        alias exported_spans finished_spans
+        alias clear reset
+
+        def shutdown(timeout: nil)
+          OpenTelemetry::SDK::Trace::Export::SUCCESS
+        end
+      end
+    end
+  end
+end

data/lib/platform_sdk/observability/langfuse/recorder.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module PlatformSdk
+  module Observability
+    module Langfuse
+      module Recorder
+        MAX_ATTRIBUTE_BYTES = 262_144 # 256KB
+        TRUNCATION_SUFFIX = "…[truncated]"
+
+        # rubocop:disable Metrics/ParameterLists
+        def self.record_generation(name:, model:, input:, output:, prompt_name: nil, prompt_version: nil, usage: nil, provider: nil)
+          return unless Langfuse.enabled?
+          return unless current_span_active?
+
+          tracer = Langfuse.tracer
+          tracer.in_span(name, attributes: build_attributes(model, input, output, prompt_name, prompt_version, usage, provider)) do
+            # span body intentionally empty — attributes carry the data
+          end
+        end
+        # rubocop:enable Metrics/ParameterLists
+
+        def self.current_span_active?
+          OpenTelemetry::Trace.current_span.context.valid?
+        end
+
+        # rubocop:disable Metrics/ParameterLists
+        def self.build_attributes(model, input, output, prompt_name, prompt_version, usage, provider = nil)
+          attrs = {
+            'langfuse.observation.type' => 'generation',
+            # `gen_ai.operation.name` is a required attribute in the OTel
+            # GenAI semantic conventions. We only emit chat-style
+            # completions today, so this is a constant.
+            'gen_ai.operation.name' => 'chat',
+            'gen_ai.request.model' => coerce_string(model),
+            'gen_ai.prompt' => stringify(input),
+            'gen_ai.completion' => stringify(output)
+          }
+          attrs['gen_ai.provider.name'] = coerce_string(provider) if provider
+          if prompt_name && prompt_version
+            attrs['langfuse.observation.prompt.name'] = coerce_string(prompt_name)
+            attrs['langfuse.observation.prompt.version'] = coerce_simple(prompt_version)
+          end
+          if usage.is_a?(Hash)
+            usage = usage.transform_keys(&:to_sym)
+            input_tokens = coerce_integer(usage[:input_tokens])
+            output_tokens = coerce_integer(usage[:output_tokens])
+            attrs['gen_ai.usage.input_tokens'] = input_tokens unless input_tokens.nil?
+            attrs['gen_ai.usage.output_tokens'] = output_tokens unless output_tokens.nil?
+          end
+          attrs.compact
+        end
+        # rubocop:enable Metrics/ParameterLists
+
+        def self.coerce_string(value)
+          Coercions.coerce_string(value)
+        end
+
+        # Pass numerics/booleans through; coerce everything else to plain String.
+        def self.coerce_simple(value)
+          return nil if value.nil?
+          return value if value.instance_of?(Integer) || value.instance_of?(Float)
+          return value if value.instance_of?(TrueClass) || value.instance_of?(FalseClass)
+
+          String.new(value.to_s)
+        end
+
+        def self.coerce_integer(value)
+          return nil if value.nil?
+
+          Integer(value)
+        rescue ArgumentError, TypeError
+          nil
+        end
+
+        def self.stringify(value)
+          str = value.is_a?(String) ? value : value.to_json
+          truncated = truncate(str)
+          # Force a plain String — value.to_json could be a String subclass
+          # in some odd cases, and value.is_a?(String) lets subclasses through.
+          String.new(truncated)
+        rescue StandardError
+          String.new(truncate(value.to_s))
+        end
+
+        def self.truncate(str)
+          return str if str.bytesize <= MAX_ATTRIBUTE_BYTES
+
+          # Slice on byte boundary then strip any partial multibyte sequence by encoding-coercing.
+          truncated = str.byteslice(0, MAX_ATTRIBUTE_BYTES).scrub('')
+          "#{truncated}#{TRUNCATION_SUFFIX}"
+        end
+      end
+    end
+  end
+end

data/lib/platform_sdk/observability/langfuse/sidekiq_lifecycle.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require 'sidekiq'
+
+module PlatformSdk
+  module Observability
+    module Langfuse
+      module SidekiqLifecycle
+        @installed = false
+        @mutex = Mutex.new
+
+        class << self
+          def install!
+            @mutex.synchronize do
+              return if @installed
+
+              @installed = true
+              ::Sidekiq.configure_server do |config|
+                config.on(:shutdown) do
+                  PlatformSdk::Observability::Langfuse.configuration&.force_flush_and_shutdown
+                end
+              end
+            end
+          end
+
+          def reset!
+            @mutex.synchronize { @installed = false }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/platform_sdk/observability/langfuse/spec_support.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+# Test-environment wiring for PlatformSdk::Observability::Langfuse.
+#
+# Consuming apps add this one line to their `spec/rails_helper.rb` (or
+# `spec_helper.rb`):
+#
+#   require 'platform_sdk/observability/langfuse/spec_support'
+#   PlatformSdk::Observability::Langfuse::SpecSupport.install!(app_name: 'my-app-test')
+#
+# What it does:
+#   * Configures the Langfuse module with a NullSpanExporter so no live network
+#     calls happen during tests.
+#   * Clears the exporter between examples so spans don't bleed across tests.
+#   * Mixes a `langfuse_exported_spans` helper into every example so specs can
+#     flush + read the exported spans for assertions.
+
+module PlatformSdk
+  module Observability
+    module Langfuse
+      module SpecSupport
+        DEFAULT_TEST_PUBLIC_KEY = 'pk-test'
+        DEFAULT_TEST_SECRET_KEY = 'sk-test'
+        DEFAULT_TEST_ENVIRONMENT = 'test'
+
+        # Register the RSpec lifecycle hooks. Call once from `rails_helper.rb`
+        # (or `spec_helper.rb`). The actual NullSpanExporter wiring happens in
+        # `before(:suite)`; this method just sets up the hooks.
+        def self.install!(app_name:, environment: DEFAULT_TEST_ENVIRONMENT)
+          require 'rspec/core'
+
+          RSpec.configure do |config|
+            config.before(:suite) do
+              PlatformSdk::Observability::Langfuse::SpecSupport.apply!(
+                app_name: app_name,
+                environment: environment
+              )
+            end
+            config.before(:each) do
+              PlatformSdk::Observability::Langfuse::SpecSupport.exporter&.clear
+            end
+            config.include TestHelpers
+          end
+        end
+
+        # Configure the Langfuse module with a NullSpanExporter. Separate from
+        # `install!` so it can be invoked directly in specs that need to test
+        # SpecSupport itself, or by apps that drive their own lifecycle.
+        def self.apply!(app_name:, environment: DEFAULT_TEST_ENVIRONMENT)
+          ENV['LANGFUSE_PUBLIC_KEY'] ||= DEFAULT_TEST_PUBLIC_KEY
+          ENV['LANGFUSE_SECRET_KEY'] ||= DEFAULT_TEST_SECRET_KEY
+
+          PlatformSdk::Observability::Langfuse.reset!
+          PlatformSdk::Observability::Langfuse.configure(
+            app_name: app_name,
+            environment: environment,
+            exporter: NullSpanExporter.new
+          )
+        end
+
+        # The currently-configured NullSpanExporter, or nil if `install!` was
+        # not called or the configuration was reset.
+        def self.exporter
+          config = PlatformSdk::Observability::Langfuse.configuration
+          return nil unless config
+
+          config.exporter
+        end
+
+        module TestHelpers
+          # Force-flush the BatchSpanProcessor and return every span the
+          # NullSpanExporter has captured during the current example. Use this
+          # to assert that a code path produced the expected spans.
+          #
+          # Example:
+          #   spans = langfuse_exported_spans
+          #   parent = spans.find { |s| s.name == 'MyJob' }
+          #   expect(parent.attributes['langfuse.trace.tags']).to include('test')
+          def langfuse_exported_spans
+            config = PlatformSdk::Observability::Langfuse.configuration
+            config.tracer_provider.force_flush(timeout: 5)
+            PlatformSdk::Observability::Langfuse::SpecSupport.exporter.exported_spans
+          end
+        end
+      end
+    end
+  end
+end

data/lib/platform_sdk/observability/langfuse/traceable.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require 'active_support/concern'
+
+module PlatformSdk
+  module Observability
+    module Langfuse
+      module Traceable
+        extend ActiveSupport::Concern
+
+        # PerformWrapper is prepended into the including class so that its
+        # perform override runs before the class's own perform definition,
+        # regardless of the order in which include and def appear.
+        module PerformWrapper
+          REENTRY_KEY = :platform_sdk_langfuse_traceable_active
+
+          def perform(*args)
+            return super(*args) unless PlatformSdk::Observability::Langfuse.enabled?
+
+            # Re-entry guard: subclass `inherited` re-prepends PerformWrapper at
+            # every level of the ancestry, so a subclass `perform` that calls
+            # `super` would otherwise hit the wrapper at each intermediate class
+            # and open one span per level. Only the outermost wrapper opens a
+            # span; inner re-entries just delegate.
+            return super(*args) if Thread.current[REENTRY_KEY]
+
+            Thread.current[REENTRY_KEY] = true
+            begin
+              tracer = PlatformSdk::Observability::Langfuse.tracer
+              tracer.in_span(self.class.langfuse_span_name, attributes: safe_langfuse_span_attributes(args)) do
+                super(*args)
+              end
+            ensure
+              Thread.current[REENTRY_KEY] = false
+              PlatformSdk::Observability::Langfuse.clear_tracked_thread_locals!
+            end
+          end
+
+          private
+
+          # Build attributes, but never raise out — a bad value should degrade tracing,
+          # not crash the wrapped job.
+          def safe_langfuse_span_attributes(args)
+            langfuse_span_attributes(args)
+          rescue StandardError => e
+            OpenTelemetry.handle_error(message: "Langfuse attribute build failed: #{e.message}") if defined?(::OpenTelemetry)
+            {}
+          end
+
+          def langfuse_span_attributes(args)
+            attrs = {
+              'sidekiq.jid' => coerce_string(jid_if_available),
+              'langfuse.trace.input' => coerce_string(args.to_json)
+            }.compact
+            tags = combined_langfuse_tags
+            attrs['langfuse.trace.tags'] = tags if tags.any?
+            attrs
+          end
+
+          def jid_if_available
+            respond_to?(:jid) ? jid : nil
+          end
+
+          def combined_langfuse_tags
+            config = PlatformSdk::Observability::Langfuse.configuration
+            base_tags = config ? [config.environment, config.prompt_label].compact : []
+            (base_tags + Array(self.class.langfuse_extra_tags)).uniq.map { |t| coerce_string(t) }.compact
+          end
+
+          def coerce_string(value)
+            Coercions.coerce_string(value)
+          end
+        end
+
+        included do
+          prepend PerformWrapper
+
+          # Subclasses that define their own perform would shadow PerformWrapper
+          # (which sits in the parent class's chain). Re-prepend on every subclass
+          # so the wrapper sits above each subclass's own perform definition.
+          def self.inherited(subclass)
+            super
+            subclass.prepend PerformWrapper
+          end
+        end
+
+        class_methods do
+          # Optional override hook so consumers can change the span name or pre-set tags.
+          def traced_with_langfuse(name: nil, tags: [])
+            @langfuse_span_name = name
+            @langfuse_extra_tags = Array(tags)
+          end
+
+          def langfuse_span_name
+            @langfuse_span_name || name
+          end
+
+          def langfuse_extra_tags
+            @langfuse_extra_tags || []
+          end
+        end
+      end
+    end
+  end
+end

data/lib/platform_sdk/observability/langfuse.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require 'platform_sdk/observability/langfuse/coercions'
+require 'platform_sdk/observability/langfuse/configuration'
+require 'platform_sdk/observability/langfuse/null_span_exporter'
+require 'platform_sdk/observability/langfuse/recorder'
+require 'platform_sdk/observability/langfuse/traceable'
+require 'platform_sdk/observability/langfuse/sidekiq_lifecycle'
+
+module PlatformSdk
+  module Observability
+    module Langfuse
+      class Error < StandardError; end
+      class ConfigurationError < Error; end
+
+      OWNED_THREAD_LOCALS_KEY = :platform_sdk_langfuse_owned_thread_locals
+
+      class << self
+        attr_reader :configuration
+
+        def configure(app_name:, environment: nil, prompt_label: nil, exporter: nil)
+          @configuration&.force_flush_and_shutdown
+          @configuration = Configuration.new(
+            app_name: app_name,
+            environment: environment,
+            prompt_label: prompt_label,
+            exporter: exporter
+          )
+          SidekiqLifecycle.install! if @configuration.enabled?
+          @configuration
+        end
+
+        def enabled?
+          !@configuration.nil? && @configuration.enabled?
+        end
+
+        def tracer
+          return nil unless enabled?
+
+          @configuration.tracer
+        end
+
+        def record_generation(**kwargs)
+          Recorder.record_generation(**kwargs)
+        end
+
+        # Set the trace-level output on the active parent span. Application
+        # code calls this from inside a Traceable job (or any block running
+        # under an active span) to record a meaningful summary of the job's
+        # result.
+        #
+        # Why this is opt-in rather than auto-captured from `perform`'s return
+        # value: Sidekiq's `perform` return is incidental — it's often nil, an
+        # AR transaction callback array, or otherwise unrelated to anything a
+        # human reading a trace would find useful. Only the application knows
+        # what's meaningful (e.g. a generated record's ID).
+        #
+        # Example:
+        #   class MyJob
+        #     include Sidekiq::Job
+        #     include PlatformSdk::Observability::Langfuse::Traceable
+        #
+        #     def perform(args)
+        #       component = generate_component(args)
+        #       PlatformSdk::Observability::Langfuse.set_trace_output(
+        #         { component_id: component.id, status: component.status }
+        #       )
+        #     end
+        #   end
+        #
+        # No-ops when the SDK is disabled or no span is currently active.
+        # Never raises — observability failures must not break callers.
+        def set_trace_output(value)
+          return unless enabled?
+
+          span = OpenTelemetry::Trace.current_span
+          return unless span.context.valid?
+
+          span.set_attribute('langfuse.trace.output', Recorder.stringify(value))
+        rescue StandardError, SystemStackError => e
+          OpenTelemetry.handle_error(message: "Langfuse set_trace_output failed: #{e.class}: #{e.message[0, 200]}")
+          nil
+        end
+
+        def reset!
+          @configuration&.force_flush_and_shutdown
+          @configuration = nil
+          SidekiqLifecycle.reset!
+        end
+
+        # Register thread-local keys that should be cleared at the next
+        # Traceable job boundary. Consumers call this when they store
+        # per-trace state on `Thread.current` (e.g. the ID of the last
+        # recorded message) so the value can't leak into the next job
+        # that lands on this Sidekiq thread.
+        #
+        # Example:
+        #   PlatformSdk::Observability::Langfuse.track_thread_local(:my_app_last_message_id)
+        #   Thread.current[:my_app_last_message_id] = msg.id
+        #
+        # Compared to a name-prefix convention, this requires explicit
+        # opt-in (so consumers can't accidentally have unrelated state
+        # zeroed) and is O(owned keys) instead of O(all thread locals).
+        def track_thread_local(*keys)
+          list = (Thread.current[OWNED_THREAD_LOCALS_KEY] ||= [])
+          keys.each { |k| list << k unless list.include?(k) }
+          nil
+        end
+
+        # Clear every thread-local registered via `track_thread_local` on
+        # this thread, then drop the registry itself. Called from the
+        # Traceable wrapper's `ensure` block.
+        def clear_tracked_thread_locals!
+          owned = Thread.current[OWNED_THREAD_LOCALS_KEY]
+          return unless owned
+
+          owned.each { |k| Thread.current[k] = nil }
+          Thread.current[OWNED_THREAD_LOCALS_KEY] = nil
+        end
+      end
+    end
+  end
+end

data/lib/platform_sdk/observability.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'platform_sdk/observability/langfuse'
+
+module PlatformSdk
+  module Observability
+  end
+end

data/lib/platform_sdk/version.rb

@@ -2,8 +2,8 @@
 
 module PlatformSdk
   MAJOR = 3
-  MINOR = 27
-  PATCH = 5
+  MINOR = 28
+  PATCH = 0
 
   VERSION = "#{PlatformSdk::MAJOR}.#{PlatformSdk::MINOR}.#{PlatformSdk::PATCH}"
 end

data/lib/platform_sdk.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative 'platform_sdk/version'
+require 'platform_sdk/observability'
 require 'platform_sdk/one_roster'
 require 'platform_sdk/identity'
 require 'platform_sdk/power_school'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: strongmind-platform-sdk
 version: !ruby/object:Gem::Version
-  version: 3.27.5
+  version: 3.28.0
 platform: ruby
 authors:
 - Platform Team
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-04-15 00:00:00.000000000 Z
+date: 2026-05-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -184,6 +184,34 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-sdk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-exporter-otlp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.27'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.27'
 - !ruby/object:Gem::Dependency
   name: asset_sync
   requirement: !ruby/object:Gem::Requirement
@@ -286,6 +314,15 @@ files:
 - lib/platform_sdk/llm_gateway/client.rb
 - lib/platform_sdk/logging.rb
 - lib/platform_sdk/logging/pii_formatter.rb
+- lib/platform_sdk/observability.rb
+- lib/platform_sdk/observability/langfuse.rb
+- lib/platform_sdk/observability/langfuse/coercions.rb
+- lib/platform_sdk/observability/langfuse/configuration.rb
+- lib/platform_sdk/observability/langfuse/null_span_exporter.rb
+- lib/platform_sdk/observability/langfuse/recorder.rb
+- lib/platform_sdk/observability/langfuse/sidekiq_lifecycle.rb
+- lib/platform_sdk/observability/langfuse/spec_support.rb
+- lib/platform_sdk/observability/langfuse/traceable.rb
 - lib/platform_sdk/one_roster.rb
 - lib/platform_sdk/one_roster/client.rb
 - lib/platform_sdk/ops_genie.rb