Skip to main content

​
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

ShortLongDescription
-s--serviceName of the service to inspect
-p--projectSelect the stable project id containing the service
---streamContinuously refresh output and render a rolling metrics window of the provided duration (e.g., 5, 1s, 2m)
-c--configPath to configuration file
---formatEmit machine-readable output (json or xml) instead of a report; defaults to json when no value is provided
---sysOpt into privileged system mode. Requires running as root
---no-colorDisable ANSI colors in output
---liveForce immediate runtime collection instead of the configured snapshot mode
---log-levelSet 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:
KeyAction
SRun sysg start -s <UNIT>
XRun sysg stop -s <UNIT>
RRun sysg restart -s <UNIT>
ESC / Ctrl+CExit 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

$ sysg inspect -s api
For multi-project supervisors, disambiguate duplicate service names with the stable project id: 
$ 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

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

​
See also

  • status - Quick service overview
  • logs - View service output