# Diagnostics

Capture machine-readable diagnostic events in a JSONL file to inspect subprocess commands,
working directories, exit codes, and durations after a run.

## Usage

Set both `enabled` and `file` to capture events:

**File:** `atmos.yaml`

```yaml
diagnostics:
  enabled: true
  file: .atmos/diagnostics.jsonl
  include_output: false
```

Atmos appends one JSON object per event and creates parent directories as needed.
Inspect process exits after running a command:

```shell
atmos terraform plan vpc -s plat-ue2-dev
jq 'select(.type == "process.exit")' .atmos/diagnostics.jsonl
```

## Configuration Reference

- **`diagnostics.enabled`** — Enable diagnostic events. Boolean; default `false`.
  Environment variable: `ATMOS_DIAGNOSTICS_ENABLED`.
- **`diagnostics.file`** — Output file path. Default: empty, which disables capture even when `enabled` is true.
  Relative paths resolve against the process working directory.
  Environment variable: `ATMOS_DIAGNOSTICS_FILE`.
- **`diagnostics.include_output`** — Include masked subprocess stdout/stderr chunks as `process.output` events.
  Boolean; default `false`. Environment variable: `ATMOS_DIAGNOSTICS_INCLUDE_OUTPUT`.

## Enable for One Invocation

```shell
ATMOS_DIAGNOSTICS_ENABLED=true \
ATMOS_DIAGNOSTICS_FILE=.atmos/diagnostics.jsonl \
atmos terraform plan vpc -s plat-ue2-dev
```

Diagnostic events are masked before writing. They complement human-readable logs with
structured execution facts; output capture is optional. Collect the JSONL file as a CI
artifact when investigating a failed run. See [error handling](/cli/configuration/errors)
for the separate error-reporting configuration.