Nestjs OpenTelemetry Instrumentation

Requirements

Supported Versions

>=4.0.0

This document contains instructions on how to set up OpenTelemetry instrumentation in your Nestjs applications and view your application traces in SigNoz.

Send traces to SigNoz Cloud

Based on your application environment, you can choose the setup below to send traces to SigNoz Cloud.

From VMs, there are two ways to send data to SigNoz Cloud.

Send traces directly to SigNoz Cloud
- No Code Automatic Instrumentation (recommended)
- Code Level Automatic Instrumentation
Send traces via OTel Collector binary (recommended)
- No Code Automatic Instrumentation (recommended)
- Code Level Automatic Instrumentation

Send traces directly to SigNoz Cloud - No Code Automatic Instrumentation (recommended)

Step 1. Install OpenTelemetry packages

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

Step 2. Run the application

export OTEL_TRACES_EXPORTER="otlp"
export OTEL_EXPORTER_OTLP_ENDPOINT="https://ingest.<region>.signoz.cloud:443"
export OTEL_NODE_RESOURCE_DETECTORS="env,host,os"
export OTEL_SERVICE_NAME="<service_name>"
export OTEL_EXPORTER_OTLP_HEADERS="signoz-ingestion-key=<your-ingestion-key>"
export NODE_OPTIONS="--require @opentelemetry/auto-instrumentations-node/register"
<your_run_command>

Set the <region> to match your SigNoz Cloud region
Replace <your-ingestion-key> with your SigNoz ingestion key
<service_name> is name of your service
replace <your_run_command> with the run command of your application

Send traces directly to SigNoz Cloud - Code Level Automatic Instrumentation

Step 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

Step 2. Create tracer.ts or tracer.js file
You need to configure the endpoint for SigNoz cloud in this file.

tracing.ts

'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: 'https://ingest.<region>.signoz.cloud:443/v1/traces',
  headers: {
    "signoz-ingestion-key": "<your-ingestion-key>"
  }
  //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;

tracing.js

'use strict'
const process = require('process');
const opentelemetry = require('@opentelemetry/sdk-node');
const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');
const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-http');
const { Resource } = require('@opentelemetry/resources');
const { SemanticResourceAttributes } = require('@opentelemetry/semantic-conventions');

// do not set headers in exporterOptions, the OTel spec recommends setting headers through ENV variables
// https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/exporter.md#specifying-headers-via-environment-variables

// highlight-start
const exporterOptions = {
  url: 'https://ingest.<region>.signoz.cloud:443/v1/traces',
  headers: {
      "signoz-ingestion-key": "<your-ingestion-key>"
    }
}
// highlight-end

const traceExporter = new OTLPTraceExporter(exporterOptions);
const sdk = new opentelemetry.NodeSDK({
  traceExporter,
  instrumentations: [getNodeAutoInstrumentations()],
  resource: new Resource({
    // highlight-next-line
    [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));
});

Set the <region> to match your SigNoz Cloud region
Replace <your-ingestion-key> with your SigNoz ingestion key
<service_name> is name of your service

Step 3. On main.ts file or file where your app starts import tracer using below command.

✅ Info

The below import should be the first line in the main file of your application (Ex -> main.ts)

const tracer = require('./tracer')

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

const tracer = require('./tracer')

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
  // All of your application code and any imports that should leverage
  // OpenTelemetry automatic instrumentation must go here.

async function bootstrap() {
    // highlight-start
    await tracer.start();
    //highlight-end
    const app = await NestFactory.create(AppModule);
    await app.listen(3001);
  }
  bootstrap();

const tracer = require('./tracer')

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
  // All of your application code and any imports that should leverage
  // OpenTelemetry automatic instrumentation must go here.

async function bootstrap() {
  // highlight-start
    await tracer.start();
    //highlight-end
    const app = await NestFactory.create(AppModule);
    await app.listen(3001);
  }
  bootstrap();

Step 5. Run the application

nest start

The data captured with OpenTelemetry from your application should start showing on the SigNoz dashboard.

Step 6. You can validate if your application is sending traces to SigNoz cloud here.

In case you encounter an issue where all applications do not get listed in the services section then please refer to the troubleshooting section.

Send traces via OTel Collector binary - No Code Automatic Instrumentation

OTel Collector binary helps to collect logs, hostmetrics, resource and infra attributes. It is recommended to install Otel Collector binary to collect and send traces to SigNoz cloud. You can correlate signals and have rich contextual data through this way.

📝 Note

You can find instructions to install OTel Collector binary here in your VM. Once you are done setting up your OTel Collector binary, you can follow the below steps for instrumenting your Javascript application.

Step 1. Install OpenTelemetry packages

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

Step 2. Run the application

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

<service_name> is name of your service
replace <your_run_command> with the run command of your application

Send traces via OTel Collector binary - Code Level Automatic Instrumentation

📝 Note

Step 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

Step 2. Create tracer.ts or tracer.js file

tracing.ts

'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;

tracing.js

'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: 'http://localhost:4318/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));
});

module.exports = sdk;

<service_name> is name of your service

Step 3. On main.ts file or file where your app starts import tracer using below command.

✅ Info

The below import should be the first line in the main file of your application (Ex -> main.ts)

const tracer = require('./tracer')

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

const tracer = require('./tracer')

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
  // All of your application code and any imports that should leverage
  // OpenTelemetry automatic instrumentation must go here.

async function bootstrap() {
    // highlight-start
    await tracer.start();
    //highlight-end
    const app = await NestFactory.create(AppModule);
    await app.listen(3001);
  }
  bootstrap();

const tracer = require('./tracer');
const { NestFactory } = require('@nestjs/core');
const { AppModule } = require('./app.module');

// All of your application code and any imports that should leverage
// OpenTelemetry automatic instrumentation must go here.

async function bootstrap() {
    await tracer.start();
    const app = await NestFactory.create(AppModule);
    await app.listen(3001);
}
bootstrap();

Step 5. Run the application

  nest start

Step 6. You can validate if your application is sending traces to SigNoz cloud here.

In case you encounter an issue where all applications do not get listed in the services section then please refer to the troubleshooting section.

You can auto-instrument sending traces from NestJS application using one of the following methods:

Using Kubernetes OTel Operator (recommended)
Using OTel Collector Agent

K8s OTel Operator Based Automatic Instrumentation (recommended)

Send traces directly to SigNoz Cloud - Using K8s OTel Operator

For NestJS application deployed on Kubernetes, you can auto-instrument the traces using Kubernetes OpenTelemetry Operator.

An OpenTelemetry Operator is a Kubernetes Operator that manages OpenTelemetry Collectors and auto-instrumentation of workloads. It basically simplifies the deployment and management of OpenTelemetry in a Kubernetes environment.

The OpenTelemetry Operator provides two Custom Resource Definitions (CRDs):

OpenTelemetryCollector
Instrumentation

The OpenTelemetryCollector CRD allows you to deploy and manage OpenTelemetry Collectors in your Kubernetes cluster.

The Instrumentation CRD allows you to configure and inject OpenTelemetry auto-instrumentation libraries into your workloads.

Here are the steps you need to follow to auto-instrument NestJS application using OTel Operator:

Step 1. Install cert-manager

Run the following commands to apply cert manager.

kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.16.1/cert-manager.yaml

kubectl wait --for=condition=Available deployments/cert-manager -n cert-manager

Step 2. Install OpenTelemetry Operator

To install the operator in the existing K8s cluster, run the following command:

kubectl apply -f https://github.com/open-telemetry/opentelemetry-operator/releases/download/v0.116.0/opentelemetry-operator.yaml

Installing the OpenTelemetry Operator sets up the necessary components and configurations to enable the observability and monitoring of applications running in the cluster.

Step 3. Setup the OpenTelemetry Collector instance

Once the opentelemetry-operator has been deployed, you can proceed with the creation of the OpenTelemetry Collector (otelcol) instance. The OpenTelemetry Collector collects, processes, and exports telemetry data.

There are different deployment modes for the OpenTelemetryCollector, and you can specify them in the spec.mode section of the custom resource. The available deployment modes are:

The default method - the Deployment mode, will be used here.

To create a simple instance of the OpenTelemetry Collector, create a file otel-collector.yaml with the following contents:

otel-collector.yaml

apiVersion: opentelemetry.io/v1alpha1
kind: OpenTelemetryCollector
metadata:
  name: otel-collector
spec:
  mode: deployment
  config: |
    receivers:
      otlp:
        protocols:
          grpc:
            endpoint: 0.0.0.0:4317
          http:
            endpoint: 0.0.0.0:4318
    processors:
      batch: {}
      resource/env:
        attributes:
        - key: deployment.environment
          value: prod # can be dev, prod, staging etc. based on your environment
          action: upsert
    exporters:
      debug: {}
      otlp:
        endpoint: "ingest.<region>.signoz.cloud:443" # replace <region> with your region of SigNoz Cloud
        tls:
          insecure: false
        headers:
          "signoz-ingestion-key": "<your-ingestion-key>" # Obtain from https://{your-signoz-tenant-url}/settings/ingestion-settings
    service:
      pipelines:
        traces:
          receivers: [otlp]
          processors: [batch, resource/env]
          exporters: [otlp]

Set the <region> to match your SigNoz Cloud region
Replace <your-ingestion-key> with your SigNoz ingestion key

Apply the above yaml file using the following command:

kubectl apply -f otel-collector.yaml

Step 4. Setup the Instrumentation instance

Once the OpenTelemetry Collector instance has been deployed, the next step will be to create an instrumentation instance, which will be responsible for sending OTLP data to the OTel Collector.

Create a file instrumentation.yaml with the following contents:

instrumentation.yaml

apiVersion: opentelemetry.io/v1alpha1
kind: Instrumentation
metadata:
  name: traces-instrumentation
spec:
  exporter:
    endpoint: https://ingest.<region>.signoz.cloud:443  # replace <region> with your region of SigNoz Cloud
  env:
    - name: OTEL_EXPORTER_OTLP_HEADERS
      value: signoz-ingestion-key="<signoz-token>"  # Obtain from https://{your-signoz-url}/settings/ingestion-settings
    - name: OTEL_EXPORTER_OTLP_INSECURE
      value: "false"
  propagators:
    - tracecontext
    - baggage
    - b3
  sampler:
    type: parentbased_traceidratio
    argument: "1"
  nodejs:
    image: ghcr.io/open-telemetry/opentelemetry-operator/autoinstrumentation-nodejs:latest

Apply the above instrumentation using the following command:

kubectl apply -f instrumentation.yaml

Step 5. Auto-instrument your NestJS app with OpenTelemetry

Create deployment.yaml file for your NestJS application as follows:

deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nestjs-app
spec:
  selector:
    matchLabels:
      app: nestjs-app
  replicas: 1
  template:
    metadata:
      labels:
        app: nestjs-app
      annotations:
        instrumentation.opentelemetry.io/inject-nodejs: "true"
        resource.opentelemetry.io/service.name: "nestjs-app"
    spec:
      containers:
      - name: app
        image: nestjs-app:latest
        ports:
        - containerPort: 8080

It is important to add the following annotation under spec > template > metadata > annotations:

instrumentation.opentelemetry.io/inject-nodejs: "true"`

This helps in auto-instrumenting the traces from the NestJS application.

Apply the deployment using the following command:

kubectl apply -f deployment.yaml

With this, the auto-instrumentation of traces for NestJS application is ready.

Step 6. Running the NestJS application

In order to run the application on port 8080, run the following commands:

export POD_NAME=$(kubectl get pod -l app=<service-name> -o jsonpath="{.items[0].metadata.name}")  # service name is `nestjs-app` in this case.   

kubectl port-forward ${POD_NAME} 8080:8080

You can now access the application on port 8080.

You can validate if your application is sending traces to SigNoz cloud here.

In case you encounter an issue where all applications do not get listed in the services section then please refer to the troubleshooting section.

For NestJS application deployed on Kubernetes, you need to install OTel Collector agent in your k8s infra to collect and send traces to SigNoz Cloud. You can find the instructions to install OTel Collector agent here.

Once you have set up OTel Collector agent, you can proceed with OpenTelemetry Javascript instrumentation by following either of the two:

No Code Automatic Instrumentation
Code Level Automatic Instrumentation

No Code Automatic Instrumentation

Send traces directly to SigNoz Cloud - No Code Automatic Instrumentation

Step 1. Install OpenTelemetry packages

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

Step 2. Run the application

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

<service_name> is name of your service
replace <your_run_command> with the run command of your application

In case you encounter an issue where all applications do not get listed in the services section then please refer to the troubleshooting section.

Code Level Automatic Instrumentation

Step 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

Step 2. Create tracer.ts or tracer.js file

tracing.ts

'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;

tracing.js

'use strict';

const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');
const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-http');
const { Resource } = require('@opentelemetry/resources');
const opentelemetry = require('@opentelemetry/sdk-node');
const { SemanticResourceAttributes } = require('@opentelemetry/semantic-conventions');

// Configure the SDK to export telemetry data to the console
// Enable all auto-instrumentations from the meta package
const exporterOptions = {
  url: 'http://localhost:4318/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));
});

module.exports = sdk;

<service_name> : Name of your service.

Step 3. On main.ts file or file where your app starts import tracer using below command.

✅ Info

The below import should be the first line in the main file of your application (Ex -> main.ts)

const tracer = require('./tracer')

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

const tracer = require('./tracer')

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
  // All of your application code and any imports that should leverage
  // OpenTelemetry automatic instrumentation must go here.

async function bootstrap() {
    // highlight-start
    await tracer.start();
    //highlight-end
    const app = await NestFactory.create(AppModule);
    await app.listen(3001);
  }
  bootstrap();

const tracer = require('./tracer');
const { NestFactory } = require('@nestjs/core');
const { AppModule } = require('./app.module');

// All of your application code and any imports that should leverage
// OpenTelemetry automatic instrumentation must go here.

async function bootstrap() {
    await tracer.start();
    const app = await NestFactory.create(AppModule);
    await app.listen(3001);
}
bootstrap();

Step 5. Run the application

  nest start

Step 6. You can validate if your application is sending traces to SigNoz cloud here.

In case you encounter an issue where all applications do not get listed in the services section then please refer to the troubleshooting section.

From Windows, there are two ways to send data to SigNoz Cloud.

Send traces directly to SigNoz Cloud
- No Code Automatic Instrumentation (recommended)
- Code Level Automatic Instrumentation
Send traces via OTel Collector binary (recommended)
- No Code Automatic Instrumentation (recommended)
- Code Level Automatic Instrumentation

Send traces directly to SigNoz Cloud - No Code Automatic Instrumentation (recommended)

Step 1. Install OpenTelemetry packages

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

Step 2. Run the application

$env:OTEL_TRACES_EXPORTER="otlp"
$env:OTEL_EXPORTER_OTLP_ENDPOINT="ingest.<region>.signoz.cloud:443"
$env:OTEL_NODE_RESOURCE_DETECTORS="env,host,os"
$env:OTEL_SERVICE_NAME="<service_name>"
$env:OTEL_EXPORTER_OTLP_HEADERS="signoz-ingestion-key=<your-ingestion-key>"
$env:NODE_OPTIONS="--require @opentelemetry/auto-instrumentations-node/register"
<your_run_command>

Set the <region> to match your SigNoz Cloud region
Replace <your-ingestion-key> with your SigNoz ingestion key
<service_name> is name of your service
replace <your_run_command> with the run command of your application

Send traces directly to SigNoz Cloud - Code Level Automatic Instrumentation

Step 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

Step 2. Create tracer.ts or tracer.js file
You need to configure the endpoint for SigNoz cloud in this file.

tracing.ts

'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: 'https://ingest.<region>.signoz.cloud:443/v1/traces',
  headers: { 'signoz-ingestion-key': '<your-ingestion-key>' },
  //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;

tracing.js

'use strict';

const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');
const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-http');
const { Resource } = require('@opentelemetry/resources');
const opentelemetry = require('@opentelemetry/sdk-node');
const { SemanticResourceAttributes } = require('@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://ingest.<region>.signoz.cloud:443/v1/traces',
  headers: { 'signoz-ingestion-key': '<your-ingestion-key>' },
};

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));
});

module.exports = sdk;

Set the <region> to match your SigNoz Cloud region
Replace <your-ingestion-key> with your SigNoz ingestion key
<service_name> is name of your service

OpenTelemetry Node SDK currently does not detect the headers from .env files as of today. That’s why we need to include the variables in the tracer.js file itself.

Step 3. On main.ts file or file where your app starts import tracer using below command.

✅ Info

The below import should be the first line in the main file of your application (Ex -> main.ts)

const tracer = require('./tracer')

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

const tracer = require('./tracer')

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
  // All of your application code and any imports that should leverage
  // OpenTelemetry automatic instrumentation must go here.

async function bootstrap() {
    // highlight-start
    await tracer.start();
    //highlight-end
    const app = await NestFactory.create(AppModule);
    await app.listen(3001);
  }
  bootstrap();

const tracer = require('./tracer')

const { NestFactory } = require('@nestjs/core');
const { AppModule } = require('./app.module');

// All of your application code and any imports that should leverage
// OpenTelemetry automatic instrumentation must go here.

async function bootstrap() {
  await tracer.start();
  const app = await NestFactory.create(AppModule);
  await app.listen(3001);
}
bootstrap();

Step 5. Run the application

nest start

The data captured with OpenTelemetry from your application should start showing on the SigNoz dashboard.

Step 6. You can validate if your application is sending traces to SigNoz cloud here.

In case you encounter an issue where all applications do not get listed in the services section then please refer to the troubleshooting section.

Send traces via OTel Collector binary - No Code Automatic Instrumentation

📝 Note

Step 1. Install OpenTelemetry packages

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

Step 2. Run the application

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

<service_name> is name of your service
replace <your_run_command> with the run command of your application

Send traces via OTel Collector binary - Code Level Automatic Instrumentation

📝 Note

Step 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

Step 2. Create tracer.ts or tracer.js file

tracing.ts

'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;

tracing.js

'use strict';

const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');
const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-http');
const { Resource } = require('@opentelemetry/resources');
const opentelemetry = require('@opentelemetry/sdk-node');
const { SemanticResourceAttributes } = require('@opentelemetry/semantic-conventions');  

const exporterOptions = {
  url: 'http://localhost:4318/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));
});

module.exports = sdk;

<service_name> is name of your service

Step 3. On main.ts file or file where your app starts import tracer using below command.

✅ Info

The below import should be the first line in the main file of your application (Ex -> main.ts)

const tracer = require('./tracer')

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

const tracer = require('./tracer')

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
  // All of your application code and any imports that should leverage
  // OpenTelemetry automatic instrumentation must go here.

async function bootstrap() {
    // highlight-start
    await tracer.start();
    //highlight-end
    const app = await NestFactory.create(AppModule);
    await app.listen(3001);
  }
  bootstrap();

const tracer = require('./tracer')

const { NestFactory } = require('@nestjs/core');
const { AppModule } = require('./app.module');

// All of your application code and any imports that should leverage
// OpenTelemetry automatic instrumentation must go here.

async function bootstrap() {
  await tracer.start();
  const app = await NestFactory.create(AppModule);
  await app.listen(3001);
}
bootstrap();

Step 5. Run the application

  nest start

Step 6. You can validate if your application is sending traces to SigNoz cloud here.

In case you encounter an issue where all applications do not get listed in the services section then please refer to the troubleshooting section.

There are two ways to send data to SigNoz Cloud. You can containerize the images in both the cases.

Send traces directly to SigNoz Cloud
Send traces via OTel Collector binary (recommended)

Send traces directly to SigNoz Cloud

Step 1. Configure OpenTelemetry to run in Docker Container

Add the following in your Dockerfile.

...

# Install opentelemetry dependencies
RUN npm install @opentelemetry/api@1.9.0 @opentelemetry/auto-instrumentations-node@0.57.0

...

# Set environment variables for OpenTelemetry
ENV OTEL_TRACES_EXPORTER="otlp"
ENV OTEL_EXPORTER_OTLP_ENDPOINT="https://ingest.<region>.signoz.cloud:443"
ENV OTEL_NODE_RESOURCE_DETECTORS="env,host,os"
ENV OTEL_SERVICE_NAME="<service_name>"
ENV OTEL_EXPORTER_OTLP_HEADERS="signoz-ingestion-key=<your-ingestion-key>"
ENV NODE_OPTIONS="--require @opentelemetry/auto-instrumentations-node/register"

...

Set the <region> to match your SigNoz Cloud region
Replace <your-ingestion-key> with your SigNoz ingestion key
<service_name> is name of your service

The above steps install OpenTelemetry dependencies directly inside the Docker container without altering package.json of project & sets environment variables to export the traces.

Step 2. Run your Docker container

Here's how you can run your docker container:

docker build -t <image-name> . && docker run -d -p <host-port>:<container-port> <image-name>

Replace <image-name>, <host-port>, and <container-port> with values for your application.
-d runs the container in detached mode
-p maps a host port to a container port

Step 3. Validate if your application is sending traces to SigNoz cloud by following the instructions here.

In case you encounter an issue where all applications do not get listed in the services section then please refer to the troubleshooting section.

Send traces via OTel Collector binary

Step 1. Configure OpenTelemetry to run in Docker Container

Add the following in your Dockerfile.

# get the OpenTelemetry Collector //STAGE 1
FROM otel/opentelemetry-collector-contrib:0.131.0 AS otel

...

# Install OpenTelemetry Node.js dependencies
RUN npm install @opentelemetry/api@1.9.0 @opentelemetry/auto-instrumentations-node@0.57.0

# Copy OpenTelemetry Collector binary + config from STAGE 1
COPY --from=otel /otelcol-contrib /otelcol-contrib
COPY --from=otel /etc/otelcol-contrib /etc/otelcol-contrib
COPY config.yaml /etc/otelcol-contrib/config.yaml

...

# Expose ports for app + collector
EXPOSE 4317 4318 <APP_PORT>

... 

# Environment variables for Node.js instrumentation
ENV NODE_OPTIONS="--require @opentelemetry/auto-instrumentations-node/register"
ENV OTEL_SERVICE_NAME="node-js-auto-instrument"
ENV OTEL_TRACES_EXPORTER="otlp"
ENV OTEL_NODE_RESOURCE_DETECTORS="env,host,os"


# Point Node.js exporter to local collector
ENV OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4317"
ENV OTEL_EXPORTER_OTLP_PROTOCOL="grpc"

...

# Run both Collector and Node.js app in same container
CMD sh -c "/otelcol-contrib --config=/etc/otelcol-contrib/config.yaml & <run_command>"

Make sure you have config.yaml in root of the application. This config.yaml should be copied from third step of this

Replace <run_command> with the command to run your application
<service_name> is name of your service

Step 2. Run your Docker container

Run your docker container to start exporting.

docker build -t <image-name> . && docker run -d -p <host-port>:<container-port> <image-name>

Replace <image-name>, <host-port>, and <container-port> with values for your application.
-d runs the container in detached mode
-p maps a host port to a container port

Step 3. You can validate if your application is sending traces to SigNoz cloud by following the instructions here.

In case you encounter an issue where all applications do not get listed in the services section then please refer to the troubleshooting section.

Send Traces to Self-Hosted SigNoz

There are three major steps to using OpenTelemetry:

Instrumenting your Nestjs application with OpenTelemetry
Configuring exporter to send data to SigNoz
Validating that configuration to ensure that data is being sent as expected.

You have two choices for instrumenting your NestJS application with OpenTelemetry.

Use the all-in-one auto-instrumentation library(Recommended)
The auto-instrumentation library of OpenTelemetry is a meta package that provides a simple way to initialize multiple Nodejs instrumnetations.
✅ Info
If you are on K8s, you should checkout opentelemetry operators which enable auto instrumenting Javascript applications very easily.
Use a specific auto-instrumentation library
You can use individual auto-instrumentation libraries too for a specific component of your application. For example, you can use @opentelemetry/instrumentation-nestjs-core for instrumenting the Nestjs web framework.

Let's see how to instrument your Nestjs application with OpenTelemetry.

Using the all-in-one auto-instrumentation library

The recommended way to instrument your Nestjs application is to use the all-in-one auto-instrumentation library - @opentelemetry/auto-instrumentations-node. It provides a simple way to initialize multiple Nodejs instrumentations.

Internally, it calls the specific auto-instrumentation library for components used in the application. You can see the complete list here.

Steps to auto-instrument Nestjs application

Install the dependencies
We start by installing the relevant dependencies.
```
npm install --save @opentelemetry/sdk-node
npm install --save @opentelemetry/auto-instrumentations-node
npm install --save @opentelemetry/exporter-trace-otlp-http
```
📝 Note
If you run into any error, you might want to use these pinned versions of OpenTelemetry libraries used in this GitHub repo.
Create a tracer.ts or tracer.js file

tracing.ts

'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;

tracing.js

'use strict';

const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');
const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-http');
const { Resource } = require('@opentelemetry/resources');
const opentelemetry = require('@opentelemetry/sdk-node');
const { SemanticResourceAttributes } = require('@opentelemetry/semantic-conventions');

const exporterOptions = {
  url: 'http://localhost:4318/v1/traces',
};

const traceExporter = new OTLPTraceExporter(exporterOptions);
const sdk = new opentelemetry.NodeSDK({
  traceExporter,
  instrumentations: [getNodeAutoInstrumentations()],
});

// 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));
});

module.exports = sdk;

<service_name> : Name of your service.

On main.ts file or file where your app starts import tracer using below command.
✅ Info
The below import should be the first line in the main file of your application (Ex -> main.ts)

const tracer = require('./tracer')

Start the tracer
In the async function boostrap section of the application code, initialize the tracer as follows:

const tracer = require('./tracer')

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
  // All of your application code and any imports that should leverage
  // OpenTelemetry automatic instrumentation must go here.

async function bootstrap() {
    // highlight-start
    await tracer.start();
    //highlight-end
    const app = await NestFactory.create(AppModule);
    await app.listen(3001);
  }
  bootstrap();

const tracer = require('./tracer')
const { NestFactory } = require('@nestjs/core');
const { AppModule } = require('./app.module');

// All of your application code and any imports that should leverage
// OpenTelemetry automatic instrumentation must go here.

async function bootstrap() {  
    await tracer.start();
    const app = await NestFactory.create(AppModule);
    await app.listen(3001);
  }
  bootstrap();

Run the application
```
nest start
```

The data captured with OpenTelemetry from your application should start showing on the SigNoz dashboard.

In case you encounter an issue where all applications do not get listed in the services section then please refer to the troubleshooting section.

Validating instrumentation by checking for traces

With your application running, you can verify that you’ve instrumented your application with OpenTelemetry correctly by confirming that tracing data is being reported to SigNoz.

To do this, you need to ensure that your application generates some data. Applications will not produce traces unless they are being interacted with, and OpenTelemetry will often buffer data before sending. So you need to interact with your application and wait for some time to see your tracing data in SigNoz.

Validate your traces in SigNoz:

Trigger an action in your app that generates a web request. Hit the endpoint a number of times to generate some data. Then, wait for some time.
In SigNoz, open the Services tab. Hit the Refresh button on the top right corner, and your application should appear in the list of Applications.
Go to the Traces tab, and apply relevant filters to see your application’s traces.

Using a specific auto-instrumentation library

If you want to instrument only your Nestjs framework, then you need to use the following package:

npm install --save @opentelemetry/instrumentation-nestjs-core

📝 Note

In the above case, you will have to install packages for all the components that you want to instrument with OpenTelemetry individually. You can find detailed instructions here.

Troubleshooting your installation

Set an environment variable to run the OpenTelemetry launcher in debug mode, where it logs details about the configuration and emitted spans:

export OTEL_LOG_LEVEL=debug

The output may be very verbose with some benign errors. Early in the console output, look for logs about the configuration. Next, look for lines like the ones below, which are emitted when spans are emitted to SigNoz.

{
  "traceId": "985b66d592a1299f7d12ebca56ca1fe3",
  "parentId": "8d62a70aa335a227",
  "name": "bar",
  "id": "17ada85c3d55376a",
  "kind": 0,
  "timestamp": 1685674607399000,
  "duration": 299,
  "attributes": {},
  "status": { "code": 0 },
  "events": []
}
{
  "traceId": "985b66d592a1299f7d12ebca56ca1fe3",
  "name": "foo",
  "id": "8d62a70aa335a227",
  "kind": 0,
  "timestamp": 1585130342183948,
  "duration": 315,
  "attributes": {
    "name": "value"
  },
  "status": { "code": 0 },
  "events": [
    {
      "name": "event in foo",
      "time": [1585130342, 184213041]
    }
  ]
}

Running short applications (Lambda/Serverless/etc) If your application exits quickly after startup, you may need to explicitly shutdown the tracer to ensure that all spans are flushed:

opentelemetry.trace.getTracer('your_tracer_name').getActiveSpanProcessor().shutdown()

Sample NestJs Application

We have included a sample NestJs application with README.md at Sample NestJs App Github Repo.

Nestjs OpenTelemetry Instrumentation

Requirements

Send traces to SigNoz Cloud

Send traces directly to SigNoz Cloud - No Code Automatic Instrumentation (recommended)

Send traces directly to SigNoz Cloud - Code Level Automatic Instrumentation

Send traces via OTel Collector binary - No Code Automatic Instrumentation

Send traces via OTel Collector binary - Code Level Automatic Instrumentation

K8s OTel Operator Based Automatic Instrumentation (recommended)

Send traces directly to SigNoz Cloud - Using K8s OTel Operator

No Code Automatic Instrumentation

Send traces directly to SigNoz Cloud - No Code Automatic Instrumentation

Code Level Automatic Instrumentation

Send traces directly to SigNoz Cloud - No Code Automatic Instrumentation (recommended)

Send traces directly to SigNoz Cloud - Code Level Automatic Instrumentation

Send traces via OTel Collector binary - No Code Automatic Instrumentation

Send traces via OTel Collector binary - Code Level Automatic Instrumentation

Send traces directly to SigNoz Cloud

Send traces via OTel Collector binary

Send Traces to Self-Hosted SigNoz

Using the all-in-one auto-instrumentation library

Steps to auto-instrument Nestjs application

Validating instrumentation by checking for traces

Using a specific auto-instrumentation library

Troubleshooting your installation

Sample NestJs Application

Was this page helpful?