langfuse-rb 0.6.0 → 0.8.0

data/lib/langfuse.rb

@@ -44,12 +44,15 @@ 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"
 require_relative "langfuse/propagation"
 require_relative "langfuse/span_processor"
 require_relative "langfuse/observations"
+require_relative "langfuse/trace_id"
 require_relative "langfuse/score_client"
 require_relative "langfuse/text_prompt_client"
 require_relative "langfuse/chat_prompt_client"
@@ -90,10 +93,6 @@ module Langfuse
     #   end
     def configure
       yield(configuration)
-
-      # Auto-initialize OpenTelemetry
-      OtelSetup.setup(configuration)
-
       configuration
     end
 
@@ -104,6 +103,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
@@ -296,6 +317,24 @@ module Langfuse
       client.flush_scores if @client
     end
 
+    # Generate a trace ID (deterministic when seeded, random otherwise).
+    #
+    # Use this to correlate Langfuse traces with external identifiers. The
+    # same seed always produces the same trace ID across the Ruby, Python,
+    # and JS SDKs (SHA-256 of the seed, first 16 bytes, as 32 hex chars).
+    #
+    # @note Avoid PII or secrets as seeds. See {TraceId.create} for details.
+    # @param seed [String, nil] Optional deterministic seed
+    # @return [String] 32-character lowercase hex trace ID
+    # @raise [ArgumentError] if seed is not nil and not a String
+    #
+    # @example
+    #   trace_id = Langfuse.create_trace_id(seed: "order-12345")
+    #   Langfuse.observe("process", trace_id: trace_id) { |span| ... }
+    def create_trace_id(seed: nil)
+      TraceId.create(seed: seed)
+    end
+
     # Reset global configuration and client (useful for testing)
     #
     # @return [void]
@@ -304,10 +343,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)
@@ -319,11 +362,14 @@ module Langfuse
     # @param name [String] Descriptive name for the observation
     # @param attrs [Hash, Types::SpanAttributes, Types::GenerationAttributes, nil] Observation attributes
     # @param as_type [Symbol, String] Observation type (:span, :generation, :event, etc.)
+    # @param trace_id [String, nil] Optional 32-char lowercase hex trace ID to attach the observation to.
+    #   Mutually exclusive with `parent_span_context`. Use {Langfuse.create_trace_id} to generate one.
     # @param parent_span_context [OpenTelemetry::Trace::SpanContext, nil] Parent span context for child observations
     # @param start_time [Time, Integer, nil] Optional start time (Time object or Unix timestamp in nanoseconds)
     # @param skip_validation [Boolean] Skip validation (for internal use). Defaults to false.
     # @return [BaseObservation] The observation wrapper (Span, Generation, or Event)
-    # @raise [ArgumentError] if an invalid observation type is provided
+    # @raise [ArgumentError] if an invalid observation type is provided, an invalid `trace_id` is given,
+    #   or both `trace_id` and `parent_span_context` are provided
     #
     # @example Create root span
     #   span = Langfuse.start_observation("root-operation", { input: {...} })
@@ -332,14 +378,16 @@ module Langfuse
     #   child = Langfuse.start_observation("llm-call", { model: "gpt-4" },
     #                                       as_type: :generation,
     #                                       parent_span_context: parent.otel_span.context)
-    def start_observation(name, attrs = {}, as_type: :span, parent_span_context: nil, start_time: nil,
-                          skip_validation: false)
+    #
+    # @example Attach to a deterministic trace ID
+    #   trace_id = Langfuse.create_trace_id(seed: "order-123")
+    #   root = Langfuse.start_observation("process-order", trace_id: trace_id)
+    # rubocop:disable Metrics/ParameterLists
+    def start_observation(name, attrs = {}, as_type: :span, trace_id: nil, parent_span_context: nil,
+                          start_time: nil, skip_validation: false)
+      parent_span_context = resolve_trace_context(trace_id, parent_span_context)
       type_str = as_type.to_s
-
-      unless skip_validation || valid_observation_type?(as_type)
-        valid_types = OBSERVATION_TYPES.values.sort.join(", ")
-        raise ArgumentError, "Invalid observation type: #{type_str}. Valid types: #{valid_types}"
-      end
+      validate_observation_type!(as_type, type_str) unless skip_validation
 
       otel_tracer = otel_tracer()
       otel_span = create_otel_span(
@@ -348,32 +396,27 @@ module Langfuse
         parent_span_context: parent_span_context,
         otel_tracer: otel_tracer
       )
+      apply_observation_attributes(otel_span, type_str, attrs)
 
-      # Serialize attributes
-      # Only set attributes if span is still recording (should always be true here, but guard for safety)
-      if otel_span.recording?
-        otel_attrs = OtelAttributes.create_observation_attributes(type_str, attrs.to_h, mask: configuration.mask)
-        otel_attrs.each { |key, value| otel_span.set_attribute(key, value) }
-      end
-
-      # Wrap in appropriate class (attributes already set on span above — pass nil to avoid double-masking)
       observation = wrap_otel_span(otel_span, type_str, otel_tracer)
-
       # Events auto-end immediately when created
       observation.end if type_str == OBSERVATION_TYPES[:event]
-
       observation
     end
+    # rubocop:enable Metrics/ParameterLists
 
     # User-facing convenience method for creating root observations
     #
     # @param name [String] Descriptive name for the observation
     # @param attrs [Hash] Observation attributes (optional positional or keyword)
     # @param as_type [Symbol, String] Observation type (:span, :generation, :event, etc.)
+    # @param trace_id [String, nil] Optional 32-char lowercase hex trace ID to attach the observation to.
+    #   Use {Langfuse.create_trace_id} to generate one. Forwarded to {.start_observation}.
     # @param kwargs [Hash] Additional keyword arguments merged into observation attributes (e.g., input:, output:, metadata:)
     # @yield [observation] Optional block that receives the observation object
     # @yieldparam observation [BaseObservation] The observation object
     # @return [BaseObservation, Object] The observation (or block return value if block given)
+    # @raise [ArgumentError] if an invalid `trace_id` is provided
     #
     # @example Block-based API (auto-ends)
     #   Langfuse.observe("operation") do |obs|
@@ -385,28 +428,12 @@ module Langfuse
     #   obs = Langfuse.observe("operation", input: { data: "test" })
     #   obs.update(output: { result: "success" })
     #   obs.end
-    def observe(name, attrs = {}, as_type: :span, **kwargs, &block)
-      # Merge positional attrs and keyword kwargs
+    def observe(name, attrs = {}, as_type: :span, trace_id: nil, **kwargs, &block)
       merged_attrs = attrs.to_h.merge(kwargs)
-      observation = start_observation(name, merged_attrs, as_type: as_type)
-
-      if block
-        # Block-based API: auto-ends when block completes
-        # Set context and execute block
-        current_context = OpenTelemetry::Context.current
-        result = OpenTelemetry::Context.with_current(
-          OpenTelemetry::Trace.context_with_span(observation.otel_span, parent_context: current_context)
-        ) do
-          block.call(observation)
-        end
-        # Only end if not already ended (events auto-end in start_observation)
-        observation.end unless as_type.to_s == OBSERVATION_TYPES[:event]
-        result
-      else
-        # Stateful API - return observation
-        # Events already auto-ended in start_observation
-        observation
-      end
+      observation = start_observation(name, merged_attrs, as_type: as_type, trace_id: trace_id)
+      return observation unless block
+
+      observation.send(:run_in_context, &block)
     end
 
     # Registry mapping observation type strings to their wrapper classes
@@ -425,6 +452,31 @@ module Langfuse
 
     private
 
+    # @api private
+    def resolve_trace_context(trace_id, parent_span_context)
+      return parent_span_context unless trace_id
+      raise ArgumentError, "Cannot specify both trace_id and parent_span_context" if parent_span_context
+
+      TraceId.send(:to_span_context, trace_id)
+    end
+
+    # @api private
+    def validate_observation_type!(as_type, type_str)
+      return if valid_observation_type?(as_type)
+
+      valid_types = OBSERVATION_TYPES.values.sort.join(", ")
+      raise ArgumentError, "Invalid observation type: #{type_str}. Valid types: #{valid_types}"
+    end
+
+    # @api private
+    def apply_observation_attributes(otel_span, type_str, attrs)
+      # Guard against ended spans — should always be recording here, but safe.
+      return unless otel_span.recording?
+
+      otel_attrs = OtelAttributes.create_observation_attributes(type_str, attrs.to_h, mask: configuration.mask)
+      otel_attrs.each { |key, value| otel_span.set_attribute(key, value) }
+    end
+
     # Validates that an observation type is valid
     #
     # Checks if the provided type (symbol or string) matches a valid observation type
@@ -450,7 +502,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)
@@ -486,6 +541,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,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: langfuse-rb
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.8.0
 platform: ruby
 authors:
 - SimplePractice
+autorequire:
 bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-04-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -178,11 +179,14 @@ files:
 - lib/langfuse/prompt_cache.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
 - lib/langfuse/timestamp_parser.rb
+- lib/langfuse/trace_id.rb
 - lib/langfuse/traced_execution.rb
 - lib/langfuse/types.rb
 - lib/langfuse/version.rb
@@ -194,6 +198,7 @@ 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
@@ -208,7 +213,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 3.4.1
+signing_key:
 specification_version: 4
 summary: Ruby SDK for Langfuse - LLM observability and prompt management
 test_files: []