strongmind-platform-sdk 3.27.5 → 3.29.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 10d6f1421ebf925d2fabec136b4afc8c4c98e93007858365f5232f2345e8082f
-  data.tar.gz: e8b7b866bc67d307abde2fbaf2b8c1c6c2c3e55dddfc95bd67e5df197da9e1cb
+  metadata.gz: 799fe97b77fb105775c8b846e6916380be6845209a5157633d832186ae81bd25
+  data.tar.gz: ee0bbab328e6e27bcf72a5e634535f9ed0ab91bb57976b94a9c1fd24fac268f1
 SHA512:
-  metadata.gz: cc9a23c8b4d71f2aa8effcd0e0c62e7e3eed2b2b09c03b0313e1eb4ec71f6fc6d1a19b1cddee0829265d265ce9b03115f7752bae073e7157bf05e306e577f927
-  data.tar.gz: 766fea6294b2dde18c78d008741a8e80d0bf9610b9eb476422cdd0ccde51e367a2ba51da952358a752483071e35005f92988f184c529bb75d8f95072b61c7f9b
+  metadata.gz: 7080031758db9d9bd0894dcc2b8054df0377f1bc33a6da0ba987f7be9888c343cb0e2feb83d9d811c95114e1891ff4a62c1cde7d445333b35a5bcbf6a2b4007a
+  data.tar.gz: c8e8bb3e06b1b6808cbc02c50664921dd6850520050cf5e0191a4bc01b3e2e4357bb8d0fa4c4edd14a95db1134d351a5ca3fbd1105243eb0cfd317ac85955f80

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 ## [Unreleased]
 
+## [3.29.0] - 2026-05-12
+
+- Add `PlatformSdk::Observability::Langfuse::NotificationSubscriber` — subscribes to the `llm_call.platform_sdk` `ActiveSupport::Notifications` event and forwards to `Recorder.record_generation`. Apps can instrument LLM calls without coupling to a host concern; adding a second observability backend later is one more `subscribe` call.
+- Auto-installed by `Langfuse.configure` (opt out with `autosubscribe: false`).
+- Payload contract: `name`, `model`, `input`, `output`, `usage: { input_tokens:, output_tokens: }`, `prompt: { name:, version: }`, `provider`, `error:` (optional Exception — when set, recorded as a failure observation).
+- Add `PlatformSdk::Observability::Langfuse::TraceSummarizable` mixin — template method for jobs to record a meaningful summary on the trace's Output column via `record_langfuse_trace_output` + `langfuse_trace_output_attributes`.
+
+## [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.29.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.2)
       base64 (>= 0.2, < 0.4)
       fog-core (~> 2.6)
       fog-json (~> 1.1)
@@ -160,16 +164,27 @@ GEM
       excon (~> 1.0)
       formatador (>= 0.2, < 2.0)
       mime-types
-    fog-json (1.2.0)
+    fog-json (1.3.0)
       fog-core
       multi_json (~> 1.10)
     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.0414)
     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.4)
       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/notification_subscriber.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require 'active_support/notifications'
+
+module PlatformSdk
+  module Observability
+    module Langfuse
+      # Subscribes to `llm_call.platform_sdk` ActiveSupport::Notifications events
+      # and forwards them to `Recorder.record_generation`.
+      #
+      # Apps instrument their LLM calls with the convention:
+      #
+      #   ActiveSupport::Notifications.instrument(
+      #     'llm_call.platform_sdk',
+      #     name: 'chat_response',
+      #     model: 'claude-3-5-sonnet',
+      #     input: prompt_messages,
+      #     output: response_text,
+      #     usage: { input_tokens: 120, output_tokens: 84 }
+      #   ) { call_the_llm }
+      #
+      # Inside the block, the payload Hash can be mutated to enrich it with
+      # values only known after the call completes. (`Instrumenter#instrument`
+      # passes the same Hash to the block and reads it again after `yield`;
+      # this isn't documented in the Rails Guide but is relied on across
+      # the ecosystem.)
+      #
+      # Two error-passing paths:
+      #
+      # 1. **Direct `instrument`-with-a-block callers** that let the block
+      #    raise: Rails populates `:exception_object` automatically and this
+      #    subscriber records a failure observation from it.
+      #
+      # 2. **Caller-rescues-and-rethrows** patterns (e.g. `RubyLLMAdapter.fire`,
+      #    course-builder's `LlmErrorHandling#with_llm_error_handling`): set
+      #    `payload[:error] = exception` before firing. Rails only auto-sets
+      #    `:exception_object` for the block form, so adapter-style callers
+      #    that `instrument` without a block need to populate `:error`.
+      #
+      # `format_output` prefers `:error` when both are set so the
+      # caller-provided value wins.
+      #
+      # Idempotent: `install!` is safe to call repeatedly — only the first
+      # call registers a subscriber.
+      module NotificationSubscriber
+        EVENT_NAME = LLM_CALL_EVENT
+        DEFAULT_NAME = 'llm_call'
+
+        @installed = false
+        @subscriber = nil
+        @mutex = Mutex.new
+
+        class << self
+          def install!
+            @mutex.synchronize do
+              return if @installed
+
+              @subscriber = ActiveSupport::Notifications.subscribe(EVENT_NAME) do |_name, _start, _finish, _id, payload|
+                handle_event(payload)
+              end
+              @installed = true
+            end
+          end
+
+          def reset!
+            @mutex.synchronize do
+              ActiveSupport::Notifications.unsubscribe(@subscriber) if @subscriber
+              @subscriber = nil
+              @installed = false
+            end
+          end
+
+          def installed?
+            @installed
+          end
+
+          private
+
+          def handle_event(payload)
+            payload ||= {}
+            Langfuse.record_generation(**build_kwargs(payload))
+          rescue StandardError => e
+            OpenTelemetry.handle_error(
+              message: "Langfuse notification subscriber failed: #{e.class}: #{e.message[0, 200]}"
+            )
+          end
+
+          def build_kwargs(payload)
+            warn_if_misshaped_prompt(payload[:prompt])
+            prompt = payload[:prompt].is_a?(Hash) ? payload[:prompt] : {}
+            {
+              name: payload[:name] || DEFAULT_NAME, model: payload[:model],
+              input: payload[:input], output: format_output(payload),
+              usage: payload[:usage],
+              prompt_name: prompt[:name], prompt_version: prompt[:version],
+              provider: payload[:provider]
+            }
+          end
+
+          # Surfaces a non-Hash `:prompt` value through OpenTelemetry so
+          # callers see the misconfiguration in development instead of
+          # silently losing prompt tracing. A plain string like
+          # `prompt: 'my_prompt_name'` (easy to confuse with `name:`) would
+          # otherwise fall back to `{}` with no feedback.
+          def warn_if_misshaped_prompt(raw_prompt)
+            return if raw_prompt.nil? || raw_prompt.is_a?(Hash)
+
+            OpenTelemetry.handle_error(
+              message: 'Langfuse NotificationSubscriber: :prompt must be a Hash with :name and :version ' \
+                       "(got #{raw_prompt.class}); prompt info will not be recorded"
+            )
+          end
+
+          # `:error` (caller-set) takes precedence over `:exception_object`
+          # (Rails-set when an instrument block raises) so a caller that
+          # rescues and re-fires has the final say. Cap the formatted
+          # message so a multi-MB upstream error body can't be forwarded
+          # verbatim to the telemetry sink.
+          def format_output(payload)
+            error = payload[:error] || payload[:exception_object]
+            error ? "[#{error.class}] #{error.message.to_s[0, 500]}" : payload[:output]
+          end
+        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/ruby_llm_adapter.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require 'active_support/notifications'
+
+module PlatformSdk
+  module Observability
+    module Langfuse
+      # Fires `llm_call.platform_sdk` ActiveSupport::Notifications events with
+      # a payload extracted from a RubyConversations / RubyLLM-shaped chat.
+      #
+      # Apps that use the RubyLLM (or RubyConversations) gem call this from
+      # any LLM call site to get cost, token, model, input, and output
+      # captured in Langfuse without having to know the OTel attribute keys:
+      #
+      #   PlatformSdk::Observability::Langfuse::RubyLLMAdapter.fire(
+      #     conversation: conversation_manager,
+      #     context: 'chat_response'
+      #   )
+      #
+      # The adapter is RubyLLM-aware but does not require the RubyLLM gem at
+      # load time — `RubyLLM::Content` references are guarded by `defined?`,
+      # so apps that don't use RubyLLM can load the SDK without paying for
+      # this code path.
+      #
+      # Dedup: nested or repeated calls that share the same `chat.messages.last`
+      # object are skipped, so a single LLM response can't double-fire when
+      # multiple layers of error-handling each wrap the same yield. The
+      # dedup state is registered via `Langfuse.track_thread_local`, so
+      # `Traceable`-wrapped Sidekiq jobs get it cleared in their ensure
+      # block. Callers outside `Traceable` (Rails controllers, long-lived
+      # Puma threads) should invoke
+      # `Langfuse.clear_tracked_thread_locals!` at their request/operation
+      # boundary to avoid dedup state leaking between unrelated calls.
+      module RubyLLMAdapter
+        MAX_PROMPT_MESSAGES = 30
+        THREAD_LOCAL_KEY = :platform_sdk_langfuse_last_message_id
+
+        class << self
+          # Fire an `llm_call.platform_sdk` notification for a single LLM call.
+          # Accepts either a RubyConversations conversation (preferred — the
+          # adapter reads `conversation.chat` and `conversation.model_identifier`)
+          # or a raw RubyLLM::Chat. Returns nil — never raises.
+          def fire(context:, conversation: nil, chat: nil, error: nil)
+            payload = build_payload(context:, conversation:, chat:, error:)
+            return unless payload
+
+            ActiveSupport::Notifications.instrument(LLM_CALL_EVENT, payload)
+          rescue StandardError => e
+            OpenTelemetry.handle_error(
+              message: "RubyLLMAdapter.fire failed: #{e.class}: #{e.message[0, 200]}"
+            )
+            nil
+          end
+
+          private
+
+          # Build the notification payload from a RubyLLM-shaped conversation
+          # or chat. Returns nil when there's nothing to record (e.g. empty
+          # chat, dup of the last recorded response, or Langfuse disabled).
+          # Internal — exercise via `fire` and span assertions; the Hash
+          # shape is not a stable public contract.
+          def build_payload(context:, conversation: nil, chat: nil, error: nil)
+            return nil unless Langfuse.enabled?
+
+            chat ||= conversation&.chat
+            last = chat&.messages&.last
+            return nil if last.nil? && error.nil?
+            return nil if duplicate_llm_response?(last)
+
+            track_llm_response(last) if last
+
+            {
+              name: context || 'llm_call',
+              model: last&.model_id || conversation&.model_identifier,
+              input: chat ? serialize_input(chat) : nil,
+              output: last&.content,
+              usage: { input_tokens: last&.input_tokens, output_tokens: last&.output_tokens },
+              error:
+            }
+          end
+
+          def duplicate_llm_response?(last)
+            return false if last.nil?
+
+            Thread.current[THREAD_LOCAL_KEY] == last.object_id
+          end
+
+          def track_llm_response(last)
+            Langfuse.track_thread_local(THREAD_LOCAL_KEY)
+            Thread.current[THREAD_LOCAL_KEY] = last.object_id
+          end
+
+          def serialize_input(chat)
+            messages = chat&.messages
+            return nil if messages.nil? || messages.empty?
+
+            # Strip the assistant's response (last message) so input represents what was sent TO the LLM.
+            # Cap to the most-recent N messages to bound allocation on long tool-heavy conversations.
+            # `last(n)` returns a fresh array, so we can pop in place — one allocation instead of two.
+            prompt_messages = messages.last(MAX_PROMPT_MESSAGES + 1).tap(&:pop)
+            prompt_messages.map { |m| { role: m.role, content: extract_message_content(m) } }
+          end
+
+          def extract_message_content(message)
+            content = message.content
+            return content.to_s unless ruby_llm_content?(content)
+
+            content.text.to_s
+          end
+
+          def ruby_llm_content?(content)
+            defined?(::RubyLLM::Content) && content.is_a?(::RubyLLM::Content)
+          end
+        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,94 @@
+# 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
+              # Drain the BatchSpanProcessor before clearing — otherwise spans
+              # emitted by the previous example sit in the processor's queue
+              # and flush into the next example's view, producing
+              # order-dependent assertion failures.
+              PlatformSdk::Observability::Langfuse.configuration&.tracer_provider&.force_flush(timeout: 5)
+              PlatformSdk::Observability::Langfuse::SpecSupport.exporter&.clear
+              PlatformSdk::Observability::Langfuse.clear_tracked_thread_locals!
+            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/trace_summarizable.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module PlatformSdk
+  module Observability
+    module Langfuse
+      # Mix into Sidekiq jobs (or anything running under a `Traceable` span)
+      # to record a meaningful summary of the work in the trace's Output
+      # column in Langfuse.
+      #
+      # Including classes implement `#langfuse_trace_output_attributes`
+      # returning a Hash; call `record_langfuse_trace_output` once the
+      # relevant instance state is settled (typically at the end of perform).
+      #
+      #   class GenerateThingJob
+      #     include Sidekiq::Job
+      #     include PlatformSdk::Observability::Langfuse::Traceable
+      #     include PlatformSdk::Observability::Langfuse::TraceSummarizable
+      #
+      #     def perform(args)
+      #       @thing = build_thing(args)
+      #       record_langfuse_trace_output
+      #     end
+      #
+      #     private
+      #
+      #     def langfuse_trace_output_attributes
+      #       { thing_id: @thing&.id, status: @thing&.status }
+      #     end
+      #   end
+      module TraceSummarizable
+        private
+
+        def record_langfuse_trace_output
+          PlatformSdk::Observability::Langfuse.set_trace_output(langfuse_trace_output_attributes)
+        end
+
+        def langfuse_trace_output_attributes
+          raise NotImplementedError, "#{self.class} must implement #langfuse_trace_output_attributes"
+        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,138 @@
+# frozen_string_literal: true
+
+# Constants declared up-front so the files we require below can reference
+# them at load time without a circular dependency.
+module PlatformSdk
+  module Observability
+    module Langfuse
+      # ActiveSupport::Notifications event name for LLM calls. Owned by the
+      # `Langfuse` namespace (rather than `NotificationSubscriber`) so the
+      # adapter can emit without requiring the subscriber to be loaded.
+      LLM_CALL_EVENT = 'llm_call.platform_sdk'
+
+      OWNED_THREAD_LOCALS_KEY = :platform_sdk_langfuse_owned_thread_locals
+    end
+  end
+end
+
+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/trace_summarizable'
+require 'platform_sdk/observability/langfuse/traceable'
+require 'platform_sdk/observability/langfuse/sidekiq_lifecycle'
+require 'platform_sdk/observability/langfuse/notification_subscriber'
+require 'platform_sdk/observability/langfuse/ruby_llm_adapter'
+
+module PlatformSdk
+  module Observability
+    module Langfuse
+      class Error < StandardError; end
+      class ConfigurationError < Error; end
+
+      class << self
+        attr_reader :configuration
+
+        def configure(app_name:, environment: nil, prompt_label: nil, exporter: nil, autosubscribe: true)
+          @configuration&.force_flush_and_shutdown
+          @configuration = Configuration.new(app_name:, environment:, prompt_label:, exporter:)
+          if @configuration.enabled?
+            SidekiqLifecycle.install!
+            NotificationSubscriber.install! if autosubscribe
+          end
+          @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!
+          NotificationSubscriber.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 = 29
+  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.29.0
 platform: ruby
 authors:
 - Platform Team
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-04-15 00:00:00.000000000 Z
+date: 2026-05-13 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,18 @@ 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/notification_subscriber.rb
+- lib/platform_sdk/observability/langfuse/null_span_exporter.rb
+- lib/platform_sdk/observability/langfuse/recorder.rb
+- lib/platform_sdk/observability/langfuse/ruby_llm_adapter.rb
+- lib/platform_sdk/observability/langfuse/sidekiq_lifecycle.rb
+- lib/platform_sdk/observability/langfuse/spec_support.rb
+- lib/platform_sdk/observability/langfuse/trace_summarizable.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