How It Works

Logs

systemg writes internal operational logs and captures service stdout/stderr by default.

What's logged

Service lifecycle (start, stop, restart, crash)
Cron job execution
Configuration changes
Supervisor events

Location

~/.local/share/systemg/logs/supervisor.log (user mode) /var/log/systemg/supervisor.log (system mode)

Service output is isolated by project:

~/.local/share/systemg/logs/{project}/{service}.log (user mode)
/var/log/systemg/{project}/{service}.log (system mode)

By default, systemg pipes each managed service's stdout and stderr into reader threads, then writes both streams through one per-service writer into {service}.log. sysg logs reads that stored file; it does not attach to the original process streams.

Info: The default service log is stacked in capture order. Each line gets a systemg UTC capture timestamp plus a stream label, such as stdout or stderr, so sysg logs --kind stderr can filter lines without needing a second stderr file.

Service output configuration

Info

Default log size cap. Each service's active log file rotates at 10 MB (max_bytes, 10485760 bytes), and systemg keeps 5 rotated files (max_files) per log. So a single service's captured output is bounded to roughly 60 MB on disk (1 active + 5 rotated) before the oldest is dropped. Raise or lower these with a logs block; set sink: none to capture nothing.

Use the top-level logs block to set defaults for all services:

version: "2"
logs:
  sink: file
  max_bytes: 10485760
  max_files: 5
services:
  api:
    command: "python app.py"

Use a service-level logs block to override the global defaults:

services:
  noisy_worker:
    command: "worker --verbose"
    logs:
      sink: none

Supported sinks:

file - Capture stdout/stderr and write systemg-managed log files.
none - Discard stdout/stderr without creating log-writer threads or files.

max_bytes controls active file rotation for the file sink. max_files controls how many numbered rotated files are retained. Set sink: none for high-output services when another logging pipeline is already responsible for collection.

View logs

# Supervisor events
$ sysg logs --supervisor --no-follow

# Follow in real-time
$ tail -f ~/.local/share/systemg/logs/supervisor.log

# Search for events
$ grep "Starting service" ~/.local/share/systemg/logs/supervisor.log

Log levels

Set verbosity when starting:

$ sysg start --log-level debug

Levels: trace (5), debug (4), info (3), warn (2), error (1), off (0)

Log format

2025-12-02T10:30:15.123456Z  INFO systemg::daemon: Starting service: api

Format: [TIMESTAMP] [LEVEL] [MODULE]: [MESSAGE]

Common messages

Service events

Starting service: api
Service api exited with status 0
Restarting service: api (attempt 1/5)
Service api crashed: exit code 1

Cron events

Running cron job 'backup'
Cron job 'backup' completed successfully
Cron job 'backup' exited with non-zero status

Supervisor events

systemg supervisor listening on "/path/to/socket"
Supervisor shutting down
Reloading configuration from "/path/to/config"

Supervisor log rotation

The supervisor log uses the supervisor.xml log defaults: a 10 MB active-file limit and five rotated files unless changed by the operator. Services can override those defaults in their project manifest. No external rotator is required.