Skip to main content

Logs

Configure where Atmos writes logs and at what verbosity level. Proper log configuration is essential for debugging and for CI/CD pipelines where you need to separate log output from command results.

Configuration​

Logs are configured in the logs section:

atmos.yaml
logs:
  # File or standard file descriptor to write logs to
  # Can also be set using 'ATMOS_LOGS_FILE' ENV var, or '--logs-file' command-line argument
  file: "/dev/stderr"
  # Supported log levels: Trace, Debug, Info, Warning, Off
  # Can also be set using 'ATMOS_LOGS_LEVEL' ENV var, or '--logs-level' command-line argument
  level: Warning
logs.file

The file to write Atmos logs to. Logs can be written to any file or any standard file descriptor, including /dev/stdout, /dev/stderr and /dev/null. If omitted, /dev/stderr will be used so logs never contaminate pipeable command output on stdout. Can also be set using ATMOS_LOGS_FILE environment variable.

logs.level

Log level. Supported log levels are Trace, Debug, Info, Warning, Off. If omitted, Warning will be used, so informational messages are hidden unless requested. The default changed from Info to Warning in the 2025-09 edition; to keep the old verbosity, set logs.level: Info explicitly or pin edition: "2025-08". If the log level is set to Off, Atmos will not log any messages (note that this does not prevent other tools like Terraform from logging). Can also be set using ATMOS_LOGS_LEVEL environment variable.

Disabling Logs​

To prevent Atmos from logging any messages (except for the outputs of the executed commands), you can do one of the following:

  • Set logs.file or the ENV variable ATMOS_LOGS_FILE to /dev/null
  • Set logs.level or the ENV variable ATMOS_LOGS_LEVEL to Off

Logs in CI/CD Pipelines​

When you set the log level to Debug or Trace, Atmos will log additional messages before printing the output of an executed command.

Problem: Mixed Output​

Consider the atmos describe affected command with verbose logging:

atmos.yaml
logs:
  file: "/dev/stdout"
  level: Trace
atmos describe affected
Checking out Git ref 'refs/remotes/origin/HEAD' ...
Checked out Git ref 'refs/remotes/origin/HEAD'

Current HEAD: ffd2154e1daa32357b75460b9f45d268922b51e1 refs/heads/update-logs
BASE: f7aa382aa8b3d48be8f06cfdb27aad344b89aff4 HEAD

Changed files:

examples/quick-start-advanced/Dockerfile
examples/quick-start-advanced/atmos.yaml

Affected components and stacks:

[
   {
      "component": "vpc",
      "component_type": "terraform",
      "component_path": "examples/quick-start-advanced/components/terraform/vpc",
      "stack": "plat-uw2-prod",
      "stack_slug": "plat-uw2-prod-vpc",
      "affected": "stack.vars"
   }
]

With logs.level: Trace and logs.file: "/dev/stdout", all messages and JSON output go to the same stream. This breaks JSON parsing with tools like jq.

Solution: Separate Streams​

Set logs.file to /dev/stderr in atmos.yaml:

atmos.yaml
logs:
  file: "/dev/stderr"
  level: Trace

Now log messages go to /dev/stderr while command output goes to /dev/stdout:

atmos describe affected
# NOTE: These messages are printed to /dev/stderr

Checking out Git ref 'refs/remotes/origin/HEAD' ...
Checked out Git ref 'refs/remotes/origin/HEAD'
Current HEAD: ffd2154e1daa32357b75460b9f45d268922b51e1 refs/heads/update-logs
BASE: f7aa382aa8b3d48be8f06cfdb27aad344b89aff4 HEAD


# NOTE: This JSON output is printed to /dev/stdout

[
   {
      "component": "vpc",
      "component_type": "terraform",
      "component_path": "examples/quick-start-advanced/components/terraform/vpc",
      "stack": "plat-uw2-prod",
      "stack_slug": "plat-uw2-prod-vpc",
      "affected": "stack.vars"
   }
]

This allows jq to parse the JSON output without errors while still logging debug information.

Environment Variables​

ATMOS_LOGS_FILE
File or standard file descriptor to write logs to.
ATMOS_LOGS_LEVEL
Log level: Trace, Debug, Info, Warning, Off.

See Also​