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.

​
Programmatic Configuration

Call configure() before calling any instrumentor’s .instrument() method. 
import tracectrl

tracectrl.configure(
    endpoint="http://localhost:4317",
    service_name="my-agent-service",
    api_key="your-api-key",        # optional
    fail_silently=True,             # optional, default: True
)

​
Parameters

​
endpoint
string
The OTel Collector gRPC endpoint. Defaults to http://localhost:4317. Use http://otel-collector:4317 when your agent runs inside Docker. The SDK strips the scheme and routes via gRPC; https:// URLs switch the exporter to TLS, anything else uses insecure mode.
​
service_name
string
The service name attached to all spans. Appears in the service.name resource attribute. Defaults to tracectrl-agent.
​
api_key
string
Optional API key for authenticated collectors. Sent as a Bearer token in the Authorization header.
​
fail_silently
boolean
When true, exporter failures are logged as warnings instead of raising exceptions. Defaults to true — your agent never crashes because tracing fails.
configure() accepts only the four kwargs above. Batch tuning (TRACECTRL_BATCH_DELAY_MS, TRACECTRL_MAX_BATCH_SIZE) is environment-only.

​
Environment Variables

All configuration can also be set via environment variables. Programmatic values take precedence.
VariableDefaultDescription
TRACECTRL_ENDPOINThttp://localhost:4317OTel Collector gRPC endpoint
TRACECTRL_SERVICE_NAMEtracectrl-agentService name for spans
TRACECTRL_API_KEY—Bearer token for authenticated collectors
TRACECTRL_BATCH_DELAY_MS1000Batch export delay in milliseconds
TRACECTRL_MAX_BATCH_SIZE512Maximum spans per export batch
TRACECTRL_FAIL_SILENTLYtrueSuppress exporter errors
TRACECTRL_SESSION_ID—Override auto-generated session ID
TRACECTRL_API_URLhttp://localhost:8000Engine HTTP base — used to fetch Protector Plus config

​
Platform Environment Variables

These are used by the TraceCtrl Engine and Docker stack, not the SDK:
VariableDefaultDescription
CLICKHOUSE_HOSTlocalhostClickHouse host (clickhouse in Docker)
CLICKHOUSE_PORT9000ClickHouse native protocol port
CLICKHOUSE_DBtracectrlClickHouse database name
PIPELINE_INTERVAL_SECONDS60Pipeline processing interval
VITE_ENGINE_URLhttp://localhost:8000Engine API URL (baked into UI at build)

​
Tagging Agents

Most agent frameworks do not emit the system prompt on their OTEL spans. Call tag_agent once per agent so TraceCtrl can attribute spans to a named agent in the dashboard: 
import tracectrl
from tracectrl import tag_agent, tag_agents
from strands import Agent

tracectrl.configure(service_name="finflow")

orchestrator = Agent(name="orchestrator", system_prompt="...")
payment = Agent(name="payment", system_prompt="...")

# Single agent — auto-introspects system_prompt / system / instructions
tag_agent(orchestrator)

# Or bulk-tag several at once
tag_agents(orchestrator, payment)
tag_agent is idempotent and installs a SystemPromptStamper SpanProcessor on the shared TracerProvider so that every subsequent agent-run span carries tracectrl.agent.system_prompt and a 16-character SHA-256 hash.

​
TracerProvider

The SDK lazily creates a shared TracerProvider with:
  • An OTLP gRPC exporter pointed at your endpoint
  • A BatchSpanProcessor for async export (configurable batch size and delay)
  • The SystemPromptStamper for agent attribution
If you need to pass a custom TracerProvider, you can skip configure() and pass it directly: 
from tracectrl.instrumentation.strands import StrandsInstrumentor

StrandsInstrumentor().instrument(tracer_provider=your_custom_provider)
When using a custom TracerProvider, you must manually add the security-enrichment processor to get TraceCtrl span attributes:
from tracectrl.processor import TraceCtrlSpanProcessor
your_custom_provider.add_span_processor(TraceCtrlSpanProcessor())