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

# Configuration

> Options, environment variables, defaults, and the export modes the SDK resolves at init.

Both SDKs resolve configuration the same way, from the same environment
variable names, with the same defaults.

## Precedence

Explicit arguments to `init()` win, then `ATLAN_*` environment variables, then
the standard OTLP environment variables, then the built-in defaults.

## Environment variables

| Variable                  | Default                                  | What it does                                                     |
| ------------------------- | ---------------------------------------- | ---------------------------------------------------------------- |
| `ATLAN_API_KEY`           | —                                        | Registry API key. Its presence selects Atlan mode.               |
| `ATLAN_WORKSPACE_ID`      | —                                        | Destination workspace. Required in Atlan mode.                   |
| `ATLAN_BASE_URL`          | `https://agentgateway.atlan.engineering` | Gateway base URL.                                                |
| `ATLAN_ENVIRONMENT`       | —                                        | Free-form environment label recorded on the resource.            |
| `ATLAN_TRACING`           | `true`                                   | Master switch. `false` makes every operation a no-op.            |
| `ATLAN_TRACE_CONTENT`     | `true`                                   | `false` suppresses payload content. See [Privacy](/sdk/privacy). |
| `ATLAN_SAMPLE_RATE`       | `1.0`                                    | Fraction of traces to keep, `0.0`–`1.0`.                         |
| `ATLAN_FLUSH_AT`          | `64`                                     | Spans buffered before a batch exports.                           |
| `ATLAN_FLUSH_INTERVAL`    | `5.0`                                    | Seconds between background flushes.                              |
| `ATLAN_TIMEOUT`           | `30.0`                                   | Export request timeout in seconds.                               |
| `ATLAN_MAX_PAYLOAD_BYTES` | `1048576`                                | Per-payload ceiling (1 MiB).                                     |
| `ATLAN_DEBUG`             | `false`                                  | Verbose logging, and forces immediate per-span export.           |

Boolean variables accept `true`, `1`, or `yes`, case-insensitively. Anything
else reads as false. A non-numeric value in a numeric variable is ignored with
a warning and the default applies.

When no `ATLAN_API_KEY` is set, the SDK falls back to
`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` or `OTEL_EXPORTER_OTLP_ENDPOINT` and
behaves as a generic OTLP client.

<Warning>
  Cloudflare Workers have no ambient environment, so none of these variables
  are readable there. Pass every value through `init()` options instead — see
  [Serverless](/sdk/serverless).
</Warning>

## Export modes

`init()` resolves exactly one mode and logs which:

| Mode       | Selected when                                    | Behavior                                                         |
| ---------- | ------------------------------------------------ | ---------------------------------------------------------------- |
| `atlan`    | `ATLAN_API_KEY` is set                           | Exports to the Gateway with Atlan authentication headers.        |
| `otlp`     | no API key, but an OTLP endpoint variable is set | Generic collector mode, driven purely by `OTEL_EXPORTER_OTLP_*`. |
| `disabled` | neither, or a precondition failed                | Every operation is a no-op.                                      |

## When tracing disables itself

Misconfiguration degrades to `disabled` with a warning rather than breaking
your application. The SDK disables itself when:

* no API key and no OTLP endpoint are configured
* `service_name` is missing
* `base_url` is not `https` — plain `http` is allowed only for `localhost`,
  `127.0.0.1`, and `::1`

Because these are warnings, a misconfigured process starts and serves traffic
normally while reporting nothing. If traces are missing, check the startup logs
first.

## The one hard failure

Exporting to an Atlan endpoint with no workspace raises `AtlanConfigError` at
`init()`:

```text theme={null}
atlan_ai: a workspace is required when exporting to an Atlan endpoint.
Set ATLAN_WORKSPACE_ID or pass workspace_id= to init().
```

This is deliberate. Traces without a workspace land in `default` and are
effectively lost, so failing at startup is better than silently discarding
production telemetry.

## init() options

Every environment variable above has an equivalent option. These have no
environment equivalent:

| Option                                    | Language   | What it does                                                |
| ----------------------------------------- | ---------- | ----------------------------------------------------------- |
| `service_name` / `serviceName`            | both       | Names your agent. Required.                                 |
| `tracer_provider` / —                     | Python     | Use an existing provider instead of creating one.           |
| `span_exporter` / `spanExporter`          | both       | Replace the OTLP exporter, for tests or a custom transport. |
| `should_export_span` / `shouldExportSpan` | both       | Replace the export allowlist decision.                      |
| `mask`                                    | both       | Redact your own spans' payloads.                            |
| `mask_otel_spans` / `maskOtelSpans`       | both       | Patch whole export batches, including foreign spans.        |
| — / `isolated`                            | TypeScript | Never touch the global provider; run a private pipeline.    |
| — / `exportMode`                          | TypeScript | `"immediate"` exports per span; default `"batch"`.          |
| — / `waitUntil`                           | TypeScript | Hand background flush promises to the platform.             |

`init()` is idempotent per API key. Calling it again with the same key returns
the existing client rather than building a second pipeline — safe in a module
that may be imported more than once.

## Lifecycle

`flush()` exports everything buffered and resolves when the request completes.
`shutdown()` flushes and then tears the pipeline down; use it on final exit.
Long-lived services rely on the background batch and need neither.

## Next steps

<CardGroup cols={2}>
  <Card title="Serverless" icon="bolt" href="/sdk/serverless">
    Immediate export, `waitUntil`, and Workers bundling.
  </Card>

  <Card title="Privacy controls" icon="shield" href="/sdk/privacy">
    Content suppression, masking, and sampling.
  </Card>
</CardGroup>