wc-logging

WooCommerce logging

Use WooCommerce's shared logger for operational diagnostics that merchants can inspect in WooCommerce Status logs. Logs are disposable observability data, never the only record that a payment, migration, export, or webhook completed.

Basic pattern

$logger = wc_get_logger();

$logger->info(
    'Order export queued.',
    array(
        'source'         => 'myplugin-export',
        'order_id'       => $order_id,
        'correlation_id' => $correlation_id,
        'attempt'        => $attempt,
    )
);

Always set a stable, plugin-prefixed source. Current file logging sanitizes it and expects at least three characters. Do not generate one source per order, user, request, or date; that fragments log browsing and creates excessive files/source records.

Levels

Level	Use
debug	Detailed development diagnostics; high volume and normally thresholded in production
info	Normal lifecycle milestones useful for operations
notice	Significant but expected condition
warning	Recoverable anomaly, fallback, retry, deprecation, or degraded behavior
error	Operation failed but the application remains usable
critical	A component or important workflow is unavailable
alert	Immediate operator action is required
emergency	Store/system is unusable

Use the level methods (debug(), info(), warning(), error()) or log(). WC_Logger::add() is legacy and explicitly not the preferred API.

WooCommerce can disable logging globally and can set a minimum severity threshold. In 11.0.0 the default threshold is none, meaning all levels are accepted, but site settings or WC_LOG_THRESHOLD can change that. Never make application correctness depend on a log entry being handled.

Structured context

Prefer a constant message plus small, allowlisted context:

$logger->error(
    'Provider capture failed.',
    array(
        'source'             => 'myplugin-gateway',
        'order_id'           => $order->get_id(),
        'provider_reference' => myplugin_mask_reference( $provider_reference ),
        'provider_code'      => sanitize_key( $provider_code ),
        'correlation_id'     => $correlation_id,
    )
);