Skip to content
English
Customer portal
Contact us
  • There are no suggestions because the search field is empty.

11.02 The Debug Log

SimpleRisk's write_debug_log() helper writes operational events at six severity levels (debug, info, notice, warning, error, critical). Configure the destination (file, database, syslog), the minimum log level, and rotation. The debug log is for application diagnostics; for record changes use the audit trail instead.

Why this is a reference article

This article documents SimpleRisk's debug log: its destinations, levels, and operational role. For specific tasks (troubleshooting an integration, investigating a cron job failure), use this as the reference for what's available and how to read it.

What the debug log is for

The debug log captures operational events that aren't entity-state changes. A few examples:

  • "Cron job X started at time T."
  • "Email sent to user@example.com."
  • "API authentication failed for key ending in ...XYZ."
  • "Workflow execution failed: webhook timeout."
  • "AI provider returned 429 rate-limit error; backing off."

These aren't audit events (the audit trail captures changes to records); they're operational events that help diagnose what the application is doing. The audit trail answers "what happened to this risk?"; the debug log answers "what is the application doing right now?"

The log is written via the write_debug_log($value, $level = 'info') helper in simplerisk/includes/functions.php. Application code calls this helper rather than PHP's error_log() directly so that destination, formatting, and filtering are centralized.

The six log levels

write_debug_log() accepts a level argument. The levels:

  • debug: Developer-focused diagnostics: function-entry traces, internal state dumps, per-cycle gating checks. Not for normal operational messages.
  • info: Normal operations: routine events, expected state changes, successful completions. Default when in doubt.
  • notice: Normal but significant events that happen infrequently and deserve operator attention: enabling/disabling a feature, completing a backup, queuing a one-off job.
  • warning: Unexpected but non-fatal conditions: malformed input, unexpected response formats, recoverable errors.
  • error: Runtime errors needing attention: exception catches, failed operations, missing required data.
  • critical: Conditions requiring immediate intervention to prevent system failure or severe impact.

The level is on every log entry; consumers (log readers, alerting tools) filter by level.

Log destinations

SimpleRisk supports three destinations for the debug log:

Database

Default for many installs. Log entries write to a database table (debug_log or similar). Pros: queryable via SQL, persistent, easily exported. Cons: log volume can bloat the database; high-traffic installs may notice the write overhead.

File

Log entries write to a file on disk (typically under simplerisk/logs/ or /var/log/simplerisk/). Pros: lightweight, integrates with standard log tooling (logrotate, log aggregators that tail files). Cons: requires filesystem rotation to avoid disk fill.

Syslog

Log entries write to the system's syslog facility. Pros: integrates with centralized log aggregation, forwards naturally to SIEM. Cons: requires syslog configuration on the server.

The destination is configured in simplerisk/includes/config.php or via the admin settings — the exact setting name varies by install version. Common keys: debug (master toggle), debug_log_destination (file/database/syslog), debug_log_path (for file destination), debug_log_level (minimum level to log).

The master debug toggle

The debug setting (boolean) controls whether the log writes at all:

  • debug = true: log writes happen (subject to the minimum level filter).
  • debug = false: log writes are no-ops; nothing is recorded.

For production: keep debug on but tune the minimum level to notice or warning to avoid log volume from debug and info entries.

For troubleshooting: temporarily lower the minimum level to debug to capture detailed traces; restore the previous level after.

Reading the log

Database destination

-- Recent entries
SELECT timestamp, log_level, log_message FROM debug_log
ORDER BY timestamp DESC LIMIT 100;

-- Errors and above in the last hour
SELECT timestamp, log_message FROM debug_log
WHERE log_level IN ('error', 'critical')
  AND timestamp >= DATE_SUB(NOW(), INTERVAL 1 HOUR)
ORDER BY timestamp DESC;

-- All entries containing a specific string
SELECT timestamp, log_level, log_message FROM debug_log
WHERE log_message LIKE '%cron_notification%'
ORDER BY timestamp DESC LIMIT 50;

File destination

# Tail the live log
tail -f /var/log/simplerisk/debug.log

# Errors and above
grep -E '(ERROR|CRITICAL)' /var/log/simplerisk/debug.log

# Specific component
grep cron_notification /var/log/simplerisk/debug.log

Syslog destination

Use your syslog tooling (journalctl, rsyslog, or your centralized aggregator). Filter by the SimpleRisk facility/program name configured in your syslog setup.

Rotation and retention

The debug log grows with operational activity. Without rotation:

  • Database destination: the table grows; queries slow; backups bloat.
  • File destination: the file grows; eventually fills the disk.
  • Syslog destination: the syslog server's rotation configuration applies (typically already in place).

For database destination:

  • Schedule periodic deletion of old entries: DELETE FROM debug_log WHERE timestamp < DATE_SUB(NOW(), INTERVAL 30 DAY);.
  • Or partition the table for efficient bulk deletion.

For file destination:

  • Use logrotate (Linux) to rotate the file daily or weekly with compression.
  • Standard logrotate config:
/var/log/simplerisk/debug.log {
    daily
    rotate 30
    compress
    delaycompress
    missingok
    notifempty
    copytruncate
}

For syslog: the syslog server's rotation is typically already in place; verify via logrotate -d /etc/logrotate.d/rsyslog or the equivalent on your distribution.

Common log content patterns

Cron job activity

Cron jobs log their start, completion, and any per-job actions:

  • cron_notification logs queued and sent emails.
  • cron_email_jobs logs delivery results.
  • cron_queue_worker logs queued job pickup and execution status.
  • cron_install_framework logs framework installations.

Investigate cron-related issues by filtering log entries on the relevant cron file's name.

API activity

API authentication failures, slow API calls, and unhandled API errors typically log here. Useful for debugging integration issues without enabling per-request access logging.

Background jobs

The cron queue worker (cron_queue_worker.php) processes queued jobs (workflows, AI requests, etc.). Each job's start, completion, and any errors log here.

Authentication events

Login attempts (configured to log at the appropriate level), MFA events, session-related activity. Note: some auth events are logged to the audit trail rather than the debug log; check both.

Configuration changes

Some configuration changes (Extra activations, settings updates) log here with notice level; they also appear in the audit trail.

Forwarding to a SIEM or aggregator

For programs running centralized log aggregation:

  • File destination + log shipper (Filebeat, Fluentd, Vector): tail the log file; forward to the aggregator.
  • Syslog destination: configure SimpleRisk to write to syslog; the syslog daemon forwards.
  • Database destination + custom export: less common; requires a periodic export job.

The file or syslog destinations integrate most cleanly with standard log aggregation tooling.

Common pitfalls

A handful of patterns recur with the debug log.

  • Leaving the minimum level at debug in production. Excessive log volume; database or disk bloat. Set to notice or warning for production.

  • Not rotating the log. A 10 GB log file is a disk-fill emergency in waiting. Configure rotation.

  • Treating the debug log as the audit trail. It captures operational events, not record changes. For "who modified this risk," use the audit trail.

  • Calling error_log() directly in custom code. Bypasses the write_debug_log() formatting and destination routing. Use write_debug_log().

  • Ignoring error and critical entries. They indicate real problems. Set up alerting on these levels (email, Slack, PagerDuty).

  • Logging sensitive content. Don't log passwords, API keys, encryption keys, or plaintext data being encrypted. Verify in code review.

  • Querying the debug_log table without filtering by timestamp. Full-table scans on a large log table are slow. Always filter on time range.

  • Not coordinating log retention with compliance requirements. Some regulations require operational logs to be retained for a specific period. Set retention to match the longest applicable requirement.

  • Confusing the debug log's storage destination with the audit trail's. They're separate. Different settings, different tables, different retention policies.

  • Treating cron-job log entries at debug level as missing log entries. No-op cron ticks log at debug; if the minimum level is info or higher, you don't see them. Lower the level to verify the cron is actually running.

  • Not periodically reviewing the log for unexpected error patterns. Errors that nobody looks at don't get fixed. Build periodic review or alerting into operations.

Related

Reference

  • Permission required: check_admin for the debug log destination configuration; database read access for direct SQL queries; OS access for file destination.
  • API endpoint(s): None native for the debug log itself.
  • Implementing files: simplerisk/includes/functions.php (write_debug_log($value, $level = 'info') — the central logging helper). Different installs may have a separate simplerisk/includes/debug.php or similar.
  • Database tables (database destination): debug_log (id, timestamp, log_level, log_message).
  • config_settings keys: debug (master toggle); debug_log_destination (file/database/syslog); debug_log_path (for file destination); debug_log_level (minimum level to log).
  • Log levels: debug, info, notice, warning, error, critical.
  • External dependencies: For syslog destination: rsyslog or equivalent; for file destination: logrotate (recommended); for database destination: regular cleanup of old entries.