diff --git a/docs/docs/examples-tutorials/recipes/running-tracetest-with-aws-x-ray-adot.mdx b/docs/docs/examples-tutorials/recipes/running-tracetest-with-aws-x-ray-adot.mdx index 12bc283373..3f34328dd5 100644 --- a/docs/docs/examples-tutorials/recipes/running-tracetest-with-aws-x-ray-adot.mdx +++ b/docs/docs/examples-tutorials/recipes/running-tracetest-with-aws-x-ray-adot.mdx @@ -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) ::: @@ -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 - - -``` - ## 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**: @@ -73,12 +62,10 @@ 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. @@ -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="" +TRACETEST_ENVIRONMENT_ID="" + AWS_ACCESS_KEY_ID="" AWS_SECRET_ACCESS_KEY="" AWS_SESSION_TOKEN="" AWS_REGION="" -TRACETEST_API_KEY="" -TRACETEST_API_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": "", - "SecretAccessKey": "", - "SessionToken": "", - "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 -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.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. -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 -tracetest run test -f ./test-api.yaml -``` - -```mdx-code-block - - +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 - - -``` +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 diff --git a/docs/docs/examples-tutorials/recipes/running-tracetest-with-aws-x-ray-pokeshop.mdx b/docs/docs/examples-tutorials/recipes/running-tracetest-with-aws-x-ray-pokeshop.mdx index 940acdf7a8..0516514ed4 100644 --- a/docs/docs/examples-tutorials/recipes/running-tracetest-with-aws-x-ray-pokeshop.mdx +++ b/docs/docs/examples-tutorials/recipes/running-tracetest-with-aws-x-ray-pokeshop.mdx @@ -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-pokeshop) ::: @@ -40,19 +36,12 @@ import CodeBlock from '@theme/CodeBlock'; This is a simple quick start guide on how to configure a fully instrumented API to be used with 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 the Pokeshop API to generate the telemetry data. -```mdx-code-block - - -``` - ## 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**: @@ -75,12 +64,10 @@ cd tracetest/examples/tracetest-amazon-x-ray-pokeshop 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 AWS X-Ray Tracing Backend. Ensure the environment you're using to run this example is configured to use the AWS X-Ray Tracing Backend by clicking on Settings, Tracing Backend, AWS X-Ray, Save. Or, use the CLI as explained below. -7. Run tests from the Tracetest Web UI by accessing the app with the URL `http://demo-api:8081/pokemon/import`. +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. @@ -101,53 +88,15 @@ This is a [fragment from the main tracing file](https://github.com/kubeshop/poke Configure the `.env` like shown below. ```bash +# Get the required information here: https://app.tracetest.io/retrieve-token + +TRACETEST_TOKEN="" +TRACETEST_ENVIRONMENT_ID="" + AWS_ACCESS_KEY_ID="" AWS_SECRET_ACCESS_KEY="" AWS_SESSION_TOKEN="" AWS_REGION="" -TRACETEST_API_KEY="" -TRACETEST_API_TOKEN="" -``` - -## Configuring AWS X-Ray - -Configure [AWS X-Ray as a Tracing Backend](/configuration/connecting-to-data-stores/awsxray) in Tracetest. - -Get temporary credentials. - -```bash -aws sts get-session-token -``` - -```json title="Output" -{ - "Credentials": { - "AccessKeyId": "", - "SecretAccessKey": "", - "SessionToken": "", - "Expiration": "2024-05-23T21:01:38+00:00" - } -} -``` - -Edit the `tracetest-tracing-backend.yaml`. - -```yaml title="tracetest-tracing-backend.yaml" ---- -type: DataStore -spec: - name: awsxray - type: awsxray - awsxray: - accessKeyId: - secretAccessKey: - sessionToken: - region: "" -``` - -```bash -tracetest config -t -tracetest apply datastore -f ./tracetest-tracing-backend.yaml ``` ## Run the Pokeshop Demo App, ADOT, and Tracetest Agent with Docker Compose @@ -156,338 +105,19 @@ The [`docker-compose.agent.yaml` file](https://github.com/kubeshop/tracetest/blo The [`docker-compose.agent.yaml` file](https://github.com/kubeshop/tracetest/blob/main/examples/tracetest-amazon-x-ray-pokeshop/docker-compose.agent.yaml) also contains the Tracetest Agent and ADOT. -To start it, run this command: - -```bash -docker compose -f ./docker-compose.agent.yaml up -d -``` +### Run Tracetest Tests -This will start the Pokeshop Demo app, ADOT, and Tracetest Agent. - -## Run Tracetest Tests - -1. Open [Tracetest](https://app.tracetest.io/). -2. [Configure AWS X-Ray as a tracing backend](/configuration/connecting-to-data-stores/awsxray) if you have not already as explained above. -3. Start creating tests! Make sure to use the `http://demo-api:8081/pokemon/import` 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 -tracetest run test -f ./tests/test.yaml -``` - -```mdx-code-block - - +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! - -And a set of AWS credentials to connect Tracetest to the cloud API. - -## Project Structure - -The project is built with Docker Compose. - -### 1. Tracetest - -The `docker-compose.yaml` file, `tracetest.provision.yaml`, and `tracetest.config.yaml` in the `root` directory are for the setting up the Pokeshop API, 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. E.g. `adot-collector:2000` in the `src/index.js` will map to the `adot-collector` service, where the port `2000` is the port where the X-Ray Daemon accepts telemetry data. - -## Pokeshop API - -The Pokeshop API is a fully instrumented REST API that makes use of different services to mimic a real life scenario. - -It is instrumented using the [OpenTelemetry standards for Node.js](https://opentelemetry.io/docs/instrumentation/js/getting-started/nodejs/), sending the data to the ADOT collector that will be pushing the telemetry information to both the AWS X-Ray service. - -This is a fragment from the main tracing file from the [Pokeshop API repo.](https://github.com/kubeshop/pokeshop) - -```typescript -import { BatchSpanProcessor } from '@opentelemetry/sdk-trace-base'; -import * as opentelemetry from '@opentelemetry/api'; -import { api, NodeSDK } from '@opentelemetry/sdk-node'; -import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-grpc'; -import { Resource } from '@opentelemetry/resources'; -import * as dotenv from 'dotenv'; -import { SemanticResourceAttributes } from '@opentelemetry/semantic-conventions'; -import { IORedisInstrumentation } from '@opentelemetry/instrumentation-ioredis'; -import { PgInstrumentation } from '@opentelemetry/instrumentation-pg'; -import { AmqplibInstrumentation } from '@opentelemetry/instrumentation-amqplib'; -import { SpanStatusCode } from '@opentelemetry/api'; -import { B3Propagator } from '@opentelemetry/propagator-b3'; - -dotenv.config(); -api.propagation.setGlobalPropagator(new B3Propagator()); - -const { COLLECTOR_ENDPOINT = '', SERVICE_NAME = 'pokeshop' } = process.env; - -let globalTracer: opentelemetry.Tracer | null = null; - -async function createTracer(): Promise { - const collectorExporter = new OTLPTraceExporter({ - url: COLLECTOR_ENDPOINT, - }); - - const spanProcessor = new BatchSpanProcessor(collectorExporter); - const sdk = new NodeSDK({ - traceExporter: collectorExporter, - // @ts-ignore - instrumentations: [new IORedisInstrumentation(), new PgInstrumentation(), new AmqplibInstrumentation()], - }); - - sdk.configureTracerProvider({}, spanProcessor); - sdk.addResource( - new Resource({ - [SemanticResourceAttributes.SERVICE_NAME]: SERVICE_NAME, - }) - ); - - await sdk.start(); - process.on('SIGTERM', () => { - sdk - .shutdown() - .then( - () => console.log('SDK shut down successfully'), - err => console.log('Error shutting down SDK', err) - ) - .finally(() => process.exit(0)); - }); - - const tracer = opentelemetry.trace.getTracer(SERVICE_NAME); - - globalTracer = tracer; - - return globalTracer; -} -``` - -The `docker-compose.yaml` file includes the definitions for all of the required services by the Pokeshop API, which includes: - -- **Postgres** - To save Pokemon information. -- **Redis** - For in memory strage. -- **RabbitMQ** - For async processing use cases. -- **API** - The Pokeshop API main container. -- **Worker** - The Pokeshop worker instance. - -```yaml -version: "3" - -services: - cache: - image: redis:6 - restart: unless-stopped - healthcheck: - test: ["CMD", "redis-cli", "ping"] - interval: 1s - timeout: 3s - retries: 60 - - queue: - image: rabbitmq:3.8-management - restart: unless-stopped - healthcheck: - test: rabbitmq-diagnostics -q check_running - interval: 1s - timeout: 5s - retries: 60 - - demo-api: - image: kubeshop/demo-pokemon-api:latest - restart: unless-stopped - pull_policy: always - environment: - REDIS_URL: cache - DATABASE_URL: postgresql://postgres:postgres@postgres:5432/postgres?schema=public - RABBITMQ_HOST: queue - POKE_API_BASE_URL: https://pokeapi.co/api/v2 - COLLECTOR_ENDPOINT: http://adot-collector:4317 - NPM_RUN_COMMAND: api - ports: - - "8081:8081" - healthcheck: - test: ["CMD", "wget", "--spider", "localhost:8081"] - interval: 1s - timeout: 3s - retries: 60 - depends_on: - postgres: - condition: service_healthy - cache: - condition: service_healthy - queue: - condition: service_healthy - - demo-worker: - image: kubeshop/demo-pokemon-api:latest - restart: unless-stopped - pull_policy: always - environment: - REDIS_URL: cache - DATABASE_URL: postgresql://postgres:postgres@postgres:5432/postgres?schema=public - RABBITMQ_HOST: queue - POKE_API_BASE_URL: https://pokeapi.co/api/v2 - COLLECTOR_ENDPOINT: http://adot-collector:4317 - NPM_RUN_COMMAND: worker - depends_on: - postgres: - condition: service_healthy - cache: - condition: service_healthy - queue: - condition: service_healthy - - demo-rpc: - image: kubeshop/demo-pokemon-api:latest - restart: unless-stopped - pull_policy: always - environment: - REDIS_URL: cache - DATABASE_URL: postgresql://postgres:postgres@postgres:5432/postgres?schema=public - RABBITMQ_HOST: queue - POKE_API_BASE_URL: https://pokeapi.co/api/v2 - COLLECTOR_ENDPOINT: http://adot-collector:4317 - NPM_RUN_COMMAND: rpc - ports: - - 8082:8082 - healthcheck: - test: ["CMD", "lsof", "-i", "8082"] - interval: 1s - timeout: 3s - retries: 60 - depends_on: - postgres: - condition: service_healthy - cache: - condition: service_healthy - queue: - condition: service_healthy -``` - -## 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 AWS X-Ray, meaning the traces will be stored in X-Ray and Tracetest will fetch them from X-Ray when running tests. - -But how does Tracetest fetch traces? - -Tracetest uses the Golang [AWS-SDK](https://aws.amazon.com/sdk-for-go/) library to pull to fetch trace data. - -```yaml ---- -type: DataStore -spec: - name: awsxray - type: awsxray - awsxray: - accessKeyId: - secretAccessKey: - sessionToken: - region: "us-west-2" - -``` - -How do traces reach AWS X-Ray? - -The Pokeshop API code uses the native Node.js OpenTelemetry modules which sends information to the ADOT Collector to be processed and then sent to the configured AWS X-Ray SaaS. - -## Run Both the Pokeshop API and Tracetest - -To start both the Pokeshop API and Tracetest, run this command: - -```bash -docker-compose up -``` - -This will start your Tracetest instance on `http://localhost:11633/`. Open it and start creating tests! -Make sure to use the `http://demo-api:8081/` url in your test creation, because your Pokeshop API and Tracetest are in the same network. - -```mdx-code-block - - -``` +This will: +1. Start the Pokeshop app, the OpenTelemetry Collector, and send the traces to AWS X-Ray. +2. Start the Tracetest Agent. +3. Configure the tracing backend and create tests in your environment. +4. Run the tests. ## Learn More diff --git a/docs/docs/examples-tutorials/recipes/running-tracetest-with-aws-x-ray.mdx b/docs/docs/examples-tutorials/recipes/running-tracetest-with-aws-x-ray.mdx index f31bba3c93..638d152722 100644 --- a/docs/docs/examples-tutorials/recipes/running-tracetest-with-aws-x-ray.mdx +++ b/docs/docs/examples-tutorials/recipes/running-tracetest-with-aws-x-ray.mdx @@ -18,10 +18,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) ::: @@ -34,19 +30,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 and a Node.js app to generate the telemetry data. -```mdx-code-block - - -``` - ## 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**: @@ -69,12 +58,10 @@ cd tracetest/examples/tracetest-amazon-x-ray 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 AWS X-Ray Tracing Backend. Ensure the environment you're using to run this example is configured to use the AWS X-Ray Tracing Backend by clicking on Settings, Tracing Backend, AWS X-Ray, 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. @@ -91,276 +78,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="" +TRACETEST_ENVIRONMENT_ID="" + AWS_ACCESS_KEY_ID="" AWS_SECRET_ACCESS_KEY="" AWS_SESSION_TOKEN="" AWS_REGION="" -TRACETEST_API_KEY="" -TRACETEST_API_TOKEN="" ``` The X-Ray tracing is contained in the `index.js` file. Traces will be sent to AWS X-Ray via the X-Ray Daemon. -## Configuring AWS X-Ray - -Configure [AWS X-Ray as a Tracing Backend](/configuration/connecting-to-data-stores/awsxray) in Tracetest. - -Get temporary credentials. - -```bash -aws sts get-session-token -``` - -```json title="Output" -{ - "Credentials": { - "AccessKeyId": "", - "SecretAccessKey": "", - "SessionToken": "", - "Expiration": "2024-05-23T21:01:38+00:00" - } -} -``` - -Edit the `tracetest-tracing-backend.yaml`. - -```yaml title="tracetest-tracing-backend.yaml" ---- -type: DataStore -spec: - name: awsxray - type: awsxray - awsxray: - accessKeyId: - secretAccessKey: - sessionToken: - region: "" -``` - -```bash -tracetest config -t -tracetest apply datastore -f ./tracetest-tracing-backend.yaml -``` - ## Run the Node.js App, X-Ray Daemon, and Tracetest Agent with Docker Compose -The [`docker-compose.agent.yaml` file](https://github.com/kubeshop/tracetest/blob/main/examples/tracetest-amazon-x-ray/docker-compose.agent.yaml) and [`Dockerfile`](https://github.com/kubeshop/tracetest/blob/main/examples/tracetest-amazon-x-ray/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/docker-compose.agent.yaml) also contains the Tracetest Agent and X-Ray Daemon. - -To start it, run this command: - -```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 AWS X-Ray as a tracing backend](/configuration/connecting-to-data-stores/awsxray) 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: - -```bash -tracetest configure -t -tracetest run test -f ./test-api.yaml -``` - -```mdx-code-block - - -``` - -## 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! - -And a set of AWS credentials to connect Tracetest to the cloud API. - -## Project Structure - -The project is built with Docker Compose. - -### 1. Node.js App +The [`docker-compose.yaml` file](https://github.com/kubeshop/tracetest/blob/main/examples/tracetest-amazon-x-ray/docker-compose.agent.yaml) and [`Dockerfile`](https://github.com/kubeshop/tracetest/blob/main/examples/tracetest-amazon-x-ray/Dockerfile) in the root directory contain the Node.js app. -The `Dockerfile` in the root directory is for the Node.js app. +The [`docker-compose.yaml` file](https://github.com/kubeshop/tracetest/blob/main/examples/tracetest-amazon-x-ray/docker-compose.agent.yaml) also contains the Tracetest Agent and X-Ray Daemon. -### 2. Tracetest +### Run Tracetest Tests -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 [X-Ray Daemon](https://docs.aws.amazon.com/xray/latest/devguide/xray-daemon.html). - -### 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, `xray-daemon:2000` in the `src/index.js` will map to the `xray-daemon` service, where the 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 initial data to the Daemon that will be pushing the telemetry data to the AWS service. - -The key following is the 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("xray-daemon: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: +To execute the tests, 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" ] +docker compose run tracetest-run ``` -## 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 X-Ray Daemon**](https://docs.aws.amazon.com/xray/latest/devguide/xray-daemon.html) - is a 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 - xray-daemon: - 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 - - xray-daemon: - image: amazon/aws-xray-daemon:latest - 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: - - 2000:2000 -``` - -Tracetest depends on Postgres and the x-ray daemon. 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 AWS X-Ray, meaning the traces will be stored in X-Ray and Tracetest will fetch them from X-Ray when running tests. - -But how does Tracetest fetch traces? - -Tracetest uses the Golang [AWS-SDK](https://aws.amazon.com/sdk-for-go/) library to pull to fetch trace data. - -```yaml ---- -type: DataStore -spec: - name: awsxray - type: awsxray - awsxray: - accessKeyId: - secretAccessKey: - sessionToken: - region: "us-west-2" -``` - -How do traces reach AWX 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 X-Ray Daemon to be processed and then sent to the configured AWS X-Ray SaaS. - -## 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 it 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 - - -``` +This will: +1. Start the Node.js app, the OpenTelemetry 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 diff --git a/examples/quick-start-grafana-cloud-tempo-nodejs/resources/datastore.yaml b/examples/quick-start-grafana-cloud-tempo-nodejs/resources/datastore.yaml new file mode 100644 index 0000000000..1c4bff5a26 --- /dev/null +++ b/examples/quick-start-grafana-cloud-tempo-nodejs/resources/datastore.yaml @@ -0,0 +1,13 @@ + +type: DataStore +spec: + id: current + name: Grafana Tempo Cloud + type: tempo + tempo: + type: http + http: + url: https://tempo-us-central1.grafana.net/tempo + headers: + Authorization: Basic Mzc0OTIzOmdsY19leUp2SWpvaU56ZzROVEV3SWl3aWJpSTZJbk4wWVdOckxUVXlPVEF6TWkxb2RDMXlaV0ZrTFcxNUxYUnZhMlZ1SWl3aWF5STZJbmszUzFOSk0wZHBUREl4TmpkcE1FWkxORFphTUdsVGFpSXNJbTBpT25zaWNpSTZJblZ6SW4xOQ== + diff --git a/examples/quick-start-sumologic-nodejs/resources/datastore.yaml b/examples/quick-start-sumologic-nodejs/resources/datastore.yaml new file mode 100644 index 0000000000..b2466fec7d --- /dev/null +++ b/examples/quick-start-sumologic-nodejs/resources/datastore.yaml @@ -0,0 +1,18 @@ + +--- +type: DataStore +spec: + id: current + 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: suIydfQjRz9OqB + accessKey: OCCNEoR6eOZJ35oxGuvW4YzjW4sDj1rMCgLp4neQ8HkSAIVqyfcP4TniDxItHV3C + diff --git a/examples/tracetest-grafana-tempo-pokeshop/.env b/examples/tracetest-grafana-tempo-pokeshop/.env new file mode 100644 index 0000000000..9d38d035bd --- /dev/null +++ b/examples/tracetest-grafana-tempo-pokeshop/.env @@ -0,0 +1,4 @@ +# Get the required information here: https://app.tracetest.io/retrieve-token + +TRACETEST_TOKEN="MCiA34CIR" +TRACETEST_ENVIRONMENT_ID="ttenv_b42fa137465c6e04"