Node.js and Honeycomb

note

Check out the source code on GitHub here.

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.

Cloud-based Managed Tracetest

Prerequisites

Tracetest Account:

• Sign up to app.tracetest.io or follow the get started docs.
• Create an environment.
• Create an environment token.
• Have access to the environment's agent API key.

Docker: Have Docker and Docker Compose installed on your machine.

Run This Quckstart Example

The example below is provided as part of the Tracetest project. You can download and run the example by following these steps:

Clone the Tracetest project and go to the Node.js Quickstart:

git clone https://github.com/kubeshop/tracetest
cd tracetest/examples/tracetest-honeycomb

Follow these instructions to run the quick start:

1. Copy the .env.template file to .env.
2. Log into the Tracetest app.
3. This example is configured to use the Honeycomb Tracing Backend. Ensure the environment you will be utilizing to run this example is also configured to use the Honeycomb Tracing Backend by clicking on Settings, Tracing Backend, Honeycomb, Save.
4. Fill out the token and API key details by editing your .env file. You can find these values in the Settings area for your environment.
5. Run docker compose -f ./docker-compose.agent.yaml up -d.
6. Run tests from the Tracetest Web UI by accessing the app with the URL http://app:8080/.

Follow along with the sections below for a detailed breakdown of what the example you just ran did and how it works.

Project Structure

The quick start Node.js project is built with Docker Compose and contains the Tracetest Agent and a Node.js app.

The docker-compose.agent.yaml file in the root directory of the quick start runs the Node.js app and the Tracetest Agent setup.

Configuring the Node.js App

The Node.js app is a simple Express app, contained in the app.js file.

Configure the .env like shown below.

TRACETEST_API_KEY="<YOUR_TRACETEST_API_KEY>"
HONEYCOMB_API_KEY="<YOUR_HONEYCOMB_API_KEY>"

The OpenTelemetry tracing is contained in the tracing.otel.grpc.js or tracing.otel.http.js files. Traces will be sent to Tracetest Agent.

Choosing the tracing.otel.grpc.js file will send traces to Tracetest Agent's GRPC endpoint.

Enabling the tracer is done by preloading the trace file. As seen in the package.json.

"scripts": {
  "app-with-grpc-tracer": "node -r ./tracing.otel.grpc.js app.js",
},

Configuring Honeycomb

Configure Honeycomb as a Tracing Backend in Tracetest.

tracetest-tracing-backend.yaml

---
type: DataStore
spec:
  name: Honeycomb
  type: honeycomb
  default: true

tracetest config -t <YOUR_API_TOKEN>
tracetest apply datastore -f ./tracetest-tracing-backend.yaml

Run the Node.js App, OpenTelemetry Collector, and Tracetest Agent with Docker Compose

To start the full setup, run the following command:

docker compose -f ./docker-compose.agent.yaml up -d

Run Tracetest Tests

1. Open Tracetest.
2. Configure Honeycomb as a tracing backend if you have not already as explained above.
3. Start creating tests! Make sure to use the http://app:8080/ URL in your test creation.
4. To trigger tests in the CLI, first install the CLI, configure it, and run a test. From the root of the quick start directory, run:

tracetest configure -t <YOUR_API_TOKEN>
tracetest run test -f ./test-api.yaml

Hobby Open-Source Tracetest Core

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!