langfuse-rb 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3b2a00b43e48c855cee6d5ccf6b12c36641c469182ddb65231323dcc566d01f2
-  data.tar.gz: 21b9bc01d7297bf7130b4530f25e4fffc8a0ac18036a7e6e97562767b2a4657a
+  metadata.gz: 2bf0fdf8f1b31f237397c90d8db3fc61c40bc8a69e20111a949aa0bdffc8dd3e
+  data.tar.gz: b6b83329218d23b3ebd53562a4eb5bb1cd01179f07fdbf5d90b2b1c97fc192ef
 SHA512:
-  metadata.gz: b121586667150434548323b0734f456f51fb06c21513bb59aaf7d8bbd07b8077ef23bbf2b87f2cac1514f5b220f54cff19175d97c11d19472306367a888aa97f
-  data.tar.gz: 9b5790ee2504681417cb7fa77fc2ebcb3c4e484bcfd512ba04abd6fbad215b609235d4bf109b0481c7855822d0643203873d49754b485aba487f6e85fb84260e
+  metadata.gz: a0bda13a371bcc93d37d4ae17548f04c65f1cc8fdf4982756eebac468d280f5b3a44d51ecb5ed5406e2ffee204a958988b3423860916471d8eb1a9e728fcf51c
+  data.tar.gz: a2bebff2e84e94c5fa30b6774c89c35f63ed4d2af214a76348a370ddbd9326ff0c8346fac9b3601e9bf9427bdb56f73a3f309f7eb71d439bd31b70426461ae3d

data/CHANGELOG.md

@@ -7,6 +7,32 @@ 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
+- Tracing payload masking via `Config#mask` (#68)
+- Cost details and usage details support on generations (#61)
+- Client-level `environment` and `release` configuration (#52)
+- Configurable parameters when creating scores (#48)
+
+### Fixed
+- Prompt cache key defaults unlabeled/unversioned fetches to production, matching JS/Python semantics (#63)
+- Tags sent as native arrays instead of JSON strings on OTel span attributes (#66)
+- Enforce 200-character tag length limit on traces (#67)
+- Score API parity between `Langfuse.create_score` and `Client#create_score` (#49)
+- Corrected misleading YARD docstrings for SWR cache config
+
 ## [0.5.0] - 2026-02-09
 
 ### Added
@@ -54,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`
 
@@ -62,7 +88,9 @@ 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.5.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
 [0.3.0]: https://github.com/simplepractice/langfuse-rb/compare/v0.2.0...v0.3.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/client.rb

@@ -285,10 +285,13 @@ module Langfuse
     #
     # @param name [String] Score name (required)
     # @param value [Numeric, Integer, String] Score value (type depends on data_type)
+    # @param id [String, nil] Score ID
     # @param trace_id [String, nil] Trace ID to associate with the score
+    # @param session_id [String, nil] Session ID to associate with the score
     # @param observation_id [String, nil] Observation ID to associate with the score
     # @param comment [String, nil] Optional comment
     # @param metadata [Hash, nil] Optional metadata hash
+    # @param environment [String, nil] Optional environment
     # @param data_type [Symbol] Data type (:numeric, :boolean, :categorical)
     # @param dataset_run_id [String, nil] Optional dataset run ID to associate with the score
     # @param config_id [String, nil] Optional score config ID
@@ -304,15 +307,18 @@ module Langfuse
     # @example Categorical score
     #   client.create_score(name: "category", value: "high", trace_id: "abc123", data_type: :categorical)
     # rubocop:disable Metrics/ParameterLists
-    def create_score(name:, value:, trace_id: nil, observation_id: nil, comment: nil, metadata: nil,
-                     data_type: :numeric, dataset_run_id: nil, config_id: nil)
+    def create_score(name:, value:, id: nil, trace_id: nil, session_id: nil, observation_id: nil, comment: nil,
+                     metadata: nil, environment: nil, data_type: :numeric, dataset_run_id: nil, config_id: nil)
       @score_client.create(
         name: name,
         value: value,
+        id: id,
         trace_id: trace_id,
+        session_id: session_id,
         observation_id: observation_id,
         comment: comment,
         metadata: metadata,
+        environment: environment,
         data_type: data_type,
         dataset_run_id: dataset_run_id,
         config_id: config_id

data/lib/langfuse/config.rb

@@ -46,10 +46,10 @@ module Langfuse
     # @return [Integer] Lock timeout in seconds for distributed cache stampede protection
     attr_accessor :cache_lock_timeout
 
-    # @return [Boolean] Enable stale-while-revalidate caching (when true, sets cache_stale_ttl to cache_ttl if not customized)
+    # @return [Boolean] Enable stale-while-revalidate caching (requires cache_stale_ttl > 0 to activate)
     attr_accessor :cache_stale_while_revalidate
 
-    # @return [Integer, Symbol] Stale TTL in seconds (grace period for serving stale data, default: 0 when SWR disabled, cache_ttl when SWR enabled)
+    # @return [Integer, Symbol] Stale TTL in seconds (grace period for serving stale data, default: 0)
     #   Accepts :indefinite which is automatically normalized to 1000 years (31,536,000,000 seconds) for practical "never expire" behavior.
     attr_accessor :cache_stale_ttl
 
@@ -68,6 +68,16 @@ module Langfuse
     # @return [Symbol] ActiveJob queue name for async processing
     attr_accessor :job_queue
 
+    # @return [String, nil] Default tracing environment applied to new traces/observations
+    attr_accessor :environment
+
+    # @return [String, nil] Default release identifier applied to new traces/observations
+    attr_accessor :release
+
+    # @return [#call, nil] Mask callable applied to input, output, and metadata before serialization.
+    #   Receives `data:` keyword argument. nil disables masking.
+    attr_accessor :mask
+
     # @return [String] Default Langfuse API base URL
     DEFAULT_BASE_URL = "https://cloud.langfuse.com"
 
@@ -107,11 +117,26 @@ module Langfuse
     # @return [Integer] Number of seconds representing indefinite cache duration (~1000 years)
     INDEFINITE_SECONDS = 1000 * 365 * 24 * 60 * 60
 
+    # @return [Array<String>] Common CI environment variables that contain a release SHA
+    COMMON_RELEASE_ENV_KEYS = %w[
+      RENDER_GIT_COMMIT
+      CI_COMMIT_SHA
+      CIRCLE_SHA1
+      SOURCE_VERSION
+      TRAVIS_COMMIT
+      GIT_COMMIT
+      GITHUB_SHA
+      BITBUCKET_COMMIT
+      BUILD_SOURCEVERSION
+      DRONE_COMMIT_SHA
+    ].freeze
+
     # Initialize a new Config object
     #
     # @yield [config] Optional block for configuration
     # @yieldparam config [Config] The config instance
     # @return [Config] a new Config instance
+    # rubocop:disable Metrics/AbcSize
     def initialize
       @public_key = ENV.fetch("LANGFUSE_PUBLIC_KEY", nil)
       @secret_key = ENV.fetch("LANGFUSE_SECRET_KEY", nil)
@@ -128,10 +153,14 @@ module Langfuse
       @batch_size = DEFAULT_BATCH_SIZE
       @flush_interval = DEFAULT_FLUSH_INTERVAL
       @job_queue = DEFAULT_JOB_QUEUE
+      @environment = env_value("LANGFUSE_TRACING_ENVIRONMENT")
+      @release = env_value("LANGFUSE_RELEASE") || detect_release_from_ci_env
+      @mask = nil
       @logger = default_logger
 
       yield(self) if block_given?
     end
+    # rubocop:enable Metrics/AbcSize
 
     # Validate the configuration
     #
@@ -154,6 +183,8 @@ module Langfuse
       validate_swr_config!
 
       validate_cache_backend!
+
+      validate_mask!
     end
     # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
@@ -223,5 +254,27 @@ module Langfuse
 
       raise ConfigurationError, "cache_refresh_threads must be positive"
     end
+
+    def validate_mask!
+      return if mask.nil? || mask.respond_to?(:call)
+
+      raise ConfigurationError, "mask must respond to #call"
+    end
+
+    def detect_release_from_ci_env
+      COMMON_RELEASE_ENV_KEYS.each do |key|
+        value = env_value(key)
+        return value if value
+      end
+
+      nil
+    end
+
+    def env_value(key)
+      value = ENV.fetch(key, nil)
+      return nil if value.nil? || value.empty?
+
+      value
+    end
   end
 end

data/lib/langfuse/masking.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Langfuse
+  # Central masking chokepoint for tracing payload fields.
+  #
+  # Applies a user-provided mask callable to input, output, and metadata
+  # before serialization. Fail-closed: if the mask raises, the entire
+  # field is replaced with {FALLBACK}.
+  #
+  # @api private
+  module Masking
+    # Replacement string used when the mask callable raises
+    FALLBACK = "<fully masked due to failed mask function>"
+
+    # Apply the mask callable to a data value.
+    #
+    # @param data [Object, nil] The value to mask (input, output, or metadata)
+    # @param mask [#call, nil] Callable receiving `data:` keyword; nil disables masking
+    # @return [Object] Masked data, original data (when mask is nil/data is nil), or {FALLBACK}
+    def self.apply(data, mask:)
+      return data if mask.nil? || data.nil?
+
+      mask.call(data: data)
+    rescue StandardError => e
+      Langfuse.configuration.logger.warn("Langfuse: Mask function failed: #{e.message}")
+      FALLBACK
+    end
+  end
+end

data/lib/langfuse/observations.rb

@@ -111,13 +111,14 @@ module Langfuse
     end
 
     # Updates trace-level attributes (user_id, session_id, tags, etc.) for the entire trace.
+    # Tags exceeding 200 characters are silently dropped with a warning log.
     #
     # @param attrs [Hash, Types::TraceAttributes] Trace attributes to set
     # @return [self]
     def update_trace(attrs)
       return self unless @otel_span.recording?
 
-      otel_attrs = OtelAttributes.create_trace_attributes(attrs.to_h)
+      otel_attrs = OtelAttributes.create_trace_attributes(attrs.to_h, mask: Langfuse.configuration.mask)
       otel_attrs.each { |key, value| @otel_span.set_attribute(key, value) }
       self
     end
@@ -132,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,
@@ -141,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.
@@ -196,9 +181,10 @@ module Langfuse
     # @param level [String] Log level (debug, default, warning, error)
     # @return [void]
     def event(name:, input: nil, level: "default")
+      masked_input = Masking.apply(input, mask: Langfuse.configuration.mask)
       attributes = {
-        "langfuse.observation.input" => input&.to_json,
-        "langfuse.observation.level" => level
+        OtelAttributes::OBSERVATION_INPUT => masked_input&.to_json,
+        OtelAttributes::OBSERVATION_LEVEL => level
       }.compact
 
       @otel_span.add_event(name, attributes: attributes)
@@ -242,7 +228,7 @@ module Langfuse
       attrs_hash = attrs.to_h.merge(kwargs)
 
       # Use @type instance variable set during initialization
-      otel_attrs = OtelAttributes.create_observation_attributes(type, attrs_hash)
+      otel_attrs = OtelAttributes.create_observation_attributes(type, attrs_hash, mask: Langfuse.configuration.mask)
       otel_attrs.each { |key, value| @otel_span.set_attribute(key, value) }
     end
 
@@ -259,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.
@@ -291,6 +298,35 @@ module Langfuse
     end
   end
 
+  # Shared setters for observation types that interact with a model (Generation, Embedding).
+  # @api private
+  module ModelSetters
+    # @param value [Hash] Usage hash with token counts
+    # @return [void]
+    # @deprecated Use #usage_details= instead.
+    def usage=(value)
+      self.usage_details = value
+    end
+
+    # @param value [Hash] Usage details hash (preserves key shape as provided)
+    # @return [void]
+    def usage_details=(value)
+      update_observation_attributes(usage_details: value)
+    end
+
+    # @param value [String] Model name (e.g., "gpt-4", "claude-3-opus")
+    # @return [void]
+    def model=(value)
+      update_observation_attributes(model: value)
+    end
+
+    # @param value [Hash] Model parameters (temperature, max_tokens, etc.)
+    # @return [void]
+    def model_parameters=(value)
+      update_observation_attributes(model_parameters: value)
+    end
+  end
+
   # Observation for LLM calls. Provides methods to set output, usage, and other LLM-specific metadata.
   #
   # @example Block-based API
@@ -299,7 +335,7 @@ module Langfuse
   #     gen.input = [{ role: "user", content: "Hello" }]
   #     response = call_llm(gen.input)
   #     gen.output = response
-  #     gen.usage = { prompt_tokens: 100, completion_tokens: 50, total_tokens: 150 }
+  #     gen.usage_details = { prompt_tokens: 100, completion_tokens: 50, total_tokens: 150 }
   #   end
   #
   # @example Stateful API
@@ -315,6 +351,8 @@ module Langfuse
   #   gen.end
   #
   class Generation < BaseObservation
+    include ModelSetters
+
     # @param otel_span [OpenTelemetry::SDK::Trace::Span] The underlying OTel span
     # @param otel_tracer [OpenTelemetry::SDK::Trace::Tracer] The OTel tracer
     # @param attributes [Hash, Types::GenerationAttributes, nil] Optional initial attributes
@@ -329,45 +367,10 @@ module Langfuse
       self
     end
 
-    # @param value [Hash] Usage hash with token counts (:prompt_tokens, :completion_tokens, :total_tokens)
-    # @return [void]
-    def usage=(value)
-      return unless @otel_span.recording?
-
-      # Convert to Langfuse API format (camelCase keys)
-      usage_hash = {
-        promptTokens: value[:prompt_tokens] || value["prompt_tokens"],
-        completionTokens: value[:completion_tokens] || value["completion_tokens"],
-        totalTokens: value[:total_tokens] || value["total_tokens"]
-      }.compact
-
-      usage_json = usage_hash.to_json
-      @otel_span.set_attribute("langfuse.observation.usage", usage_json)
-    end
-
-    # @param value [String] Model name (e.g., "gpt-4", "claude-3-opus")
+    # @param value [Hash] Cost details hash (prefer :input, :output, :total for aggregate Langfuse cost metrics)
     # @return [void]
-    def model=(value)
-      return unless @otel_span.recording?
-
-      @otel_span.set_attribute("langfuse.observation.model", value.to_s)
-    end
-
-    # @param value [Hash] Model parameters (temperature, max_tokens, etc.)
-    # @return [void]
-    def model_parameters=(value)
-      return unless @otel_span.recording?
-
-      # Convert to Langfuse API format (camelCase keys)
-      params_hash = {}
-      value.each do |k, v|
-        key_str = k.to_s
-        # Convert snake_case to camelCase
-        camel_key = key_str.gsub(/_([a-z])/) { Regexp.last_match(1).upcase }
-        params_hash[camel_key] = v
-      end
-      params_json = params_hash.to_json
-      @otel_span.set_attribute("langfuse.observation.modelParameters", params_json)
+    def cost_details=(value)
+      update_observation_attributes(cost_details: value)
     end
   end
 
@@ -630,7 +633,7 @@ module Langfuse
   #     vectors = embedding_service.generate(embedding.input, model: embedding.model)
   #     embedding.update(
   #       output: vectors,
-  #       usage: { prompt_tokens: 20, total_tokens: 20 }
+  #       usage_details: { prompt_tokens: 20, total_tokens: 20 }
   #     )
   #   end
   #
@@ -647,6 +650,8 @@ module Langfuse
   #   embedding.end
   #
   class Embedding < BaseObservation
+    include ModelSetters
+
     # @param otel_span [OpenTelemetry::SDK::Trace::Span] The underlying OTel span
     # @param otel_tracer [OpenTelemetry::SDK::Trace::Tracer] The OTel tracer
     # @param attributes [Hash, Types::EmbeddingAttributes, nil] Optional initial attributes
@@ -660,23 +665,5 @@ module Langfuse
       update_observation_attributes(attrs)
       self
     end
-
-    # @param value [Hash] Usage hash with token counts (:prompt_tokens, :total_tokens)
-    # @return [void]
-    def usage=(value)
-      update_observation_attributes(usage_details: value)
-    end
-
-    # @param value [String] Model name (e.g., "text-embedding-ada-002")
-    # @return [void]
-    def model=(value)
-      update_observation_attributes(model: value)
-    end
-
-    # @param value [Hash] Model parameters (temperature, max_tokens, etc.)
-    # @return [void]
-    def model_parameters=(value)
-      update_observation_attributes(model_parameters: value)
-    end
   end
 end

data/lib/langfuse/otel_attributes.rb

@@ -59,12 +59,16 @@ module Langfuse
     RELEASE = "langfuse.release"
     ENVIRONMENT = "langfuse.environment"
 
+    # Validation limits
+    MAX_TAG_LENGTH = 200
+
     # Creates OpenTelemetry attributes from Langfuse trace attributes
     #
     # Converts user-friendly trace attributes into the internal OpenTelemetry
     # attribute format required by the span processor.
     #
     # @param attrs [Types::TraceAttributes, Hash] Trace attributes object or hash
+    # @param mask [#call, nil] Mask callable applied to input, output, and metadata
     # @return [Hash] OpenTelemetry attributes hash with non-nil values
     #
     # @example
@@ -77,23 +81,25 @@ module Langfuse
     #   )
     #   otel_attrs = Langfuse::OtelAttributes.create_trace_attributes(attrs)
     #
-    def self.create_trace_attributes(attrs)
+    def self.create_trace_attributes(attrs, mask: nil)
       # Convert to hash if it's a TraceAttributes object
       attrs = attrs.to_h
       get_value = ->(key) { get_hash_value(attrs, key) }
 
+      input, output, metadata = mask_payload_fields(get_value, mask: mask)
+
       attributes = {
         TRACE_NAME => get_value.call(:name),
         TRACE_USER_ID => get_value.call(:user_id),
         TRACE_SESSION_ID => get_value.call(:session_id),
         VERSION => get_value.call(:version),
         RELEASE => get_value.call(:release),
-        TRACE_INPUT => serialize(get_value.call(:input)),
-        TRACE_OUTPUT => serialize(get_value.call(:output)),
-        TRACE_TAGS => serialize(get_value.call(:tags)),
+        TRACE_INPUT => serialize(input),
+        TRACE_OUTPUT => serialize(output),
+        TRACE_TAGS => normalize_tags(get_value.call(:tags)),
         ENVIRONMENT => get_value.call(:environment),
         TRACE_PUBLIC => get_value.call(:public),
-        **flatten_metadata(get_value.call(:metadata), TRACE_METADATA)
+        **flatten_metadata(metadata, TRACE_METADATA)
       }
 
       # Remove nil values
@@ -107,6 +113,7 @@ module Langfuse
     #
     # @param type [String] Observation type (e.g., "generation", "span", "event")
     # @param attrs [Types::SpanAttributes, Types::GenerationAttributes, Hash] Observation attributes
+    # @param mask [#call, nil] Mask callable applied to input, output, and metadata
     # @return [Hash] OpenTelemetry attributes hash with non-nil values
     #
     # @example
@@ -117,11 +124,11 @@ module Langfuse
     #   )
     #   otel_attrs = Langfuse::OtelAttributes.create_observation_attributes("generation", attrs)
     #
-    def self.create_observation_attributes(type, attrs)
+    def self.create_observation_attributes(type, attrs, mask: nil)
       attrs = attrs.to_h
       get_value = ->(key) { get_hash_value(attrs, key) }
 
-      otel_attributes = build_observation_base_attributes(type, get_value)
+      otel_attributes = build_observation_base_attributes(type, get_value, mask: mask)
       add_prompt_attributes(otel_attributes, get_value.call(:prompt))
 
       # Remove nil values
@@ -155,6 +162,27 @@ module Langfuse
       end
     end
 
+    # Filters tags to String-only elements within 200-char limit, returns nil if empty or nil
+    #
+    # @param tags [Array, nil] Raw tags array (each tag must be ≤200 characters; oversized tags are dropped with a warning)
+    # @return [Array<String>, nil] Filtered tags or nil
+    # @api private
+    def self.normalize_tags(tags)
+      return nil if tags.nil?
+
+      logger = Langfuse.configuration.logger
+      filtered = tags.select do |t|
+        next false unless t.is_a?(String)
+
+        if t.length > MAX_TAG_LENGTH
+          logger.warn("Langfuse: Tag exceeds #{MAX_TAG_LENGTH} characters (#{t.length} chars). Dropping.")
+          next false
+        end
+        true
+      end
+      filtered.empty? ? nil : filtered
+    end
+
     # Flattens and serializes metadata into OpenTelemetry attribute format
     #
     # Converts nested metadata objects into dot-notation attribute keys.
@@ -210,6 +238,20 @@ module Langfuse
       end
     end
 
+    # Applies masking to the three payload fields (input, output, metadata)
+    #
+    # @param get_value [Proc] Lambda to get values from attributes hash
+    # @param mask [#call, nil] Mask callable
+    # @return [Array(Object, Object, Object)] Masked [input, output, metadata]
+    # @api private
+    def self.mask_payload_fields(get_value, mask:)
+      [
+        Masking.apply(get_value.call(:input), mask: mask),
+        Masking.apply(get_value.call(:output), mask: mask),
+        Masking.apply(get_value.call(:metadata), mask: mask)
+      ]
+    end
+
     # Gets a value from a hash supporting both symbol and string keys
     # Handles false values correctly (doesn't treat false as nil)
     #
@@ -228,23 +270,26 @@ module Langfuse
     #
     # @param type [String] Observation type
     # @param get_value [Proc] Lambda to get values from attributes hash
+    # @param mask [#call, nil] Mask callable applied to input, output, and metadata
     # @return [Hash] Base observation attributes
     # @api private
-    def self.build_observation_base_attributes(type, get_value)
+    def self.build_observation_base_attributes(type, get_value, mask: nil)
+      input, output, metadata = mask_payload_fields(get_value, mask: mask)
+
       {
         OBSERVATION_TYPE => type,
         OBSERVATION_LEVEL => get_value.call(:level),
         OBSERVATION_STATUS_MESSAGE => get_value.call(:status_message),
         VERSION => get_value.call(:version),
-        OBSERVATION_INPUT => serialize(get_value.call(:input)),
-        OBSERVATION_OUTPUT => serialize(get_value.call(:output)),
+        OBSERVATION_INPUT => serialize(input),
+        OBSERVATION_OUTPUT => serialize(output),
         OBSERVATION_MODEL => get_value.call(:model),
         OBSERVATION_USAGE_DETAILS => serialize(get_value.call(:usage_details)),
         OBSERVATION_COST_DETAILS => serialize(get_value.call(:cost_details)),
         OBSERVATION_COMPLETION_START_TIME => serialize(get_value.call(:completion_start_time)),
         OBSERVATION_MODEL_PARAMETERS => serialize(get_value.call(:model_parameters)),
         ENVIRONMENT => get_value.call(:environment),
-        **flatten_metadata(get_value.call(:metadata), OBSERVATION_METADATA)
+        **flatten_metadata(metadata, OBSERVATION_METADATA)
       }
     end
 

data/lib/langfuse/otel_setup.rb

@@ -56,9 +56,10 @@ module Langfuse
         @tracer_provider = OpenTelemetry::SDK::Trace::TracerProvider.new
         @tracer_provider.add_span_processor(processor)
 
-        # Add span processor for propagated attributes
-        # This must be added AFTER the BatchSpanProcessor to ensure attributes are set before export
-        span_processor = SpanProcessor.new
+        # Add span processor for propagated attributes and env/release defaults
+        # This must be added AFTER the BatchSpanProcessor so it runs before export and can
+        # apply all attributes (propagated IDs, environment, release) to the spans being sent
+        span_processor = SpanProcessor.new(config: config)
         @tracer_provider.add_span_processor(span_processor)
 
         # Set as global tracer provider

data/lib/langfuse/prompt_cache.rb

@@ -164,6 +164,7 @@ module Langfuse
       key = name.to_s
       key += ":v#{version}" if version
       key += ":#{label}" if label
+      key += ":production" unless version || label
       key
     end
 

data/lib/langfuse/propagation.rb

@@ -166,15 +166,12 @@ module Langfuse
         span_key = _get_propagated_span_key(key)
 
         if key == "metadata" && value.is_a?(Hash)
-          # Handle metadata - flatten into individual attributes
           value.each do |k, v|
             metadata_key = "#{OtelAttributes::TRACE_METADATA}.#{k}"
             propagated_attributes[metadata_key] = v.to_s
           end
         elsif key == "tags" && value.is_a?(Array)
-          # Handle tags - serialize as JSON array for span attributes
-          serialized_tags = OtelAttributes.serialize(value)
-          propagated_attributes[span_key] = serialized_tags if serialized_tags
+          propagated_attributes[span_key] = value unless value.empty?
         else
           propagated_attributes[span_key] = value.to_s
         end
@@ -209,7 +206,7 @@ module Langfuse
     def self._merge_tags(context, context_key, new_tags)
       existing = context.value(context_key) || []
       existing = existing.to_a if existing.respond_to?(:to_a)
-      (existing + new_tags).uniq
+      (existing + new_tags).uniq.freeze
     end
 
     # Set a propagated attribute in context and on current span
@@ -229,36 +226,31 @@ module Langfuse
       baggage_key = _get_propagated_baggage_key(key)
 
       # Merge metadata/tags with existing context values
-      value = if key == "metadata" && value.is_a?(Hash)
-                _merge_metadata(context, context_key, value)
-              elsif key == "tags" && value.is_a?(Array)
-                _merge_tags(context, context_key, value)
-              else
-                value
-              end
+      merged = if key == "metadata" && value.is_a?(Hash)
+                 _merge_metadata(context, context_key, value)
+               elsif key == "tags" && value.is_a?(Array)
+                 _merge_tags(context, context_key, value)
+               else
+                 value
+               end
 
-      # Set in context
-      context = context.set_value(context_key, value)
+      context = context.set_value(context_key, merged)
 
       # Set on current span (if recording)
       if span&.recording?
-        if key == "metadata" && value.is_a?(Hash)
-          # Handle metadata - flatten into individual attributes
-          value.each do |k, v|
+        if key == "metadata" && merged.is_a?(Hash)
+          merged.each do |k, v|
             metadata_key = "#{OtelAttributes::TRACE_METADATA}.#{k}"
             span.set_attribute(metadata_key, v.to_s)
           end
-        elsif key == "tags" && value.is_a?(Array)
-          # Handle tags - serialize as JSON array
-          serialized_tags = OtelAttributes.serialize(value)
-          span.set_attribute(span_key, serialized_tags) if serialized_tags
+        elsif key == "tags" && merged.is_a?(Array)
+          span.set_attribute(span_key, merged) unless merged.empty?
         else
-          span.set_attribute(span_key, value.to_s)
+          span.set_attribute(span_key, merged.to_s)
         end
       end
 
       # Set in baggage (if requested and available)
-      # Note: Baggage support requires opentelemetry-baggage gem
       if as_baggage
         unless baggage_available?
           Langfuse.configuration.logger.warn(
@@ -270,7 +262,7 @@ module Langfuse
         context = _set_baggage_attribute(
           context: context,
           key: key,
-          value: value,
+          value: merged,
           baggage_key: baggage_key
         )
       end

data/lib/langfuse/score_client.rb

@@ -51,10 +51,13 @@ module Langfuse
     #
     # @param name [String] Score name (required)
     # @param value [Numeric, Integer, String] Score value (type depends on data_type)
+    # @param id [String, nil] Score ID
     # @param trace_id [String, nil] Trace ID to associate with the score
+    # @param session_id [String, nil] Session ID to associate with the score
     # @param observation_id [String, nil] Observation ID to associate with the score
     # @param comment [String, nil] Optional comment
     # @param metadata [Hash, nil] Optional metadata hash
+    # @param environment [String, nil] Optional environment
     # @param data_type [Symbol] Data type (:numeric, :boolean, :categorical)
     # @param dataset_run_id [String, nil] Optional dataset run ID to associate with the score
     # @param config_id [String, nil] Optional score config ID
@@ -70,19 +73,23 @@ module Langfuse
     # @example Categorical score
     #   create(name: "category", value: "high", trace_id: "abc123", data_type: :categorical)
     # rubocop:disable Metrics/ParameterLists
-    def create(name:, value:, trace_id: nil, observation_id: nil, comment: nil, metadata: nil,
-               data_type: :numeric, dataset_run_id: nil, config_id: nil)
+    def create(name:, value:, id: nil, trace_id: nil, session_id: nil, observation_id: nil, comment: nil,
+               metadata: nil, environment: nil, data_type: :numeric, dataset_run_id: nil, config_id: nil)
       validate_name(name)
+      # Keep identifier policy server-side to preserve cross-SDK parity and avoid blocking valid future payloads.
       normalized_value = normalize_value(value, data_type)
       data_type_str = Types::SCORE_DATA_TYPES[data_type] || raise(ArgumentError, "Invalid data_type: #{data_type}")
 
       event = build_score_event(
         name: name,
         value: normalized_value,
+        id: id,
         trace_id: trace_id,
+        session_id: session_id,
         observation_id: observation_id,
         comment: comment,
         metadata: metadata,
+        environment: environment,
         data_type: data_type_str,
         dataset_run_id: dataset_run_id,
         config_id: config_id
@@ -204,25 +211,30 @@ module Langfuse
     #
     # @param name [String] Score name
     # @param value [Object] Normalized score value
+    # @param id [String, nil] Score ID
     # @param trace_id [String, nil] Trace ID
+    # @param session_id [String, nil] Session ID
     # @param observation_id [String, nil] Observation ID
     # @param comment [String, nil] Comment
     # @param metadata [Hash, nil] Metadata
+    # @param environment [String, nil] Environment
     # @param data_type [String] Data type string (NUMERIC, BOOLEAN, CATEGORICAL)
     # @return [Hash] Event hash
-    # rubocop:disable Metrics/ParameterLists
-    def build_score_event(name:, value:, trace_id:, observation_id:, comment:, metadata:, data_type:,
-                          dataset_run_id: nil, config_id: nil)
+    # rubocop:disable Metrics/ParameterLists, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+    def build_score_event(name:, value:, id:, trace_id:, session_id:, observation_id:, comment:, metadata:,
+                          environment:, data_type:, dataset_run_id: nil, config_id: nil)
       body = {
-        id: SecureRandom.uuid,
+        id: id || SecureRandom.uuid,
         name: name,
         value: value,
         dataType: data_type
       }
       body[:traceId] = trace_id if trace_id
+      body[:sessionId] = session_id if session_id
       body[:observationId] = observation_id if observation_id
       body[:comment] = comment if comment
       body[:metadata] = metadata if metadata
+      body[:environment] = environment if environment
       body[:datasetRunId] = dataset_run_id if dataset_run_id
       body[:configId] = config_id if config_id
 
@@ -233,7 +245,7 @@ module Langfuse
         body: body
       }
     end
-    # rubocop:enable Metrics/ParameterLists
+    # rubocop:enable Metrics/ParameterLists, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
     # Normalize and validate score value based on data type
     #

data/lib/langfuse/span_processor.rb

@@ -3,14 +3,21 @@
 require "opentelemetry/sdk"
 
 module Langfuse
-  # Span processor that automatically sets propagated attributes on new spans.
+  # Span processor that applies default and propagated trace attributes on new spans.
   #
-  # This processor reads propagated attributes from OpenTelemetry context and
-  # sets them on spans when they are created. This ensures that attributes set
-  # via `propagate_attributes` are automatically applied to all child 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.
   #
   # @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)
+      @default_trace_attributes = build_default_trace_attributes(config).freeze
+      super()
+    end
+
     # Called when a span starts
     #
     # @param span [OpenTelemetry::SDK::Trace::Span] The span that started
@@ -19,13 +26,8 @@ module Langfuse
     def on_start(span, parent_context)
       return unless span.recording?
 
-      # Get propagated attributes from context
-      propagated_attrs = Propagation.get_propagated_attributes_from_context(parent_context)
-
-      # Set attributes on span
-      propagated_attrs.each do |key, value|
-        span.set_attribute(key, value)
-      end
+      apply_attributes(span, @default_trace_attributes)
+      apply_attributes(span, propagated_attributes(parent_context))
     end
 
     # Called when a span ends
@@ -57,5 +59,25 @@ module Langfuse
       _ = timeout # Suppress unused argument warning
       0
     end
+
+    private
+
+    def build_default_trace_attributes(config)
+      return {} unless config
+
+      OtelAttributes.create_trace_attributes(
+        { environment: config.environment, release: config.release }
+      )
+    end
+
+    def propagated_attributes(parent_context)
+      return {} unless parent_context
+
+      Propagation.get_propagated_attributes_from_context(parent_context)
+    end
+
+    def apply_attributes(span, attributes)
+      attributes.each { |key, value| span.set_attribute(key, value) }
+    end
   end
 end

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/types.rb

@@ -173,7 +173,7 @@ module Langfuse
       # @return [Hash, nil] Token usage and other model-specific usage metrics
       attr_accessor :usage_details
 
-      # @return [Hash, nil] Cost breakdown for the generation (total_cost, etc.)
+      # @return [Hash, nil] Cost breakdown for the generation (prefer :input, :output, :total)
       attr_accessor :cost_details
 
       # @return [Hash, nil] Information about the prompt used from Langfuse prompt management
@@ -186,7 +186,7 @@ module Langfuse
       # @param model [String, nil] Model name
       # @param model_parameters [Hash, nil] Model parameters
       # @param usage_details [Hash, nil] Usage metrics
-      # @param cost_details [Hash, nil] Cost breakdown
+      # @param cost_details [Hash, nil] Cost breakdown (prefer :input, :output, :total)
       # @param prompt [Hash, nil] Prompt information with :name, :version, :is_fallback keys
       # @param kwargs [Hash] Additional keyword arguments passed to SpanAttributes
       # rubocop:disable Metrics/ParameterLists
@@ -287,7 +287,7 @@ module Langfuse
       # @param input [Object, nil] Input data
       # @param output [Object, nil] Output data
       # @param metadata [Hash, nil] Additional metadata
-      # @param tags [Array<String>, nil] Tags array
+      # @param tags [Array<String>, nil] Tags array (each tag must be ≤200 characters; oversized tags are dropped)
       # @param public [Boolean, nil] Public visibility flag
       # @param environment [String, nil] Environment identifier
       # rubocop:disable Metrics/ParameterLists

data/lib/langfuse/version.rb

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

data/lib/langfuse.rb

@@ -45,10 +45,12 @@ require_relative "langfuse/rails_cache_adapter"
 require_relative "langfuse/cache_warmer"
 require_relative "langfuse/api_client"
 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"
@@ -190,11 +192,16 @@ module Langfuse
     #
     # @param name [String] Score name (required)
     # @param value [Numeric, Integer, String] Score value (type depends on data_type)
+    # @param id [String, nil] Score ID
     # @param trace_id [String, nil] Trace ID to associate with the score
+    # @param session_id [String, nil] Session ID to associate with the score
     # @param observation_id [String, nil] Observation ID to associate with the score
     # @param comment [String, nil] Optional comment
     # @param metadata [Hash, nil] Optional metadata hash
+    # @param environment [String, nil] Optional environment
     # @param data_type [Symbol] Data type (:numeric, :boolean, :categorical)
+    # @param dataset_run_id [String, nil] Optional dataset run ID to associate with the score
+    # @param config_id [String, nil] Optional score config ID
     # @return [void]
     # @raise [ArgumentError] if validation fails
     #
@@ -207,16 +214,21 @@ module Langfuse
     # @example Categorical score
     #   Langfuse.create_score(name: "category", value: "high", trace_id: "abc123", data_type: :categorical)
     # rubocop:disable Metrics/ParameterLists
-    def create_score(name:, value:, trace_id: nil, observation_id: nil, comment: nil, metadata: nil,
-                     data_type: :numeric)
+    def create_score(name:, value:, id: nil, trace_id: nil, session_id: nil, observation_id: nil, comment: nil,
+                     metadata: nil, environment: nil, data_type: :numeric, dataset_run_id: nil, config_id: nil)
       client.create_score(
         name: name,
         value: value,
+        id: id,
         trace_id: trace_id,
+        session_id: session_id,
         observation_id: observation_id,
         comment: comment,
         metadata: metadata,
-        data_type: data_type
+        environment: environment,
+        data_type: data_type,
+        dataset_run_id: dataset_run_id,
+        config_id: config_id
       )
     end
     # rubocop:enable Metrics/ParameterLists
@@ -285,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]
@@ -308,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: {...} })
@@ -321,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(
@@ -337,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)
-        otel_attrs.each { |key, value| otel_span.set_attribute(key, value) }
-      end
-
-      # Wrap in appropriate class
-      observation = wrap_otel_span(otel_span, type_str, otel_tracer, attributes: attrs)
-
+      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|
@@ -374,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
@@ -414,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.5.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
@@ -171,6 +172,7 @@ files:
 - lib/langfuse/experiment_result.rb
 - lib/langfuse/experiment_runner.rb
 - lib/langfuse/item_result.rb
+- lib/langfuse/masking.rb
 - lib/langfuse/observations.rb
 - lib/langfuse/otel_attributes.rb
 - lib/langfuse/otel_setup.rb
@@ -182,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
@@ -193,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
@@ -207,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: []