Semantic Convention Reference - HoneyHive AI Docs

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:

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

`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.

Framework Attribute Mapping - how OTel GenAI, OpenInference, and Traceloop attributes map to the canonical schema above

​Canonical Event Schema

​Root Fields

​Seven Structured Buckets

​Stability Levels

​Reserved Attribute Reference

​Root Field Behaviors

​event_type

​event_name

​error

​start_time

​duration

​session_id

​parent_id

​Tree view, timeline view, and graph view

​inputs Bucket

​Well-known inputs sub-keys

​inputs.chat_history

​outputs Bucket

​Well-known outputs sub-keys

​Chat message rendering mode

​outputs.tool_calls.* (dot-notation keys)

​outputs.text

​Generic rendering mode

​config Bucket

​Well-known config sub-keys

​config.template

​metadata Bucket

​Well-known metadata sub-keys

​metadata.num_events and metadata.num_model_events

​metadata.total_tokens and metadata.cost

​metrics Bucket

​Well-known metrics sub-keys

​feedback Bucket

​user_properties Bucket

​UI Sideview Section Map

​Session Summary Panel

​Stability Policy

​Related pages

Canonical Event Schema

Root Fields

Seven Structured Buckets

Stability Levels

Reserved Attribute Reference

Root Field Behaviors

`event_type`

`event_name`

`error`

`start_time`

`duration`

`session_id`

`parent_id`

Tree view, timeline view, and graph view

`inputs` Bucket

Well-known `inputs` sub-keys

`inputs.chat_history`

`outputs` Bucket

Well-known `outputs` sub-keys

Chat message rendering mode

`outputs.tool_calls.*` (dot-notation keys)

`outputs.text`

Generic rendering mode

`config` Bucket

Well-known `config` sub-keys

`config.template`

`metadata` Bucket

Well-known `metadata` sub-keys

`metadata.num_events` and `metadata.num_model_events`

`metadata.total_tokens` and `metadata.cost`

`metrics` Bucket

Well-known `metrics` sub-keys

`feedback` Bucket

`user_properties` Bucket

UI Sideview Section Map

Session Summary Panel

Stability Policy

Related pages