> ## Documentation Index
> Fetch the complete documentation index at: https://sysg.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# inspect

# inspect

View detailed metrics for a specific service.

```sh theme={null}
$ 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 theme={null}
$ sysg inspect -s api
```

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

```sh theme={null}
$ 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 theme={null}
$ 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 theme={null}
$ 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