@metis-data/pg-interceptor

Metis Pg Instrumentation

Using the Documentation of Metis.

Installation

$ npm i @metis-data/pg-interceptor --save

Setup

• Create tracing file (tracer):

import opentelemetry from '@opentelemetry/api';
import { registerInstrumentations } from '@opentelemetry/instrumentation';
import { Resource } from '@opentelemetry/resources';
import {
  BatchSpanProcessor,
  ConsoleSpanExporter,
  SimpleSpanProcessor,
} from '@opentelemetry/sdk-trace-base';
import { SemanticResourceAttributes } from '@opentelemetry/semantic-conventions';
import { getMetisExporter, MetisHttpInstrumentation, MetisPgInstrumentation } from '@metis-data/pg-interceptor';
import { AsyncHooksContextManager } from '@opentelemetry/context-async-hooks';

let tracerProvider;
const connectionString = process.env.PG_CONNECTION_STRING;

export const startMetisInstrumentation = () => {
  tracerProvider = new BasicTracerProvider({
    resource: new Resource({
      [SemanticResourceAttributes.SERVICE_NAME]: process.env.METIS_SERVICE_NAME,
      [SemanticResourceAttributes.SERVICE_VERSION]: 'service-version',
    }),
  });

  const metisExporter = getMetisExporter(process.env.METIS_API_KEY);

  tracerProvider.addSpanProcessor(new BatchSpanProcessor(metisExporter));
  
  if (process.env.OTEL_DEBUG) {
      tracerProvider.addSpanProcessor(new SimpleSpanProcessor(new ConsoleSpanExporter()));
  }

  const contextManager = new AsyncHooksContextManager();

  contextManager.enable();
  opentelemetry.context.setGlobalContextManager(contextManager);

  tracerProvider.register();

  // Urls regex to exclude from instrumentation
  const excludeUrls = [/favicon.ico/];
  registerInstrumentations({
    instrumentations: [
      new MetisPgInstrumentation({ connectionString }),
      new MetisHttpInstrumentation(excludeUrls)
    ],
  });
};

Environment:

• PG_CONNECTION_STRING: your database connection details e.g 'postgres://user:password@host:port/database'
• METIS_API_KEY: Metis Api Key generated at Metis
• OTEL_DEBUG: Console Span Exporter to have the span logged to console - optional

Pass a valid connectionString to Metis Interceptor, can be set through <process.env.PG_CONNECTION_STRING>, This will generate pg pool to collect queries plans.

:warning: Note: If for any reason connectionString is not available during the tracer setup, there is an option to set it later as follows:

import { setPgConnection } from '@metis-data/pg-interceptor';

// When the connectionString available
setPgConnection(connectionString);

Until connection string is passed, instrumentation will work but won't collect the queries plans.

For more details about tracing setup and components, visit our docs

• Import the tracing in your main app file:

import { startMetisInstrumentation } from './tracer';
startMetisInstrumentation();

// imports and bootstrap