Configuration

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.

Variable	Default	Description
`TRACECTRL_ENDPOINT`	`http://localhost:4317`	OTel Collector gRPC endpoint
`TRACECTRL_SERVICE_NAME`	`tracectrl-agent`	Service name for spans
`TRACECTRL_API_KEY`	—	Bearer token for authenticated collectors
`TRACECTRL_BATCH_DELAY_MS`	`1000`	Batch export delay in milliseconds
`TRACECTRL_MAX_BATCH_SIZE`	`512`	Maximum spans per export batch
`TRACECTRL_FAIL_SILENTLY`	`true`	Suppress exporter errors
`TRACECTRL_SESSION_ID`	—	Override auto-generated session ID
`TRACECTRL_API_URL`	`http://localhost:8000`	Engine HTTP base — used to fetch Protector Plus config

Platform Environment Variables

These are used by the TraceCtrl Engine and Docker stack, not the SDK:

Variable	Default	Description
`CLICKHOUSE_HOST`	`localhost`	ClickHouse host (`clickhouse` in Docker)
`CLICKHOUSE_PORT`	`9000`	ClickHouse native protocol port
`CLICKHOUSE_DB`	`tracectrl`	ClickHouse database name
`PIPELINE_INTERVAL_SECONDS`	`60`	Pipeline processing interval
`VITE_ENGINE_URL`	`http://localhost:8000`	Engine 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())

Getting Started

SDK

Framework Instrumentors

Security

Platform

Programmatic Configuration

Parameters

Environment Variables

Platform Environment Variables

Tagging Agents

TracerProvider

​Programmatic Configuration

​Parameters

​Environment Variables

​Platform Environment Variables

​Tagging Agents

​TracerProvider

Programmatic Configuration

Parameters

Environment Variables

Platform Environment Variables

Tagging Agents

TracerProvider