Module: Langfuse::OtelAttributes

Defined in:
lib/langfuse/otel_attributes.rb

Overview

Serialization layer that converts Langfuse domain models to OpenTelemetry span attributes format

This module provides methods to convert user-friendly Langfuse attribute objects into the internal OpenTelemetry attribute format required by the span processor.

rubocop:disable Metrics/ModuleLength

Examples:

Converting trace attributes

attrs = Langfuse::Types::TraceAttributes.new(
  name: "user-checkout-flow",
  user_id: "user-123",
  tags: ["checkout", "payment"],
  metadata: { version: "2.1.0" }
)
otel_attrs = Langfuse::OtelAttributes.create_trace_attributes(attrs)
span.set_attributes(otel_attrs)

Converting observation attributes

attrs = Langfuse::Types::GenerationAttributes.new(
  model: "gpt-4",
  input: { messages: [...] },
  usage_details: { prompt_tokens: 100 }
)
otel_attrs = Langfuse::OtelAttributes.create_observation_attributes("generation", attrs)
span.set_attributes(otel_attrs)

Constant Summary collapse

TRACE_NAME =

Trace attributes

"langfuse.trace.name"
TRACE_USER_ID =

TRACE_USER_ID and TRACE_SESSION_ID are without langfuse prefix because they follow OpenTelemetry semantic conventions

"user.id"
TRACE_SESSION_ID = 
"session.id"
TRACE_INPUT = 
"langfuse.trace.input"
TRACE_OUTPUT = 
"langfuse.trace.output"
TRACE_METADATA = 
"langfuse.trace.metadata"
TRACE_TAGS = 
"langfuse.trace.tags"
TRACE_PUBLIC = 
"langfuse.trace.public"
OBSERVATION_TYPE =

Observation attributes

"langfuse.observation.type"
OBSERVATION_INPUT = 
"langfuse.observation.input"
OBSERVATION_OUTPUT = 
"langfuse.observation.output"
OBSERVATION_METADATA = 
"langfuse.observation.metadata"
OBSERVATION_LEVEL = 
"langfuse.observation.level"
OBSERVATION_STATUS_MESSAGE = 
"langfuse.observation.status_message"
OBSERVATION_MODEL = 
"langfuse.observation.model.name"
OBSERVATION_MODEL_PARAMETERS = 
"langfuse.observation.model.parameters"
OBSERVATION_USAGE_DETAILS = 
"langfuse.observation.usage_details"
OBSERVATION_COST_DETAILS = 
"langfuse.observation.cost_details"
OBSERVATION_PROMPT_NAME = 
"langfuse.observation.prompt.name"
OBSERVATION_PROMPT_VERSION = 
"langfuse.observation.prompt.version"
OBSERVATION_COMPLETION_START_TIME = 
"langfuse.observation.completion_start_time"
IS_APP_ROOT = 
"langfuse.internal.is_app_root"
VERSION =

Common attributes

"langfuse.version"
RELEASE = 
"langfuse.release"
ENVIRONMENT = 
"langfuse.environment"
MAX_TAG_LENGTH =

Validation limits

200

Class Method Summary collapse

Class Method Details

.add_prompt_attributes(otel_attributes, prompt) ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Adds prompt attributes if prompt is present and not a fallback

rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity

Parameters:

  • otel_attributes (Hash) —

    Attributes hash to modify

  • prompt (Hash, Object, nil) —

    Prompt hash or object



304
305
306
307
308
309
310
311
312
313
314
315
316
 
# File 'lib/langfuse/otel_attributes.rb', line 304

def self.add_prompt_attributes(otel_attributes, prompt)
  return unless prompt
  return if fallback_prompt?(prompt)

  if prompt.is_a?(Hash) || prompt.respond_to?(:[])
    otel_attributes[OBSERVATION_PROMPT_NAME] = prompt[:name] || prompt["name"]
    otel_attributes[OBSERVATION_PROMPT_VERSION] = prompt[:version] || prompt["version"]
  # Handle objects with name/version methods (already converted in Trace#generation)
  elsif prompt.respond_to?(:name) && prompt.respond_to?(:version)
    otel_attributes[OBSERVATION_PROMPT_NAME] = prompt.name
    otel_attributes[OBSERVATION_PROMPT_VERSION] = prompt.version
  end
end

.build_observation_base_attributes(type, get_value, mask: nil) ⇒ Hash

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Builds base observation attributes (without prompt)

Parameters:

  • type (String) —

    Observation type

  • get_value (Proc) —

    Lambda to get values from attributes hash

  • mask (#call, nil) (defaults to: nil) —

    Mask callable applied to input, output, and metadata

Returns:

  • (Hash) —

    Base observation attributes



277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
 
# File 'lib/langfuse/otel_attributes.rb', line 277

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(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(metadata, OBSERVATION_METADATA)
  }
end

.create_observation_attributes(type, attrs, mask: nil) ⇒ Hash

Creates OpenTelemetry attributes from Langfuse observation attributes

Converts user-friendly observation attributes into the internal OpenTelemetry attribute format required by the span processor.

Examples:

attrs = Langfuse::Types::GenerationAttributes.new(
  model: "gpt-4",
  input: { messages: [...] },
  usage_details: { prompt_tokens: 100 }
)
otel_attrs = Langfuse::OtelAttributes.create_observation_attributes("generation", attrs)

Parameters:

  • type (String) —

    Observation type (e.g., "generation", "span", "event")

  • attrs (Types::SpanAttributes, Types::GenerationAttributes, Hash) —

    Observation attributes

  • mask (#call, nil) (defaults to: nil) —

    Mask callable applied to input, output, and metadata

Returns:

  • (Hash) —

    OpenTelemetry attributes hash with non-nil values



128
129
130
131
132
133
134
135
136
137
 
# File 'lib/langfuse/otel_attributes.rb', line 128

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, mask: mask)
  add_prompt_attributes(otel_attributes, get_value.call(:prompt))

  # Remove nil values
  otel_attributes.compact
end

.create_trace_attributes(attrs, mask: nil) ⇒ Hash

Creates OpenTelemetry attributes from Langfuse trace attributes

Converts user-friendly trace attributes into the internal OpenTelemetry attribute format required by the span processor.

Examples:

attrs = Langfuse::Types::TraceAttributes.new(
  name: "user-checkout-flow",
  user_id: "user-123",
  session_id: "session-456",
  tags: ["checkout", "payment"],
  metadata: { version: "2.1.0" }
)
otel_attrs = Langfuse::OtelAttributes.create_trace_attributes(attrs)

Parameters:

  • attrs (Types::TraceAttributes, Hash) —

    Trace attributes object or hash

  • mask (#call, nil) (defaults to: nil) —

    Mask callable applied to input, output, and metadata

Returns:

  • (Hash) —

    OpenTelemetry attributes hash with non-nil values



85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
 
# File 'lib/langfuse/otel_attributes.rb', line 85

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(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(metadata, TRACE_METADATA)
  }

  # Remove nil values
  attributes.compact
end

.flatten_hash_value(value, key) ⇒ Hash

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Flattens a single hash value (recursively if it's a hash, serializes otherwise)

Parameters:

  • value (Object) —

    Value to flatten

  • key (String) —

    Attribute key prefix

Returns:

  • (Hash) —

    Flattened attributes hash



228
229
230
231
232
233
234
235
236
237
238
239
240
 
# File 'lib/langfuse/otel_attributes.rb', line 228

def self.flatten_hash_value(value, key)
  if value.is_a?(Hash)
    # Recursively flatten nested hashes
    flatten_metadata(value, key)
  elsif value.is_a?(Array)
    # Serialize arrays to JSON
    serialized = serialize(value, preserve_strings: true)
    serialized ? { key => serialized } : {}
  else
    # Convert simple values (strings, numbers, booleans) to strings
    { key => value.to_s }
  end
end

.flatten_metadata(metadata, prefix) ⇒ Hash

Flattens and serializes metadata into OpenTelemetry attribute format

Converts nested metadata objects into dot-notation attribute keys. For example, { database: { host: 'localhost' } } becomes { 'langfuse.trace.metadata.database.host': 'localhost' }.

Examples:

flatten_metadata({ user: { id: 123 } }, "langfuse.trace.metadata")
# => { "langfuse.trace.metadata.user.id" => "123" }

Parameters:

  • metadata (Hash, Array, Object, nil) —

    Metadata to flatten

  • prefix (String) —

    Prefix for attribute keys (e.g., "langfuse.trace.metadata")

Returns:

  • (Hash) —

    Flattened metadata attributes



201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
 
# File 'lib/langfuse/otel_attributes.rb', line 201

def self.flatten_metadata(metadata, prefix)
  return {} if metadata.nil?

  # Handle non-hash metadata (arrays, primitives, etc.)
  unless metadata.is_a?(Hash)
    serialized = serialize(metadata, preserve_strings: true)
    return serialized ? { prefix => serialized } : {}
  end

  # Recursively flatten hash metadata
  result = {}
  metadata.each do |key, value|
    next if value.nil?

    new_key = "#{prefix}.#{key}"
    result.merge!(flatten_hash_value(value, new_key))
  end

  result
end

.get_hash_value(hash, key) ⇒ Object?

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Gets a value from a hash supporting both symbol and string keys Handles false values correctly (doesn't treat false as nil)

Parameters:

  • hash (Hash) —

    Hash to get value from

  • key (Symbol, String) —

    Key to look up

Returns:

  • (Object, nil) —

    Value from hash or nil



263
264
265
266
267
268
 
# File 'lib/langfuse/otel_attributes.rb', line 263

def self.get_hash_value(hash, key)
  return hash[key] if hash.key?(key)
  return hash[key.to_s] if hash.key?(key.to_s)

  nil
end

.mask_payload_fields(get_value, mask:) ⇒ Array(Object, Object, Object)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Applies masking to the three payload fields (input, output, metadata)

Parameters:

  • get_value (Proc) —

    Lambda to get values from attributes hash

  • mask (#call, nil) —

    Mask callable

Returns:

  • (Array(Object, Object, Object)) —

    Masked [input, output, metadata]



248
249
250
251
252
253
254
 
# File 'lib/langfuse/otel_attributes.rb', line 248

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

.normalize_tags(tags) ⇒ Array<String>?

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Filters tags to String-only elements within 200-char limit, returns nil if empty or nil

Parameters:

  • tags (Array, nil) —

    Raw tags array (each tag must be ≤200 characters; oversized tags are dropped with a warning)

Returns:

  • (Array<String>, nil) —

    Filtered tags or nil



171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
 
# File 'lib/langfuse/otel_attributes.rb', line 171

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

.serialize(obj, preserve_strings: false) ⇒ String?

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Safely serializes an object to JSON string

Examples:

Always JSON-serialize (default)

serialize({ key: "value" }) # => '{"key":"value"}'
serialize("string") # => '"string"'
serialize(nil) # => nil

Preserve strings

serialize("already a string", preserve_strings: true) # => "already a string"
serialize([1, 2, 3], preserve_strings: true) # => "[1,2,3]"

Parameters:

  • obj (Object, nil) —

    Object to serialize

  • preserve_strings (Boolean) (defaults to: false) —

    If true, preserves strings as-is; if false, JSON-serializes everything including strings

Returns:

  • (String, nil) —

    JSON string, original string (if preserve_strings is true), or nil if nil/undefined



155
156
157
158
159
160
161
162
163
164
 
# File 'lib/langfuse/otel_attributes.rb', line 155

def self.serialize(obj, preserve_strings: false)
  return nil if obj.nil?
  return obj if preserve_strings && obj.is_a?(String)

  begin
    obj.to_json
  rescue StandardError
    nil
  end
end