Skip to main content

Telemetry

Atmos collects anonymous usage telemetry to help us understand how the tool is used and where to invest engineering effort. Telemetry is fully opt-out and never includes personal information, repository contents, or stack values. The settings.telemetry section gives you complete control over whether events are sent and where they go.

You will learn

  • Disable telemetry entirely with a single setting or environment variable
  • Override the endpoint and token to send events to your own collector
  • No user data, repository paths, or stack values are ever transmitted
  • Diagnostic logging can be enabled to inspect every event before it's sent

Configuration​

atmos.yaml

settings:
  telemetry:
    # Enable or disable telemetry collection. Defaults to true.
    enabled: true
    # Override the telemetry endpoint (advanced).
    endpoint: ""
    # Override the telemetry token (advanced).
    token: ""
    # Enable verbose telemetry diagnostic logging. Defaults to false.
    logging: false

To opt out completely:

atmos.yaml

settings:
  telemetry:
    enabled: false

Or via environment variable:

export ATMOS_TELEMETRY_ENABLED=false

Configuration Reference​

settings.telemetry.enabled

Controls whether Atmos sends anonymous usage events. When false, no telemetry is collected or transmitted regardless of any other setting.

  • Type: boolean
  • Default: true
  • Environment Variable: ATMOS_TELEMETRY_ENABLED
settings.telemetry.endpoint

Override the endpoint that telemetry events are sent to. Most users should leave this unset; it's intended for organizations that want to route Atmos telemetry to their own collector for internal observability.

  • Type: string
  • Default: (built-in default endpoint)
  • Environment Variable: ATMOS_TELEMETRY_ENDPOINT
settings.telemetry.token

Override the API token used to authenticate with the telemetry endpoint. Pair this with endpoint when sending events to your own collector. Most users should leave this unset.

  • Type: string
  • Default: (built-in default token)
  • Environment Variable: ATMOS_TELEMETRY_TOKEN
settings.telemetry.logging

Enable diagnostic logging for the telemetry client. When true, every event the telemetry client emits is also logged through Atmos' standard logger so you can audit exactly what is being sent. When false, the telemetry client runs silently. Disabled by default to keep CI logs clean.

  • Type: boolean
  • Default: false
  • Environment Variable: ATMOS_TELEMETRY_LOGGING

Environment Variables​

Environment variables take precedence over atmos.yaml settings.

ATMOS_TELEMETRY_ENABLED
Set to false to disable telemetry. Maps to settings.telemetry.enabled.
ATMOS_TELEMETRY_ENDPOINT
Override the telemetry endpoint URL. Maps to settings.telemetry.endpoint.
ATMOS_TELEMETRY_TOKEN
Override the telemetry API token. Maps to settings.telemetry.token.
ATMOS_TELEMETRY_LOGGING
Enable verbose telemetry diagnostic logging. Maps to settings.telemetry.logging.

What Atmos Collects​

Atmos telemetry is designed to capture only the minimum information needed to understand product usage. Events include:

  • The Atmos command that was run (e.g., terraform plan, list components)
  • Whether the command succeeded or failed
  • Atmos version, OS, and architecture
  • An anonymous, randomly generated machine identifier

Atmos never collects:

  • Repository contents, file paths, or stack manifest values
  • Component names, stack names, or variable values
  • Environment variable values
  • AWS account IDs, ARNs, or any cloud credentials
  • Personally identifiable information

Use Cases​

Disable in CI​

Many teams prefer to keep CI logs clean and avoid any outbound telemetry from automation. Disable globally with an environment variable in your CI configuration:

export ATMOS_TELEMETRY_ENABLED=false

Route to a Self-Hosted Collector​

Organizations with strict data-egress policies can route Atmos telemetry to their own internal endpoint:

atmos.yaml

settings:
  telemetry:
    enabled: true
    endpoint: "https://telemetry.internal.example.com"
    token: "${TELEMETRY_TOKEN}"

Audit What's Being Sent​

To verify exactly what Atmos sends, enable diagnostic logging:

atmos.yaml

settings:
  telemetry:
    enabled: true
    logging: true

The telemetry client will log every event through Atmos' standard logger.

NOTE:

Telemetry is sent asynchronously and never blocks command execution. If the telemetry endpoint is unreachable, the event is dropped silently — Atmos commands always succeed or fail based on their own work, not on telemetry delivery.

See Also​

  • Settings — Overview of all settings
  • Atmos Pro — Atmos Pro integration (separate from telemetry)