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';

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

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

initializeLogger();

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>
  );
}

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, isLoaded, error } = useLogger();

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

  if (error) {
    return <div>Error initializing logger: {error.message}</div>;
  }

  return <div>{isLoaded ? 'Logger is loaded' : 'Loading logger...'}</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);
  }
}

async 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 = await 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 LoggerContextType {
  logger: Logger | null;
  isLoaded: boolean;
  error: Error | null;
}

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.
• isLoaded: Indicates if the logger is successfully initialized.
• error: Error object if logger initialization fails.

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