@procore/web-sdk-logging

Web Platform Logging

A flexible logging solution for Procore front-end applications, providing a standardized interface and integration with various logging services.

Installation

You can install @procore/web-sdk-logging via yarn:

yarn add @procore/web-sdk-logging

Features

• Initialize and manage logging with configurable options.
• Provides a React context-based LoggerProvider for easy integration.
• Hooks (useLogger) for seamless logging integration within React components.
• Error handling and fallback mechanisms included.

Usage

Initialize Logger

To initialize the logger in a non-React environment, you can use the getLogger function directly. Here's an example:

import { getLogger, LoggerOptions } from '@procore/web-sdk-logging';

function initializeLogger() {
  const options: LoggerOptions = {
    level: 'debug',
    endpoint: 'https://api.sumologic.com/receiver/v1/http/<unique_id>',
    name: 'MyApp',
    category: 'ApplicationLogs',
  };

  try {
    const logger = getLogger(options);
    logger.info('Logger initialized.');
  } catch (error) {
    console.error('Failed to initialize logger:', error);
  }
}

initializeLogger();

Note: If the getLogger method cannot initialize the SumoLogic logger, it will initialize a console logger instead.

LoggerProvider

Wrap your application with LoggerProvider to manage the logger instance throughout your app:

import { LoggerProvider } from '@procore/web-sdk-logging';

function Index() {
  return (
    <LoggerProvider initialContext={initialContext}>
      <App />
    </LoggerProvider>
  );
}

Note: If the logger provider cannot initialize the SumoLogic logger, it will initialize and provide a console logger instead.

useLogger Hook

Use the useLogger hook in functional components to access the logger instance:

import { useLogger } from '@procore/web-sdk-logging';

function Component() {
  const logger = useLogger();

  React.useEffect(() => {
    if (logger) {
      logger.info('Component initialized.');
    }
  }, [logger]);


  return </div>;
}

Logging Methods

Use the logger instance to log messages with different severity levels:

if (logger) {
  logger.info('Informational message');
  logger.warn('Warning message');
  logger.error('Error message');
  logger.debug('Debug message');
}

Custom Backend Integration

Adding Custom Backends

You can extend the logging capabilities by adding custom backend implementations to getLogger. Here's an example of adding a custom backend:

import { getLogger, Backend } from '@procore/web-sdk-logging';
import { LoggerOptions } from '@procore/web-sdk-logging/types';

class CustomBackend implements Backend {
  async log(
    level: LogLevel,
    message: string,
    metadata: Record<string, unknown>
  ): Promise<void> {
    // Implement custom logging logic here
    console.log(`Custom logging ${level}: ${message}`, metadata);
  }
}

function initializeLoggerWithCustomBackend() {
  const options: LoggerOptions = {
    level: 'debug',
    endpoint: 'https://api.sumologic.com/receiver/v1/http/<unique_id>',
    name: 'MyApp',
    category: 'ApplicationLogs',
  };

  const customBackend = new CustomBackend();

  try {
    const logger = getLogger(options, [customBackend]);
    logger.debug('Logger initialized with custom backend.');
  } catch (error) {
    console.error('Failed to initialize logger:', error);
  }
}

In this example, CustomBackend implements the Backend interface from @procore/web-sdk-logging, allowing you to integrate your custom logging logic seamlessly into the logging framework provided by @procore/web-sdk-logging.

If you prefer using hooks (useLogger) or the LoggerProvider from our library, typically, you work with the default or configured logger instances, which internally utilize getLogger for initialization. Therefore, the process of adding custom backends would involve directly using getLogger as shown above.

API

Types

type LogLevel = 'error' | 'warn' | 'info' | 'debug';

interface LoggerOptions {
  /**
   * The logger filters messages based on the log level.
   * @default - error
   * level priority:
   * {
   *  error: 0,
   *  warn: 1,
   *  info: 2,
   *  debug: 3
   * }
   * Specifying "error" would only send calls from the logger.error() method.
   * Specifying "info" would send calls from logger.error(), logger.warn(), and logger.info() methods.
   */
  level?: LogLevel;
  /**
   * The URL of the logging service
   */
  endpoint: string;
  /**
   * The name of the application
   */
  name?: string;
  /**
   * The category of the application
   */
  category?: string;
  /**
   * The name of the host from which the log is being sent.
   */
  hostName?: string;
}

interface LoggerProviderProps {
  initialContext: LoggerOptions;
  children: React.ReactNode;
}

interface Logger {
  log(logLevel: LogLevel, data: any): void;
  info(data: any): void;
  warn(data: any): void;
  error(data: any): void;
  debug(data: any): void;
}

LoggerProvider

A React context provider component to initialize and provide the logger instance.

Props

• initialContext: Initial configuration options for the logger.

useLogger

A hook to initialize the logger instance within a functional React component.

Returns

• logger: The logger instance.

LoggerOptions

Configuration options for initializing the logger:

• level: Log level (default: 'error').
• endpoint: URL of the logging service.
• name: Name of the application.
• category: Category of the application.

Logger

The logger interface with methods for logging messages:

• log(level: LogLevel, data: any): void
• info(data: any): void
• warn(data: any): void
• error(data: any): void
• debug(data: any): void

getLogger

A function to initialize the logger instance with provided options and backends.

Props

• options: Configuration options for the logger.
• backends: (Optional) An array of custom backends to extend logging capabilities.

Returns

• A Promise that resolves to a Logger instance.

Implementation Details

• Utilizes SumoLogger for logging operations.
• Error handling and fallback mechanisms included for robust logging.
• Supports non-React environments with modular components.

Support

#team-ui-foundations