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:

Level	Use for
emergency	System is unusable
alert	Immediate action required
critical	Critical conditions (component failure)
error	Runtime errors that need attention
warning	Unusual conditions, not errors
notice	Normal but significant events
info	General operational messages
debug	Detailed debug info (dev only)