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: Info
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/stdout will be used. Can also be set using ATMOS_LOGS_FILE environment variable.

logs.level

Log level. Supported log levels are Trace, Debug, Info, Warning, Off. 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​