---
title: inspect
---

# inspect

View detailed metrics for a specific service.

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

When a supervisor is running, `sysg inspect` reads the cached status snapshot
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 a
fresh snapshot 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 |
| `-` | `--json` | Emit machine-readable JSON output instead of a report |
| `-` | `--sys` | Opt into privileged system mode. Requires running as root |
| `-` | `--no-color` | Disable ANSI colors in output |
| `-` | `--live` | Force a fresh supervisor snapshot instead of reading the cached snapshot |
| `-` | `--log-level` | Set verbosity (`debug`, `info`, `warn`, `error`) |

## 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 reuses cached supervisor snapshots and recent metric samples. The
rolling window controls the charted sample range, not how often systemg performs
live process discovery.

### Force fresh inspect data

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

`--live` recomputes the status snapshot before selecting the inspected unit and
loading recent metric samples. With `status.snapshot_mode: summary`, it remains
a fresh summary snapshot; with `detailed`, it refreshes 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

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