File Logging

Ricochet writes logs to files and rotates and compresses them for you. You set this up in the [logs] section of ricochet-config.toml.

If ricochet-config.toml has no [logs] section, ricochet picks defaults based on how you installed it:

• Kubernetes backend: File logging is off. Logs go to stdout so your cluster can collect them.
• Host & Container: File logging is on, with daily rotation and gzip compression.

Configuration

Add a [logs] section to ricochet-config.toml to change how ricochet logs. This example rotates logs every hour and compresses them. It keeps at most 100 files and deletes any file older than a week.

[logs]
level = "debug"
file_logging = true
rotation = "hourly"
compress = true
max_files = 100
max_age_days = 7

Configuration Options

• level: How much detail to log (default: "info")

  • "trace": Most detail, includes all debug output
  • "debug": Detailed output for finding problems
  • "info": General messages (default)
  • "warn": Warnings
  • "error": Least detail, errors only

• file_logging: Turn file logging on or off (default: true for all installs except Kubernetes)

• rotation: How often to rotate logs (default: "daily")

  • "hourly": Rotate logs every hour
  • "daily": Rotate logs every day
  • "never": Never rotate (one log file)

• compress: Compress rotated logs with gzip (default: true)

• max_files: Most rotated log files to keep (default: no limit)

• max_age_days: Oldest age in days a rotated log file may reach (default: no limit)

Logs Location

Ricochet stores log files in RICOCHET_HOME/logs/, named by rotation schedule:

• Daily rotation: ricochet.log-yyyy-MM-dd (e.g., ricochet.log-2026-02-21)
• Hourly rotation: ricochet.log-yyyy-MM-dd-HH (e.g., ricochet.log-2026-02-21-08)
• No rotation: ricochet.log

Tip

With the systemd service, RICOCHET_HOME defaults to /var/lib/ricochet/data. See the Configuration Overview to learn how to set RICOCHET_HOME.

Log Rotation and Cleanup

Each time ricochet rotates logs, it cleans up in this order:

1. Delete all log files older than max_age_days (if set)
2. Delete the oldest files beyond the max_files limit (if set)
3. Compress any rotated files that are not yet compressed with gzip (except the current log file)

Old logs are deleted before compression runs, which keeps disk use low.

Pair file logging with OpenTelemetry tracing to get a full view of what your server does:

OpenTelemetry IntegrationExport traces to Jaeger, Grafana, or other OTLP-compatible backends.