> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tracectrl.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Span Schema

> Complete reference for TraceCtrl span attributes

## Overview

Every span captured by TraceCtrl carries two layers of attributes:

1. **OpenInference attributes** — set by the framework instrumentor (LLM calls, tool names, I/O values)
2. **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](https://docs.tracectrl.ai/security/tool-categories.md). |
| `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:

```python theme={"dark"}
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,
)
```

> [!TIP]
>
> 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.