> ## 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.
# Semantic Convention Reference
> Canonical HoneyHive attribute names, special attribute behaviors, and UI sideview rendering reference
HoneyHive stores every event in a fixed canonical schema. This page defines that schema, identifies which attributes trigger special platform behavior (different rendering, filtering, or aggregation), and maps canonical attributes to their UI sideview sections.
***
## Canonical Event Schema
Every event stored in HoneyHive has the following top-level structure. Root fields are stored directly on the event object. The seven buckets are nested objects.
### Root Fields
| Field | Type | Description |
| ------------ | ------ | -------------------------------------------------------------------- |
| `event_id` | string | Unique event identifier |
| `session_id` | string | Session grouping identifier; links all spans in one invocation |
| `project` | string | Project name; routes the event to the correct project |
| `source` | string | Environment tag: `"prod"`, `"dev"`, or `"staging"` |
| `event_type` | string | Event classification: `"model"`, `"tool"`, `"chain"`, or `"session"` |
| `event_name` | string | Human-readable span label |
| `error` | string | Error message if the traced function raised; null when no error |
| `parent_id` | string | Parent span ID for hierarchical trace rendering |
| `start_time` | number | Span start timestamp (Unix ms) |
| `end_time` | number | Span end timestamp (Unix ms) |
| `duration` | number | Wall-clock duration in milliseconds |
### Seven Structured Buckets
| Bucket | Type | Purpose |
| ----------------- | ------ | ----------------------------------------------------------------------- |
| `inputs` | object | Input data: prompts, queries, messages passed into the span |
| `outputs` | object | Output data: completions, responses, results from the span |
| `config` | object | Model or tool configuration: model name, temperature, max\_tokens, etc. |
| `metadata` | object | Operational data: framework info, response IDs, token counts |
| `metrics` | object | Scalar performance metrics: latency, token counts, evaluation scores |
| `feedback` | object | Human or automated feedback annotations |
| `user_properties` | object | Per-user profile attributes |
Any OTLP or REST attribute that does not match a known canonical field is routed to `metadata` by default.
***
## Stability Levels
| Level | Meaning |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **stable** | Part of the public API. Breaking changes require a major version bump and a migration guide. Safe to reference in evaluator configuration, dashboards, and saved filters. |
| **development** | May change name, type, or semantics in minor releases. Do not configure evaluators, dashboards, or automation against development attributes. |
If an attribute is absent from this reference, treat it as development-level stability.
***
## Reserved Attribute Reference
Reserved attributes have pre-set platform behavior regardless of how they are set — via the HoneyHive SDK, REST API, or OTLP ingestion. Each entry describes what the platform does differently when the attribute is present.
### Root Field Behaviors
#### `event_type`
Controls icon, color coding, and available actions in the sideview header.
| Value | Icon | Color | Additional UI behavior |
| --------------------------- | ----------- | ------ | ------------------------------------------------------------- |
| `session` or `conversation` | Network | Purple | Shows Session Summary panel and Composite Evaluations section |
| `model` or `completion` | Sparkles | Blue | Shows "Open in Playground" button |
| `tool` | Wrench | Red | Standard sideview layout |
| `chain` or `generic` | Link/Braces | Gray | Standard sideview layout |
**Stability:** stable
#### `event_name`
Displayed as the span title in the sideview header alongside the `event_type` icon.
**Stability:** stable
#### `error`
When non-null and non-empty, renders a red error panel at the top of the Output section in the sideview. The error string is JSON-stringified before display.
**Stability:** stable
#### `start_time`
Children within a session are sorted by `start_time` ascending before trace tree rendering. Also displayed as the event timestamp in the table and sideview header.
**Stability:** stable
#### `duration`
Displayed as the "Latency" column in the events table. Computed automatically as `end_time - start_time` if not set explicitly.
**Stability:** stable
#### `session_id`
Used to fetch the full session tree when a sideview is opened. Enables the tree, timeline, and graph views. Cached by the sideview via an LRU cache keyed on session\_id.
**Stability:** stable
#### `parent_id`
Used to determine sibling relationships in the trace tree (controls prev/next navigation between sibling spans).
**Stability:** stable
#### Tree view, timeline view, and graph view
All three session visualization views (tree list, timeline, and graph) exclusively read root fields. No bucket sub-keys are used. The fields consumed are:
| Field | Usage |
| ------------ | --------------------------------------------------------------------------------------- |
| `event_type` | Icon and color coding per node |
| `event_name` | Node label |
| `event_id` | Node key and linking |
| `duration` | Duration badge on each node |
| `error` | Success/error indicator (green checkmark vs red X) |
| `start_time` | Children sorted ascending by start\_time before rendering; used in timeline positioning |
| `parent_id` | Sibling detection for prev/next navigation |
The graph view tooltip additionally shows `event_type`, `start_time`, `duration`, and `error` inline.
***
### `inputs` Bucket
#### Well-known `inputs` sub-keys
| Sub-key | Description |
| ---------------- | ---------------------------------------------------------------------------- |
| `chat_history` | Message thread array; triggers Chat History tab (see below) |
| `messages` | Raw messages array; used by frameworks that do not use `chat_history` naming |
| `query` | Search or retrieval query string |
| `chunks` | Retrieved document chunks (RAG pipelines) |
| `nodes` | Retrieved nodes (LlamaIndex / graph RAG) |
| `parameters` | Function or tool call parameters |
| `tool_arguments` | Tool call arguments, alternative to `parameters` |
| `tool_name` | Name of the tool being called |
| `user_message` | Raw user message string |
| `system_context` | System context string (non-template format) |
| `user_id` | User identifier embedded in inputs |
| `session_id` | Session identifier embedded in inputs |
#### `inputs.chat_history`
The single most special sub-key in the schema. When present:
* A **"Chat History" tab** appears in the Input section of the sideview (blue tab with chat icon).
* `inputs.chat_history` is **excluded** from the general "Inputs" key-value view (`cleanInputs` strips it).
* The Chat History tab renders the array using `OpenAIChatRenderer`.
* If `config.template` is also present (see below), the first `template.length` messages in `chat_history` are rendered as template messages with `{{variable}}` substitution; remaining messages are rendered normally.
* When both non-chat inputs and `chat_history` exist, the sideview defaults to showing the Chat History tab.
* When only non-chat inputs exist (no `chat_history`), the sideview defaults to showing the Inputs tab.
Expected format: array of message objects with at minimum a `role` field and one of `content`, `value`, `tool_calls`, or `function_call`.
**Stability:** stable
***
### `outputs` Bucket
The sideview uses the presence of specific sub-keys to select a rendering mode.
#### Well-known `outputs` sub-keys
| Sub-key | Description | Chat rendering mode |
| --------------- | ----------------------------------------------------------------------------------- | --------------------------------------------------- |
| `role` | Speaker role (`user`/`assistant`/`system`/`tool`); presence triggers chat rendering | Required to enter chat mode |
| `content` | Text content of the message; rendered as markdown | Rendered as markdown |
| `value` | Alternative to `content`; rendered as markdown | Rendered as markdown when `content` absent |
| `tool_calls` | Array of tool call objects | Each rendered as named JSON block |
| `function_call` | Legacy OpenAI function call object (`name` + `arguments`) | Rendered as named JSON block |
| `name` | Message author name | Used as speaker label supplement |
| `chat_history` | Array of messages; first element rendered when `role` absent | Triggers chat mode when `role` absent |
| `message` | Message object (nested); some frameworks wrap the output message in this key | Rendered as nested object |
| `result` | Generic result string for tool/agent outputs | No chat rendering; generic markdown/JSON view |
| `author` | Agent author identifier (Google ADK multi-agent) | Generic key-value in non-chat mode |
| `invocation_id` | Invocation identifier (Google ADK) | Generic key-value in non-chat mode |
| `text` | Text string; when present, used as output value instead of full `outputs` object | Bypasses bucket entirely |
| `finish_reason` | Model finish reason stored directly in outputs (some frameworks) | Generic key-value |
| `status` | Status string for tool or agent outputs | Generic key-value |
| `error` | Error string from the traced function (also mirrored in root `error` field) | Generic key-value; red panel shown via root `error` |
| `choices` | Raw API response choices array (OpenAI-format) | Generic key-value; not rendered in chat mode |
| `tool_call_id` | Tool call identifier (present on tool result spans) | Generic key-value |
#### Chat message rendering mode
Within chat message rendering mode, individual message fields are handled as follows:
| Field | Rendering |
| -------------------- | ---------------------------------------------------------------------------------------- |
| `content` | Rendered as markdown (truncated at 400 chars with expand) |
| `value` | Rendered as markdown; fallback when `content` is absent |
| `tool_calls` (array) | Each tool call rendered as a named JSON block |
| `function_call` | Object with `name` and `arguments`; arguments parsed as JSON and rendered as named block |
| `role` | Used as the speaker label (capitalized) |
| `name` | Message author name |
If a message object contains keys with `.` in them (non-standard dot-notation fields such as `tool_calls.0.id`), the entire message is rendered as raw JSON instead of the structured chat layout.
**Stability of `outputs.role`:** stable\
**Stability of `outputs.chat_history`:** stable
#### `outputs.tool_calls.*` (dot-notation keys)
When `outputs.role` is present and the outputs object contains flattened dot-notation keys like `tool_calls.0.id`, `tool_calls.0.function.name`, etc., the sideview reconstructs a proper `tool_calls` array before rendering. The reconstruction logic:
1. Collects all keys starting with `tool_calls.`
2. Groups by index (second segment after split on `.`)
3. Builds an array of tool call objects; `arguments` values are JSON-parsed
**Stability:** stable
#### `outputs.text`
When `outputs.text` exists, that string is used as the output value instead of the full `outputs` object. The text is then rendered in the standard markdown/JSON toggle view.
**Stability:** stable
#### Generic rendering mode
When neither `outputs.role` nor `outputs.chat_history` is present, the output renders in a markdown/JSON toggle view. Users can switch between markdown rendering and raw JSON rendering via a dropdown.
***
### `config` Bucket
The `config` bucket holds model and tool configuration. The sub-keys below are produced by the normalizer from various framework attributes. All are rendered as generic key-value pairs in the "Configuration" sideview section, except `config.template`.
#### Well-known `config` sub-keys
| Sub-key | Description |
| --------------------- | ---------------------------------------------------------------------------- |
| `model` | Model identifier used for the call |
| `provider` | Provider name (`openai`, `anthropic`, `bedrock`, `google`, etc.) |
| `temperature` | Sampling temperature |
| `max_tokens` | Max output token limit |
| `max_output_tokens` | Max output tokens (Google GenAI / Vertex AI variant of `max_tokens`) |
| `top_p` | Top-p sampling parameter |
| `top_k` | Top-k sampling parameter |
| `frequency_penalty` | Frequency penalty |
| `presence_penalty` | Presence penalty |
| `stop_sequences` | Stop sequences array |
| `seed` | Random seed |
| `reasoning_effort` | Reasoning effort level |
| `system` | Provider system field (e.g., `"openai"`, `"anthropic"`) |
| `system_instructions` | System instructions prepended to the prompt (modern format) |
| `system_instruction` | System instruction string, older format used by pydantic-ai and Google GenAI |
| `tools` | Tool/function definitions array available to the model |
| `destination` | Messaging destination, set for messaging-system spans |
| `template` | Prompt template; triggers special sideview rendering (see below) |
`config.model` and `config.provider` are also read by the Playground when loading an event for replay.
#### `config.template`
When `config.template` is an array of prompt template objects (each with `role` and `content`), the sideview renders a **Template** section above the chat history. Template messages are rendered via `SideviewChatTemplateRenderer`, which:
* Displays each message with its `role` as a label.
* Finds `{{variableName}}` placeholders in `content` using the regex `/{{(.*?)}}/g`.
* Substitutes each placeholder with the matching key from `inputs` (non-chat-history inputs), highlighted in a blue badge.
* Truncates content at 400 characters with a "Show more" / "Show less" toggle.
The `template.length` also controls how many messages in `inputs.chat_history` are skipped by the main `OpenAIChatRenderer` (they are already shown as template messages above).
`config.template` can also be an object with `name`, `version`, and `content` sub-keys (from `honeyhive_prompt_template.template.*`), in which case it is rendered as a generic key-value block.
**Stability:** stable
***
### `metadata` Bucket
Most `metadata` sub-keys render as generic key-value pairs in the "Metadata" sideview section. The table below lists well-known canonical sub-keys produced by the normalizer, followed by the sub-keys that have additional platform treatment.
#### Well-known `metadata` sub-keys
**Agent and model identity**
| Sub-key | Description |
| ------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `agent_name` | Agent name |
| `agent_description` | Agent description |
| `agent_id` | Agent identifier |
| `model_name` | Resolved model name (response model, if available; otherwise request model) |
| `llm.model_name` | Legacy dotted model name key; set by older OpenInference instrumentation alongside `model_name`; both are stored |
| `provider` | Provider name (`openai`, `anthropic`, `bedrock`, `google`, etc.) |
| `system` | Provider system string (mirrors `provider`; set from `gen_ai.system`) |
| `span_kind` | Instrumentor span kind string (`LLM`, `AGENT`, `TOOL`, `CHAIN`, etc.) |
| `operation_name` | Operation name |
| `conversation_id` | Conversation identifier |
| `request_type` | LLM request type (`chat`, `completion`, `embedding`, etc.) |
| `event_id` | Internal event ID copy set from tool call ID or GCP ADK event ID |
| `event_type` | Event type label (informational copy; does not override root `event_type`) |
| `event_name` | Event name label (informational copy; does not override root `event_name`) |
**Token counts**
| Sub-key | Description |
| ------------------------- | ----------------------------------------------------------------------------------------------- |
| `prompt_tokens` | Input/prompt token count |
| `input_tokens` | OTel v1.36+ alias for `prompt_tokens`; both are stored when the source attribute is present |
| `completion_tokens` | Output/completion token count |
| `output_tokens` | OTel v1.36+ alias for `completion_tokens`; both are stored when the source attribute is present |
| `total_tokens` | Total token count; read by Session Summary (see below) |
| `cache_read_input_tokens` | Prompt cache read tokens (Anthropic models) |
| `reasoning_tokens` | Internal reasoning tokens consumed (o-series, Claude extended thinking) |
**Finish reasons**
| Sub-key | Description |
| ------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `finish_reason` | Scalar model finish reason (`stop`, `length`, `tool_calls`, etc.); first element of the finish reasons array |
| `finish_reasons` | Array of all model finish reasons |
| `response_finish_reasons` | Alias for `finish_reasons`; set alongside it by the OpenInference strategy for backwards compatibility |
**Response context**
| Sub-key | Description |
| --------------------------- | ------------------------------------------------------------------------------------------ |
| `response_id` | Model API response identifier |
| `response_model` | Model name as returned by the API response (may differ from request model due to aliasing) |
| `openai_api_base` | OpenAI-compatible API base URL |
| `openai_system_fingerprint` | OpenAI system fingerprint |
| `status_code` | HTTP status code of the underlying API call |
**Session-level aggregates** (set by normalizer on session events)
| Sub-key | Description |
| ------------------ | ----------------------------------------------------------------------- |
| `num_events` | Total child event count; shown as "Num of Events" in the sessions table |
| `num_model_events` | Model event count; shown as "Num of LLM Requests" in the sessions table |
| `has_feedback` | Boolean; `true` when the session has at least one feedback annotation |
| `cost` | Aggregated cost for the session; displayed as a stat in Session Summary |
**Latency** (note: set in `metadata` by the standard GenAI strategy; set in `metrics` by the Traceloop strategy; check both buckets)
| Sub-key | Description |
| ------------------------ | --------------------------------------------- |
| `latency_ms` | End-to-end request latency in milliseconds |
| `time_to_first_token_ms` | Time to first streaming token in milliseconds |
**Context identifiers**
| Sub-key | Description |
| ---------------------- | ---------------------------------------------------------------------------------------- |
| `session_id` | OTel session ID (informational; does not override root `session_id`) |
| `user_id` | User identifier |
| `run_id` | Evaluation run ID (HoneyHive dataset run) |
| `dataset_id` | Dataset ID (HoneyHive dataset) |
| `datapoint_id` | Datapoint ID within a dataset |
| `tool_call_id` | Tool call identifier |
| `disable_http_tracing` | Boolean; when true, HTTP spans emitted by the same trace are suppressed during ingestion |
**Multimodal**
| Sub-key | Description |
| ------------------ | --------------------------------------------------------- |
| `input_mime_type` | MIME type of the input (e.g., `image/jpeg`, `text/plain`) |
| `output_mime_type` | MIME type of the output |
**Tool / agent status**
| Sub-key | Description |
| ------------- | ---------------------------- |
| `tool_status` | Tool execution status string |
**Messaging**
| Sub-key | Description |
| ----------------------- | ------------------------------------------- |
| `messaging_destination` | Messaging system destination topic or queue |
**MCP (Model Context Protocol)**
| Sub-key | Description |
| ------------------ | ---------------- |
| `mcp_client_name` | MCP client name |
| `mcp_server_name` | MCP server name |
| `mcp_tool_name` | MCP tool name |
| `mcp_request_type` | MCP request type |
| `mcp_session_id` | MCP session ID |
**Google ADK**
| Sub-key | Description |
| --------------------------- | ------------------------------------------------------------ |
| `gcp.vertex.agent.event_id` | Google ADK event ID (dotted key preserved as-is in metadata) |
**OTLP traceability** (set on every OTLP-ingested event)
| Sub-key | Description |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `trace_id` | Original OTel trace ID (hex string) |
| `span_id` | Original OTel span ID (hex string) |
| `parent_span_id` | Original OTel parent span ID (hex string); used for tree reconstruction before `parent_id` is resolved |
| `instrumentor` | Detected instrumentation library (`openinference`, `traceloop`, `aws-strands`, `google-adk`, `standardgenai`, etc.) |
| `has_otlp_lineage` | Always `true` on OTLP-ingested events; signals the tree-builder to use span ID lineage instead of temporal containment for parent-child relationships |
| `honeyhive_event_type` | Preserved copy of the `honeyhive_event_type` source attribute when present (informational) |
#### `metadata.num_events` and `metadata.num_model_events`
`metadata.num_events` is shown as the "Num of Events" column in the sessions table and as the "Number of children" stat in Session Summary. `metadata.num_model_events` is shown as the "Num of LLM Requests" column in the sessions table. Both are initialized to `0` by the normalizer on session events.
**Stability:** stable
#### `metadata.total_tokens` and `metadata.cost`
`metadata.total_tokens` is displayed as the "Total Tokens" stat in Session Summary (parsed as integer). `metadata.cost` is displayed as the "Cost" stat (parsed as float, formatted as `$X.XXXX`). Both initialized to `0` / `0.1` by the normalizer on session events.
**Stability:** stable
***
### `metrics` Bucket
All sub-keys in `metrics` render in the "Automated Evaluations" section of the sideview. The following filtering rules apply:
* Keys with `null` values are **hidden**.
* Keys that match `humanEvalFields` (human annotation fields fetched separately) are **excluded** from Automated Evaluations and rendered instead under "Human Annotations".
* In the Session Summary panel, metrics are collected from all child events, grouped by `event_type`, and displayed as a grid. String values and arrays are **excluded** from this grid; only numeric and boolean primitives are shown.
* Keys ending in `_explanation` are **skipped** in both the Session Summary metrics and feedback aggregations.
#### Well-known `metrics` sub-keys
The following sub-keys are set by the ingestion pipeline for OTLP-ingested events. All other sub-keys are user-defined.
| Sub-key | Description |
| ------------------------ | ---------------------------------------------------------------------------- |
| `latency_ms` | End-to-end request latency in milliseconds, set by the Traceloop strategy |
| `time_to_first_token_ms` | Time to first streaming token in milliseconds, set by the Traceloop strategy |
The standard GenAI strategy routes `latency_ms` and `time_to_first_token_ms` to `metadata` instead of `metrics`. When querying these values, check both `metadata.latency_ms` and `metrics.latency_ms` depending on the instrumentor.
**Stability:** stable
***
### `feedback` Bucket
All sub-keys in `feedback` render in the "User Feedback" dropdown section of the sideview. In the Session Summary panel, feedback is collected from all child events and grouped by `event_type`. The same filtering rules as `metrics` apply: string values, arrays, and `_explanation`-suffixed keys are excluded from the summary grid.
**Stability:** stable
***
### `user_properties` Bucket
All sub-keys in `user_properties` render in the "User Properties" dropdown section of the sideview. No sub-keys have additional special behavior beyond this.
**Stability:** stable
***
## UI Sideview Section Map
The sideview panel renders canonical attributes into labeled sections in this order:
| Sideview Section | Canonical Attribute | Display Label | Special Notes |
| --------------------- | --------------------------- | ------------------------ | ----------------------------------------------------------------------------------------------------- |
| Event header | `event_type`, `event_name` | Icon + span title | Icon and color vary by event\_type |
| Event header | `event_id` | Event ID | Copyable on click |
| Event header | `start_time` | Timestamp | Formatted with local timezone |
| Input / Chat History | `inputs` | "Inputs" | Chat History tab shown when `inputs.chat_history` exists; `chat_history` key excluded from Inputs tab |
| Input / Chat History | `inputs.chat_history` | "Chat History" | Rendered as message thread via OpenAIChatRenderer |
| Output | `outputs` | "Output" or "Assistant:" | Chat rendering when `outputs.role` or `outputs.chat_history` present; markdown/JSON toggle otherwise |
| Error panel | `error` | "Error:" | Shown only when non-null and non-empty; red background |
| Human Annotations | `metrics` (human-eval keys) | "Human Annotations" | Keys in humanEvalFields list |
| Automated Evaluations | `metrics` | "Automated Evaluations" | Non-human-eval keys; null values hidden |
| Configuration | `config` | "Configuration" | Generic key-value; `config.template` triggers template rendering |
| User Feedback | `feedback` | "User Feedback" | Generic key-value dropdown |
| User Properties | `user_properties` | "User Properties" | Generic key-value dropdown |
| Metadata | `metadata` | "Metadata" | Generic key-value dropdown |
| Event JSON | All fields | "Event JSON" | Raw event JSON; `index` and `zOrder` keys excluded |
### Session Summary Panel
Shown only when `event_type === "session"`. Reads these specific attributes:
| Stat | Source Attribute | Notes |
| ------------------ | --------------------------------------------------------- | ------------------------------------------- |
| Number of children | `metadata.num_events` | Falls back to `events.length - 1` if absent |
| Model Events | Counted from child `event_type === "model"` | Live count, not stored |
| Success Rate | Percentage of child events with null `error` | Live count |
| Total Duration | Calculated from `start_time` / `end_time` across children | Not a stored attribute |
| Total Tokens | `metadata.total_tokens` | Parsed as integer |
| Cost | `metadata.cost` | Parsed as float; formatted as `$X.XXXX` |
***
## Stability Policy
| Level | Change policy |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **stable** | Breaking changes (rename, removal, type change) require a major version bump and a published migration guide. New stable attributes may be added in minor releases. |
| **development** | May change name, type, or semantics in minor releases. Do not configure evaluators, dashboards, or saved filters against development attributes. |
| **absent from this reference** | Treat as development-level stability. It may have been added by an auto-instrumentor or internal SDK path and carries no stability guarantee. |
***
## Related pages
* [Framework Attribute Mapping](/v2/sdk-reference/semconv-alignment) - how OTel GenAI, OpenInference, and Traceloop attributes map to the canonical schema above