Update Atmos logs. Update docs #605

aknysh · 2024-05-23T16:46:43Z

what

Update Atmos logs
Make the logs respect the standard file descriptors like /dev/stderr
Update docs
- https://pr-605.atmos-docs.ue2.dev.plat.cloudposse.org/cli/configuration/

why

Atmos logs are configured in the logs section in the atmos.yaml CLI config file:

logs:
  # Can also be set using 'ATMOS_LOGS_FILE' ENV var, or '--logs-file' command-line argument
  # File or standard file descriptor to write logs to
  # Logs can be written to any file or any standard file descriptor, including `/dev/stdout`, `/dev/stderr` and `/dev/null`
  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. The environment variable ATMOS_LOGS_FILE can also be used to specify the log file
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). The environment variable ATMOS_LOGS_LEVEL can also be used to specify the log level

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

Note that when you set the log level to Debug or Trace, Atmos will log additional messages before printing the output of an executed command. For example, let's consider the atmos describe affected command:

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 working repo HEAD: ffd2154e1daa32357b75460b9f45d268922b51e1 refs/heads/update-logs
Remote repo HEAD: f7aa382aa8b3d48be8f06cfdb27aad344b89aff4 HEAD

Changed files:

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

Affected components and stacks:

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

With logs.level: Trace, and logs.file: "/dev/stdout", all the messages and the command's JSON output will be printed to the console to the /dev/stdout standard output.

This behavior might be undesirable when you execute the command atmos describe affected in CI/CD (e.g. GitHub Actions).

For example, you might want to log all the Atmos messages (by setting logs.level: Trace) for debugging purposes, and also want to parse the JSON output of the command (e.g. by using jq) for further processing. In this case, jq will not be able to parse the JSON output because all the other messages make the output an invalid JSON document.

To deal with that, you can set logs.file to /dev/stderr in atmos.yaml:

logs:
  file: "/dev/stderr"
  level: Trace

Now when the atmos describe affected command is executed, the additional messages are printed to /dev/stderr, but the command's JSON output is printed to /dev/stdout, allowing jq to parse it without errors.

> 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 working repo HEAD: ffd2154e1daa32357b75460b9f45d268922b51e1 refs/heads/update-logs
Remote repo HEAD: f7aa382aa8b3d48be8f06cfdb27aad344b89aff4 HEAD


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

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

website/docs/cli/configuration.mdx

Co-authored-by: Erik Osterman (CEO @ Cloud Posse) <erik@cloudposse.com>

osterman · 2024-05-23T22:02:06Z

Also relates to #112

* master: Update `atmos validate stacks` command (#611) Add Atmos manifest lists merge strategies (#609) Improve `atmos validate stacks` and `atmos describe affected` commands (#608) Use Darker Theme, Add File Component (#607) Update Atmos logs. Update docs (#605)

aknysh added 6 commits May 22, 2024 23:54

updates

7158ec4

updates

22cfd82

updates

ffd2154

updates

a7876b2

updates

9820498

updates

abe2ac0

aknysh added the minor New features that do not break anything label May 23, 2024

aknysh requested a review from osterman May 23, 2024 16:46

aknysh self-assigned this May 23, 2024

aknysh requested review from a team as code owners May 23, 2024 16:46

aknysh requested review from kevcube and joe-niland May 23, 2024 16:46

aknysh temporarily deployed to preview May 23, 2024 16:46 — with GitHub Actions Inactive