Skip to main content

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.

​
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:
AttributeTypeDescription
tracectrl.agent.idstringUnique agent identifier. Derived from framework metadata or agent name.
tracectrl.agent.namestringHuman-readable agent name.
tracectrl.agent.rolestringAgent’s role or purpose (e.g., “Researcher”, “Writer”). Set by user code; the SDK reserves the attribute but does not infer it.
tracectrl.agent.frameworkstringDetected framework. Inferred from span naming conventions. One of: strands, openclaw, agno, unknown.
tracectrl.session_idstringSession correlation ID. Groups related spans across a conversation. Falls back to Agno’s session.id if not explicitly set.
tracectrl.caller.agent_idstringThe agent that triggered this span (for multi-agent delegation).
tracectrl.input.sourcestringInput provenance: user, agent, external, or memory.
tracectrl.tool.categorystringRisk category of the tool. See Tool Categories.
tracectrl.tool.directionstringTool data-flow direction: input (ingress), output (egress), or internal.
tracectrl.tool.targetstringTarget resource of the tool call (e.g., URL, file path).
tracectrl.memory.operationstringMemory operation type: read or write.
tracectrl.memory.store_idstringIdentifier of the memory/vector store.
tracectrl.memory.write_provenancestringOrigin of data being written to memory (mirrors the producing span’s input.source).
tracectrl.system_prompt_hashstringSHA-256 hash (first 16 hex chars) of the system prompt. Used for prompt drift detection.
tracectrl.span_sequencestringMonotonic counter per session, stamped at span end.
tracectrl.ingressbooleantrue when the span has no valid parent context (root-span / entry-point detection).
tracectrl.trigger_typestringInferred 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.
AttributeTypeDescription
tracectrl.guardrail.namestringFully-qualified guardrail identifier (e.g., protector_plus.pii).
tracectrl.guardrail.decisionstringpass, fail, or error.
tracectrl.guardrail.providerstringProvider, e.g. protector_plus.
tracectrl.guardrail.judge_modelstringJudge model identifier (e.g., protector_plus:pii).
tracectrl.guardrail.severitystringSeverity classification of the rule.
tracectrl.guardrail.timingstringWhen the check ran: pre_input or post_output.
tracectrl.guardrail.reasonstringShort explanation of the verdict.
tracectrl.guardrail.evidencestringTriggering message, truncated to 2048 chars.
tracectrl.guardrail.response_jsonstringFull provider response payload, capped at 8KB.
tracectrl.guardrail.evaluated_atstringISO-8601 UTC timestamp of evaluation.
tracectrl.guardrail.modestringRegistration-only: e.g. monitoring.
tracectrl.guardrail.descriptionstringRegistration-only: human-readable rule description.
tracectrl.guardrail.judge_promptstringRegistration-only: judge prompt template (in-SDK judges).
tracectrl.guardrail.registered_atstringRegistration-only: ISO-8601 timestamp.
tracectrl.guardrail.healthstringRegistration-only: e.g. active.
tracectrl.guardrail.health_reasonstringRegistration-only: reason for current health state.

​
OpenInference Attributes

These are set by the underlying framework instrumentors:
AttributeTypeDescription
openinference.span.kindstringSpan type: AGENT, TOOL, LLM, CHAIN, RETRIEVER, EMBEDDING.
input.valuestringInput to the operation (prompt, query, etc.).
output.valuestringOutput from the operation (response, result).
llm.model_namestringModel identifier (e.g., gpt-4o, claude-sonnet-4-20250514).
llm.systemstringSystem prompt text.
llm.prompt_template.templatestringPrompt template if used.
tool.namestringTool function name.
tool.descriptionstringTool description string.
tool.parametersstringTool call parameters (JSON).
retrieval.documentsstringRetrieved 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.