woocommerce/packages/js/remote-logging/README.md

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

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

1. 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.

   import { init } from '@woocommerce/remote-logging';
   
   init({
     errorRateLimitMs: 60000 // Set rate limit to 1 minute
   });
   

2. 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:

1. 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.

2. 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' ]
  }
);