@shellicar/pino-applicationinsights-transport

Azure Application Insights transport for pino

Overview

@shellicar/pino-applicationinsights-transport is a transport module for the pino logging library that enables seamless integration with Azure Application Insights. It allows developers to send log data directly to Application Insights, leveraging the power of pino's high-performance logging with Azure's robust telemetry and monitoring capabilities.

Motivation

While pino is a highly efficient logging library for Node.js applications, integrating it with Azure Application Insights requires a reliable and straightforward transport mechanism. Existing solutions may not fully support the latest features of pino or Azure Application Insights, especially with the advancements in TypeScript and modern JavaScript environments. To bridge this gap, @shellicar/pino-applicationinsights-transport was developed to provide a type-safe, configurable, and easy-to-use transport for sending pino logs to Azure Application Insights.

Features

• Seamless Integration with pino
  • Easily attach Application Insights as a transport stream to pino.
• Support for Azure Application Insights v2 and v3
  • Compatible with both applicationinsights@^2 and applicationinsights@^3 packages.
• Type-Safe Configuration
  • Leverages TypeScript for type-safe transport options and logger configurations.
• Customizable Log Levels
  • Map pino log levels to Azure Application Insights severity levels.
• Error Tracking
  • Automatically tracks exceptions and errors in Application Insights.
• Flexible Logging Options
  • Choose between console logging and Application Insights, or use both simultaneously.
• Pretty Printing for Console
  • Integrate with pino-pretty for human-readable console logs.
• Efficient Stream Handling
  • Utilizes pino-abstract-transport for high-performance log processing.

Installation

To use @shellicar/pino-applicationinsights-transport, install it along with pino and your desired version of applicationinsights.

Install with applicationinsights@^2

pnpm add @shellicar/pino-applicationinsights-transport pino applicationinsights@^2

Install with applicationinsights@^3

pnpm add @shellicar/pino-applicationinsights-transport pino applicationinsights@^3

Note: Choose the version of applicationinsights that aligns with your project's requirements. Do not install both versions simultaneously.

Usage

Basic Setup

Below is a concise example demonstrating how to set up the logger with either applicationinsights@^2 or applicationinsights@^3. The primary difference lies in the version specified in the configuration.

import { createLogger } from '@shellicar/pino-applicationinsights-transport';
import { TelemetryClient, setup, defaultClient } from 'applicationinsights';

// Option 1: Using setup and defaultClient
setup().start();
const logger = createLogger({
  console: true, // Enable console logging
  insights: {
    client: defaultClient,
    version: 2, // Specify the version: 2 or 3
  },
});

// Option 2: Using a new TelemetryClient instance
const client = new TelemetryClient(process.env.APPLICATIONINSIGHTS_CONNECTION_STRING);
const logger = createLogger({
  console: true, // Enable console logging
  insights: {
    client,
    version: 3, // Specify the version: 2 or 3
  },
});

// Log messages
logger.info('Hello, Application Insights!');
logger.error('An error occurred', new Error('Sample error'));

Advanced Configuration

Customize the logger with additional pino options and specify log levels as needed.

import { createLogger } from '@shellicar/pino-applicationinsights-transport';
import { TelemetryClient } from 'applicationinsights'; // Import from the installed version

// Initialize Azure Application Insights client
const client = new TelemetryClient(process.env.APPLICATIONINSIGHTS_CONNECTION_STRING);

// Create pino logger with custom settings
const logger = createLogger({
  console: true, // Enable console logging with pretty print
  pino: {
    level: 'debug',
    // Additional pino options can be specified here
  },
  insights: {
    client, // Pass the TelemetryClient instance
    version: 3, // Specify the version: 2 or 3
  },
});

// Log messages with different levels
logger.debug('Debugging information');
logger.info('Informational message');
logger.warn('Warning message');
logger.error('Error message');
logger.fatal('Fatal error');

Using Transport Directly

If you prefer to use the transport directly without the createLogger helper:

import { createTransport } from '@shellicar/pino-applicationinsights-transport';
import pino from 'pino';
import { TelemetryClient } from 'applicationinsights'; // Import from the installed version

// Initialize Azure Application Insights client
const client = new TelemetryClient(process.env.APPLICATIONINSIGHTS_CONNECTION_STRING);

// Create Application Insights transport stream
const appInsightsTransport = createTransport({
  client, // Pass the TelemetryClient instance
  version: 3, // Specify the version: 2 or 3
}, 'info'); // Default log level

// Create pino logger with multiple streams
const logger = pino({
  level: 'info',
}, pino.multistream([
  { stream: process.stdout, level: 'info' }, // Console stream
  { stream: appInsightsTransport, level: 'info' }, // Application Insights stream
]));

// Log messages
logger.info('Logging to both console and Application Insights');

API

createLogger(options: CreateLoggerOptions): pino.Logger

Creates a pino logger instance configured with Application Insights transport.

CreateLoggerOptions

• insights (required): Configuration options for Application Insights transport.
  • client: Instance of TelemetryClient from applicationinsights.
  • version: Specifies the version of Application Insights (2 or 3).
• pino (optional): Custom pino logger options.
• console (optional): Enable or disable console logging. Defaults to false.

createTransport(options: PinoApplicationInsightsTransportOptions, defaultLevel: LevelWithSilentOrString): Writable

Creates a writable stream that can be used as a pino transport for Application Insights.

PinoApplicationInsightsTransportOptions

• client: Instance of TelemetryClient from applicationinsights.
• version: Specifies the version of Application Insights (2 or 3).

Examples

Refer to the examples directory for detailed usage scenarios:

Development

Building the Project

The library uses tsup for bundling. To build the project, run:

pnpm build

Running Tests

Tests are written using Mocha. To run the tests:

pnpm test

License

This project is licensed under the MIT License.