Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Chore updating xray examples #3964

Merged
merged 6 commits into from
Aug 14, 2024
Merged

Chore updating xray examples #3964

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
b4d5dfa
chore(examples): updating xray examples
xoscar Aug 13, 2024
f4bbf09
chore(examples): updating xray examples
xoscar Aug 13, 2024
d109560
chore(examples): updating xray examples
xoscar Aug 13, 2024
65b1637
chore(examples): updating xray examples
xoscar Aug 13, 2024
b9413c8
chore(examples): updating xray examples
xoscar Aug 13, 2024
62eb9f4
updating pr comments
xoscar Aug 14, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
313 changes: 21 additions & 292 deletions docs/docs/examples-tutorials/recipes/running-tracetest-with-aws-x-ray-adot.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,10 +20,6 @@ keywords:
image: https://res.cloudinary.com/djwdcmwdz/image/upload/v1698686403/docs/Blog_Thumbnail_14_rsvkmo.jpg
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import CodeBlock from '@theme/CodeBlock';

:::note
[Check out the source code on GitHub here.](https://github.com/kubeshop/tracetest/tree/main/examples/tracetest-amazon-x-ray-adot)
:::
Expand All @@ -38,19 +34,12 @@ import CodeBlock from '@theme/CodeBlock';

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.

```mdx-code-block
<Tabs groupId="running-tracetest-without-a-trace-data-store">
<TabItem value="Tracetest" label="Cloud-based Managed Tracetest" default>
```

## Prerequisites

**Tracetest Account**:

- Sign up to [`app.tracetest.io`](https://app.tracetest.io) or follow the [get started](/getting-started/installation) docs.
- Create an [environment](/concepts/environments).
- Create an [environment token](/concepts/environment-tokens).
- Have access to the environment's [agent API key](/configuration/agent).
- Have access to the environment's [agent API key](https://app.tracetest.io/retrieve-token).

**AWS Account**:

Expand All @@ -73,20 +62,18 @@ cd tracetest/examples/tracetest-amazon-x-ray-adot
Follow these instructions to run the quick start:

1. Copy the `.env.template` file to `.env`.
2. Log into the [Tracetest app](https://app.tracetest.io/).
3. Fill out the [token](https://docs.tracetest.io/concepts/environment-tokens) and [API key](https://docs.tracetest.io/concepts/agent) details by editing your `.env` file. You can find these values in the Settings area for your environment.
4. Fill out the AWS credentials in the `.env` file. You can [create credentials by following this guide](/configuration/connecting-to-data-stores/awsxray).
5. Run `docker compose -f ./docker-compose.agent.yaml up -d`.
6. 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.
7. Run tests from the Tracetest Web UI by accessing the app with the URL `http://app:3000/http-request/`.
2. Fill out the [TRACETEST_TOKEN and ENVIRONMENT_ID](https://app.tracetest.io/retrieve-token) details by editing your `.env` file.
3. Fill out the AWS credentials in the `.env` file. You can [create credentials by following this guide](/configuration/connecting-to-data-stores/awsxray).
4. Run `docker compose run tracetest-run`.
5. Follow the links in the output to view the test results.

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 the [Tracetest Agent](/getting-started/installation#install-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)](https://aws-otel.github.io/docs/getting-started/collector), and the [Tracetest Agent](/concepts/agent) setup.
The `docker-compose.yaml` file in the root directory of the quick start runs the Node.js app, [AWS Distro for OpenTelemetry (ADOT)](https://aws-otel.github.io/docs/getting-started/collector), and the [Tracetest Agent](/concepts/agent) setup.

## Configuring the Node.js App

Expand All @@ -95,296 +82,38 @@ The Node.js app is a simple Express app, contained in [the `index.js` file](http
Configure the `.env` like shown below.

```bash
# Get the required information here: https://app.tracetest.io/retrieve-token

TRACETEST_TOKEN="<YOUR_TRACETEST_TOKEN>"
TRACETEST_ENVIRONMENT_ID="<YOUR_ENV_ID>"

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.

## Configuring AWS X-Ray

Get temporary credentials.

```bash
aws sts get-session-token
```

```json title="Output"
{
"Credentials": {
"AccessKeyId": "<yourkeyid>",
"SecretAccessKey": "<youraccesskey>",
"SessionToken": "<yoursessiontoken>",
"Expiration": "2024-05-23T21:01:38+00:00"
}
}
```

Configure [OTLP as a Tracing Backend](/configuration/connecting-to-data-stores/opentelemetry-collector) in Tracetest.

```yaml title="tracetest-tracing-backend.yaml"
---
type: DataStore
spec:
name: otlp
type: otlp
```

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

## Run the Node.js App, ADOT, and Tracetest Agent with Docker Compose

The [`docker-compose.agent.yaml` file](https://github.com/kubeshop/tracetest/blob/main/examples/tracetest-amazon-x-ray-adot/docker-compose.agent.yaml) and [`Dockerfile`](https://github.com/kubeshop/tracetest/blob/main/examples/tracetest-amazon-x-ray-adot/Dockerfile) in the root directory contain the Node.js app.
The [`docker-compose.yaml` file](https://github.com/kubeshop/tracetest/blob/main/examples/tracetest-amazon-x-ray-adot/docker-compose.yaml) and [`Dockerfile`](https://github.com/kubeshop/tracetest/blob/main/examples/tracetest-amazon-x-ray-adot/Dockerfile) in the root directory contain the Node.js app.

The [`docker-compose.agent.yaml` file](https://github.com/kubeshop/tracetest/blob/main/examples/tracetest-amazon-x-ray-adot/docker-compose.agent.yaml) also contains the Tracetest Agent and ADOT.
The [`docker-compose.yaml` file](https://github.com/kubeshop/tracetest/blob/main/examples/tracetest-amazon-x-ray-adot/docker-compose.yaml) also contains the Tracetest Agent and ADOT.

To start it, run this command:
### Run Tracetest Tests

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

This will start the Node.js app and Tracetest Agent.

## Run Tracetest Tests

1. Open [Tracetest](https://app.tracetest.io/).
2. [Configure OpenTelemetry Collector as a tracing backend](/configuration/connecting-to-data-stores/opentelemetry-collector) if you have not already as explained above.
3. Start creating tests! Make sure to use the `http://app:3000/http-request/` URL in your test creation.
4. To trigger tests in the CLI, first [install the CLI](/cli/cli-installation-reference), [configure it](/cli/configuring-your-cli), and [run a test](/cli/running-tests). From the root of the quick start directory, run:
To execute the tests, run this command:

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

```mdx-code-block
</TabItem>
<TabItem value="Tracetest Core" label="Hobby Open-Source Tracetest Core">
docker compose run tracetest-run
```

## Prerequisites

You will need [Docker](https://docs.docker.com/get-docker/) and [Docker Compose](https://docs.docker.com/compose/install/) installed on your machine to run this quick start app!

## Project Structure

The project is built with Docker Compose.

### 1. Node.js App

The `Dockerfile` in the root directory is for the Node.js app.

### 2. Tracetest

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.

### 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. 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.

## Node.js App

The Node.js app is a simple Express app, contained in the `src/index.js` file.

It is instrumented using [AWS X-Ray SDK](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-nodejs.html), 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.

```js
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.

```bash
npm start
```

As you can see the `Dockerfile` uses the command above.

```Dockerfile
FROM node:slim
WORKDIR /usr/src/app

COPY ./src/package*.json ./

RUN npm install
COPY ./src .

EXPOSE 3000
CMD [ "npm", "start" ]
```

## Tracetest

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)**](https://aws-otel.github.io/docs/getting-started/collector) - 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**](https://tracetest.io/) - Trace-based testing that generates end-to-end tests automatically from traces.

```yaml
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.

```yaml
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.

```yaml
---
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.

```yaml
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.

## Run Both the Node.js App and Tracetest

To start both the Node.js app and Tracetest, run this command:

```bash
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.

```mdx-code-block
</TabItem>
</Tabs>
```
This will:
1. Start the Node.js app, the ADOT Collector, and send the traces to X-Ray.
2. Start the Tracetest Agent.
3. Configure the tracing backend and create tests in your environment.
4. Run the tests.

## Learn More

Expand Down
Loading
Loading