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

# Configuration

> Configure the TraceCtrl SDK via code or environment variables

## Programmatic Configuration

Call `configure()` before calling any instrumentor's `.instrument()` method.

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

> [!NOTE]
>
> `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:

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

```python theme={"dark"}
from tracectrl.instrumentation.strands import StrandsInstrumentor

StrandsInstrumentor().instrument(tracer_provider=your_custom_provider)
```

> [!WARNING]
>
> When using a custom `TracerProvider`, you must manually add the security-enrichment processor to get TraceCtrl span attributes:
>
> ```python theme={"dark"}
> from tracectrl.processor import TraceCtrlSpanProcessor
> your_custom_provider.add_span_processor(TraceCtrlSpanProcessor())
> ```


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