Skip to main content

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:

atmos.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:

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​

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 for the separate error-reporting configuration.