Superpowers Sage:acorn Logging

Error Handling & Logging with Acorn

Acorn uses Laravel's logging system inside WordPress. Logs are configured per-theme in config/logging.php and coexist with WordPress's native debug.log.

When to use

• Structured logging with log levels (emergency, alert, critical, error, warning, notice, info, debug)
• Multiple log channels (daily rotating, single file, syslog, Sentry, custom)
• Exception reporting with context and stack traces
• Environment-aware logging (more verbose in dev, error-only in production)
• Integration with external monitoring (Sentry, Papertrail, Loggly)

When NOT to use

• Simple error_log() calls for local debugging — still valid for quick traces
• WordPress-specific debug output (WP_DEBUG_LOG = true) — native WordPress debug log is complementary, not redundant
• Performance-critical paths where per-call overhead of the logger matters — prefer conditional WP_DEBUG gating

Prerequisites

• Acorn installed and bootstrapped
• config/logging.php published (step shown below)
• storage/logs/ writable by the web server user

Using the Logger

use Illuminate\Support\Facades\Log;

// Basic usage
Log::info('Order placed successfully');
Log::warning('API rate limit approaching');
Log::error('Payment gateway timeout');

// Always pass context as an array — never interpolate strings
Log::error('Payment failed', [
    'order_id' => $orderId,
    'gateway' => $gateway,
    'amount' => $amount,
]);

// Write to a specific channel
Log::channel('errorlog')->critical('Database connection lost');

// Write to multiple channels simultaneously
Log::stack(['daily', 'errorlog'])->error('Critical failure', ['trace' => $e->getMessage()]);

Log Levels

From most to least severe — use the appropriate level:

See references/channels.md for channel config, custom channels, and WordPress debug.log bridge. See references/structured-logging.md for context arrays, custom exceptions, and structured logging conventions. See references/troubleshooting.md for logs not appearing, permission errors, daily rotation issues, Slack not notified.

Verification

• Write a test log entry (Log::info('test', ['key' => 'value'])) and confirm it appears in the expected log file (e.g., storage/logs/acorn.log or the daily rotated variant).
• Verify the correct channel is being used by writing to a named channel (Log::channel('payments')->info('test')) and checking the channel-specific log file.

Failure modes

Problem: Permission denied when writing to log file

• Cause: The web server process does not have write permissions on the storage/logs/ directory or the log file itself.
• Fix: Fix permissions with lando ssh -s appserver -c "chmod -R 775 /app/content/themes/{theme}/storage/logs". Ensure the storage/ directory is writable by the web server user. In Lando, this is typically handled automatically but can break after manual file operations.

Problem: Log channel not configured (driver not found)

• Cause: The channel name used in Log::channel('name') does not exist in the channels array in config/logging.php.
• Fix: Add the missing channel definition to config/logging.php with the appropriate driver (single, daily, errorlog, etc.) and path. Verify config/logging.php exists in your theme directory.

Escalation

• If the log disk is full or storage permissions cannot be resolved at the application level, this is an infrastructure issue -- check disk usage with df -h and coordinate with the server administrator.
• If you need to route logs to an external service (Sentry, Datadog, Slack), add a custom channel driver in config/logging.php or use the exception handler's reportable() method.