id | title | description | hide_table_of_contents | keywords | image | |||||
---|---|---|---|---|---|---|---|---|---|---|
running-tracetest-with-aws-x-ray-adot |
Node.js with AWS X-Ray (Node.js SDK) and AWS Distro for OpenTelemetry |
Quick start on how to configure a Node.js app with OpenTelemetry traces, AWS X-Ray as a trace data store, including AWS Distro for OpenTelemetry, and Tracetest for enhancing your E2E and integration tests with trace-based testing. |
true |
|
import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import CodeBlock from '@theme/CodeBlock';
:::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.
AWS X-Ray provides a complete view of requests as they travel through your application and filters visual data across payloads, functions, traces, services, APIs and more with no-code and low-code motions.
AWS Distro for OpenTelemetry (ADOT) is a secure, production-ready, AWS-supported distribution of the OpenTelemetry project. Part of the Cloud Native Computing Foundation, OpenTelemetry provides open source APIs, libraries and agents to collect distributed traces and metrics for application monitoring.
This is a simple quick start guide on how to configure a Node.js app to use instrumentation with traces and Tracetest for enhancing your E2E and integration tests with trace-based testing. The infrastructure will use AWS X-Ray as the trace data store, the ADOT as a middleware and a Node.js app to generate the telemetry data.
<Tabs groupId="running-tracetest-without-a-trace-data-store">
<TabItem value="Tracetest" label="Cloud-based Managed Tracetest" default>
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.
AWS Account:
Docker: Have Docker and Docker Compose installed on your machine.
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 AWS X-Ray Node.js Quickstart:
git clone https://github.com/kubeshop/tracetest
cd tracetest/examples/tracetest-amazon-x-ray-adot
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. - Fill out the AWS credentials in the
.env
file. You can create credentials by following this guide. - Run
docker compose -f ./docker-compose.agent.yaml up -d
. - This example is configured to use the OpenTelemetry Collector (OTLP) Tracing Backend. Ensure the environment you're using to run this example is configured to use the OpenTelemetry Collector Tracing Backend by clicking on Settings, Tracing Backend, OpenTelemetry Collector, Save. Or, use the CLI as explained below.
- Run tests from the Tracetest Web UI by accessing the app with the URL
http://app:3000/http-request/
.
Follow along with the sections below for an in detail breakdown of what the example you just ran did and how it works.
The project 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, AWS Distro for OpenTelemetry (ADOT), and the Tracetest Agent setup.
The Node.js app is a simple Express app, contained in the index.js
file.
Configure the .env
like shown below.
AWS_ACCESS_KEY_ID="<YOUR_AWS_ACCESS_KEY_ID>"
AWS_SECRET_ACCESS_KEY="<YOUR_AWS_SECRET_ACCESS_KEY>"
AWS_SESSION_TOKEN="<YOURAWS_SESSION_TOKEN>"
AWS_REGION="<YOUR_AWS_REGION>"
TRACETEST_API_KEY="<YOUR_TRACETEST_API_KEY>"
TRACETEST_API_TOKEN="<YOUR_TRACETEST_TOKEN>"
The X-Ray tracing is contained in the index.js
file. Traces will be sent to AWS X-Ray via ADOT.
Get temporary credentials.
aws sts get-session-token
{
"Credentials": {
"AccessKeyId": "<yourkeyid>",
"SecretAccessKey": "<youraccesskey>",
"SessionToken": "<yoursessiontoken>",
"Expiration": "2024-05-23T21:01:38+00:00"
}
}
Configure OTLP as a Tracing Backend in Tracetest.
---
type: DataStore
spec:
name: otlp
type: otlp
tracetest config -t <YOUR_API_TOKEN>
tracetest apply datastore -f ./tracetest-tracing-backend.yaml
The docker-compose.agent.yaml
file and Dockerfile
in the root directory contain the Node.js app.
The docker-compose.agent.yaml
file also contains the Tracetest Agent and ADOT.
To start it, run this command:
docker compose -f ./docker-compose.agent.yaml up -d
This will start the Node.js app and Tracetest Agent.
- Open Tracetest.
- Configure OpenTelemetry Collector as a tracing backend if you have not already as explained above.
- Start creating tests! Make sure to use the
http://app:3000/http-request/
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
</TabItem>
<TabItem value="Tracetest Core" label="Hobby Open-Source Tracetest Core">
You will need Docker and Docker Compose installed on your machine to run this quick start app!
The project is built with Docker Compose.
The Dockerfile
in the root directory is for the Node.js app.
The docker-compose.yaml
file, tracetest.provision.yaml
, and tracetest-config.yaml
in the root
directory are for the setting up the Node.js App, Tracetest and ADOT Collector.
All services
in the docker-compose.yaml
are on the same network and will be reachable by hostname from within other services. For example, adot-collector:2000
in the src/index.js
will map to the adot-collector
service, where port 2000
is the port where the X-Ray Daemon accepts telemetry data.
The Node.js app is a simple Express app, contained in the src/index.js
file.
It is instrumented using AWS X-Ray SDK, sending the data to the ADOT collector that will push the telemetry information to both the AWS service and the Tracetest OLTP endpoint.
The key instrumentation section from the src/index.js
file.
const AWSXRay = require("aws-xray-sdk");
const XRayExpress = AWSXRay.express;
const express = require("express");
AWSXRay.setDaemonAddress("adot-collector:2000");
// Capture all AWS clients we create
const AWS = AWSXRay.captureAWS(require("aws-sdk"));
AWS.config.update({
region: process.env.AWS_REGION || "us-west-2",
});
// Capture all outgoing https requests
AWSXRay.captureHTTPsGlobal(require("https"));
const https = require("https");
const app = express();
const port = 3000;
app.use(XRayExpress.openSegment("Tracetest"));
To start the server run this command.
npm start
As you can see the Dockerfile
uses the command above.
FROM node:slim
WORKDIR /usr/src/app
COPY ./src/package*.json ./
RUN npm install
COPY ./src .
EXPOSE 3000
CMD [ "npm", "start" ]
The docker-compose.yaml
includes three other services.
- Postgres - Postgres is a prerequisite for Tracetest to work. It stores trace data when running the trace-based tests.
- AWS Distro for OpenTelemetry (ADOT) - Software application that listens for traffic on UDP port 2000, gathers raw segment data and relays it to the AWS X-Ray API. The daemon works in conjunction with the AWS X-Ray SDKs and must be running so that data sent by the SDKs can reach the X-Ray service.
- Tracetest - Trace-based testing that generates end-to-end tests automatically from traces.
version: "3"
services:
tracetest:
image: kubeshop/tracetest:${TAG:-latest}
platform: linux/amd64
volumes:
- type: bind
source: ./tracetest-config.yaml
target: /app/tracetest.yaml
- type: bind
source: ./tracetest.provision.yaml
target: /app/provisioning.yaml
ports:
- 11633:11633
command: --provisioning-file /app/provisioning.yaml
extra_hosts:
- "host.docker.internal:host-gateway"
depends_on:
postgres:
condition: service_healthy
adot-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
ports:
- 5432:5432
adot-collector:
image: amazon/aws-otel-collector:latest
command:
- "--config"
- "/otel-local-config.yaml"
volumes:
- ./collector.config.yaml:/otel-local-config.yaml
environment:
AWS_ACCESS_KEY_ID: ${AWS_ACCESS_KEY_ID}
AWS_SECRET_ACCESS_KEY: ${AWS_SECRET_ACCESS_KEY}
AWS_SESSION_TOKEN: ${AWS_SESSION_TOKEN}
AWS_REGION: ${AWS_REGION}
ports:
- 4317:4317
- 2000:2000
Tracetest depends on Postgres and the ADOT collector. Tracetest requires config files to be loaded via a volume. The volumes are mapped from the root directory into the root
directory and the respective config files.
The tracetest.config.yaml
file contains the basic setup of connecting Tracetest to the Postgres instance.
postgres:
host: postgres
user: postgres
password: postgres
port: 5432
dbname: postgres
params: sslmode=disable
The tracetest.provision.yaml
file defines the trace data store, set to the OTel Collector, meaning the traces will be sent to the ADOT instance where later on will be pushed to the AWX X-Ray service and the OTLP Tracetest endpoint.
---
type: DataStore
spec:
name: otlp
type: otlp
But how does Tracetest fetch traces?
The ADOT collector is configured with the awsxray
receiver and exporting the OpenTelemetry format directly intro Tracetest.
receivers:
awsxray:
transport: udp
processors:
batch:
exporters:
awsxray:
region: ${AWS_REGION}
otlp/tracetest:
endpoint: tracetest:4317
tls:
insecure: true
service:
pipelines:
traces/tracetest:
receivers: [awsxray]
processors: [batch]
exporters: [otlp/tracetest]
traces/awsxray:
receivers: [awsxray]
exporters: [awsxray]
How do traces reach AWS X-Ray?
The application code in the src/index.js
file uses the native AWS SDK X-Ray library which sends telemetry data to the ADOT Collector to be processed and then sent to the configured AWS X-Ray SaaS and Tracetest.
To start both the Node.js app and Tracetest, run this command:
docker-compose up
This will start your Tracetest instance on http://localhost:11633/
. Open the instance and start creating tests!
Make sure to use the http://app:3000/
url in your test creation, because your Node.js app and Tracetest are in the same network.
</TabItem>
</Tabs>
Please visit our examples in GitHub and join our Slack Community for more info!