This guide provides step-by-step instructions for setting up OpenTelemetry (OTel) instrumentation in your Nest.js applications to enable comprehensive observability. OpenTelemetry is an open-source framework that helps you collect telemetry data—such as traces, metrics, and logs—from your app to monitor its performance and health.

Once your telemetry data is captured, you can configure an exporter to send it directly to Atatus for advanced monitoring and insights.

The process of setting up OpenTelemetry in Nest.js involves three key steps:

Instrumenting Your Nest.js Application: Add the necessary OpenTelemetry components to your Nest.js app for trace and metric collection.
Configuring the Exporter: Set up the exporter to send your telemetry data to Atatus.
Validating the Setup: Verify that the configuration is working and that your data is being correctly sent to Atatus.

Sending Telemetry Data to Atatus in Two Ways

Send Telemetry Traces to Atatus

Option 1: No Code Automatic Instrumentation (recommended)
Option 2: Code Level Automatic Instrumentation

Send Traces Using the OTel Collector Binary

Option 1: No Code Automatic Instrumentation (recommended)
Option 2: Code Level Automatic Instrumentation

Send Telemetry Traces to Atatus

Option 1: No Code Automatic Instrumentation

  1. Install OpenTelemetry packages

    npm install --save @opentelemetry/api
npm install --save @opentelemetry/auto-instrumentations-node

  2. Run your application

    export OTEL_TRACES_EXPORTER="otlp"
export OTEL_EXPORTER_OTLP_ENDPOINT="https://otel-rx.atatus.com:443"
export OTEL_NODE_RESOURCE_DETECTORS="env,host,os"
export OTEL_SERVICE_NAME="<APP_NAME>"
export OTEL_EXPORTER_OTLP_HEADERS="api-key=ATATUS_INGESTION_KEY"
export NODE_OPTIONS="--require @opentelemetry/auto-instrumentations-node/register"
<your_run_command>

    You can get the ATATUS_INGESTION_KEY from Settings -> Account Settings -> API Keys in Atatus dashboard.

Option 2: Code Level Automatic Instrumentation

  1. Install OpenTelemetry packages

    npm install --save @opentelemetry/api@^1.6.0
npm install --save @opentelemetry/sdk-node@^0.45.0
npm install --save @opentelemetry/auto-instrumentations-node@^0.39.4
npm install --save @opentelemetry/exporter-trace-otlp-http@^0.45.0

  2. Create a tracer.ts file and add the following configuration.

    'use strict';

import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
import { Resource } from '@opentelemetry/resources';
import * as opentelemetry from '@opentelemetry/sdk-node';
import { SemanticResourceAttributes } from '@opentelemetry/semantic-conventions';

// Configure the SDK to export telemetry data to the console
// Enable all auto-instrumentations from the meta package
const exporterOptions = {
  url: 'https://otel-rx.atatus.com:443/v1/traces',
};

const traceExporter = new OTLPTraceExporter(exporterOptions);
const sdk = new opentelemetry.NodeSDK({
  traceExporter,
  instrumentations: [getNodeAutoInstrumentations()],
  resource: new Resource({
    [SemanticResourceAttributes.SERVICE_NAME]: '<service_name>',
  }),
});

// initialize the SDK and register with the OpenTelemetry API
// this enables the API to record telemetry
sdk.start();

// gracefully shut down the SDK on process exit
process.on('SIGTERM', () => {
  sdk
    .shutdown()
    .then(() => console.log('Tracing terminated'))
    .catch((error) => console.log('Error terminating tracing', error))
    .finally(() => process.exit(0));
});

export default sdk;

  3. In the main.ts file, or the file where your app starts, import the tracer using the following command.

    const tracer = require('./tracer')

  4. In the async function bootstrap section of the application code, initialize the tracer as follows:

    const tracer = require('./tracer')

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';

async function bootstrap() {

    await tracer.start();

    const app = await NestFactory.create(AppModule);
    await app.listen(3001);
  }
  bootstrap();

  5. Run the application with OTEL_EXPORTER_OTLP_HEADERS env as follows

    OTEL_EXPORTER_OTLP_HEADERS="api-key=ATATUS_INGESTION_KEY" nest start

Send Traces Using the OTel Collector Binary:

To collect and send traces to Atatus, it's recommended to install the OpenTelemetry (OTel) Collector binary. The OTel Collector helps gather logs, host metrics, resource, and infrastructure attributes, enabling richer contextual data and easier signal correlation.

For detailed instructions on setting up the OTel Collector binary on your VM, please refer to the official installation guide. Once the Collector is up and running, you can proceed with instrumenting your Java application to start sending telemetry data to Atatus.

Option 1: No Code Automatic Instrumentation

  1. Install OpenTelemetry packages

    npm install --save @opentelemetry/api
npm install --save @opentelemetry/auto-instrumentations-node

  2. Run your application

    export OTEL_TRACES_EXPORTER="otlp"
export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318/v1/traces"
export OTEL_NODE_RESOURCE_DETECTORS="env,host,os"
export OTEL_SERVICE_NAME="<APP_NAME>"
export NODE_OPTIONS="--require @opentelemetry/auto-instrumentations-node/register"
<your_run_command>

    You can get the ATATUS_INGESTION_KEY from Settings -> Account Settings -> API Keys in Atatus dashboard.

Option 2: Code Level Automatic Instrumentation

  1. Install OpenTelemetry packages

    npm install --save @opentelemetry/api@^1.6.0
npm install --save @opentelemetry/sdk-node@^0.45.0
npm install --save @opentelemetry/auto-instrumentations-node@^0.39.4
npm install --save @opentelemetry/exporter-trace-otlp-http@^0.45.0

  2. Create a tracer.ts file and add the following configuration.

    'use strict';

import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
import { Resource } from '@opentelemetry/resources';
import * as opentelemetry from '@opentelemetry/sdk-node';
import { SemanticResourceAttributes } from '@opentelemetry/semantic-conventions';

// Configure the SDK to export telemetry data to the console
// Enable all auto-instrumentations from the meta package
const exporterOptions = {
  //highlight-start
  url: 'http://localhost:4318/v1/traces',
  //highlight-end
};

const traceExporter = new OTLPTraceExporter(exporterOptions);
const sdk = new opentelemetry.NodeSDK({
  traceExporter,
  instrumentations: [getNodeAutoInstrumentations()],
  resource: new Resource({
    [SemanticResourceAttributes.SERVICE_NAME]: '<service_name>',
  }),
});

// initialize the SDK and register with the OpenTelemetry API
// this enables the API to record telemetry
sdk.start();

// gracefully shut down the SDK on process exit
process.on('SIGTERM', () => {
  sdk
    .shutdown()
    .then(() => console.log('Tracing terminated'))
    .catch((error) => console.log('Error terminating tracing', error))
    .finally(() => process.exit(0));
});

export default sdk;

  3. In the main.ts file, or the file where your app starts, import the tracer using the following command.

    const tracer = require('./tracer')

  4. In the async function bootstrap section of the application code, initialize the tracer as follows:

    const tracer = require('./tracer')

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';

async function bootstrap() {
    await tracer.start();

    const app = await NestFactory.create(AppModule);
    await app.listen(3001);
  }
  bootstrap();

  5. Run the application

    nest start