Commands

inspect

View detailed metrics for a specific service.

$ 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
`-v`	`--verbose`	Print operation progress
`-`	`--sys`	Opt into privileged system mode. Requires running as root
`-`	`--drop-privileges`	Accepted globally but ignored; inspect does not spawn services
`-`	`--no-color`	Disable ANSI colors in output
`-`	`--plain`	Disable terminal decoration for automation
`-`	`--live`	Force immediate runtime collection instead of the configured snapshot mode
`-`	`--log-level`	Set logging verbosity for this invocation (`trace` through `off`, or 5-0)

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.

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

$ sysg inspect -s api

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

$ sysg inspect --project arbitration --service api

--project may name any project the supervisor has loaded, not just the first one a multi-project config declares.

Note

Inspect refuses rather than guesses:

a service name that does not exist → SG0202,
a bare -s <name> that matches a service in more than one project → SG0006 (pass -p to choose),
a -p that disagrees with a project/service prefix → SG0201.

Shows CPU and memory usage chart:

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

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

Stream with a longer rolling window

$ 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

$ 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.