langfuse-rb 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3b2a00b43e48c855cee6d5ccf6b12c36641c469182ddb65231323dcc566d01f2
-  data.tar.gz: 21b9bc01d7297bf7130b4530f25e4fffc8a0ac18036a7e6e97562767b2a4657a
+  metadata.gz: e320f34169f77bea79aa259867b62aa7164d77a693e864cb1d03cb86d0d188a2
+  data.tar.gz: 59a40715dbb46604f6287b46b80c34e1524f7279fed261b7795d781854df987f
 SHA512:
-  metadata.gz: b121586667150434548323b0734f456f51fb06c21513bb59aaf7d8bbd07b8077ef23bbf2b87f2cac1514f5b220f54cff19175d97c11d19472306367a888aa97f
-  data.tar.gz: 9b5790ee2504681417cb7fa77fc2ebcb3c4e484bcfd512ba04abd6fbad215b609235d4bf109b0481c7855822d0643203873d49754b485aba487f6e85fb84260e
+  metadata.gz: d18c3cb807c759c20f72a4259ccfb0502f1800b671aadcf14ea24f88e0be227ed200677f1cbabef22e467c06f2f1ce5f1cf0a0d1a379e14fe29327fce5597ec0
+  data.tar.gz: ff132aea8911b044a43de1a9abe1e54f3a680069b3b480f2e8109953600600b80abe4b923a13d3672f22ff1fe5c4ab3aef93246f2a9946d1c4f593495228ac0f

data/CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
@@ -62,7 +77,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.5.0...HEAD
+[Unreleased]: https://github.com/simplepractice/langfuse-rb/compare/v0.6.0...HEAD
+[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/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
@@ -196,9 +197,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 +244,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
 
@@ -291,6 +293,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 +330,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 +346,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 +362,10 @@ module Langfuse
       self
     end
 
-    # @param value [Hash] Usage hash with token counts (:prompt_tokens, :completion_tokens, :total_tokens)
+    # @param value [Hash] Cost details hash (prefer :input, :output, :total for aggregate Langfuse cost metrics)
     # @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")
-    # @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 +628,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 +645,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 +660,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/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.6.0"
 end

data/lib/langfuse.rb

@@ -45,6 +45,7 @@ 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"
@@ -190,11 +191,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 +213,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
@@ -341,12 +352,12 @@ module Langfuse
       # 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 = 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
-      observation = wrap_otel_span(otel_span, type_str, otel_tracer, attributes: attrs)
+      # 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]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: langfuse-rb
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - SimplePractice
@@ -171,6 +171,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