Node.js and Honeycomb
Tracetest is a testing tool based on OpenTelemetry that allows you to test your distributed application. It allows you to use data from distributed traces generated by OpenTelemetry to validate and assert if your application has the desired behavior defined by your test definitions.
Honeycomb is an observability solution that shows you the patterns and outliers of how users experience your code in complex and unpredictable environments.
Node.js App with Honeycomb, OpenTelemetry and 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 and Honeycomb as a trace data store.
Prerequisites​
You will need Docker and Docker Compose installed on your machine to run this sample app! Additionally, you will need a Honeycomb account and api key. Sign up to use Honeycomb here.
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​
The docker-compose.yaml
file, collector.config.yaml
, tracetest-provision.yaml
, and tracetest-config.yaml
in the root directory are for the setting up Tracetest and the OpenTelemetry Collector.
The root
directory is self-contained and will run all the prerequisites for enabling OpenTelemetry traces and trace-based testing with Tracetest, as well as routing all traces the Node.js App generates to Honeycomb.
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​
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 - Trace-based testing that generates end-to-end tests automatically from traces.
version: "3.2"
services:
tracetest:
restart: unless-stopped
image: kubeshop/tracetest:${TAG:-latest}
platform: linux/amd64
ports:
- 11633:11633
extra_hosts:
- "host.docker.internal:host-gateway"
volumes:
- type: bind
source: ./tracetest/tracetest-config.yaml
target: /app/tracetest.yaml
- type: bind
source: ./tracetest/tracetest-provision.yaml
target: /app/provision.yaml
command: --provisioning-file /app/provision.yaml
healthcheck:
test: ["CMD", "wget", "--spider", "localhost:11633"]
interval: 1s
timeout: 3s
retries: 60
depends_on:
postgres:
condition: service_healthy
otel-collector:
condition: service_started
environment:
TRACETEST_DEV: ${TRACETEST_DEV}
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.68.0
restart: unless-stopped
command:
- "--config"
- "/otel-local-config.yaml"
volumes:
- ./tracetest/collector.config.yaml:/otel-local-config.yaml
Tracetest depends on both Postgres and the OpenTelemetry Collector. Both Tracetest 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, run this command:
docker-compose up # add --build if the images are not built already
The tracetest-config.yaml
file contains the basic setup of connecting Tracetest to the Postgres instance.
# tracetest-config.yaml
---
postgres:
host: postgres
user: postgres
password: postgres
port: 5432
dbname: postgres
params: sslmode=disable
The tracetest-provision.yaml
file contains the data store setup. The data store is set to Honeycomb
meaning the traces will be received by Tracetest OTLP API and stored in Tracetest itself.
# tracetest-provision.yaml
---
type: DataStore
spec:
name: Honeycomb
type: honeycomb
How to Send Traces to Tracetest and Honeycomb
The collector.config.yaml
explains that. It receives traces via either grpc
or http
. Then, exports them to Tracetest's OTLP endpoint tracetest:4317
in one pipeline, and to Honeycomb in another.
Make sure to add your Honeycomb access token in the headers of the otlp/ls
exporter.
receivers:
otlp:
protocols:
grpc:
http:
processors:
batch:
timeout: 100ms
exporters:
logging:
logLevel: debug
# OTLP for Tracetest
otlp/tracetest:
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
# OTLP for Honeycomb
otlp/honeycomb:
endpoint: "api.honeycomb.io:443"
headers:
"x-honeycomb-team": <HONEYCOMB_API_KEY>
# Read more in docs here: https://docs.honeycomb.io/getting-data-in/otel-collector/
service:
pipelines:
traces/tracetest:
receivers: [otlp]
processors: [batch]
exporters: [otlp/tracetest]
traces/honeycomb:
receivers: [otlp]
processors: [batch]
exporters: [logging, otlp/honeycomb]
Run Both the Node.js App and Tracetest​
To start both the Node.js App and Tracetest, run this command:
docker-compose up # add --build if the images are not built already
This will start your Tracetest 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 are in the same network.
Run Tracetest Tests with the Tracetest CLI​
First, install the CLI. Then, configure the CLI:
tracetest configure --server-url http://localhost:11633
Once configured, you can run a test against the Tracetest instance via the terminal.
Check out the test-api.yaml
file.
# test-api.yaml
type: Test
spec:
id: W656Q0c4g
name: http://app:8080
description: akadlkasjdf
trigger:
type: http
httpRequest:
url: http://app:8080
method: GET
headers:
- key: Content-Type
value: application/json
specs:
- selector: span[tracetest.span.type="http" name="GET /" http.target="/" http.method="GET"]
assertions:
- attr:http.status_code = 200
- attr:tracetest.span.duration < 500ms
This file defines a test the same way you would through the Web UI.
To run the test, run this command in the terminal:
tracetest run test -f ./test-api.yaml
✔ http://app:8080 (http://localhost:11633/test/W656Q0c4g/run/2/test)
✔ span[tracetest.span.type="http" name="GET /" http.target="/" http.method="GET"]
View Trace Spans Over Time in Honeycomb​
To access a historical overview of all the trace spans the Node.js App generates, jump over to your Honeycomb account.
You can also drill down into a particular trace.
With Honeycomb and Tracetest, you get the best of both worlds. You can run trace-based tests and automate running E2E and integration tests against real trace data. And, use Honeycomb to get a historical overview of all traces your distributed application generates.
Learn More​
Feel free to check out our examples in GitHub and join our Slack Community for more info!