@optimizely/js-sdk-logging

What is @optimizely/js-sdk-logging?

@optimizely/js-sdk-logging is a logging utility for the Optimizely JavaScript SDK. It provides a way to log messages with different levels of severity and can be integrated with various logging frameworks.

What are @optimizely/js-sdk-logging's main functionalities?

Basic Logging

This feature allows you to create a logger and log messages with different severity levels such as info and error.

const logging = require('@optimizely/js-sdk-logging');
const logger = logging.getLogger('my-logger');
logger.info('This is an info message');
logger.error('This is an error message');

Custom Log Levels

This feature allows you to set custom log levels for your logger, enabling more granular control over what gets logged.

const logging = require('@optimizely/js-sdk-logging');
const logger = logging.getLogger('my-logger');
logger.setLogLevel(logging.LogLevel.DEBUG);
logger.debug('This is a debug message');

Integrating with External Logging Frameworks

This feature allows you to integrate @optimizely/js-sdk-logging with external logging frameworks like Winston, enabling you to leverage their advanced logging capabilities.

const logging = require('@optimizely/js-sdk-logging');
const winston = require('winston');
const logger = logging.getLogger('my-logger');
const winstonLogger = winston.createLogger({
  level: 'info',
  transports: [
    new winston.transports.Console()
  ]
});
logger.addLogHandler((logEvent) => {
  winstonLogger.log({
    level: logEvent.level,
    message: logEvent.message
  });
});
logger.info('This message will be logged by Winston');

Other packages similar to @optimizely/js-sdk-logging

winston

Winston is a versatile logging library for Node.js that supports multiple transports, log levels, and formats. It is more feature-rich compared to @optimizely/js-sdk-logging and is widely used in the Node.js community.

bunyan

Bunyan is a simple and fast JSON logging library for Node.js services. It provides a structured logging approach and is known for its performance. Compared to @optimizely/js-sdk-logging, Bunyan offers more advanced features for JSON logging.

log4js

Log4js is a logging library inspired by Apache Log4j. It provides a variety of appenders for different logging outputs and supports hierarchical loggers. Log4js offers more flexibility and configuration options compared to @optimizely/js-sdk-logging.

README

Javascript SDK Logging

Provides a centralized LogManager and errorHandler for Javascript SDK packages.

Installation

npm install @optimizely/js-sdk-logging

Architecture

• LogHandler - the component that determines where to write logs. Common log handlers are ConsoleLogHandler or NoopLogHandler
• LogManager - returns Logger facade instances via LogManager.getLogger(name)
• LoggerFacade the internal logging interface available to other packages via LogManager.getLogger(name)

Usage

Using the logger

import { getLogger } from '@optimizely/js-sdk-logging'

const logger = getLogger('myModule')
logger.log('warn', 'this is a warning')

logger.debug('string interpolation is easy and %s', 'lazily evaluated')

logger.info('info logging')
logger.warn('this is a warning')
logger.error('this is an error')

// `info` `warn` `debug` and `error` all support passing an Error as the last argument
// this will call the registered errorHandler
logger.error('an error occurred: %s', ex.message)

// also Error passes to errorHandler.handleError(ex)
logger.error('an error occurred: %s', ex.message, ex)

// if no message is passed will log `ex.message`
logger.error(ex)

Setting the log level

import { LogLevel, setLogLevel } from '@optimizely/js-sdk-logging'

// can use enum
setLogLevel(LogLevel.ERROR)

// can also use a string (lowercase or uppercase)
setLogLevel('debug')
setLogLevel('info')
setLogLevel('warn')
setLogLevel('error')

Setting a LogHandler

import { setLogHandler, ConsoleLogHandler } from '@optimizely/js-sdk-logging'

const handler = new ConsoleLogHandler({
  logLevel: 'error',
  prefix: '[My custom prefix]', // defaults to "[OPTIMIZELY]"
})

setLogHandler(handler)

Implementing a custom LogHandler

Perhaps you want to integrate Optimizely with your own logging system or use an existing library.

A valid LogHandler is anything that implements this interface

interface LogHandler {
  log(level: LogLevel, message: string): void
}

Example: integrating with Winston

import winston from 'winston'
import { setLogHandler, LogLevel } from '@optimizely/js-sdk-logging'

const winstonLogger = winston.createLogger({
  level: 'info',
  format: winston.format.json(),
  defaultMeta: { service: 'optimizely' },
  transports: [
    new winston.transports.File({ filename: 'combined.log' }),
  ],
})

/**
 * Convert from optimizely log levels to winston
 */
function convertLogLevels(level) {
  switch(level) {
    case LogLevel.DEBUG:
      return 'debug'
    case LogLevel.INFO:
      return 'info'
    case LogLevel.WARNING:
      return 'warning'
    case LogLevel.ERROR:
      return 'error'
    default:
      return 'silly'
  }
}

setLogHandler({
  log(level, message) {
    winstoLogger.log({
      level: convertLogLevels(level),
      message,
    })
  }
})

API Interfaces

interface LoggerFacade {
  log(level: LogLevel | string, message: string): void

  info(message: string | Error, ...splat: any[]): void

  debug(message: string | Error, ...splat: any[]): void

  warn(message: string | Error, ...splat: any[]): void

  error(message: string | Error, ...splat: any[]): void
}

interface LogManager {
  getLogger(name?: string): LoggerFacade
}

interface LogHandler {
  log(level: LogLevel, message: string): void
}