OTel GenAI Message Ingestion#

Overview#

GenAI-related OpenTelemetry attributes are parsed inside OtelIngestionProcessor.extractInputAndOutput() 1, which converts OTel span attributes and events into Langfuse input/output fields on observations. The method uses a priority-based fallback chain: each framework's attributes are tried in sequence, and the first match wins.

extractInputAndOutput — Priority Chain#

The chain checks these sources in order 2:

Attribute keys used by the winning path are removed from filteredAttributes before they are stored in metadata.attributes 3.

OTel GenAI Span Events (Standard Path)#

When a span carries standard OTel GenAI per-message span events, extractInputAndOutput builds a message array from them 4:

• Input events match names gen_ai.system.message, gen_ai.user.message, gen_ai.assistant.message, gen_ai.tool.message. Each event becomes { role: "<role>", ...eventAttributes } where role is derived by stripping gen_ai. and .message from the event name.
• Output events match gen_ai.choice. If there is exactly one choice event, a single object is returned; otherwise an array.

Each event's attributes are deserialized from protobuf via convertValueToPlainJavascript() 5.

gen_ai.client.inference.operation.details (v1.37+ conventions, PR #14930): OTel GenAI semantic conventions v1.37+ moved prompts/completions to an opt-in span event named gen_ai.client.inference.operation.details, which carries gen_ai.input.messages, gen_ai.output.messages, and gen_ai.system_instructions as event attributes rather than span attributes. Emitters like Hindsight use this convention. PR #14930 6 added extraction from this event — the processor filters for this event name, converts its attributes to plain JS, and then delegates to the same gen_ai.input/output.messages parsing (including gen_ai.system_instructions prepending). This path is inserted before the older per-message events in the chain, so v1.37+ emitters are handled first.

gen_ai.system_instructions — Multi-Format Serialization#

The attribute gen_ai.system_instructions carries system prompts separately from the message array. Two code paths invoke prependSystemInstructions() 7:

1. Pydantic AI agent spans — when pydantic_ai.all_messages is the input and gen_ai.system_instructions is present 8.
2. Generic OTel path — when gen_ai.input.messages is the input and gen_ai.system_instructions is present 9.

prependSystemInstructions behavior 10:

• Parses input as JSON if it is a string.
• No-ops if the array already contains a { role: "system" } message — preventing duplication.
• Converts systemInstructions to a content string:
  • If already an array (e.g., Google Gemini sends system instructions as [{ content: "..." }]), joins content fields with "\n".
  • Otherwise, stringifies to a plain string.
• Prepends { role: "system", content } and returns in the same format (string-encoded JSON if input was a string; array otherwise).

This was introduced in PR #12442 11.

Dotted-Path Message Reconstruction#

For providers using the OpenInference convention (Agno, BeeAI, etc.), messages arrive as flattened dotted keys such as llm.input_messages.0.role, llm.input_messages.0.content, etc. convertKeyPathToNestedObject() 12 reconstructs these into a nested array or object. The same function handles gen_ai.prompt.* / gen_ai.completion.* for TraceLoop. It detects whether numeric index segments are present to decide whether to build an array or a plain object.

Key Source Files#

Related knowledge base articles:

• OTel Attribute Serialization 14 — protobuf-to-JS conversion details and filteredAttributes stringify behavior
• OTel Ingestion and Trace Hierarchy 15 — overall pipeline, trace deduplication, parent-child relationships
• OTel Token Usage Processing 16 — extractUsageDetails and token normalization