langfuse-rb 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e320f34169f77bea79aa259867b62aa7164d77a693e864cb1d03cb86d0d188a2
-  data.tar.gz: 59a40715dbb46604f6287b46b80c34e1524f7279fed261b7795d781854df987f
+  metadata.gz: 2bf0fdf8f1b31f237397c90d8db3fc61c40bc8a69e20111a949aa0bdffc8dd3e
+  data.tar.gz: b6b83329218d23b3ebd53562a4eb5bb1cd01179f07fdbf5d90b2b1c97fc192ef
 SHA512:
-  metadata.gz: d18c3cb807c759c20f72a4259ccfb0502f1800b671aadcf14ea24f88e0be227ed200677f1cbabef22e467c06f2f1ce5f1cf0a0d1a379e14fe29327fce5597ec0
-  data.tar.gz: ff132aea8911b044a43de1a9abe1e54f3a680069b3b480f2e8109953600600b80abe4b923a13d3672f22ff1fe5c4ab3aef93246f2a9946d1c4f593495228ac0f
+  metadata.gz: a0bda13a371bcc93d37d4ae17548f04c65f1cc8fdf4982756eebac468d280f5b3a44d51ecb5ed5406e2ffee204a958988b3423860916471d8eb1a9e728fcf51c
+  data.tar.gz: a2bebff2e84e94c5fa30b6774c89c35f63ed4d2af214a76348a370ddbd9326ff0c8346fac9b3601e9bf9427bdb56f73a3f309f7eb71d439bd31b70426461ae3d

data/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.0] - 2026-04-14
+
+### Added
+- Custom/deterministic trace ID support (#74)
+
+### Fixed
+- Bump faraday, json, and addressable to patch CVEs (#75)
+
+### Documentation
+- Align docs with implementation (#70, #76)
+
 ## [0.6.0] - 2026-03-06
 
 ### Added
@@ -69,7 +80,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - OpenTelemetry-based tracing with OTLP export
 - Distributed caching with Rails.cache backend and stampede protection
 - Prompt management (text and chat) with Mustache templating
-- In-memory caching with TTL and LRU eviction
+- In-memory caching with TTL and bounded expiration-ordered eviction
 - Fallback prompt support
 - Global configuration pattern with `Langfuse.configure`
 
@@ -77,7 +88,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Migrated from legacy ingestion API to OTLP endpoint
 - Removed `tracing_enabled` configuration flag (#2)
 
-[Unreleased]: https://github.com/simplepractice/langfuse-rb/compare/v0.6.0...HEAD
+[Unreleased]: https://github.com/simplepractice/langfuse-rb/compare/v0.7.0...HEAD
+[0.7.0]: https://github.com/simplepractice/langfuse-rb/compare/v0.6.0...v0.7.0
 [0.6.0]: https://github.com/simplepractice/langfuse-rb/compare/v0.5.0...v0.6.0
 [0.5.0]: https://github.com/simplepractice/langfuse-rb/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/simplepractice/langfuse-rb/compare/v0.3.0...v0.4.0

data/lib/langfuse/cache_warmer.rb

@@ -85,7 +85,7 @@ module Langfuse
     # @example Warm with a different default label
     #   results = warmer.warm_all(default_label: "staging")
     #
-    # @example Warm without any label (latest versions)
+    # @example Warm without any label (API-determined selection)
     #   results = warmer.warm_all(default_label: nil)
     #
     # @example With specific versions for some prompts

data/lib/langfuse/observations.rb

@@ -133,8 +133,7 @@ module Langfuse
     # @yield [observation] Optional block that receives the observation object
     # @return [BaseObservation, Object] The child observation (or block return value if block given)
     def start_observation(name, attrs = {}, as_type: :span, &block)
-      # Call module-level factory with parent context
-      # Skip validation to allow unknown types to fall back to Span
+      # Skip validation so unknown types fall back to Span in the factory.
       child = Langfuse.start_observation(
         name,
         attrs,
@@ -142,24 +141,9 @@ module Langfuse
         parent_span_context: @otel_span.context,
         skip_validation: true
       )
+      return child unless block
 
-      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(child.otel_span, parent_context: current_context)
-        ) do
-          block.call(child)
-        end
-        # Only end if not already ended (events auto-end in start_observation)
-        child.end unless as_type.to_s == OBSERVATION_TYPES[:event]
-        result
-      else
-        # Stateful API - return observation
-        # Events already auto-ended in start_observation
-        child
-      end
+      child.send(:run_in_context, &block)
     end
 
     # Sets observation-level input attributes.
@@ -261,6 +245,27 @@ module Langfuse
         prompt
       end
     end
+
+    private
+
+    # Runs the block with this observation as the active OTel span,
+    # then ends the span in ensure (events excluded — they auto-end).
+    # @api private
+    def run_in_context
+      parent_ctx = OpenTelemetry::Context.current
+      span_ctx = OpenTelemetry::Trace.context_with_span(@otel_span, parent_context: parent_ctx)
+      OpenTelemetry::Context.with_current(span_ctx) { yield self }
+    ensure
+      safe_end
+    end
+
+    # Ends the span, swallowing errors so ensure never masks a block exception.
+    # @api private
+    def safe_end
+      self.end unless @type == OBSERVATION_TYPES[:event]
+    rescue StandardError
+      nil
+    end
   end
 
   # General-purpose observation for tracking operations, functions, or logical units of work.

data/lib/langfuse/trace_id.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Langfuse
+  # Deterministic and random trace/observation ID generation.
+  #
+  # Mirrors the Python and JS SDK helpers so the same seed produces the same
+  # trace ID across all three SDKs. This lets callers correlate Langfuse traces
+  # with external system identifiers (database primary keys, request IDs, etc.)
+  # and score or reference traces later without having to persist the generated
+  # Langfuse ID.
+  #
+  # @example Deterministic from an external ID
+  #   trace_id = Langfuse::TraceId.create(seed: "order-12345")
+  #   Langfuse.observe("process-order", trace_id: trace_id) { |span| ... }
+  #   Langfuse.create_score(name: "quality", value: 0.9, trace_id: trace_id)
+  #
+  # @example Random (no seed)
+  #   trace_id = Langfuse::TraceId.create
+  module TraceId
+    TRACE_ID_PATTERN = /\A[0-9a-f]{32}\z/
+    INVALID_TRACE_ID = ("0" * 32)
+
+    private_constant :TRACE_ID_PATTERN, :INVALID_TRACE_ID
+
+    class << self
+      # Generate a W3C trace ID (32 lowercase hex chars).
+      #
+      # With no seed, delegates to OpenTelemetry's random trace ID generator.
+      # With a seed, takes the first 16 bytes of SHA-256(seed) so the same
+      # input always produces the same trace ID.
+      #
+      # @note Avoid passing PII, secrets, or credentials as seeds — the raw seed
+      #   value appears in application code and may leak through logs/backtraces.
+      #   Use stable external identifiers (database PKs, UUIDs, request IDs).
+      # @param seed [String, nil] Optional seed for deterministic generation.
+      #   Must be a String if provided; non-String values raise ArgumentError
+      #   for cross-SDK parity (Python/JS both reject non-strings).
+      # @return [String] 32-character lowercase hex trace ID
+      # @raise [ArgumentError] if seed is not nil and not a String
+      def create(seed: nil)
+        return OpenTelemetry::Trace.generate_trace_id.unpack1("H*") if seed.nil?
+
+        Digest::SHA256.digest(validate_seed!(seed))[0, 16].unpack1("H*")
+      end
+
+      private
+
+      # @api private
+      def validate_seed!(seed)
+        raise ArgumentError, "seed must be a String, got #{seed.class}" unless seed.is_a?(String)
+
+        # ASCII-8BIT strings (binary) often already hold valid UTF-8 bytes
+        # but can't be transcoded — re-tag them instead.
+        return seed.dup.force_encoding("UTF-8") if seed.encoding == Encoding::ASCII_8BIT
+
+        seed.encode("UTF-8")
+      end
+
+      # @api private
+      def valid?(trace_id)
+        return false unless trace_id.is_a?(String) && TRACE_ID_PATTERN.match?(trace_id)
+
+        trace_id != INVALID_TRACE_ID
+      end
+
+      # Build a sampled OpenTelemetry SpanContext carrying the given hex trace ID.
+      #
+      # A random span_id is generated as a placeholder — only the trace_id is
+      # consumed by the child span that gets created.
+      #
+      # @api private
+      def to_span_context(trace_id)
+        raise ArgumentError, "Invalid trace_id: #{trace_id.inspect}" unless valid?(trace_id)
+
+        OpenTelemetry::Trace::SpanContext.new(
+          trace_id: [trace_id].pack("H*"),
+          span_id: OpenTelemetry::Trace.generate_span_id,
+          trace_flags: OpenTelemetry::Trace::TraceFlags::SAMPLED,
+          # Cross-SDK parity: Python uses is_remote=False (_create_remote_parent_span).
+          # Changing this would alter ParentBased sampler behavior across SDKs.
+          remote: false
+        )
+      end
+    end
+  end
+end

data/lib/langfuse/version.rb

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

data/lib/langfuse.rb

@@ -50,6 +50,7 @@ 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"
@@ -296,6 +297,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]
@@ -319,11 +338,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 +354,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 +372,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 +404,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 +428,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

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: langfuse-rb
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - SimplePractice
+autorequire:
 bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-04-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -183,6 +184,7 @@ files:
 - 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 +196,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 +211,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: []