Log Level and Rotation
LinuxGuard agent log rotation defaults, configurable knobs, and runtime log level management via config set + SIGHUP reload.
This page covers the operator-facing knobs for the LinuxGuard agent's log file: the rotation defaults, the four configurable rotation fields, the strict wire format for log levels, and the runtime reload flow via config set log_level + SIGHUP.
For redaction scope and rate-limiting behavior, see Log Management.
Log Rotation Defaults
The agent uses the lumberjack rotator to manage /var/log/linuxguard/agent.log. Defaults are verified against the agent source:
max_size_mb
50 MB max file size
When the active log file reaches this size, it is rotated and a new file is opened.
max_age_days
14-day retention
Rotated backup files older than this are pruned at the next rotation event.
max_backups
5 backups
At most this many rotated files are retained; older backups are pruned at the next rotation.
compress
gzip compression
Rotated backup files are gzip-compressed and named agent.log.<N>.gz.
Worst-case live + backup footprint under defaults: approximately 75 MB on disk (50 MB live file + ≈25 MB compressed backups).
The max_size_mb default is the only field with a built-in fallback at the lumberjack bridge layer (size=0 has no useful lumberjack meaning). The 14-day / 5-backup / gzip-on defaults are applied one layer up in config.GetLoggingConfig — operators who pass a zero-valued configuration explicitly get "no age pruning, retain all backups, no compression" rather than the legacy defaults.
Configurable Rotation Knobs
All four rotation fields are configurable via linuxguard-agent config set logging.<key> <value>. Validation is enforced by the agent runtime.
logging.max_size_mb
int
1 – 10000
Cannot be 0; min 1 MB.
logging.max_age_days
int
0 – 3650
0 means never delete rotated files by age.
logging.max_backups
int
0 – 100
0 means retain all rotated files.
logging.compress
bool
true / false / 1 / 0
gzip-compress rotated backup files.
Setting a Rotation Knob
After changing a rotation knob, restart the agent service to pick up the new rotation configuration:
Rotation configuration is not re-read on SIGHUP — only log level is reloaded via SIGHUP. See Log Level Management below.
Log Level Management
Wire Format (Strict Lowercase)
The agent enforces a strict lowercase wire format for log levels across every external surface (config file, ack envelope, CLI flag, audit log row).
Valid log levels:
Uppercase variants (DEBUG, INFO), integer representations, and the empty string are rejected with a descriptive error. There is no strings.ToLower normalization — the wire format is strict.
Performance Impact Per Level
trace
Deep diagnostic; off in production
Yes (1000/s default)
Highest cost; can be heavy on disk and CPU under load
debug
Debugging individual subsystems
Yes (500/s default)
Significant overhead under steady load
info
Operator-visible lifecycle events
No
Default production level; low overhead
warn
Recoverable degradations
No
Minimal overhead
error
Operator action required
No
Minimal overhead
TRACE and DEBUG are rate-limited to protect the rotation file under bursty load — see Log Management § Rate Limiting.
Persisting a New Log Level + SIGHUP Reload Flow
The config set log_level <level> subcommand performs three actions atomically:
Validates the level against the strict lowercase wire format.
Persists the new level to the agent's local config database.
Sends SIGHUP to the running agent process so the new level takes effect without a service restart.
The SIGHUP handler re-reads the config, resolves the new log level, and updates the live slog level. An INFO line "SIGHUP reload: log level updated" is emitted on success.
If you need to send SIGHUP manually (e.g., after editing the config file directly):
Clearing a Persisted Log Level
To remove the local pin and revert to the backend-ack-delivered or tenant-default level:
config unset is supported ONLY for log_level — identity fields (api_key, tenant_id) are not unsettable via the CLI.
logrotate Integration
The agent ships a packaged logrotate fragment at /etc/logrotate.d/linuxguard matching the following template.
How logrotate Coexists With Lumberjack
The agent uses lumberjack for in-process rotation, AND it ships the logrotate fragment above so external rotation tooling can drive rotation alongside the in-process rotator. The postrotate SIGHUP signals the agent to close and reopen its log file descriptor — implementing the external-rotation close+reopen semantics in the agent runtime.
The agent's SIGHUP handler calls Rotate() on the active lumberjack rotator to perform the close+reopen on the lumberjack-managed file. The same SIGHUP also triggers log-level reload via a separate handler — both handlers run on every SIGHUP because signal.Notify broadcasts the signal to both channels independently.
Per-Distribution logrotate Behavior
Debian / Ubuntu
systemd logrotate.timer (default daily)
Standard daily rotation; fragment in /etc/logrotate.d/linuxguard.
RedHat / CentOS
systemd logrotate.timer (default daily)
Standard daily rotation; fragment in /etc/logrotate.d/linuxguard.
SUSE / openSUSE
systemd logrotate.timer (default daily)
Standard daily rotation; fragment in /etc/logrotate.d/linuxguard.
Alpine
OpenRC crond + logrotate cron job
Daily cron via /etc/periodic/daily/logrotate; fragment under /etc/logrotate.d/linuxguard.
Examples
Verify Current Rotation Config
Enable Verbose Debug Logging Temporarily
Increase Rotation Size and Retention
Disable Compression on Rotated Backups
Note: Disabling compression increases on-disk footprint by approximately 3-5x per backup file.
Cross-References
Log Management — Redaction scope, rate limiting, central log collection patterns.
Support Bundles — Bundle contents and per-file redaction status.
Related: Log Management | Support Bundles | Troubleshooting
Last updated
Was this helpful?