Node.js and OpenTelemetry
Build integration and end-to-end tests in minutes, instead of days, using OpenTelemetry and Tracetest.
Node.js App with Tracetest​
This is a quick start on how to configure a Node.js app to use OpenTelemetry instrumentation with traces, and Tracetest for enhancing your E2E and integration tests with trace-based testing.
- Tracetest
- Tracetest Core
Prerequisites​
You can run this example with Docker, or locally with Node.js installed on your machine.
Project Structure​
The project contains Tracetest Agent and a Node.js app.
1. Tracetest Agent​
Install and run Tracetest Agent locally.
tracetest start
Once started, Tracetest Agent will:
- Expose OTLP ports
4317
(gRPC) and4318
(HTTP) for trace ingestion. - Be able to trigger test runs in the environment where it is running.
- Be able to connect to a trace data store that is not accessible outside of your environment.
2. Node.js App​
The Node.js app is a simple Express app, contained in the app.js
file.
The OpenTelemetry tracing is contained in the tracing.otel.grpc.js
or tracing.otel.http.js
files.
Traces will be sent to Tracetest Agent.
Here's the content of the tracing.otel.grpc.js
file:
const opentelemetry = require('@opentelemetry/sdk-node')
const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node')
const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-grpc');
const sdk = new opentelemetry.NodeSDK({
// OTEL_EXPORTER_OTLP_TRACES_ENDPOINT is passed into "new OTLPTraceExporter" automatically
traceExporter: new OTLPTraceExporter(),
instrumentations: [getNodeAutoInstrumentations()],
})
sdk.start()
Choosing the tracing.otel.grpc.js
file will send traces to Tracetest Agent's GRPC
.
Configure it an environment variable:
- Running in Docker:
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://host.docker.internal:4317
- Running locally:
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4317
Enabling the tracer is done by preloading the trace file.
node -r ./tracing.otel.grpc.js app.js
In the package.json
you will see two npm scripts for running the respective tracers alongside the app.js
.
"scripts": {
"with-grpc-tracer":"node -r ./tracing.otel.grpc.js app.js",
"with-http-tracer":"node -r ./tracing.otel.http.js app.js"
},
To start the server, run this command:
npm run with-grpc-tracer
# or
npm run with-http-tracer
Run the Node.js App with Docker Compose​
The docker-compose.yaml
file and Dockerfile
in the root directory are for the Node.js app.
As you can see, the Dockerfile
uses the command above.
FROM node:slim
WORKDIR /usr/src/app
COPY package*.json ./
RUN npm install
COPY . .
EXPOSE 8080
CMD [ "npm", "run", "with-grpc-tracer" ]
And, the docker-compose.yaml
contains just one service for the Node.js app.
version: '3'
services:
app:
image: quick-start-nodejs
extra_hosts:
- "host.docker.internal:host-gateway"
build: .
ports:
- "8080:8080"
environment:
- OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://host.docker.internal:4317
To start it, run this command:
docker compose build # optional if you haven't already built the image
docker compose up
This will start the Node.js app and send the traces to Tracetest Agent.
Run the Node.js App Locally​
Install Node.js and npm in your local development environment.
Install the npm modules, export the OTLP endpoint, and run the Node.js app.
npm i
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4317
npm run with-grpc-tracer
This will start the Node.js app and send the traces to Tracetest Agent.
Run Tracetest Tests​
Open Tracetest and start creating tests! Make sure to use the http://localhost:8080/
URL in your test creation.
Prerequisites​
You will need Docker and Docker Compose installed on your machine to run this quick start app!
Project Structure​
The project is built with Docker Compose. It contains two distinct docker-compose.yaml
files.
1. Node.js App​
The docker-compose.yaml
file and Dockerfile
in the root directory are for the Node.js app.
2. Tracetest Core​
The docker-compose.yaml
file, collector.config.yaml
, tracetest-provision.yaml
, and tracetest.config.yaml
in the tracetest
directory are for the setting up Tracetest and the OpenTelemetry Collector.
The tracetest
directory is self-contained and will run all the prerequisites for enabling OpenTelemetry traces and trace-based testing with Tracetest.
Docker Compose Network​
All services
in the docker-compose.yaml
are on the same network and will be reachable by hostname from within other services. E.g. tracetest:4317
in the collector.config.yaml
will map to the tracetest
service, where the port 4317
is the port where Tracetest accepts traces.
Node.js App​
The Node.js app is a simple Express app, contained in the app.js
file.
The OpenTelemetry tracing is contained in the tracing.otel.grpc.js
or tracing.otel.http.js
files.
Traces will be sent to the OpenTelemetry Collector.
Here's the content of the tracing.otel.grpc.js
file:
const opentelemetry = require('@opentelemetry/sdk-node')
const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node')
const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-grpc');
const sdk = new opentelemetry.NodeSDK({
traceExporter: new OTLPTraceExporter({ url: 'http://otel-collector:4317' }),
instrumentations: [getNodeAutoInstrumentations()],
})
sdk.start()
Depending on which of these you choose, traces will be sent to either the GRPC
or HTTP
endpoint.
The hostnames and ports for these are:
- GRPC:
http://otel-collector:4317
- HTTP:
http://otel-collector:4318/v1/traces
Enabling the tracer is done by preloading the trace file.
node -r ./tracing.otel.grpc.js app.js
In the package.json
you will see two npm scripts for running the respective tracers alongside the app.js
.
"scripts": {
"with-grpc-tracer":"node -r ./tracing.otel.grpc.js app.js",
"with-http-tracer":"node -r ./tracing.otel.http.js app.js"
},
To start the server, run this command:
npm run with-grpc-tracer
# or
npm run with-http-tracer
As you can see, the Dockerfile
uses the command above.
FROM node:slim
WORKDIR /usr/src/app
COPY package*.json ./
RUN npm install
COPY . .
EXPOSE 8080
CMD [ "npm", "run", "with-grpc-tracer" ]
And, the docker-compose.yaml
contains just one service for the Node.js app.
version: '3'
services:
app:
image: quick-start-nodejs
build: .
ports:
- "8080:8080"
To start it, run this command:
docker compose build # optional if you haven't already built the image
docker compose up
This will start the Node.js app. But, you're not sending the traces anywhere.
Let's fix this by configuring Tracetest and OpenTelemetry Collector.
Tracetest Core​
The docker-compose.yaml
in the tracetest
directory is configured with three services.
- Postgres - Postgres is a prerequisite for Tracetest to work. It stores trace data when running the trace-based tests.
- OpenTelemetry Collector - A vendor-agnostic implementation of how to receive, process and export telemetry data.
- Tracetest Core - Trace-based testing that generates end-to-end tests automatically from traces.
version: "3"
services:
tracetest:
image: kubeshop/tracetest:latest
platform: linux/amd64
volumes:
- type: bind
source: ./tracetest/tracetest-config.yaml
target: /app/tracetest.yaml
- type: bind
source: ./tracetest/tracetest-provision.yaml
target: /app/provisioning.yaml
ports:
- 11633:11633
command: --provisioning-file /app/provisioning.yaml
depends_on:
postgres:
condition: service_healthy
otel-collector:
condition: service_started
healthcheck:
test: ["CMD", "wget", "--spider", "localhost:11633"]
interval: 1s
timeout: 3s
retries: 60
postgres:
image: postgres:14
environment:
POSTGRES_PASSWORD: postgres
POSTGRES_USER: postgres
healthcheck:
test: pg_isready -U "$$POSTGRES_USER" -d "$$POSTGRES_DB"
interval: 1s
timeout: 5s
retries: 60
otel-collector:
image: otel/opentelemetry-collector-contrib:0.59.0
command:
- "--config"
- "/otel-local-config.yaml"
volumes:
- ./tracetest/collector.config.yaml:/otel-local-config.yaml
Tracetest Core depends on both Postgres and the OpenTelemetry Collector. Both Tracetest Core and the OpenTelemetry Collector require config files to be loaded via a volume. The volumes are mapped from the root directory into the tracetest
directory and the respective config files.
To start both the Node.js app and Tracetest Core we will run this command:
docker-compose -f docker-compose.yaml -f tracetest/docker-compose.yaml up # add --build if the images are not built already
The tracetest-config.yaml
file contains the basic setup of connecting Tracetest Core to the Postgres instance.
postgres:
host: postgres
user: postgres
password: postgres
port: 5432
dbname: postgres
params: sslmode=disable
The tracetest-provision.yaml
file provisions the trace data store and polling to store in the Postgres database. The data store is set to OTLP, meaning the traces will be sent to Tracetest Core.
But how are traces sent to Tracetest?
The collector.config.yaml
explains that. It receives traces via either grpc
or http
. Then, exports them to Tracetest's OLTP endpoint tracetest:4317
.
receivers:
otlp:
protocols:
grpc:
http:
processors:
batch:
timeout: 100ms
exporters:
logging:
loglevel: debug
otlp/1:
endpoint: tracetest:4317
# Send traces to Tracetest.
# Read more in docs here: https://docs.tracetest.io/configuration/connecting-to-data-stores/opentelemetry-collector
tls:
insecure: true
service:
pipelines:
traces/1:
receivers: [otlp]
processors: [batch]
exporters: [otlp/1]
Run Both the Node.js App and Tracetest​
To start both the Node.js app and Tracetest, run this command:
docker-compose -f docker-compose.yaml -f tracetest/docker-compose.yaml up # add --build if the images are not built already
This will start your Tracetest Core instance on http://localhost:11633/
.
Open the URL and start creating tests! Make sure to use the http://app:8080/
URL in your test creation, because your Node.js app and Tracetest Core are in the same network.
Learn More​
Feel free to check out our examples in GitHub and join our Slack Community for more info!