---
title: inspect
---

# inspect

View detailed metrics for a specific service.

```sh
$ sysg inspect -s myservice
```

When a supervisor is running, `sysg inspect` reads current persisted state such
as cron history and attaches recent metric samples from the supervisor's metrics
store. It does not rebuild the full process tree on every invocation unless
`status.snapshot_mode` is configured as `detailed`. Use `--live` to force
immediate runtime collection for a specific inspect request.

## Options

| Short | Long | Description |
|-------|------|-------------|
| `-s` | `--service` | Name of the service to inspect |
| `-p` | `--project` | Select the stable project id containing the service |
| `-` | `--stream` | Continuously refresh output and render a rolling metrics window of the provided duration (e.g., `5`, `1s`, `2m`) |
| `-c` | `--config` | Path to configuration file |
| `-` | `--format` | Emit machine-readable output (`json` or `xml`) instead of a report; defaults to `json` when no value is provided |
| `-` | `--sys` | Opt into privileged system mode. Requires running as root |
| `-` | `--no-color` | Disable ANSI colors in output |
| `-` | `--live` | Force immediate runtime collection instead of the configured snapshot mode |
| `-` | `--log-level` | Set verbosity (`debug`, `info`, `warn`, `error`) |

## Stream Mode Controls

When `--stream` is attached to a TTY, inspect stays open and accepts keyboard
shortcuts for the inspected unit:

| Key | Action |
|-----|--------|
| **S** | Run `sysg start -s <UNIT>` |
| **X** | Run `sysg stop -s <UNIT>` |
| **R** | Run `sysg restart -s <UNIT>` |
| **ESC** / **Ctrl+C** | Exit stream mode |

If the inspected unit belongs to a project, these shortcuts also pass
`--project <PROJECT_ID>` so only that project's unit is controlled.

:::info Cron units
The **S**, **X**, and **R** controls apply to service units only. Cron units are
scheduler entries, not persistent services, so these shortcuts are no-ops on a
cron unit: inspect shows a notice that cron units cannot be controlled directly
and that you should reload the project to reschedule them.
:::

## Examples

### View service metrics

```sh
$ sysg inspect -s api
```

For multi-project supervisors, disambiguate duplicate service names with the
stable project id:

```sh
$ sysg inspect --project arbitration --service api
```

Shows CPU and memory usage chart:

```
CPU & Memory Usage - api (Last 5m)
100% ┤
     │     ╭─╮
 80% ┤    ╱  ╰╮
     │   ╱    ╰─╮
 60% ┤  ╱       ╰───╮
     │ ╱            ╰───────
 40% ┤╱
     │
 20% ┤━━━━━━━━━━━━━━━━━━━━━━  Memory
     │
  0% └────────────────────────
     0s              5m

CPU: 45.2% (current)  Memory: 23.1% (current)
```

### Stream with a longer rolling window

```sh
$ sysg inspect -s api --stream 24h
```

Stream mode refreshes inspect output using the configured snapshot mode and
recent metric samples. The rolling window controls the charted sample range, not
how much runtime detail systemg collects.

### Force fresh inspect data

```sh
$ sysg inspect -s api --live
```

`--live` forces immediate runtime collection before selecting the inspected unit
and loading recent metric samples. Regular inspect requests still read current
persisted state such as cron history, while `status.snapshot_mode` controls
runtime command lines and process/spawn descendants.

## Metrics shown

- **CPU usage** - Percentage over time
- **Memory usage** - Percentage over time
- **Execution count** - For cron jobs
- **Average duration** - For completed processes
- **Success rate** - For cron jobs

## Cron run history

For cron units, inspect prints a `Cron Run History` table. The `STATUS` column is
color-coded so outcomes are obvious at a glance:

- `success` - light green
- `running` - light blue (the run is still in progress)
- `failed` / `failed: <reason>` - red
- `overlap` - yellow (a run was skipped because the previous one was still going)

Pass `--no-color` to disable the coloring.

## Snapshot detail

The default `status.snapshot_mode: summary` is intended for production-scale
systems. It keeps inspect useful for service health and sampled metrics while
omitting expensive process tree details. Set `status.snapshot_mode: detailed`
when you need runtime command lines and spawn/process descendants in inspect
output.

## See also

- [`status`](/how-it-works/commands/status) - Quick service overview
- [`logs`](/how-it-works/commands/logs) - View service output
