> ## Documentation Index
> Fetch the complete documentation index at: https://docs.elementum.io/llms.txt
> Use this file to discover all available pages before exploring further.

# GenAI Attribute Reference

> Every gen_ai, elementum, and voice attribute Elementum sets on AI agent, model, tool, and voice spans.

Every attribute Elementum sets on the AI spans described in [GenAI tracing](https://docs.elementum.io/administration/trace-forwarding/genai-tracing.md). Keys are listed exactly as they arrive. Most follow the OpenTelemetry GenAI semantic conventions (`gen_ai.*`). A few duplicate the same value under OpenInference names (`openinference.*`, `llm.*`, `input.*`, `output.*`), which some evaluation platforms read instead.

## Conventions

* **Type** is the OTLP value type: `string`, `int` (64-bit integer), `double`, `boolean`, or `string[]`.
* **Spans**: A = `invoke_agent`, L = `chat` (LLM call), T = `execute_tool`, V = voice spans.
* An attribute with no value is left out. It is never sent empty. "Absent when" lists the usual reasons.
* Example ids are placeholders.

## Resource and span properties

| Property | Value |
| - | - |
| Resource `service.name` | `elementum`, as on automation spans. A resource attribute configured on your endpoint with this key replaces it. |
| Resource `service.version` | The current Elementum platform release, when set. |
| Other resource attributes | The resource attributes you added to the endpoint. |
| Instrumentation scope | `elementum` |
| Span kind | `INTERNAL` |
| Status | `OK`, `ERROR`, or `UNSET`. No status description is sent. |
| Trace flags | Sampled |

## Operation

| Key | Type | Spans | Meaning | Example | Absent when |
| - | - | - | - | - | - |
| `gen_ai.operation.name` | string | A, L, T, V | What the span does: `invoke_agent`, `chat`, or `execute_tool`. | `chat` | `a2a.message.handle` and some voice spans. |
| `openinference.span.kind` | string | A, L, T, V | The same classification in OpenInference terms: `AGENT`, `LLM`, or `TOOL`. | `LLM` | `voice.realtime.*` and most other voice spans. Set on the voice end-of-call `invoke_agent` span. |

## Model and provider

| Key | Type | Spans | Meaning | Example | Absent when |
| - | - | - | - | - | - |
| `gen_ai.request.model` | string | L, V | The model id Elementum asked for. Also the second word of the `chat` span name. | `gpt-4o` | The model is not known. |
| `gen_ai.response.model` | string | L | The same value as `gen_ai.request.model`. It is not read from the provider's response. | `gpt-4o` | The model is not known. |
| `gen_ai.provider.name` | string | L, V | The AI provider the agent used, as named in Elementum. Realtime voice spans report `openai`. | `openai` | The provider is not known. |
| `llm.provider` | string | L, V | The same value as `gen_ai.provider.name`. | `openai` | Same as above. |
| `gen_ai.request.temperature` | double | L | Temperature configured on the agent. | `0.2` | Not configured on the agent. |
| `gen_ai.request.max_tokens` | int | L | Maximum reply length configured on the agent. | `4096` | Not configured on the agent. |

## Response and usage

| Key | Type | Spans | Meaning | Example | Absent when |
| - | - | - | - | - | - |
| `gen_ai.response.id` | string | L | The provider's id for the reply. | `chatcmpl-0000000000` | Streamed replies, or the provider sent no id. |
| `gen_ai.response.finish_reasons` | string\[] | L | Why the model stopped, as the provider reported it. | `["stop"]` | The provider reported no reason. |
| `gen_ai.usage.input_tokens` | int | L, V | Tokens in the prompt. On a voice end-of-call summary, the total for the call. | `1834` | The provider reported no usage. |
| `gen_ai.usage.output_tokens` | int | L, V | Tokens in the reply. | `212` | Same as above. |
| `gen_ai.usage.cache_read.input_tokens` | int | L, V | Prompt tokens served from the provider's prompt cache. | `1536` | No cache use was reported. |

## Content

| Key | Type | Spans | Meaning | Absent when |
| - | - | - | - | - |
| `gen_ai.input.messages` | string (JSON) | L, V | Every message sent to the model, in order. On a voice end-of-call summary, the call transcript. | No messages. |
| `gen_ai.output.messages` | string (JSON) | L, V | The model's reply. On a voice end-of-call summary, the agent's last reply. | The model returned no text and no tool call. |

Both values are JSON arrays of messages, sent as text. One message per object:

| Field | Meaning |
| - | - |
| `role` | `system`, `user`, `assistant`, or `tool`. |
| `content` | The message text. Empty for an assistant message that only calls tools. |
| `tool_calls` | On an assistant message, the tools the model asked for. Each has `id`, `function.name`, and `function.arguments`. |
| `tool_call_id` | On a tool message, the `id` of the tool call this message answers. |

Example `gen_ai.output.messages` for a reply that calls a tool:

```json theme={null}
[
  {
    "role": "assistant",
    "content": "",
    "tool_calls": [
      {
        "id": "call_1",
        "function.name": "searchRecords",
        "function.arguments": "{\"query\":\"open incidents\"}"
      }
    ]
  }
]
```

On LLM call spans, the tool call keys are the flat strings `function.name` and `function.arguments`. In voice transcripts, a tool call is an object with `id`, `type` set to `function`, and a nested `function` object that has `name` and `arguments`.

If Elementum cannot write the messages as JSON, the value is `serialization_error`.

## Agent and conversation

| Key | Type | Spans | Meaning | Example | Absent when |
| - | - | - | - | - | - |
| `gen_ai.agent.id` | string | A, V | Id of the Elementum agent. | `a0000000-0000-4000-8000-000000000001` | Never on `invoke_agent`. |
| `gen_ai.agent.name` | string | A, V | Name of the agent, as entered in Elementum. Also the second word of the `invoke_agent` span name. | `Support Assistant` | The agent has no name. |
| `gen_ai.agent.description` | string | A | Description of the agent, as entered. | `Answers questions about open incidents` | The agent has no description. |
| `gen_ai.conversation.id` | string | A, L, V | Id of the conversation. The same on every turn of one conversation. For a voice call through Elementum's voice provider, the call id. | `c0000000-0000-4000-8000-000000000001` | The turn has no conversation. |

## Tool

| Key | Type | Spans | Meaning | Example | Absent when |
| - | - | - | - | - | - |
| `gen_ai.tool.name` | string | T | Name of the tool the model called. | `searchRecords` | The tool was not found, or the run failed before it started. |
| `gen_ai.tool.type` | string | T | Always `function`. | `function` | Same as above. |
| `gen_ai.tool.call.id` | string | T | Id of the tool call. Matches an `id` in the previous `chat` span's `tool_calls`. | `call_1` | Same as above. |
| `gen_ai.tool.call.arguments` | string (JSON) | T | Arguments passed to the tool. | `{"query":"open incidents"}` | The call had no arguments. |
| `gen_ai.tool.call.result` | string | T | What the tool returned to the model. | `{"count":3}` | The tool returned nothing. |
| `input.value` | string | T | The same value as `gen_ai.tool.call.arguments`. | | Same as above. |
| `output.value` | string | T | The same value as `gen_ai.tool.call.result`. | | Same as above. |

When one `execute_tool` span covers several tool calls, these attributes describe one of them. See [Span tree](https://docs.elementum.io/administration/trace-forwarding/genai-tracing.md#span-tree).

## Elementum attributes

| Key | Type | Spans | Meaning | Example | Absent when |
| - | - | - | - | - | - |
| `elementum.source` | string | all | Marks a span produced by Elementum tracing. | `chronicle` | Rarely. |
| `elementum.action.status` | string | all | `SUCCESS` or `FAILURE`. | `SUCCESS` | Some failed tool runs carry only the `ERROR` status. |
| `elementum.error.type` | string | all | Class name of the error. | `java.util.concurrent.TimeoutException` | The span succeeded. |
| `elementum.error.message` | string | all | The error's message text. It can quote the model provider. | `Request timed out` | The span succeeded. |
| `elementum.action.has_events` | boolean | A, T, and others | `true` when the span carries span events. | `true` | No events. |
| `elementum.action.event_count` | int | A, T, and others | Number of span events recorded. | `4` | No events. |
| `elementum.trace.is_new` | boolean | V | `true` on `voice.realtime.call`, which starts a new trace. | `true` | Other spans. |

## Voice attributes

| Key | Type | Spans | Meaning | Example |
| - | - | - | - | - |
| `voice.call.id` | string | V | Id of the call. | `call-0000` |
| `voice.auth.session.id` | string | V | Id of the caller authentication session. | `d0000000-0000-4000-8000-000000000001` |
| `voice.call.analysis.summary` | string | `invoke_agent` (end-of-call) | The voice provider's summary of the call. PINs are masked. | `Caller asked about an order.` |
| `voice.realtime.transport` | string | realtime | How the call was connected. | |
| `voice.realtime.leg` | string | `voice.realtime.session` | `auth` for the authentication part of the call, `agent` for the agent conversation. | `agent` |
| `voice.realtime.response.status` | string | `voice.realtime.response` | `completed`, `interrupted`, `error`, `incomplete`, or `abandoned`. | `completed` |
| `voice.realtime.response.tool_calls` | int | `voice.realtime.response` | Tool calls in the reply. | `1` |
| `voice.realtime.response.duration_ms` | int | `voice.realtime.response` | Time from the start of the reply to its end, in milliseconds. | `2310` |
| `voice.realtime.response.interrupted` | boolean | `voice.realtime.response` | The caller spoke over the reply. | `false` |
| `voice.realtime.caller.duration_ms` | int | `voice.realtime.caller` | Length of the caller's turn, in milliseconds. | `1800` |
| `voice.realtime.caller.interrupted` | boolean | `voice.realtime.caller` | The caller interrupted the agent in this turn. | `false` |
| `voice.realtime.dictated.kind` | string | `voice.realtime.dictated` | `greeting`, `line`, or `reply`. | `greeting` |
| `voice.realtime.dictated.duration_ms` | int | `voice.realtime.dictated` | Length of the scripted line, in milliseconds. | `1200` |

## Attributes per span

| Span | Attributes |
| - | - |
| `invoke_agent` | `gen_ai.operation.name`, `openinference.span.kind`, `gen_ai.agent.id`, `gen_ai.agent.name`, `gen_ai.agent.description`, `gen_ai.conversation.id`, `elementum.*` |
| `chat` | `gen_ai.operation.name`, `openinference.span.kind`, model and provider, response and usage, content, `gen_ai.conversation.id`, `elementum.*` |
| `execute_tool` | `gen_ai.operation.name`, `openinference.span.kind`, tool attributes, `elementum.*` |
| Voice end-of-call `invoke_agent` | Agent, model, provider, usage, content, `voice.call.analysis.summary`, other `voice.*` keys, `elementum.*` |
| `voice.realtime.*` | Operation, model, provider, agent, conversation, and the `voice.realtime.*` keys listed above, plus `elementum.*` |

## Keys Elementum does not send

Some evaluation tools and older guides mention these keys. Elementum does not send them.

| Key | Use instead |
| - | - |
| `gen_ai.prompt`, `gen_ai.completion` | `gen_ai.input.messages`, `gen_ai.output.messages` |
| `gen_ai.system` | `gen_ai.provider.name` |
| `gen_ai.system_instructions` | The `system` message in `gen_ai.input.messages` |
| `gen_ai.tool.definitions` | Not available on these spans |
| `session.id`, `weave.thread_id` | `gen_ai.conversation.id` |
| `gen_ai.usage.prompt_tokens`, `gen_ai.usage.completion_tokens` | `gen_ai.usage.input_tokens`, `gen_ai.usage.output_tokens` |

Organization and environment ids are never attributes. To label spans, add resource attributes to the endpoint.

Next: [Evaluating AI with traces](https://docs.elementum.io/administration/trace-forwarding/evaluating-ai.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.