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

<ParamField path="endpoint" type="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.
</ParamField>

<ParamField path="service_name" type="string">
  The service name attached to all spans. Appears in the `service.name` resource attribute. Defaults to `tracectrl-agent`.
</ParamField>

<ParamField path="api_key" type="string">
  Optional API key for authenticated collectors. Sent as a `Bearer` token in the `Authorization` header.
</ParamField>

<ParamField path="fail_silently" type="boolean">
  When `true`, exporter failures are logged as warnings instead of raising exceptions. Defaults to `true` — your agent never crashes because tracing fails.
</ParamField>

<Note>
  `configure()` accepts only the four kwargs above. Batch tuning (`TRACECTRL_BATCH_DELAY_MS`, `TRACECTRL_MAX_BATCH_SIZE`) is environment-only.
</Note>

## 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())
  ```
</Warning>