PSR-3 Logging & Magento Logging

What is PSR-3?

PSR-3 is a PHP standard (PHP Standard Recommendation) that defines a common interface for logging libraries. It allows different logging implementations to be interchangeable.

The LoggerInterface

namespace Psr\Log;

interface LoggerInterface
{
    public function emergency(string|\Stringable $message, array $context = []): void;
    public function alert(string|\Stringable $message, array $context = []): void;
    public function critical(string|\Stringable $message, array $context = []): void;
    public function error(string|\Stringable $message, array $context = []): void;
    public function warning(string|\Stringable $message, array $context = []): void;
    public function notice(string|\Stringable $message, array $context = []): void;
    public function info(string|\Stringable $message, array $context = []): void;
    public function debug(string|\Stringable $message, array $context = []): void;
    public function log($level, string|\Stringable $message, array $context = []): void;
}

Log Levels (Most to Least Severe)

Usage

use Psr\Log\LoggerInterface;

class OrderProcessor
{
    public function __construct(
        private LoggerInterface $logger
    ) {}

    public function process(array $orderData): void
    {
        $this->logger->info('Processing order', [
            'order_id' => $orderData['id'],
            'customer' => $orderData['email'],
            'total' => $orderData['total'],
        ]);

        try {
            $this->createOrder($orderData);
        } catch (\Exception $e) {
            $this->logger->error('Order processing failed', [
                'order_id' => $orderData['id'],
                'exception' => $e,
                'trace' => $e->getTraceAsString(),
            ]);
            throw $e;
        }
    }
}

What is Structured Logging?

Instead of free-form text, structured logging adds context data that can be queried and analyzed:

// BAD: Unstructured
$this->logger->error('Order failed for customer john@example.com with amount $50.00');

// GOOD: Structured
$this->logger->error('Order failed', [
    'customer_email' => 'john@example.com',
    'amount' => 50.00,
    'currency' => 'USD',
    'payment_method' => 'credit_card',
    'error_code' => 'GATEWAY_TIMEOUT',
    'attempt' => 3,
]);

Context Array Keys

Use consistent keys across your application:

// Common context keys
$this->logger->info('Product imported', [
    'sku' => 'ABC-123',
    'product_id' => 456,
    'operation' => 'import',
    'source' => 'csv',
    'duration_ms' => 150,
    'memory_peak_mb' => round(memory_get_peak_usage(true) / 1048576, 2),
]);

// Exception context (PSR-3 standard)
try {
    $this->process();
} catch (\Exception $e) {
    $this->logger->error('Processing failed', [
        'exception' => $e, // PSR-3 knows to format this as stack trace
    ]);
}

Log Context Best Practices

1. Always include identifiers: order_id, product_id, sku
2. Include operation context: what was being attempted
3. Include timing: duration for performance analysis
4. Don't log sensitive data: passwords, credit cards, tokens
5. Use consistent key names: snake_case across the application

Magento Logger Setup

Magento uses PSR-3 with Monolog as the implementation:

// Magento\Framework\Logger\Monolog
// This is the default logger in Magento

// Inject via DI
namespace Vendor\Module\Model;

class ProcessManager
{
    public function __construct(
        private \Psr\Log\LoggerInterface $logger
    ) {}

    public function execute(): void
    {
        $this->logger->info('Process started');
        // ... processing
        $this->logger->info('Process completed', ['items_processed' => 100]);
    }
}

Magento Log Files

Custom Logger Channels

<!-- etc/di.xml -->
<config>
    <type name="Magento\Framework\Logger\Monolog">
        <arguments>
            <argument name="name" xsi:type="string">vendor_module</argument>
            <argument name="handlers" xsi:type="array">
                <item name="default" xsi:type="object">Magento\Framework\Logger\Handler\Base</item>
                <item name="system" xsi:type="object">Magento\Framework\Logger\Handler\System</item>
                <item name="debug" xsi:type="object">Magento\Framework\Logger\Handler\Debug</item>
            </argument>
        </arguments>
    </type>
</config>

Logging Performance

// Use log level checks to avoid unnecessary string formatting
if ($this->logger->isHandling(Monolog\Logger::DEBUG)) {
    $this->logger->debug('SQL query', [
        'query' => $sql, // Expensive string building only when needed
        'params' => $params,
    ]);
}

// Or use lazy evaluation with closures
$this->logger->debug('Complex debug', function () {
    return ['data' => $this->expensiveDebugData()];
});