@procore/web-sdk-logging NPM

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