pino applicationinsights transport

Forward pino logger to Application Insights.

Have a look in Example app to get inspiration of how to use this lib.

Ships with fake applicationinsights helper test class.

Usage

1import { pino } from 'pino';
2import compose from '@0dep/pino-applicationinsights';
3import { Contracts } from 'applicationinsights';
4
5const tagKeys = new Contracts.ContextTagKeys();
6
7const transport = compose({
8  track(chunk) {
9    const { time, severity, msg: message, properties, exception } = chunk;
10    this.trackTrace({ time, severity, message, properties });
11    if (exception) this.trackException({ time, exception, severity });
12  },
13  connectionString: process.env.APPLICATIONINSIGHTS_CONNECTION_STRING,
14  config: { maxBatchSize: 1 },
15});
16
17const logger = pino(
18  {
19    level: 'trace',
20    mixin(context) {
21      return {
22        tagOverrides: {
23          [tagKeys.userId]: 'someUserIdPickedFromRequest',
24          ...context.tagOverrides,
25        },
26      };
27    },
28  },
29  transport,
30);

or as multi transport:

1import { pino } from 'pino';
2
3const transport = pino.transport({
4  targets: [
5    {
6      level: 'info',
7      target: '@0dep/pino-applicationinsights',
8      options: {
9        connectionString: process.env.APPLICATIONINSIGHTS_CONNECTION_STRING,
10        config: {
11          disableStatsbeat: true,
12        },
13      },
14    },
15    {
16      level: 'debug',
17      target: 'pino-pretty',
18      options: {
19        colorize: true,
20        ignore: 'pid,hostname',
21        translateTime: "yyyy-mm-dd'T'HH:MM:ss.l",
22      },
23    },
24  ],
25});
26
27const logger = pino({ level: 'trace' }, transport);

API

compose(opts[, TelemetryTransformation]) => Stream

Build transport stream function.

• opts:
  • connectionString: Application Insights connection string or instrumentation key
  • track(chunk): optional track function called with Telemetry client context, defaults to tracking trace and exception
    • chunk: Telemetry:ish object
  • config: optional Application Insights Telemetry client config
  • destination: optional destination stream, makes compose ignore the above options
  • ignoreKeys: optional pino ignore keys, used to filter telemetry properties, defaults to ['hostname', 'pid', 'level', 'time', 'msg']
• TelemetryTransformation: optional transformation stream extending TelemetryTransformation

class TelemetryTransformation(options[, config])

Telemetry transformation stream. Transforms pino log record to Telemetry:ish object.

• constructor(options[, config])
  • options: transform stream options, { objectMode: true } is always set
  • config: optional config object
    • ignoreKeys: optional pino ignore keys as string array
• _transform(chunk, encoding, callback)
• convertToTelemetry(chunk): convert pino log record string or object to telemetry:ish object
• convertLevel(level): map pino log level number to Contracts.SeverityLevel
• extractProperties(line, ignoreKeys): extract properties from log line
  • line: log line record object
  • ignoreKeys: configured ignore keys
• properties:
  • ignoreKeys: configured ignore keys, defaults to ['hostname', 'pid', 'level', 'time', 'msg']

Telemetrish object

• severity: pino log level mapped to application insights severeity level, i.e. Contracts.SeverityLevel
• msg: log message string
• properties: telemetry properties object, filtered through ignore keys
• exception?: logged Error if any
• [k: string]: any other properties that facilitate telemetry logging

class FakeApplicationInsights(setupString)

Intercept calls to application insights.

• constructor(setupString);
  • setupString: Fake application insights connection string
• expectMessageData(): Expect tracked message, returns Promise<FakeCollectData>
• expectEventData(): Expect tracked event, returns Promise<FakeCollectData>
• expectExceptionData(): Expect tracked exception, returns Promise<FakeCollectData>
• expectEventType(telemetryType: string): Expect tracked telemetry type, returns Promise<FakeCollectData>
  • telemetryType: Telemetry type string
• expect(count = 1): Expect tracked telemetrys, returns promise with list of FakeCollectData
  • count: wait for at least tracked telemetrys before returning, default is 1
• reset(): Reset expected faked Application Insights calls, calls nock.cleanAll
• properties:
  • client: TelemetryClient, used to get endpoint URL
  • _endpointURL: endpoint URL
  • _scope: nock Scope

Example

1import { randomUUID } from 'node:crypto';
2import 'mocha';
3import { pino } from 'pino';
4
5import compose from '@0dep/pino-applicationinsights';
6import { FakeApplicationInsights } from '@0dep/pino-applicationinsights/fake-applicationinsights';
7
8describe('test logger', () => {
9  const connectionString = `InstrumentationKey=${randomUUID()};IngestionEndpoint=https://ingestion.local;LiveEndpoint=https://livemonitor.local/`;
10
11  let fakeAI;
12  before(() => {
13    fakeAI = new FakeApplicationInsights(connectionString);
14  });
15  after(() => {
16    fakeAI.reset();
17  });
18
19  it('log event track event', async () => {
20    const transport = compose({
21      track(chunk) {
22        const { time, properties } = chunk;
23        this.trackEvent({ name: 'my event', time, properties, measurements: { logins: 1 } });
24      },
25      connectionString,
26      config: { maxBatchSize: 1, disableStatsbeat: true },
27    });
28    const logger = pino(transport);
29
30    const expectMessage = fakeAI.expectEventData();
31
32    logger.info({ bar: 'baz' }, 'foo');
33
34    const msg = await expectMessage;
35
36    expect(msg.body.data.baseData).to.deep.include({
37      properties: { bar: 'baz' },
38      measurements: { logins: 1 },
39      name: 'my event',
40    });
41
42    transport.destroy();
43  });
44});

FakeCollectData

An object representing the request sent to application insights.

• uri: request uri
• method: request method
• headers: request headers object
• body:
  • ver: some version number, usually 1
  • sampleRate: sample rate number, usually 100
  • tags: object with tags, tag names can be inspected under TelemetryClient.context.keys, e.g:
    • ai.application.ver: your package.json version
    • ai.device.id: ?
    • ai.cloud.roleInstance: computer hostname?
    • ai.device.osVersion: computer os
    • ai.cloud.role: Web maybe?
    • ai.device.osArchitecture: probably x64
    • ai.device.osPlatform: os platform, as the name says
    • ai.internal.sdkVersion: applicationinsights package version, e.g. node:2.9.1
    • [tag name]: any other tag found under TelemetryClient.context.keys
  • data:
    • baseType: telemetry type string
    • baseData:
      • ver: some version number, usually 2 for some reason
      • properties: telemetry properties object
      • [message]: logged message when tracking trace
      • [severityLevel]: applicationinsights severity level number when tracking trace and exception
      • [exceptions]: list of exceptions when tracking exception
        • message: error message
        • hasFullStack: boolean, true
        • parsedStack: stack parsed as objects
      • [x: string]: any other telemetry property
  • iKey: applicationinsights instrumentation key
  • name: some ms name with iKey and the tracked type
  • time: log time