> ## Documentation Index
> Fetch the complete documentation index at: https://www.botgauge.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Environment variables

> Every BotGauge and OpenTelemetry environment variable the tracing SDK reads, with defaults, which command reads each, and how they interact.

Arguments to `tracing.init()` win over these variables. In the **Read by** column, **Both** means `tracing.init()` and `botgauge instrument`. **instrument** means only the zero-code launcher reads the variable. With `init()`, use the matching argument instead.

## BotGauge variables

| Variable | Read by | Default | Effect |
| - | - | - | - |
| `BOTGAUGE_API_KEY` | Both | unset | Your BotGauge key, sent only as `Authorization: Bearer <key>`. The one setting you need. |
| `BOTGAUGE_ENDPOINT` | Both | `https://api.botgauge.com/v1/traces` when a key is set | Full OTLP/HTTP traces URL of the collector to send to. |
| `BOTGAUGE_CAPTURE` | instrument | `text` | `metadata`, `text`, or `full`. See [Capture and redaction](https://www.botgauge.com/docs/tracing/capture-and-redaction.md). |
| `BOTGAUGE_REDACTED` | instrument | `true` | `false` exports original content without masking, in every capture mode. It overrides `BOTGAUGE_CAPTURE`. |
| `BOTGAUGE_CAPTURE_ALLOW_KEYS` | Both | empty | Comma-separated extra attribute keys to keep. Globs are allowed, for example `app.tenant_tier,myco.*`. Merged with `capture_allow_keys=`. |
| `BOTGAUGE_TRACE_SCOPE` | Both | `filtered` | `all` exports infrastructure spans (HTTP, database) in full instead of filtering them. |
| `BOTGAUGE_STRICT` | instrument | off | `1` stops the app from starting on instrumentation problems. Same as `--strict`. |
| `BOTGAUGE_VERIFIED_ONLY` | instrument | off | `1` traces only framework versions BotGauge verified. |
| `BOTGAUGE_PRODUCER_OWNER` | instrument | empty | For example `langchain=customer` (comma-separated) leaves a framework you already instrument to you. |
| `BOTGAUGE_ALLOW_INSECURE_HTTP` | Both | `false` | `true` allows sending the key to a remote `http://` endpoint. Local addresses such as `127.0.0.1` need no opt-in. Prefer `https`. |
| `BOTGAUGE_CONSOLE_EXPORT` | Both | off | `1` prints spans to stdout when no key or endpoint is set. For local development only. |

## OpenTelemetry variables that affect BotGauge

BotGauge is built on the OpenTelemetry SDK, so some standard variables apply too. "When BotGauge creates the provider" means you called `tracing.init()` without `tracer_provider=` and no provider was set up yet. Otherwise your own provider's configuration applies.

| Variable | Effect on BotGauge |
| - | - |
| `OTEL_SDK_DISABLED=true` | Turns tracing off. No spans are recorded or exported, with or without your own provider. Use it to disable BotGauge in tests or one environment without changing code. |
| `OTEL_SERVICE_NAME`, `OTEL_RESOURCE_ATTRIBUTES` | Added to the exported resource when BotGauge creates the provider. |
| `OTEL_TRACES_SAMPLER`, `OTEL_TRACES_SAMPLER_ARG` | Apply when BotGauge creates the provider and `sample_ratio=` is not given, so a sampler set for another tool samples BotGauge's traces too. BotGauge prints a one-time warning at startup when it will drop traces, and `botgauge doctor` shows the active sampler. Pass `sample_ratio=1.0` to record everything regardless. |
| `OTEL_BSP_SCHEDULE_DELAY`, `OTEL_BSP_MAX_QUEUE_SIZE`, `OTEL_BSP_MAX_EXPORT_BATCH_SIZE`, `OTEL_BSP_EXPORT_TIMEOUT` | Tune the batching of BotGauge's own export. An unusable value is logged once on the `botgauge` logger and OpenTelemetry's default is used. |
| `OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT` and the other span limit variables | Apply when BotGauge creates the provider. Protected string values are already capped at 4096 characters. |
| `OTEL_PROPAGATORS` | Which headers carry trace context between services. BotGauge never replaces your propagator. See the note below. |
| `OTEL_EXPORTER_OTLP_*` | Ignored by BotGauge's exporter. They stay with your own exporters, which never receive the BotGauge key. |

> [!WARNING]
>
> With server or MCP instrumentation, a caller's `traceparent` sets the trace ID and, with the default sampler or `sample_ratio=` (both parent-based, while other samplers decide on their own), whether its request is recorded. For a service with untrusted callers, set `OTEL_PROPAGATORS=none` (OpenTelemetry 1.33 or newer). See the `botgauge-tracing` README section on public edges, and the OpenTelemetry SDK configuration docs for the values of this variable and the sampler variables.

## Logging

BotGauge reports problems, such as a rejected key, an invalid setting, or an untraced framework, as warnings on the standard Python logger named `botgauge`. Route or silence them like any other logger. For a full picture of what is active, use [`botgauge doctor`](https://www.botgauge.com/docs/reference/cli#botgauge-doctor).


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