@tbint/logger

A lightweight and configurable logger for Node.js applications with support for external logging services like DataDog.

Installation

Install the package via npm or yarn:

npm install @tbint/logger

or

yarn add @tbint/logger

Usage

Set the environment variables

# can be info, debug, warn, error
# anything else will throw an error
export LOG_LEVEL=debug
# can be local, development, staging, production
# anything else will throw an error
export LOG_ENVIRONMENT=local

Import the Logger

import { Logger } from "@tbint/logger";

Initialize the Logger

This logger is designed to be initialized once and used throughout the application. The logger accepts an options object with the following properties:

All properties are optional and can be set later the logging methods except for system, service, ddtags, obfuscateContextFields and obfuscateContextCharacter.

obfuscateContextFields is an array of fields to obfuscate in the context object. obfuscateContextCharacter is the character to use for obfuscation.

The obfuscation is applied to the context object before logging. It is recursive and will obfuscate nested objects.

The keys are checked case-insensitive.

So if you want to obfuscate a keys Password and password, you can add simply add password to the obfuscateContextFields array.

ddtags is a string of comma-separated tags to be sent to DataDog.

Key and value are separated by a colon.

const logger = new Logger({
  project: "my-project", // Optional
  service: "my-service", // Required
  system: "my-system", // Optional
  component: "my-component", // Optional
  className: "MyClass", // Optional
  correlationId: "1234", // Optional
  obfuscateContextFields: [], // Optional
  obfuscateContextCharacter: "*", // Optional
  ddtags: "team:api,env:local", // Optional
});

Logging Methods

The logger provides four methods to log messages:

• info
• debug
• warn
• error

Each method accepts a log message in the following format:

/**
 * LogFormat
 * @description Interface for log format
 * @property {string} event - Event name, e.g., 'user-logged-in'
 * @property {string} correlationId - Correlation ID, e.g., '1234'
 * @property {string} component - Component name, e.g., 'email-component'
 * @property {string} className - Class name, e.g., 'UserService'
 * @property {string} methodName - Method name, e.g., 'sendEmail'
 * @property {string} description - Human-readable description, e.g., 'User logged in'
 * @property {number} durationInMilliseconds - Duration in milliseconds
 * @property {unknown} context - Additional context data
 */
export type LogFormat = {
  event?: string;
  correlationId?: string;
  component?: string;
  className?: string;
  methodName?: string;
  description?: string;
  durationInMilliseconds?: number;
  context?: unknown;
};

Example

export LOG_LEVEL=debug
export LOG_ENVIRONMENT=local

// Import and initialize
import { Logger } from "@tbint/logger";
const logger = new Logger({
  project: "my-project", // Optional
  service: "my-service", // Required
  system: "my-system", // Optional
  component: "my-component", // Optional
  className: "MyClass", // Optional
  correlationId: "1234", // Optional
});

// Log messages
logger.info({
  event: "user-logged-in",
  component: "auth-service",
  className: "LoginHandler",
  methodName: "handleLogin",
  description: "User successfully logged in",
  durationInMilliseconds: 150
});

logger.error({
  event: "email-failed",
  correlationId: "5678",
  component: "email-service",
  className: "EmailSender",
  methodName: "sendWelcomeEmail",
  description: "Failed to send welcome email",
  durationInMilliseconds: 200,
  context: { retryCount: 3 }
});

Configuration

Log Level

Set the environment variable LOG_LEVEL to control the verbosity of the logger. Available levels are:

• info
• debug
• warn
• error

Example:

export LOG_LEVEL=debug

DataDog Integration

To enable DataDog logging, set the DATADOG_API_KEY and DATADOG_API_URL environment variables:

export DATADOG_API_KEY=your-datadog-api-key
export DATADOG_API_URL=https://http-intake.logs.datadoghq.eu/api/v2/logs

If this variable is not set, DataDog integration won't be enabled.

API

Logger Constructor

new Logger(options);

• project: Project name (optional)
• service: Service name (required)
• system: System name (optional)
• component: Component name (optional)
• className: Class name (optional)
• correlationId: Correlation ID (optional)
• obfuscateContextFields: Fields to obfuscate in the context object (optional)
• obfuscateContextCharacter: Character to use for obfuscation (optional)

Logging Methods

All methods accept an object of type LogFormat.

logger.info(log: LogFormat)

Logs informational messages.

logger.debug(log: LogFormat)

Logs debug-level messages.

logger.warn(log: LogFormat)

Logs warnings.

logger.error(log: LogFormat)

Logs errors.

Example with Environment Variables

export LOG_LEVEL=debug
export DATADOG_API_KEY=your-datadog-api-key

import { Logger } from "@tbint/logger";

const logger = new Logger({
  service: "example-service",
});

logger.info({
  event: "startup",
  component: "server",
  description: "Server is starting up",
  durationInMilliseconds: 500
});