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

# Framework Attribute Mapping

> How attributes from OTel GenAI, OpenInference, and Traceloop map to HoneyHive canonical schema keys

If you're already instrumented with OpenTelemetry, OpenInference, or Traceloop and want to know where your attributes land in HoneyHive's schema, this is the page to consult. Use it to look up which `bucket.key` to query and to understand how HoneyHive normalizes across ecosystems.

<Note>
  OTel GenAI columns are pinned to **semantic conventions v1.36** (stable release). Attributes introduced in v1.37 are noted inline.
</Note>

***

## How to read this matrix

Each section covers one concept group. Columns are:

| Column                  | Instrumentation source                                                                                                                                                 |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **OTel GenAI**          | Official OpenTelemetry GenAI semantic conventions (v1.36+)                                                                                                             |
| **OpenInference**       | Arize AI OpenInference instrumentation (`openinference-*` packages)                                                                                                    |
| **Traceloop**           | Traceloop OpenLLMetry (`opentelemetry-instrumentation-*` packages)                                                                                                     |
| **HoneyHive canonical** | Destination key in HoneyHive schema (`bucket.key` notation; see [Semantic Convention Reference](/v2/sdk-reference/semconv-reference) for the full seven-bucket schema) |

A `-` in a source column means no standard attribute exists in that ecosystem for this concept. Where HoneyHive canonical also shows `-`, the attribute is a **confirmed gap** and must be set manually.

***

## Span / Operation Kinds

Each ecosystem classifies spans by type (LLM call, tool call, agent step, chain, etc.) using a different attribute:

| Ecosystem           | Span kind attribute       | Common values                                             |
| ------------------- | ------------------------- | --------------------------------------------------------- |
| OTel GenAI v1.37+   | `gen_ai.agent.type`       | `llm`, `tool`, `agent`                                    |
| OpenInference       | `openinference.span.kind` | `LLM`, `TOOL`, `AGENT`, `CHAIN`, `RETRIEVER`, `EMBEDDING` |
| Traceloop           | `traceloop.span.kind`     | `llm`, `tool`, `agent`, `task`, `workflow`                |
| HoneyHive canonical | `metadata.span_kind`      | normalized from whichever is present                      |

**Why this matters for attribute routing:** Tool attributes (`config.tool_name`, `config.tool_description`, `metadata.tool_call_id`) are surfaced in HoneyHive's Tool section only on spans classified as tool calls. If these attributes are missing in the UI, check that your instrumentation sets the span kind correctly.

**Pure OTel v1.36 tool spans:** OTel v1.36 has no `gen_ai.agent.type` attribute. If you're on pure OTel v1.36, `gen_ai.tool.*` attributes are still captured and mapped to their canonical destinations (`config.tool_name`, etc.), they just won't have a `metadata.span_kind` set, since there is no source attribute to derive it from. The `gen_ai.agent.type` attribute arriving in v1.37 will give OTel parity with OpenInference and Traceloop for span kind classification.

***

## Token Counts

| Attribute                  | OTel GenAI                                                                                            | OpenInference                                                      | Traceloop                                                          | HoneyHive canonical                                        |
| -------------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------ | ---------------------------------------------------------- |
| Input / prompt tokens      | `gen_ai.usage.input_tokens` (v1.36+, preferred)<br />`gen_ai.usage.prompt_tokens` (legacy alias)      | `llm.token_count.prompt`<br />`gen_ai.usage.prompt_tokens`         | `llm.token_count.prompt`<br />`gen_ai.usage.prompt_tokens`         | `metadata.input_tokens`<br />`metadata.prompt_tokens`      |
| Output / completion tokens | `gen_ai.usage.output_tokens` (v1.36+, preferred)<br />`gen_ai.usage.completion_tokens` (legacy alias) | `llm.token_count.completion`<br />`gen_ai.usage.completion_tokens` | `llm.token_count.completion`<br />`gen_ai.usage.completion_tokens` | `metadata.output_tokens`<br />`metadata.completion_tokens` |
| Total tokens               | - (derived by normalizer)                                                                             | `llm.token_count.total`<br />`gen_ai.usage.total_tokens`           | `llm.token_count.total`<br />`llm.usage.total_tokens`              | `metadata.total_tokens` (auto-computed if absent)          |
| Cache read tokens          | `gen_ai.usage.cache_read_input_tokens`                                                                | `gen_ai.usage.cache_read_input_tokens`                             | `gen_ai.usage.cache_read_input_tokens`                             | `metadata.cache_read_input_tokens`                         |
| Cache write tokens         | `gen_ai.usage.cache_write_input_tokens`                                                               | -                                                                  | `gen_ai.usage.cache_write_input_tokens`                            | `metadata.cache_write_input_tokens`                        |
| Reasoning tokens           | `gen_ai.usage.reasoning_tokens`                                                                       | `gen_ai.usage.reasoning_tokens`                                    | `gen_ai.usage.reasoning_tokens`                                    | `metadata.reasoning_tokens`                                |

<Note>
  `metadata.total_tokens` is auto-computed by the normalizer from `prompt_tokens + completion_tokens` (or `input_tokens + output_tokens`) when not explicitly set. It is the source for the **Total Tokens** stat in Session Summary.

  **Traceloop uses `llm.usage.total_tokens`.** The `llm.usage` prefix (instead of `gen_ai.usage`) is intentional in Traceloop's instrumentation, not a typo.
</Note>

***

## Model Identity

| Attribute           | OTel GenAI                                           | OpenInference                       | Traceloop                                    | HoneyHive canonical                                                      |
| ------------------- | ---------------------------------------------------- | ----------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------ |
| Request model       | `gen_ai.request.model`                               | `gen_ai.request.model`              | `gen_ai.request.model`<br />`llm.model_name` | `config.model`                                                           |
| Response model      | `gen_ai.response.model`                              | `gen_ai.response.model`             | `gen_ai.response.model`                      | `metadata.response_model`                                                |
| Resolved model name | -                                                    | `llm.model_name`                    | `llm.model_name`                             | `metadata.model_name`<br />`metadata.llm.model_name` (legacy dotted key) |
| Provider / system   | `gen_ai.system`<br />`gen_ai.provider.name` (v1.37+) | `gen_ai.system`<br />`llm.provider` | `gen_ai.system`<br />`llm.provider`          | `metadata.system`<br />`config.provider`                                 |
| Response ID         | `gen_ai.response.id`                                 | `gen_ai.response.id`                | `gen_ai.response.id`                         | `metadata.response_id`                                                   |

<Note>
  `metadata.model_name` is the resolved model name shown in the HoneyHive UI. The normalizer sets it from `config.model` (request model) as a fallback when no response model is available. Use `metadata.response_model` for the exact model returned by the API.

  **Provider / system mapping:** `gen_ai.system` (all three ecosystems) maps to `metadata.system`. `gen_ai.provider.name` (OTel v1.37+) and `llm.provider` (OpenInference/Traceloop) map to `config.provider`.
</Note>

***

## Finish Reason

| Attribute              | OTel GenAI                                                                  | OpenInference                    | Traceloop                                                                   | HoneyHive canonical                                                                     |
| ---------------------- | --------------------------------------------------------------------------- | -------------------------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| Finish reason (scalar) | First element of `gen_ai.response.finish_reasons` (extracted by normalizer) | `gen_ai.response.finish_reason`  | First element of `gen_ai.response.finish_reasons` (extracted by normalizer) | `metadata.finish_reason`                                                                |
| Finish reasons (array) | `gen_ai.response.finish_reasons`                                            | `gen_ai.response.finish_reasons` | `gen_ai.response.finish_reasons`                                            | `metadata.finish_reasons`<br />`metadata.response_finish_reasons` (OpenInference alias) |

<Note>
  OTel GenAI defines `gen_ai.response.finish_reasons` as a string array. HoneyHive extracts the first element into `metadata.finish_reason` for single-choice filtering and also stores the full array in `metadata.finish_reasons`. OpenInference's singular `gen_ai.response.finish_reason` maps directly to `metadata.finish_reason`.
</Note>

***

## Agent Context

| Attribute             | OTel GenAI                            | OpenInference                                                    | Traceloop                  | HoneyHive canonical                   |
| --------------------- | ------------------------------------- | ---------------------------------------------------------------- | -------------------------- | ------------------------------------- |
| Agent name            | `gen_ai.agent.name`                   | `gen_ai.agent.name`                                              | `gen_ai.agent.name`        | `metadata.agent_name`                 |
| Agent description     | `gen_ai.agent.description`            | `gen_ai.agent.description`                                       | `gen_ai.agent.description` | `metadata.agent_description`          |
| Agent ID              | `gen_ai.agent.id`                     | `gen_ai.agent.id`                                                | `gen_ai.agent.id`          | `metadata.agent_id`                   |
| Span / operation kind | - (`gen_ai.agent.type` in v1.37+)     | `openinference.span.kind` (`LLM`, `AGENT`, `TOOL`, `CHAIN`, ...) | `traceloop.span.kind`      | `metadata.span_kind`                  |
| Agent handoff context | - (gap - no cross-ecosystem standard) | - (gap)                                                          | - (gap)                    | - (gap - set manually via `metadata`) |

<Note>
  **Gap: agent handoff context.** None of the three ecosystems has a stable standard attribute for passing context between agents in a handoff (e.g., handoff reason, receiving agent name, continuation pointer). If you need this in HoneyHive, set it manually as arbitrary `metadata` sub-keys. A naming convention such as `metadata.handoff_reason` and `metadata.handoff_target_agent` is recommended for consistency.
</Note>

***

## Tool Linking

| Attribute        | OTel GenAI                | OpenInference             | Traceloop                 | HoneyHive canonical       |
| ---------------- | ------------------------- | ------------------------- | ------------------------- | ------------------------- |
| Tool name        | `gen_ai.tool.name`        | `gen_ai.tool.name`        | `gen_ai.tool.name`        | `config.tool_name`        |
| Tool description | `gen_ai.tool.description` | `gen_ai.tool.description` | `gen_ai.tool.description` | `config.tool_description` |
| Tool call ID     | `gen_ai.tool.call.id`     | `gen_ai.tool.call.id`     | `gen_ai.tool.call.id`     | `metadata.tool_call_id`   |
| Tool status      | `gen_ai.tool.status`      | `gen_ai.tool.status`      | `gen_ai.tool.status`      | `metadata.tool_status`    |

<Note>
  Tool call argument mapping (`gen_ai.tool.call.arguments` vs OpenInference `llm.tools.*`) is intentionally out of scope. The attribute structures are complex and framework-specific. See your framework's instrumentation docs for argument schema details: [OTel GenAI tool span spec](https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-spans/#tool-call-span), [OpenInference semantic conventions](https://github.com/Arize-ai/openinference/blob/main/spec/semantic_conventions.md#llm-span-attributes), [Traceloop OpenLLMetry instrumentation](https://www.traceloop.com/docs/openllmetry/tracing/manual).
</Note>

***

## Session / Conversation Context

| Attribute                 | OTel GenAI               | OpenInference | Traceloop       | HoneyHive canonical                                                                     |
| ------------------------- | ------------------------ | ------------- | --------------- | --------------------------------------------------------------------------------------- |
| Conversation / Session ID | `gen_ai.conversation.id` | `session.id`  | - (no standard) | `metadata.conversation_id`<br />root `session_id` (when set via `honeyhive.session_id`) |
| User ID                   | - (no standard)          | `user.id`     | - (no standard) | `metadata.user_id`                                                                      |

***

## Gaps Summary

The following concepts have no stable attribute in any of the three instrumentation ecosystems:

| Concept               | Recommended workaround                                                   |
| --------------------- | ------------------------------------------------------------------------ |
| Agent handoff context | Set manually: `metadata.handoff_reason`, `metadata.handoff_target_agent` |

***

## Related pages

* [Semantic Convention Reference](/v2/sdk-reference/semconv-reference) - full HoneyHive canonical schema with stability levels and UI behavior