Unified trace table schema reference

The unified trace table follows the OpenTelemetry span data model. Each row is one span. The table is clustered by time.

Column Description Type
record_id Unique identifier for this table row. STRING
time Timestamp when the span was recorded. TIMESTAMP
date UTC date when the span was recorded. Useful for partition pruning. DATE
service_name Name of the Unity Gateway service (endpoint name). STRING
service_id Identifier for the service named in service_name. STRING
trace_id Identifier shared by all spans in a single request tree. Filter on this to reconstruct a full trace. STRING
span_id Unique identifier for this span. STRING
trace_state OpenTelemetry tracestate header value, if present. STRING
parent_span_id span_id of the parent span. NULL for root spans (one per request). STRING
flags OpenTelemetry trace flags bitmask. INT
name Human-readable span name, for example my-endpoint-mlflow/v1/chat/completions. STRING
kind Span kind: SPAN_KIND_SERVER (root, one per request) or SPAN_KIND_CLIENT (downstream call). STRING
start_time_unix_nano Span start time in nanoseconds since Unix epoch. BIGINT
end_time_unix_nano Span end time in nanoseconds since Unix epoch. BIGINT
attributes Span attributes as a VARIANT object. Key names contain dots; use backtick syntax to access them: attributes:\enduser.id``. See Key attributes below. VARIANT
dropped_attributes_count Number of attributes dropped due to limits. INT
events Array of timed events within the span. The primary event type is policy_evaluated, which records per-policy evaluation detail. See Policy evaluation events. ARRAY<STRUCT>
dropped_events_count Number of events dropped due to limits. INT
links Array of links to other spans or traces. ARRAY<STRUCT>
dropped_links_count Number of links dropped due to limits. INT
status Span status with code (STATUS_CODE_OK or STATUS_CODE_ERROR) and optional message. STRUCT
resource Resource attributes describing the instrumented entity, for example service.name and SDK metadata. STRUCT
resource_schema_url Schema URL for the resource semantic conventions. STRING
instrumentation_scope Name and version of the instrumentation library that produced the span. STRUCT
span_schema_url Schema URL for the span semantic conventions. STRING

The table also carries columns needed for its physical optimization, notably clustering, that are not useful for queries. These columns are named with an _ prefix. Treat them as implementation details that may change in future versions.

Key attributes

The attributes column is a VARIANT. Access fields using backtick syntax for keys that contain dots: attributes:\gen_ai.request.model``. The keys present depend on whether the span is a model service (LLM) call or an MCP service call.

Model service (LLM) spans:

Attribute Description
databricks.api_type Inbound API type, for example openai/v1/responses.
enduser.id User or service principal that made the request.
databricks.requester_type Requester type, for example USER.
databricks.request_id Azure Databricks-generated request ID.
databricks.url Full request URL.
databricks.latency_ms End-to-end request latency in milliseconds.
databricks.time_to_first_byte_ms Time to first byte in milliseconds.
databricks.action Attempt type, for example initial_attempt or retry.
databricks.destination_id Target model, for example databricks-claude-sonnet-4-6.
databricks.outcome success or failure.
gen_ai.operation.name Operation, for example chat.
gen_ai.request.model Requested model.
gen_ai.provider.name Provider, for example databricks.
gen_ai.usage.input_tokens Input tokens consumed.
gen_ai.usage.output_tokens Output tokens generated.
http.response.status_code HTTP status code.
error.type Error type on failures, for example invalid_request.
mlflow.chat.tokenUsage Detailed token usage as a JSON string.
mlflow.spanInputs Serialized request payload.
mlflow.spanOutputs Serialized response payload (empty on failure).

MCP service spans:

Attribute Description
mcp.method.name MCP method, for example tools/list or tools/call.
gen_ai.operation.name Operation, for example execute_tool for tools/call.
gen_ai.tool.name Name of the tool being invoked, for example atlassianUserInfo.
gen_ai.tool.call.arguments Extracted tool arguments, as a JSON string.
gen_ai.tool.call.result Extracted tool result, as a JSON string.
databricks.requester_type Requester type, for example USER.
databricks.request_id Azure Databricks-generated request ID.
databricks.tool.connection_type MCP connection type, for example EXTERNAL_MCP.
tool_source Backing connection or managed MCP server name, for example main.default.gh-conn (external) or code_interpreter (managed). The MCP service name is in the service_name column.
tool_type Tool type, for example external_connection.
workspace_id Workspace ID.
enduser.id User or service principal that made the request.
http.response.status_code HTTP status from the MCP call.
rpc.response.status_code JSON-RPC status code, for example -32003. The primary MCP failure signal.
error.type Failure classification, for example policy_deny, upstream_error, or internal_error.
mlflow.spanType Span type. TOOL for MCP spans. Useful for WHERE filtering.
mlflow.spanInputs Serialized JSON-RPC request.
mlflow.spanOutputs Serialized MCP/JSON-RPC response.

Policy enforcement attributes (model service and MCP service spans):

When a policy blocks a request, the server span (the root span) sets the following scalar attributes. Because they are set only when a policy short-circuits the request, they also serve as a quick filter for "did any policy block this request?"

Attribute Description
databricks.policy.name The policy that blocked the request. The Unity Catalog function FQN for a custom policy, or the attachment label for a built-in policy. <unknown> if the policy is unnamed.
databricks.policy.action Enforced action, either DENY or ASK.

Policy evaluation events

The events column holds an array of policy_evaluated events, one per evaluated (policy, phase) pair. This is where per-policy detail lives, beyond the scalar databricks.policy.* attributes on the server span. Each event carries the following keys:

Key Description
policy.name Name of the evaluated policy.
policy.type Policy type, either CUSTOM or BUILTIN.
policy.handler Handler for the policy. Built-in policies only.
policy.options Handler options. Built-in policies only.
policy.action Evaluated action, one of ALLOW, DENY, or ASK.
policy.phase Evaluation phase, either on_call or on_result. Custom policies only.

When a policy runs in dry-run (monitor or shadow) mode with dry_run=true, the enforced action is downgraded to ALLOW so the request proceeds, and the would-be verdict is recorded on the same event:

Key Description
policy.dry_run_action The action that would have been enforced, for example DENY. Its presence signals the policy ran in dry-run mode.
policy.dry_run_reason Reason for the would-be action.
policy.dry_run_transformed_message The payload a would-be transform or mask policy would have written.
  • Last updated on