Node.js and Sumo Logic
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.
Sumo Logic is a cloud-based machine data analytics company focusing on security, operations and BI use-cases. It provides log management and analytics services that use machine-generated big data.
Node.js App with Sumo Logic, OpenTelemetry, and Tracetest​
This is a simple 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. The infrastructure will use Sumo Logic as the trace data store, and the Sumo Logic distribution of OpenTelemetry Collector to receive traces from the Node.js app and send them to Sumo Logic.
- Cloud-based Managed Tracetest
- Hobby Open-Source Tracetest Core
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.
Sumo Logic Account:
- Sign up to Sumo Logic
- Create a Sumo Logic installation token
- Create a Sumo Logic
accessID
andaccessKey
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 Sumo Logic Node.js Quickstart:
git clone https://github.com/kubeshop/tracetest
cd tracetest/examples/quick-start-sumologic-nodejs
Follow these instructions to run the quick start:
- Copy the
.env.template
file to.env
. - Log into the Tracetest app.
- 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. - Run
docker compose up -d
. - This example is configured to use the Sumo Logic Tracing Backend. Ensure the environment you're using to run this example is configured to use the Sumo Logic Tracing Backend by clicking on Settings, Tracing Backend, Sumo Logic, Save. Or, use the CLI as explained below.
- Run tests from the Tracetest Web UI by accessing the app with the URL
http://app:8080/
.
Follow along with the sections below for an in detail breakdown of what the example you just ran did and how it works.
Project Structure​
The project contains Tracetest Agent, Sumo Logic OpenTelemetry Collector, and a Node.js app.
The docker-compose.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>"
The OpenTelemetry tracing is contained in the tracing.otel.grpc.js
or tracing.otel.http.js
files.
Choosing the tracing.otel.grpc.js
file will send traces to Sumo Logic OpenTelemetry Collector'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 Sumo Logic​
Configure the .env
like shown below.
SUMOLOGIC_INSTALLATION_TOKEN="<YOUR_SUMOLOGIC_INSTALLATION_TOKEN>"
View the Sumo Logic docs here to learn more about installation tokens.
Configure Sumo Logic as a Tracing Backend:
---
type: DataStore
spec:
name: Sumo Logic
type: sumologic
sumologic:
# The URL will differ based on your location. View this
# docs page to figure out which URL you need:
# https://help.sumologic.com/docs/api/getting-started/#which-endpoint-should-i-should-use
url: "https://api.sumologic.com/api/"
# Create your ID and Key under Administration > Security > Access Keys
# in your Sumo Logic account:
# https://help.sumologic.com/docs/manage/security/access-keys/#create-your-access-key
accessID: "your-access-id"
accessKey: "your-access-key"
- Your Sumo Logic URL will differ based on which region you are using. Here's a guide which Sumo Logic API endpoint to use.
- Create your ID and Key under Administration > Security > Access Keys in your Sumo Logic account.
tracetest config -t <YOUR_API_TOKEN>
tracetest apply datastore -f ./tracetest.datastore.yaml
Run the Node.js App and Sumo Logic OpenTelemetry Collector with Docker Compose​
The docker-compose.yaml
file and Dockerfile
in the root directory are for the Node.js app.
And, the docker-compose.yaml
contains one service for the Node.js app, one service for the Sumo Logic OpenTelemetry Collector, and one service for Tracetest Agent.
The collector.config.yaml
configures the OpenTelemetry Collector. It receives traces via either grpc
or http
. Then, exports them to Sumo Logic via the Sumo Logic extension
and an installation_token
.
To start it, run this command:
docker compose up -d
This will start the Node.js app and Sumo Logic OpenTelemetry Collector and send the traces to Sumo Logic.
Run Tracetest Tests​
- Open Tracetest
- Configure Sumo Logic as a tracing backend if you have not already as explained above.
- Start creating tests! Make sure to use the
http://app:8080/
URL in your test creation. - 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
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, tracetest-provision.yaml
, and tracetest.config.yaml
in the tracetest
directory are for the setting up Tracetest.
The tracetest
directory is self-contained and will run all the prerequisites for enabling 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. app:8080
will map to the app
service.
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({
// 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://otel-collector:4317
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 one service for the Node.js app and one service for the Sumo Logic OpenTelemetry Collector.
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://otel-collector:4317
otel-collector:
image: public.ecr.aws/sumologic/sumologic-otel-collector:0.75.0-sumo-0
volumes:
- ./collector.config.yaml:/etc/otel/config.yaml
Traces sent to Sumo Logic from the OpenTelemetry Collector.
The collector.config.yaml
configures the OpenTelemetry Collector. It receives traces via either grpc
or http
. Then, exports them to Sumo Logic via the Sumo Logic extension
and an installation_token
.
View the Sumo Logic docs here to learn more about installation tokens.
receivers:
otlp:
protocols:
grpc:
http:
exporters:
sumologic:
extensions:
sumologic:
installation_token: <your-sumologic-installation-token>
service:
extensions: [sumologic]
pipelines:
traces:
receivers: [otlp]
exporters: [sumologic]
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 Sumo Logic OpenTelemetry Collector and send the traces to Sumo Logic.
Let's add trace-based testing by configuring Tracetest.
Tracetest Core​
The docker-compose.yaml
in the tracetest
directory is configured with two services.
- Postgres - Postgres is a prerequisite for Tracetest to work. It stores trace data when running the trace-based tests.
- 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
Tracetest Core depends on both Postgres and the Sumo Logic OpenTelemetry Collector from the root docker-compose.yaml
. Tracetest Core requires 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 build
docker-compose -f docker-compose.yaml -f tracetest/docker-compose.yaml up
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 Sumo Logic, meaning the Tracetest Core will fetch traces from Sumo Logic when tests are run.
You'll need to set Sumo Logic:
- URL
- Access ID
- Access Key
- Your Sumo Logic URL will differ based on which region you are using. Here's a guide which Sumo Logic API endpoint to use.
- Create your ID and Key under Administration > Security > Access Keys in your Sumo Logic account.
- View the Sumo Logic configuration docs for guidance.
---
type: PollingProfile
spec:
name: Default
strategy: periodic
default: true
periodic:
retryDelay: 5s
timeout: 10m
---
type: DataStore
spec:
name: Sumo Logic
type: sumologic
sumologic:
url: "https://api.sumologic.com/api/"
accessID: "your-access-id"
accessKey: "your-access-key"
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 build
docker-compose -f docker-compose.yaml -f tracetest/docker-compose.yaml up
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!