WooCommerce Remote Logging

A remote logging package for Automattic based projects. This package provides error tracking and logging capabilities, with support for rate limiting, stack trace formatting, and customizable error filtering.

Installation

bash

npm install @woocommerce/remote-logging --save

Description

The WooCommerce Remote Logging package offers the following features:

Remote error logging with stack trace analysis
Customizable log severity levels
Rate limiting to prevent API flooding
Automatic capture of unhandled errors and promise rejections
Filtering of errors based on WooCommerce asset paths
Extensibility through WordPress filters

Usage

Initialize the remote logger at the start of your application. If your plugin depends on WooCommerce plugin, the logger will be initialized in WooCommerce, so you don't need to call this function.
js
```
import { init } from '@woocommerce/remote-logging';

init({
  errorRateLimitMs: 60000 // Set rate limit to 1 minute
});
```

Log messages or errors:

import { log, captureException } from '@woocommerce/remote-logging';

// Log an informational message
log('info', 'User completed checkout', { extra: { orderId: '12345' } });

// Log a warning
log('warning', 'API request failed, retrying...', { extra: { attempts: 3 } });

// Log an error
try {
  // Some operation that might throw
} catch (error) {
  captureException(error, { extra: { orderId: '12345' } });
}

Remote Logging Conditions

Remote logging is subject to the following conditions:

Remote Logging Enabled: The package checks window.wcSettings.isRemoteLoggingEnabled to determine if the feature should be enabled. The value is set via PHP and passed to JS as a boolean. It requires tracks to be enabled and a few other conditions internally. Please see the RemoteLogger.php for more details.
Non-Development Environment: It also checks process.env.NODE_ENV to ensure logging only occurs in non-development environments.

If either of these conditions are not met (Tracks is not enabled or the environment is development), no logs will be transmitted to the remote server.

API Reference

init(config: RemoteLoggerConfig): void: Initializes the remote logger with the given configuration.
log(severity: LogSeverity, message: string, extraData?: object): Promise<boolean>: Logs a message with the specified severity and optional extra data.
captureException(error: Error, extraData?: object): void: Captures an error and sends it to the remote API.

For more detailed information about types and interfaces, refer to the source code and inline documentation.

Customization

You can customize the behavior of the remote logger using WordPress filters. Here are the available filters:

`woocommerce_remote_logging_should_send_error`

Control whether an error should be sent to the remote API.

Parameters:

shouldSend (boolean): The default decision on whether to send the error.
error (Error): The error object.
stackFrames (Array): An array of stack frames from the error.

Return value: (boolean) Whether the error should be sent.

Usage example:

import { addFilter } from '@wordpress/hooks';

addFilter(
  'woocommerce_remote_logging_should_send_error',
  'my-plugin',
  (shouldSend, error, stackFrames) => {
    const containsPluginFrame = stackFrames.some(
      (frame) => frame.url && frame.url.includes( /YOUR_PLUGIN_ASSET_PATH/ )
    );
    // Only send errors that originate from our plugin
    return shouldSend && containsPluginFrame;
  }
);

`woocommerce_remote_logging_error_data`

Modify the error data before sending it to the remote API.

Parameters:

errorData (ErrorData): The error data object to be sent.

Return value: (ErrorData) The modified error data object.

Usage example:

import { addFilter } from '@wordpress/hooks';

addFilter(
  'woocommerce_remote_logging_error_data',
  'my-plugin',
  (errorData) => {
    // Custom logic to modify error data
    errorData.tags = [ ...errorData.tags, 'my-plugin' ];
    return errorData;
  }
);

`woocommerce_remote_logging_log_endpoint`

Modify the URL of the remote logging API endpoint.

Parameters:

endpoint (string): The default endpoint URL.

Return value: (string) The modified endpoint URL.

Usage example:

import { addFilter } from '@wordpress/hooks';

addFilter(
  'woocommerce_remote_logging_log_endpoint',
  'my-plugin',
  (endpoint) => 'https://my-custom-endpoint.com/log'
);

`woocommerce_remote_logging_js_error_endpoint`

Modify the URL of the remote logging API endpoint for JavaScript errors.

Parameters:

endpoint (string): The default endpoint URL for JavaScript errors.

Return value: (string) The modified endpoint URL for JavaScript errors.

Usage example:

import { addFilter } from '@wordpress/hooks';

addFilter(
  'woocommerce_remote_logging_js_error_endpoint',
  'my-plugin',
  (endpoint) => 'https://my-custom-endpoint.com/js-error-log'
);

`woocommerce_remote_logging_request_uri_whitelist`

Modifies the list of whitelisted query parameters that won't be masked in the logged request URI

Parameters:

whitelist (string[]): The default whitelist.

Return value: (string[]) The modified whitelist.

Usage example:

import { addFilter } from '@wordpress/hooks';

addFilter(
  'woocommerce_remote_logging_request_uri_whitelist',
  'my-plugin',
  ( whitelist ) => {
    return [ ...whitelist, 'exampleParam' ]
  }
);