This document contains instructions on how to set up OpenTelemetry instrumentation in your express applications and view your application traces in SigNoz.
Requirements
Supported Versions
^4.0.0
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
- Send traces via OTel Collector binary (recommended)
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 tracing.js or tracing.ts file
You need to configure the endpoint for SigNoz cloud in this file. You can find your ingestion key from SigNoz cloud account details sent on your email.
'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));
});
import * as opentelemetry from '@opentelemetry/sdk-node';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto';
import { resourceFromAttributes } from '@opentelemetry/resources';
import { SemanticResourceAttributes } from '@opentelemetry/semantic-conventions';
const sdk = new opentelemetry.NodeSDK({
traceExporter: new OTLPTraceExporter({
// optional - default url is http://localhost:4318/v1/traces
url: 'https://ingest.<region>.signoz.cloud:443/v1/traces', // url is optional and can be omitted
headers: {
"signoz-ingestion-key": "<your-ingestion-key>"
} // an optional object containing custom headers to be sent with each request
}),
instrumentations: [getNodeAutoInstrumentations()],
resource: resourceFromAttributes({
// highlight-next-line
[SemanticResourceAttributes.SERVICE_NAME]: '<service_name>'
})
});
sdk.start();
- 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. Run the application
node -r ./tracing.js index.js
Import tracing file in main.tsx
// main.tsx
import './tracing';
Run the app
node ts-node src/index.ts
Step 4. 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.
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
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.
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@^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 tracing.js or tracing.ts file
'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');
const exporterOptions = {
url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT || 'http://localhost:4318/v1/traces',
}
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));
});
import process from 'process';
import { NodeSDK } from '@opentelemetry/sdk-node';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
import { Resource } from '@opentelemetry/resources';
import { SemanticResourceAttributes } from '@opentelemetry/semantic-conventions';
const exporterOptions = {
url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT || '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))
})
<service_name>is name of your service
Step 4. 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 ExpressJS 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 ExpressJS 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):
OpenTelemetryCollectorInstrumentation
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 ExpressJS 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:
- Daemonset
- Sidecar
- StatefulSet
- Deployment (default mode)
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:
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:
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 ExpressJS app with OpenTelemetry
Create deployment.yaml file for your ExpressJS application as follows:
apiVersion: apps/v1
kind: Deployment
metadata:
name: expressjs-app
spec:
selector:
matchLabels:
app: expressjs-app
replicas: 1
template:
metadata:
labels:
app: expressjs-app
annotations:
instrumentation.opentelemetry.io/inject-nodejs: "true"
resource.opentelemetry.io/service.name: "expressjs-app"
spec:
containers:
- name: app
image: expressjs-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 ExpressJS application.
Apply the deployment using the following command:
kubectl apply -f deployment.yaml
With this, the auto-instrumentation of traces for ExpressJS application is ready.
Step 6. Running the ExpressJS 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 `expressjs-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 ExpressJS 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
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 tracing.js or tracing.ts file
'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');
const exporterOptions = {
url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT || 'http://localhost:4318/v1/traces',
}
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));
});
<service_name>is name of your service
import process from 'process';
import { NodeSDK } from '@opentelemetry/sdk-node';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
import { Resource } from '@opentelemetry/resources';
import { SemanticResourceAttributes } from '@opentelemetry/semantic-conventions';
const exporterOptions = {
url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT || '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))
})
<service_name>is name of your service
Step 3. Run the application
node -r ./tracing.js app.js
Step 4. 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
- Send traces via OTel Collector binary (recommended)
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 tracing.js or tracing.ts file
You need to configure the endpoint for SigNoz cloud in this file. You can find your ingestion key from SigNoz cloud account details sent on your email.
'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': process.env.SIGNOZ_INGESTION_KEY || <your-ingestion-key> }, // Use if you are using SigNoz Cloud
}
// 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))
})
import process from 'process';
import { NodeSDK } from '@opentelemetry/sdk-node';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
import { Resource } from '@opentelemetry/resources';
import { SemanticResourceAttributes } from '@opentelemetry/semantic-conventions';
const exporterOptions = {
url: 'https://ingest.<region>.signoz.cloud:443/v1/traces',
headers: { 'signoz-ingestion-key': process.env.SIGNOZ_INGESTION_KEY || <your-ingestion-key> }, // Use if you are using SigNoz Cloud
}
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))
})
- 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 tracing.js file itself.
Step 3. Run the application
node -r ./tracing.js app.js
We have used -r flag to preload tracing.js as commonjs, alternatively you can modify your run script in package.json's script section.
Step 4. 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.
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
$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
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.
You can find instructions to install OTel Collector binary here in your Windows machine. 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@^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 tracing.js or tracing.ts file
'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')
const exporterOptions = {
url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT || 'http://localhost:4318/v1/traces',
}
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))
})
import process from 'process';
import { NodeSDK } from '@opentelemetry/sdk-node';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
import { Resource } from '@opentelemetry/resources';
import { SemanticResourceAttributes } from '@opentelemetry/semantic-conventions';
const exporterOptions = {
url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT || '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))
})
Set OTEL_EXPORTER_OTLP_ENDPOINT as env variable using powershell:
$env:OTEL_EXPORTER_OTLP_ENDPOINT="<otlp_endpoint>"
Step 3. Run the application
node -r ./tracing.js app.js
Step 4. 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 to Self-Hosted SigNoz
You have two choices for instrumenting your Express 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.✅ InfoIf 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-expressfor instrumenting the Express web framework.
Let's see how to instrument your Express application with OpenTelemetry.
Using the all-in-one auto-instrumentation library
The recommended way to instrument your Express 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 Express 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-httpThe dependencies included are briefly explained below:
@opentelemetry/sdk-node- This package provides the full OpenTelemetry SDK for Node.js including tracing and metrics.@opentelemetry/auto-instrumentations-node- This module provides a simple way to initialize multiple Node instrumentations.@opentelemetry/exporter-trace-otlp-http- This module provides the exporter to be used with OTLP (http/json) compatible receivers.📝 NoteIf you run into any error, you might want to use these pinned versions of OpenTelemetry libraries used in this GitHub repo.
Create a
tracing.jsfile
Thetracing.jsfile will contain the tracing setup code. Notice, that we have set some environment variables in the code(highlighted). You can update these variables based on your environment.
'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');
const exporterOptions = {
// highlight-next-line
url: 'http://localhost:4318/v1/traces'
}
const traceExporter = new OTLPTraceExporter(exporterOptions);
const sdk = new opentelemetry.NodeSDK({
traceExporter,
instrumentations: [getNodeAutoInstrumentations()],
// highlight-start
resource: new Resource({
[SemanticResourceAttributes.SERVICE_NAME]: '<service_name>'
})
// highlight-end
});
// 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));
});
import process from 'process';
import { NodeSDK } from '@opentelemetry/sdk-node';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
import { Resource } from '@opentelemetry/resources';
import { SemanticResourceAttributes } from '@opentelemetry/semantic-conventions';
const exporterOptions = {
url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT || '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))
})
OpenTelemetry Node SDK currently does not detect the OTEL_RESOURCE_ATTRIBUTES from .env files as of today. That’s why we need to include the variables in the tracing.js file itself.
About environment variables:
<service_name>is name of your servicehttp://localhost:4318/v1/tracesis the default url for sending your tracing data. We are assuming you have installed SigNoz on yourlocalhost. Based on your environment, you can update it accordingly. It should be in the following format:http://<IP of SigNoz backend>:4318/v1/tracesHere’s a handy grid to figure out which address to use to send data to SigNoz.
📝 NoteRemember to allow incoming requests to port 4318 of machine where SigNoz backend is hosted.
Run the application
The tracing configuration should be run before your application code. We will use the-r, —require moduleflag for that.node -r ./tracing.js app.js📝 NoteIf you're running your nodejs application in PM2 cluster mode, it doesn't support node args: Unitech/pm2#3227. As above sample app instrumentation requires to load
tracing.jsbefore app load by passing node arg, so nodejs instrumentation doesn't work in PM2 cluster mode. So you need to importtracing.jsin your main application. Theimport ./tracing.jsshould be the first line of your application code and initialize it before any other function. Here's the sample github repo which shows the implementation.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
Servicestab. Hit theRefreshbutton on the top right corner, and your application should appear in the list ofApplications. - Go to the
Tracestab, and apply relevant filters to see your application’s traces.
Using a specific auto-instrumentation library
If you want to instrument only your Express framework, then you need to use the following package:
npm install --save @opentelemetry/instrumentation-express
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 Express App
- We have included a sample applications at: Sample NodeJs App Github Repo
