npm package: @shellicar/pino-applicationinsights-transport
Description: Azure Application Insights transport for pino
Author: Stephen Hellicar
Latest version: 1.0.2

# @shellicar/pino-applicationinsights-transport

Azure Application Insights transport for [pino](https://github.com/pinojs/pino)

## Overview

`@shellicar/pino-applicationinsights-transport` is a transport module for the [pino](https://github.com/pinojs/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`

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

### Install with `applicationinsights@^3`

```bash
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.

```typescript
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.

```typescript
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:

```typescript
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](./examples) directory for detailed usage scenarios:

## Development

### Building the Project

The library uses [tsup](https://github.com/egoist/tsup) for bundling. To build the project, run:

```bash
pnpm build
```

### Running Tests

Tests are written using [Mocha](https://github.com/mochajs/mocha). To run the tests:

```bash
pnpm test
```

## License

This project is licensed under the [MIT License](./LICENSE).