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 |
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 |
event_type, start_time, duration, and error inline.
| 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 |
. 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
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:
- Collects all keys starting with
tool_calls.
- Groups by index (second segment after split on
.)
- 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
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.
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) |
| 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) |
| 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 |
| 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 |
| 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 |
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 |
| 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 |
| 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 |
| Sub-key | Description |
|---|
tool_status | Tool execution status string |
| Sub-key | Description |
|---|
messaging_destination | Messaging system destination topic or queue |
| 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 |
| Sub-key | Description |
|---|
gcp.vertex.agent.event_id | Google ADK event ID (dotted key preserved as-is in metadata) |
| 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 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 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.
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. |
