Skip to main content
Management and tracing use separate clients. Passing a token to AtlanClient does not configure tracing, and calling init() does not configure management.

Management client

Pass configuration to AtlanClient explicitly. It does not read the tracing environment variables or a CLI sign-in. client.with_workspace(id) in Python and client.withWorkspace(id) in TypeScript return a client with a different default workspace and the same credentials and connections. An operation’s explicit workspace argument wins over the client default. Creates that require workspace_id in their body still need that field. The bearer credential determines the organization; workspace selection never grants access to another organization. Python clients support a with block or close(). Workspace copies share connection pools, so closing one closes the family. See Connect management client.

Tracing configuration

The following settings apply to atlanai.tracing.init() in Python and @atlanai/sdk/tracing’s init() in TypeScript.

Precedence

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

Environment variables

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.
Cloudflare Workers have no ambient environment, so none of these variables are readable there. Pass every value through init() options instead — see Serverless.

Export modes

init() resolves exactly one mode and logs which:

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.

Hard failure

Exporting to an Atlan endpoint with no workspace raises AtlanConfigError at 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

Common options also have environment variables above. The following options configure application behavior directly: init() reuses a client for the same pipeline identity: credential, export mode, destination URL, workspace, service name, and agent or harness subject. Changing one of these can create another client. Configure initialization in one place so imports do not create competing export pipelines. When a new client activates an integration, the options you passed for it under instrumentation replace the earlier ones; if you pass none, the earlier ones stay. The SDK reads them at each traced call, so a change applies from the next call. Changing the object you passed after init() does not change tracing, because the SDK keeps a copy.

Lifecycle

flush() exports everything buffered and returns when the request completes. It raises (rejects in TypeScript) if the export failed, after waiting up to ATLAN_TIMEOUT seconds; catch it in a request path and log export_health (exportHealth). See the quickstart. 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

See also