# Metrics

Atmos can print a one-line resource-usage summary — elapsed time, CPU time, and peak memory of the largest process — after `terraform plan`/`apply`/`deploy` complete, plus a final aggregate summary covering every subprocess spawned during the whole invocation. The `settings.metrics` section controls whether that local display is shown. The same numbers also appear in the GitHub Actions job summary when [Native CI](/cli/configuration/ci) is active, independent of this setting.

> **Key points**
>
> - Shown by default after `terraform plan`, `apply`, and `deploy`
> - A final aggregate line summarizes every subprocess spawned during the whole run (e.g. every component plan in a multi-component `--affected` run)
> - Disable the local display with a single setting
> - Also appears in the Native CI job summary — a quick way to see what a component actually costs before sizing a runner
> - Never affects the separate Atmos Pro command-execution metadata upload

## Configuration

**File:** `atmos.yaml`

```yaml
settings:
  metrics:
    # Show the local per-command / final-summary resource-usage display. Defaults to true.
    enabled: true
```

To disable the local display:

**File:** `atmos.yaml`

```yaml
settings:
  metrics:
    enabled: false
```

## Configuration Reference

- **`settings.metrics.enabled`**

  Controls whether the local resource-usage summary (elapsed time, CPU time, peak memory) is printed after `terraform plan`/`apply`/`deploy`, and whether the final aggregate summary is printed at the end of the whole `atmos` invocation. This setting only controls local display — it never gates or affects the separate Atmos Pro command-execution metadata upload, which is controlled by CI detection and Atmos Pro configuration (see [Atmos Pro settings](/cli/configuration/settings/pro)).

  "Peak memory" here means the largest single process's peak RSS observed during the run (Terraform, OpenTofu, or a provider plugin) — not a simultaneous sum across every concurrently running process. See the note below for what that means when sizing a runner.
  - **Type:** `boolean`
  - **Default:** `true`

> **Note**
>
> The per-command display only appears for `terraform plan`, `apply`, and `deploy` — the same commands that synchronously report execution metadata to Atmos Pro when it's configured. Commands with no subprocess (e.g. `describe affected`) don't show a per-command line, and don't trigger the final aggregate summary either — that line only appears when at least one subprocess ran during the invocation (Terraform/OpenTofu, Helmfile, Packer, or a workflow step), and covers Atmos's own usage together with every one of those subprocess runs.

> **Note**
>
> **Peak memory is a lower bound, not an exact whole-job figure.** The underlying measurement (`ru_maxrss`) reports the peak RSS of the single largest process observed in the run, not a simultaneous sum across every concurrently running process. If `terraform` and two provider plugins each peak at 200 MB at the same moment, this reports roughly 200 MB, not 600 MB. Use it to catch obviously undersized runners, but don't treat it as the exact ceiling a runner needs.

## Native CI Job Summaries

When [Native CI](/cli/configuration/ci) is active, `terraform plan` and `apply` also render a **Resource usage** line in the GitHub Actions job summary — the same wall-time, CPU-time, and peak-memory figures as the local display, formatted identically:

```
📊 Resource usage: 45.2s wall · 12.3s user / 4.1s sys CPU · 512.0 MB peak memory (largest process)
```

This is controlled by CI detection, not by `settings.metrics.enabled` — it appears whenever the job summary itself is generated, so it's visible directly in the GitHub Actions run UI without opening a log. It's the fastest way to see what a component actually costs when sizing a runner tier or a self-hosted pool.

## Use Cases

### Disable for Scripted/CI Output

Teams that parse `atmos terraform` output in scripts, or want minimal CI logs, can turn off the local display entirely:

**File:** `atmos.yaml`

```yaml
settings:
  metrics:
    enabled: false
```

## See Also

- [Settings](/cli/configuration/settings) — Overview of all settings
- [Atmos Pro](/cli/configuration/settings/pro) — Command-execution metadata upload (separate from this local display)