Span Schema

Overview

Every span captured by TraceCtrl carries two layers of attributes:

OpenInference attributes — set by the framework instrumentor (LLM calls, tool names, I/O values)
TraceCtrl security attributes — set by the TraceCtrlSpanProcessor (agent identity, risk classification, session correlation)

TraceCtrl Security Attributes

These are the tracectrl.* attributes added to spans by the TraceCtrlSpanProcessor:

Attribute	Type	Description
`tracectrl.agent.id`	`string`	Unique agent identifier. Derived from framework metadata or agent name.
`tracectrl.agent.name`	`string`	Human-readable agent name.
`tracectrl.agent.role`	`string`	Agent’s role or purpose (e.g., “Researcher”, “Writer”). Set by user code; the SDK reserves the attribute but does not infer it.
`tracectrl.agent.framework`	`string`	Detected framework. Inferred from span naming conventions. One of: `strands`, `openclaw`, `agno`, `unknown`.
`tracectrl.session_id`	`string`	Session correlation ID. Groups related spans across a conversation. Falls back to Agno’s `session.id` if not explicitly set.
`tracectrl.caller.agent_id`	`string`	The agent that triggered this span (for multi-agent delegation).
`tracectrl.input.source`	`string`	Input provenance: `user`, `agent`, `external`, or `memory`.
`tracectrl.tool.category`	`string`	Risk category of the tool. See Tool Categories.
`tracectrl.tool.direction`	`string`	Tool data-flow direction: `input` (ingress), `output` (egress), or `internal`.
`tracectrl.tool.target`	`string`	Target resource of the tool call (e.g., URL, file path).
`tracectrl.memory.operation`	`string`	Memory operation type: `read` or `write`.
`tracectrl.memory.store_id`	`string`	Identifier of the memory/vector store.
`tracectrl.memory.write_provenance`	`string`	Origin of data being written to memory (mirrors the producing span’s `input.source`).
`tracectrl.system_prompt_hash`	`string`	SHA-256 hash (first 16 hex chars) of the system prompt. Used for prompt drift detection.
`tracectrl.span_sequence`	`string`	Monotonic counter per session, stamped at span end.
`tracectrl.ingress`	`boolean`	`true` when the span has no valid parent context (root-span / entry-point detection).
`tracectrl.trigger_type`	`string`	Inferred trigger for ingress spans: `email`, `upload`, `webhook`, `scheduled`, or `manual`.

Guardrail Span Attributes

When Protector Plus or an in-SDK LLM-judge guardrail evaluates a message, a dedicated tracectrl.guardrail.evaluation span is emitted. A tracectrl.guardrail.registered span is emitted once per enabled guardrail at startup.

Attribute	Type	Description
`tracectrl.guardrail.name`	`string`	Fully-qualified guardrail identifier (e.g., `protector_plus.pii`).
`tracectrl.guardrail.decision`	`string`	`pass`, `fail`, or `error`.
`tracectrl.guardrail.provider`	`string`	Provider, e.g. `protector_plus`.
`tracectrl.guardrail.judge_model`	`string`	Judge model identifier (e.g., `protector_plus:pii`).
`tracectrl.guardrail.severity`	`string`	Severity classification of the rule.
`tracectrl.guardrail.timing`	`string`	When the check ran: `pre_input` or `post_output`.
`tracectrl.guardrail.reason`	`string`	Short explanation of the verdict.
`tracectrl.guardrail.evidence`	`string`	Triggering message, truncated to 2048 chars.
`tracectrl.guardrail.response_json`	`string`	Full provider response payload, capped at 8KB.
`tracectrl.guardrail.evaluated_at`	`string`	ISO-8601 UTC timestamp of evaluation.
`tracectrl.guardrail.mode`	`string`	Registration-only: e.g. `monitoring`.
`tracectrl.guardrail.description`	`string`	Registration-only: human-readable rule description.
`tracectrl.guardrail.judge_prompt`	`string`	Registration-only: judge prompt template (in-SDK judges).
`tracectrl.guardrail.registered_at`	`string`	Registration-only: ISO-8601 timestamp.
`tracectrl.guardrail.health`	`string`	Registration-only: e.g. `active`.
`tracectrl.guardrail.health_reason`	`string`	Registration-only: reason for current health state.

OpenInference Attributes

These are set by the underlying framework instrumentors:

Attribute	Type	Description
`openinference.span.kind`	`string`	Span type: `AGENT`, `TOOL`, `LLM`, `CHAIN`, `RETRIEVER`, `EMBEDDING`.
`input.value`	`string`	Input to the operation (prompt, query, etc.).
`output.value`	`string`	Output from the operation (response, result).
`llm.model_name`	`string`	Model identifier (e.g., `gpt-4o`, `claude-sonnet-4-20250514`).
`llm.system`	`string`	System prompt text.
`llm.prompt_template.template`	`string`	Prompt template if used.
`tool.name`	`string`	Tool function name.
`tool.description`	`string`	Tool description string.
`tool.parameters`	`string`	Tool call parameters (JSON).
`retrieval.documents`	`string`	Retrieved documents (for retriever spans).

Schema Constants

Import attribute names as constants to avoid typos:

from tracectrl.schema import (
    # TraceCtrl security fields
    TC_AGENT_ID,
    TC_AGENT_NAME,
    TC_AGENT_ROLE,
    TC_AGENT_FRAMEWORK,
    TC_SESSION_ID,
    TC_CALLER_AGENT_ID,
    TC_INPUT_SOURCE,
    TC_TOOL_CATEGORY,
    TC_TOOL_DIRECTION,
    TC_TOOL_TARGET,
    TC_MEMORY_OPERATION,
    TC_MEMORY_STORE_ID,
    TC_MEMORY_WRITE_PROVENANCE,
    TC_SYSTEM_PROMPT_HASH,
    TC_SPAN_SEQUENCE,
    # Ingress detection
    TC_INGRESS,
    TC_TRIGGER_TYPE,
    # Standard OpenInference fields
    OI_SPAN_KIND,
    INPUT_VALUE,
    OUTPUT_VALUE,
    LLM_MODEL_NAME,
    LLM_SYSTEM,
    LLM_PROMPT_TEMPLATE,
    TOOL_NAME,
    TOOL_DESCRIPTION,
    TOOL_PARAMETERS,
    RETRIEVAL_DOCUMENTS,
)

The tracectrl.system_prompt_hash attribute enables prompt drift detection — if the hash changes between observations, the system prompt was modified. This is a key indicator for prompt injection attacks.

Getting Started

SDK

Framework Instrumentors

Security

Platform

Overview

TraceCtrl Security Attributes

Guardrail Span Attributes

OpenInference Attributes

Schema Constants

​Overview

​TraceCtrl Security Attributes

​Guardrail Span Attributes

​OpenInference Attributes

​Schema Constants

Overview

TraceCtrl Security Attributes

Guardrail Span Attributes

OpenInference Attributes

Schema Constants