@spec attribute_value(term()) :: term()

Coerces a caller-supplied value into something safe to set as a span attribute.

Values the OpenTelemetry spec supports natively — strings, integers, floats, booleans, and homogeneous lists of those — pass through unchanged, so numeric attributes stay numeric and remain filterable as numbers in the backend. Anything else is JSON-encoded, falling back to inspect/1 when it cannot be encoded.

This exists because an uncoerced value is not a loud failure. A nested map has no String.Chars implementation, so the SDK's stringification raises; the span handler traps that exception (it must, since a raising :telemetry handler is detached VM-wide) and the result is that the whole span silently disappears. Every caller-supplied value must pass through here.

nil returns nil so callers can drop the attribute entirely; there is no meaningful "null" span attribute.

@spec chain_start(map()) :: [{String.t(), term()}]

Builds attributes for a chain execution event.

Sets gen_ai.conversation.id, gen_ai.agent.name, and gen_ai.agent.id from custom_context, extracts Langfuse-specific attributes when present, and applies the caller's :otel_attributes passthrough (see passthrough_attributes/1).

@spec chain_stop(map(), LangChain.OpenTelemetry.Config.t()) :: [{String.t(), term()}]

Builds attributes for a chain execution stop event.

Extracts the first user message as input and the last assistant message as output so they appear on the trace-level span in Langfuse (and other OTEL backends).

@spec custom_context_attributes(map() | nil) :: [{String.t(), term()}]

Extracts Langfuse-specific attributes from a custom_context map.

Supported keys:

• :langfuse_trace_name -> langfuse.trace.name
• :langfuse_user_id -> langfuse.user.id
• :langfuse_session_id -> langfuse.session.id
• :langfuse_tags -> langfuse.trace.tags
• :langfuse_metadata -> langfuse.trace.metadata.* (flattened)

@spec llm_call_start(map(), LangChain.OpenTelemetry.Config.t()) :: [
  {String.t(), term()}
]

Builds attributes for an LLM call start event.

Returns operation name, output type, model, provider, and request-parameter attributes (gen_ai.request.*, sourced from metadata[:request_options]). Input message capture is handled separately by the prompt event handler in SpanHandler.

@spec llm_call_stop(map(), LangChain.OpenTelemetry.Config.t()) :: [
  {String.t(), term()}
]

Builds attributes for an LLM call stop event (token usage and response model).

When config.capture_output_messages is true and metadata[:result] contains a message, serializes output messages into gen_ai.output.messages.

@spec merge(list(), list()) :: list()

Merges two attribute lists, with override winning on duplicate keys.

Attribute lists are keyword-like lists of {key, value} tuples, and the SDK's own de-duplication order is an implementation detail we should not depend on. Resolving collisions here keeps precedence explicit and testable at the two places it matters:

• caller-supplied :otel_attributes override LangChain-derived values on the same span, because a caller who names a key means it;
• inherited attributes (see LangChain.OpenTelemetry.SpanHandler) lose to the values an event derives, so an inherited gen_ai.request.model can never overwrite the real per-call model on a chat span.

Returns the gen_ai.operation.name attribute key.

@spec passthrough_attributes(map() | nil) :: [{String.t(), term()}]

Extracts caller-supplied span attributes from custom_context[:otel_attributes].

:otel_attributes is a reserved key in LLMChain.custom_context: a flat map of attribute name to value that LangChain copies onto the spans it creates.

chain =
  %{llm: llm, messages: messages}
  |> LLMChain.new!()
  |> Map.put(:custom_context, %{
    otel_attributes: %{
      "user.id" => user.id,
      "organization.id" => org.id,
      "myapp.feature" => "support_chat"
    }
  })

The key is reserved and explicit rather than LangChain forwarding all of custom_context, because custom_context routinely holds structs, PIDs, and whole conversation states. Copying it wholesale would produce enormous spans and leak data the caller never intended to export.

Keys may be strings or atoms; values are coerced by attribute_value/1. Entries with an unusable key or a nil value are dropped rather than exported as empty attributes.

Namespace application-specific names (myapp.*) per the semantic conventions. A gen_ai.* key is honoured deliberately, so a caller can fill a convention slot LangChain does not populate itself.

@spec tool_call(map(), LangChain.OpenTelemetry.Config.t()) :: [{String.t(), term()}]

Builds attributes for a tool call start event.

When config.capture_tool_arguments is true and metadata[:arguments] is present, serializes arguments into gen_ai.tool.call.arguments. Also applies the caller's :otel_attributes passthrough (see passthrough_attributes/1), which reaches tool spans because LLMChain includes custom_context in the tool-call telemetry metadata.

@spec tool_call_stop(map(), LangChain.OpenTelemetry.Config.t()) :: [
  {String.t(), term()}
]

Builds attributes for a tool call stop event.

When config.capture_tool_results is true and metadata[:tool_result] is present, extracts the result content into gen_ai.tool.call.result.