langfuse-rb 0.7.0 → 0.9.0

data/lib/langfuse/span_processor.rb

@@ -3,22 +3,26 @@
 require "opentelemetry/sdk"
 
 module Langfuse
-  # Span processor that applies default and propagated trace attributes on new spans.
-  #
-  # On span start, this processor first applies configured trace defaults
-  # (environment/release), then overlays attributes propagated in OpenTelemetry
-  # context (user/session/metadata/tags/version). This ensures consistent
-  # trace dimensions while still honoring per-request propagation.
+  # Batch span processor that owns Langfuse's enrichment and export filtering.
   #
   # @api private
-  class SpanProcessor < OpenTelemetry::SDK::Trace::SpanProcessor
-    # @param config [Langfuse::Config, nil] SDK configuration used to build trace defaults
-    def initialize(config: Langfuse.configuration)
+  class SpanProcessor < OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor
+    # @param config [Langfuse::Config] SDK configuration used for defaults and filtering
+    # @param exporter [#export, #force_flush, #shutdown] Span exporter used by the batch processor
+    def initialize(config:, exporter:)
+      @logger = config.logger
       @default_trace_attributes = build_default_trace_attributes(config).freeze
-      super()
+      @should_export_span = config.should_export_span || Langfuse.method(:default_export_span?)
+
+      super(
+        exporter,
+        max_queue_size: config.batch_size * 2,
+        schedule_delay: schedule_delay_for(config),
+        max_export_batch_size: config.batch_size
+      )
     end
 
-    # Called when a span starts
+    # Apply Langfuse trace defaults and propagated attributes before a span records work.
     #
     # @param span [OpenTelemetry::SDK::Trace::Span] The span that started
     # @param parent_context [OpenTelemetry::Context] The parent context
@@ -30,41 +34,28 @@ module Langfuse
       apply_attributes(span, propagated_attributes(parent_context))
     end
 
-    # Called when a span ends
+    # Drop spans when the export filter rejects them or raises.
     #
     # @param span [OpenTelemetry::SDK::Trace::Span] The span that ended
     # @return [void]
     def on_finish(span)
-      # No-op - we don't need to do anything when spans finish
-    end
+      return unless should_export_span?(span)
 
-    # Shutdown the processor
-    #
-    # @param timeout [Integer, nil] Timeout in seconds (unused for this processor)
-    # @return [Integer] Always returns 0 (no timeout needed for no-op)
-    def shutdown(timeout: nil)
-      # No-op - nothing to clean up
-      # Return 0 to match OpenTelemetry SDK expectation (it finds max timeout from processors)
-      _ = timeout # Suppress unused argument warning
-      0
-    end
-
-    # Force flush (no-op for this processor)
-    #
-    # @param timeout [Integer, nil] Timeout in seconds (unused for this processor)
-    # @return [Integer] Always returns 0 (no timeout needed for no-op)
-    def force_flush(timeout: nil)
-      # No-op - nothing to flush
-      # Return 0 to match OpenTelemetry SDK expectation (it finds max timeout from processors)
-      _ = timeout # Suppress unused argument warning
-      0
+      super
     end
 
     private
 
-    def build_default_trace_attributes(config)
-      return {} unless config
+    # Sync mode relies on explicit `force_flush` calls, so keep the background flush
+    # interval long enough that it rarely fires on its own.
+    SYNC_SCHEDULE_DELAY_MS = 60_000
+    private_constant :SYNC_SCHEDULE_DELAY_MS
+
+    def schedule_delay_for(config)
+      config.tracing_async ? config.flush_interval * 1000 : SYNC_SCHEDULE_DELAY_MS
+    end
 
+    def build_default_trace_attributes(config)
       OtelAttributes.create_trace_attributes(
         { environment: config.environment, release: config.release }
       )
@@ -79,5 +70,15 @@ module Langfuse
     def apply_attributes(span, attributes)
       attributes.each { |key, value| span.set_attribute(key, value) }
     end
+
+    def should_export_span?(span)
+      @should_export_span.call(span)
+    rescue StandardError => e
+      @logger.error(
+        "Langfuse tracing dropped span '#{span.name}' because should_export_span raised: " \
+        "#{e.class}: #{e.message}"
+      )
+      false
+    end
   end
 end

data/lib/langfuse/text_prompt_client.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require "mustache"
+require_relative "prompt_renderer"
 
 module Langfuse
   # Text prompt client for compiling text prompts with variable substitution
@@ -38,11 +38,21 @@ module Langfuse
     # @return [String] Raw prompt template string
     attr_reader :prompt
 
+    # @return [String, nil] Optional commit message for this prompt version
+    attr_reader :commit_message
+
+    # @return [Hash, nil] Optional dependency resolution graph for composed prompts
+    attr_reader :resolution_graph
+
+    # @return [Boolean] Whether this client uses caller-provided fallback content
+    attr_reader :is_fallback
+
     # Initialize a new text prompt client
     #
     # @param prompt_data [Hash] The prompt data from the API
+    # @param is_fallback [Boolean] Whether this client wraps caller-provided fallback content
     # @raise [ArgumentError] if prompt data is invalid
-    def initialize(prompt_data)
+    def initialize(prompt_data, is_fallback: false)
       validate_prompt_data!(prompt_data)
 
       @name = prompt_data["name"]
@@ -51,6 +61,14 @@ module Langfuse
       @labels = prompt_data["labels"] || []
       @tags = prompt_data["tags"] || []
       @config = prompt_data["config"] || {}
+      @commit_message = prompt_data["commitMessage"]
+      @resolution_graph = prompt_data["resolutionGraph"]
+      @is_fallback = is_fallback
+    end
+
+    # @return [String] Prompt type ("text")
+    def type
+      "text"
     end
 
     # Compile the prompt with variable substitution
@@ -64,7 +82,7 @@ module Langfuse
     def compile(**kwargs)
       return prompt if kwargs.empty?
 
-      Mustache.render(prompt, kwargs)
+      PromptRenderer.render(prompt, kwargs)
     end
 
     private

data/lib/langfuse/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Langfuse
-  VERSION = "0.7.0"
+  VERSION = "0.9.0"
 end

data/lib/langfuse.rb

@@ -44,6 +44,8 @@ require_relative "langfuse/prompt_cache"
 require_relative "langfuse/rails_cache_adapter"
 require_relative "langfuse/cache_warmer"
 require_relative "langfuse/api_client"
+require_relative "langfuse/span_filter"
+require_relative "langfuse/sampling"
 require_relative "langfuse/otel_setup"
 require_relative "langfuse/masking"
 require_relative "langfuse/otel_attributes"
@@ -52,6 +54,7 @@ require_relative "langfuse/span_processor"
 require_relative "langfuse/observations"
 require_relative "langfuse/trace_id"
 require_relative "langfuse/score_client"
+require_relative "langfuse/prompt_renderer"
 require_relative "langfuse/text_prompt_client"
 require_relative "langfuse/chat_prompt_client"
 require_relative "langfuse/timestamp_parser"
@@ -91,10 +94,6 @@ module Langfuse
     #   end
     def configure
       yield(configuration)
-
-      # Auto-initialize OpenTelemetry
-      OtelSetup.setup(configuration)
-
       configuration
     end
 
@@ -105,6 +104,28 @@ module Langfuse
       @client ||= Client.new(configuration)
     end
 
+    # Return Langfuse's internal tracer provider for explicit global OpenTelemetry installation.
+    #
+    # @return [OpenTelemetry::SDK::Trace::TracerProvider]
+    # @raise [ConfigurationError] if tracing is not fully configured
+    #
+    # @example
+    #   Langfuse.configure do |config|
+    #     config.public_key = ENV["LANGFUSE_PUBLIC_KEY"]
+    #     config.secret_key = ENV["LANGFUSE_SECRET_KEY"]
+    #   end
+    #
+    #   OpenTelemetry.tracer_provider = Langfuse.tracer_provider
+    def tracer_provider
+      unless tracing_config_ready?
+        raise ConfigurationError,
+              "Langfuse tracing is disabled until public_key, secret_key, and base_url are configured."
+      end
+
+      OtelSetup.setup(configuration) unless OtelSetup.initialized?
+      OtelSetup.tracer_provider
+    end
+
     # Shutdown Langfuse and flush any pending traces and scores
     #
     # Call this when shutting down your application to ensure
@@ -323,10 +344,14 @@ module Langfuse
       OtelSetup.shutdown(timeout: 5) if OtelSetup.initialized?
       @configuration = nil
       @client = nil
+      @noop_tracer = nil
+      @tracing_disabled_warning_emitted = false
     rescue StandardError
       # Ignore shutdown errors during reset (e.g., in tests)
       @configuration = nil
       @client = nil
+      @noop_tracer = nil
+      @tracing_disabled_warning_emitted = false
     end
 
     # Creates a new observation (root or child)
@@ -478,7 +503,10 @@ module Langfuse
     #
     # @return [OpenTelemetry::SDK::Trace::Tracer] The OTel tracer
     def otel_tracer
-      OpenTelemetry.tracer_provider.tracer("langfuse-rb", Langfuse::VERSION)
+      return tracer_provider.tracer(LANGFUSE_TRACER_NAME, Langfuse::VERSION) if setup_tracing_if_ready
+
+      warn_tracing_disabled_once
+      noop_tracer
     end
 
     # Creates an OpenTelemetry span (root or child)
@@ -514,6 +542,47 @@ module Langfuse
       observation_class = OBSERVATION_TYPE_REGISTRY[type_str] || Span
       observation_class.new(otel_span, otel_tracer, attributes: attributes)
     end
+
+    # rubocop:disable Naming/PredicateMethod
+    def setup_tracing_if_ready
+      return true if OtelSetup.initialized?
+      return false unless tracing_config_ready?
+
+      OtelSetup.setup(configuration)
+      true
+    end
+    # rubocop:enable Naming/PredicateMethod
+
+    def tracing_config_ready?
+      configured?(configuration.public_key) &&
+        configured?(configuration.secret_key) &&
+        configured?(configuration.base_url)
+    end
+
+    def configured?(value)
+      !value.nil? && !value.empty?
+    end
+
+    def warn_tracing_disabled_once
+      return if @tracing_disabled_warning_emitted
+
+      tracing_warning_mutex.synchronize do
+        return if @tracing_disabled_warning_emitted
+
+        configuration.logger.warn(
+          "Langfuse tracing is disabled until public_key, secret_key, and base_url are configured."
+        )
+        @tracing_disabled_warning_emitted = true
+      end
+    end
+
+    def tracing_warning_mutex
+      @tracing_warning_mutex ||= Mutex.new
+    end
+
+    def noop_tracer
+      @noop_tracer ||= OpenTelemetry::Trace::TracerProvider.new.tracer(LANGFUSE_TRACER_NAME, Langfuse::VERSION)
+    end
   end
   # rubocop:enable Metrics/ClassLength
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: langfuse-rb
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.9.0
 platform: ruby
 authors:
 - SimplePractice
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-14 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -177,9 +176,12 @@ files:
 - lib/langfuse/otel_attributes.rb
 - lib/langfuse/otel_setup.rb
 - lib/langfuse/prompt_cache.rb
+- lib/langfuse/prompt_renderer.rb
 - lib/langfuse/propagation.rb
 - lib/langfuse/rails_cache_adapter.rb
+- lib/langfuse/sampling.rb
 - lib/langfuse/score_client.rb
+- lib/langfuse/span_filter.rb
 - lib/langfuse/span_processor.rb
 - lib/langfuse/stale_while_revalidate.rb
 - lib/langfuse/text_prompt_client.rb
@@ -196,7 +198,6 @@ metadata:
   source_code_uri: https://github.com/simplepractice/langfuse-rb
   changelog_uri: https://github.com/simplepractice/langfuse-rb/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -211,8 +212,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.1
-signing_key:
+rubygems_version: 4.0.8
 specification_version: 4
 summary: Ruby SDK for Langfuse - LLM observability and prompt management
 test_files: []