# 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:

**File:** `atmos.yaml`

```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:

**File:** `atmos.yaml`

```yaml
logs:
  file: "/dev/stdout"
  level: Trace
```

```shell
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`:

**File:** `atmos.yaml`

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

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

```shell
# 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

- [CLI Configuration](/cli/configuration) — Overview of CLI configuration
- [Environment Variables](/cli/environment-variables) — All configuration environment variables