Skip to main content

​
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.
​
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.

​
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

​
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)

​
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 TraceCtrlSpanProcessor for security enrichment
If you need to pass a custom TracerProvider, you can skip configure() and pass it directly: 
from tracectrl.instrumentation.langchain import LangChainInstrumentor

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