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

> ## Agent Instructions
> To act on Atlan objects, use the Atlan MCP server at https://api.atlan.com/mcp or the atlanai CLI; `atlanai --map json` prints its command map. Run a read-only identity check before any write.
> The docs MCP server at /mcp searches these docs only. It cannot read or change Atlan objects.
> SDK packages: Python `atlanai` (PyPI) and TypeScript `@atlanai/sdk` (npm). Show Python first, then TypeScript.

# 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://api.atlan.com` | 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](/tools/sdk/how-tos/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](/tools/sdk/how-tos/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}
atlanai: 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="/tools/sdk/how-tos/serverless">
    Immediate export, `waitUntil`, and Workers bundling.
  </Card>

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