diff --git a/docs/docs/configuration/connecting-to-data-stores/sumologic.mdx b/docs/docs/configuration/connecting-to-data-stores/sumologic.mdx index e37ff15c0c..a3e2fb9f77 100644 --- a/docs/docs/configuration/connecting-to-data-stores/sumologic.mdx +++ b/docs/docs/configuration/connecting-to-data-stores/sumologic.mdx @@ -13,7 +13,31 @@ image: https://res.cloudinary.com/djwdcmwdz/image/upload/v1698686403/docs/Blog_T Tracetest fetches traces from [Sumo Logic's API](https://help.sumologic.com/docs/api/tracing/). -## Connect Tracetest to Tempo with the CLI +:::tip +Examples of configuring Tracetest can be found in the [`examples` folder of the Tracetest GitHub repo](https://github.com/kubeshop/tracetest/tree/main/examples). +::: + +## Configure Tracetest to Use Sumo Logic as a Trace Data Store + +Configure Tracetest to fetch trace data from Sumo Logic. + +Tracetest uses Sumo Logic's **API** `https://api.sumologic.com` to fetch trace data. + +You need to know which **Access ID**, **Access Key** you are using. + +Find them in the [preferences settings](https://help.sumologic.com/docs/manage/security/access-keys/) in your Sumo Logic account. + +:::tip +Need help configuring the OpenTelemetry Collector so send trace data from your application to Sumo Logic? Read more in [the reference page here](/configuration/opentelemetry-collector-configuration-file-reference). +::: + +## Connect Tracetest to Sumo Logic with the Web UI + +In the Web UI, (1) open Settings and, on the (2) Configure Data Store tab, select (3) Sumo Logic. Add the Sumo Logic **API**, your **Access ID**, and **Access Key**. + +![sumo logic](../img/sumologic-settings.png) + +## Connect Tracetest to Sumo Logic with the CLI If you prefer using the CLI, you can use this file config. @@ -25,8 +49,8 @@ spec: name: Sumo Logic type: sumologic sumologic: - url: "https://api.sumologic.com", - accessID: "your-access-id", + url: "https://api.sumologic.com" + accessID: "your-access-id" accessKey: "your-access-key" ``` diff --git a/docs/docs/configuration/img/sumologic-settings.png b/docs/docs/configuration/img/sumologic-settings.png new file mode 100644 index 0000000000..ea96b3f147 Binary files /dev/null and b/docs/docs/configuration/img/sumologic-settings.png differ diff --git a/docs/docs/examples-tutorials/recipes/running-tracetest-with-sumologic.mdx b/docs/docs/examples-tutorials/recipes/running-tracetest-with-sumologic.mdx new file mode 100644 index 0000000000..fa94d289d8 --- /dev/null +++ b/docs/docs/examples-tutorials/recipes/running-tracetest-with-sumologic.mdx @@ -0,0 +1,448 @@ +--- +id: running-tracetest-with-sumologic +title: Node.js and Sumo Logic +description: Quick start on how to configure a Node.js app with OpenTelemetry traces, Sumo Logic as a trace data store, and Tracetest for enhancing your E2E and integration tests with trace-based testing. +hide_table_of_contents: true +keywords: + - tracetest + - trace-based testing + - observability + - distributed tracing + - testing +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/quick-start-sumologic-nodejs) +::: + +[Tracetest](https://tracetest.io/) is a testing tool based on [OpenTelemetry](https://opentelemetry.io/) 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](https://www.sumologic.com/) 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. + +```mdx-code-block + + +``` + +## Prerequisites + +You can run this example with [Docker](https://docs.docker.com/get-docker/). + +## Project Structure + +The project contains [Tracetest Agent](/getting-started/installation#install-the-tracetest-agent), [Sumo Logic OpenTelemetry Collector](https://github.com/SumoLogic/sumologic-otel-collector/tree/main), and a Node.js app. + +### 1. Tracetest Agent + +Install and run Tracetest Agent locally. + +```bash title=Terminal +tracetest start +``` + +Once started, Tracetest Agent will: + +- Expose OTLP ports `4317` (gRPC) and `4318` (HTTP) for trace ingestion. +- Be able to trigger test runs in the environment where it is running. +- Be able to connect to a trace data store that is not accessible outside of your environment. + +### 2. 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 Tracetest Agent. + +Here's the content of the `tracing.otel.grpc.js` file: + +```js +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://host.docker.internal:4317` + +Enabling the tracer is done by preloading the trace file. + +```bash +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`. + +```json +"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: + +```bash +npm run with-grpc-tracer +# or +npm run with-http-tracer +``` + +## 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. + +As you can see, the `Dockerfile` uses the command above. + +```Dockerfile +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. + +```yaml +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://host.docker.internal: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](https://help.sumologic.com/docs/manage/security/installation-tokens/) to learn more about installation tokens. + +```yaml +receivers: + otlp: + protocols: + grpc: + http: + +exporters: + sumologic: + +extensions: + sumologic: + installation_token: + +service: + extensions: [sumologic] + pipelines: + traces: + receivers: [otlp] + exporters: [sumologic] +``` + +To start it, run this command: + +```bash +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. + +## Run Tracetest Tests + +Open [Tracetest](https://app.tracetest.io/) and [configure Sumo Logic as a trace data store](/configuration/connecting-to-data-stores/sumologic). + +Next, start creating tests! Make sure to use the `http://localhost:8080/` URL in your test creation. + +```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! + +## 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: + +```js +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://host.docker.internal:4317` + +```bash +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`. + +```json +"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: + +```bash +npm run with-grpc-tracer +# or +npm run with-http-tracer +``` + +As you can see, the `Dockerfile` uses the command above. + +```Dockerfile +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. + +```yaml +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://host.docker.internal: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](https://help.sumologic.com/docs/manage/security/installation-tokens/) to learn more about installation tokens. + +```yaml title="collector.config.yaml" +receivers: + otlp: + protocols: + grpc: + http: + +exporters: + sumologic: + +extensions: + sumologic: + installation_token: + +service: + extensions: [sumologic] + pipelines: + traces: + receivers: [otlp] + exporters: [sumologic] +``` + +To start it, run this command: + +```bash +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**](https://github.com/kubeshop/tracetest) - Trace-based testing that generates end-to-end tests automatically from traces. + +```yaml title="./tracetest/docker-compose.yaml" +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: + +```bash +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. + +```yaml title="tracetest-config.yaml" +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: + +- Access ID +- Access Key + +View the [Sumo Logic configuration docs](http://localhost:3000/configuration/connecting-to-data-stores/sumologic) for guidance. + +```yaml title="tracetest-provision.yaml" +--- +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" + 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: + +```bash +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. + +```mdx-code-block + + +``` + +## Learn More + +Feel free to check out our [examples in GitHub](https://github.com/kubeshop/tracetest/tree/main/examples) and join our [Discord Community](https://discord.gg/8MtcMrQNbX) for more info! diff --git a/docs/sidebars.js b/docs/sidebars.js index b77475d0d3..19a42516fa 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -172,11 +172,6 @@ const sidebars = { id: "examples-tutorials/recipes/running-tracetest-with-new-relic", label: "OpenTelemetry Demo and New Relic", }, - { - type: "doc", - id: "examples-tutorials/recipes/running-tracetest-with-elasticapm", - label: "Node.js and Elastic APM", - }, { type: "doc", id: "examples-tutorials/recipes/running-tracetest-with-datadog", @@ -201,87 +196,109 @@ const sidebars = { }, { type: "category", - label: "Jaeger", + label: "AWS X-Ray", items: [ { type: "doc", - id: "examples-tutorials/recipes/running-tracetest-with-jaeger", - label: "Node.js and Jaeger", + id: "examples-tutorials/recipes/running-tracetest-with-aws-x-ray", + label: "Node.js and AWS X-Ray (Node.js SDK)", }, { type: "doc", - id: "examples-tutorials/recipes/running-tracetest-with-aws-terraform", - label: "Serverless Node.js and Jaeger with Terraform", + id: "examples-tutorials/recipes/running-tracetest-with-aws-x-ray-adot", + label: "Node.js with AWS X-Ray (Node.js SDK) and AWS Distro for OpenTelemetry", + }, + { + type: "doc", + id: "examples-tutorials/recipes/running-tracetest-with-aws-x-ray-pokeshop", + label: "Pokeshop API with AWS X-Ray (Node.js SDK) and AWS Distro for OpenTelemetry", + }, + + { + type: "doc", + id: "examples-tutorials/recipes/running-tracetest-with-step-functions-terraform", + label: ".NET Step Functions with AWS X-Ray, AWS Distro for OpenTelemetry, and Terraform", }, ], }, { type: "category", - label: "OpenSearch", + label: "Azure App Insights", items: [ { type: "doc", - id: "examples-tutorials/recipes/running-tracetest-with-opensearch", - label: "Node.js and OpenSearch", + id: "examples-tutorials/recipes/running-tracetest-with-azure-app-insights", + label: "Node.js and Azure Application Insights (Node.js SDK)", + }, + { + type: "doc", + id: "examples-tutorials/recipes/running-tracetest-with-azure-app-insights-collector", + label: "Node.js and Azure Application Insights with OpenTelemetry Collector", + }, + { + type: "doc", + id: "examples-tutorials/recipes/running-tracetest-with-azure-app-insights-pokeshop", + label: "Pokeshop API and Azure Application Insights with OpenTelemetry Collector", }, ], }, { type: "category", - label: "Grafana Tempo", + label: "Elastic", items: [ { type: "doc", - id: "examples-tutorials/recipes/running-tracetest-with-tempo", - label: "Node.js and Grafana Tempo", + id: "examples-tutorials/recipes/running-tracetest-with-elasticapm", + label: "Node.js and Elastic APM", }, ], }, { type: "category", - label: "AWS X-Ray", + label: "Grafana Tempo", items: [ { type: "doc", - id: "examples-tutorials/recipes/running-tracetest-with-aws-x-ray", - label: "Node.js and AWS X-Ray (Node.js SDK)", - }, - { - type: "doc", - id: "examples-tutorials/recipes/running-tracetest-with-aws-x-ray-adot", - label: "Node.js with AWS X-Ray (Node.js SDK) and AWS Distro for OpenTelemetry", + id: "examples-tutorials/recipes/running-tracetest-with-tempo", + label: "Node.js and Grafana Tempo", }, + ], + }, + { + type: "category", + label: "Jaeger", + items: [ { type: "doc", - id: "examples-tutorials/recipes/running-tracetest-with-aws-x-ray-pokeshop", - label: "Pokeshop API with AWS X-Ray (Node.js SDK) and AWS Distro for OpenTelemetry", + id: "examples-tutorials/recipes/running-tracetest-with-jaeger", + label: "Node.js and Jaeger", }, - { type: "doc", - id: "examples-tutorials/recipes/running-tracetest-with-step-functions-terraform", - label: ".NET Step Functions with AWS X-Ray, AWS Distro for OpenTelemetry, and Terraform", + id: "examples-tutorials/recipes/running-tracetest-with-aws-terraform", + label: "Serverless Node.js and Jaeger with Terraform", }, ], }, { type: "category", - label: "Azure App Insights", + label: "OpenSearch", items: [ { type: "doc", - id: "examples-tutorials/recipes/running-tracetest-with-azure-app-insights", - label: "Node.js and Azure Application Insights (Node.js SDK)", - }, - { - type: "doc", - id: "examples-tutorials/recipes/running-tracetest-with-azure-app-insights-collector", - label: "Node.js and Azure Application Insights with OpenTelemetry Collector", + id: "examples-tutorials/recipes/running-tracetest-with-opensearch", + label: "Node.js and OpenSearch", }, + ], + }, + { + type: "category", + label: "Sumo Logic", + items: [ { type: "doc", - id: "examples-tutorials/recipes/running-tracetest-with-azure-app-insights-pokeshop", - label: "Pokeshop API and Azure Application Insights with OpenTelemetry Collector", + id: "examples-tutorials/recipes/running-tracetest-with-sumologic", + label: "Node.js and Sumo Logic", }, ], }, @@ -548,7 +565,7 @@ const sidebars = { { type: "doc", id: "configuration/connecting-to-data-stores/signoz", - label: "Signoz", + label: "SigNoz", }, { type: "doc", diff --git a/examples/quick-start-nodejs/readme.md b/examples/quick-start-nodejs/readme.md index 27477a3f05..19bbe43e02 100644 --- a/examples/quick-start-nodejs/readme.md +++ b/examples/quick-start-nodejs/readme.md @@ -37,7 +37,7 @@ OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4317 npm run with-grpc-trace ### 3. Run tests -Create and run a test against `http://localhost:8080`. +Create and run a test against `http://localhost:8080` on [`https://app.tracetest.io/`](https://app.tracetest.io/). View the `./test-api.yaml` for reference. ## Steps to run Tracetest Core @@ -49,7 +49,7 @@ docker compose -f ./docker-compose.yaml -f ./tracetest/docker-compose.yaml up -- ### 2. Run tests -Once started, you will need to make sure to trigger tests with correct service names since both the Node.js app and Tracetest Core are running in the same Docker Network. In this example the Node.js app would be at `http://app:8080`. +Once started, you will need to make sure to trigger tests with correct service names since both the Node.js app and Tracetest Core are running in the same Docker Network. In this example the Node.js app would be at `http://app:8080`. View the `./test-api.yaml` for reference. --- diff --git a/examples/quick-start-sumologic-nodejs/.gitignore b/examples/quick-start-sumologic-nodejs/.gitignore new file mode 100644 index 0000000000..fd4f2b066b --- /dev/null +++ b/examples/quick-start-sumologic-nodejs/.gitignore @@ -0,0 +1,2 @@ +node_modules +.DS_Store diff --git a/examples/quick-start-sumologic-nodejs/Dockerfile b/examples/quick-start-sumologic-nodejs/Dockerfile new file mode 100644 index 0000000000..4d40dc62ad --- /dev/null +++ b/examples/quick-start-sumologic-nodejs/Dockerfile @@ -0,0 +1,7 @@ +FROM node:slim +WORKDIR /usr/src/app +COPY package*.json ./ +RUN npm install +COPY . . +EXPOSE 8080 +CMD [ "npm", "run", "with-grpc-tracer" ] diff --git a/examples/quick-start-sumologic-nodejs/app.js b/examples/quick-start-sumologic-nodejs/app.js new file mode 100644 index 0000000000..279dbe1a13 --- /dev/null +++ b/examples/quick-start-sumologic-nodejs/app.js @@ -0,0 +1,8 @@ +const express = require("express") +const app = express() +app.get("/", (req, res) => { + res.send("Hello World") +}) +app.listen(8080, () => { + console.log(`Listening for requests on http://localhost:8080`) +}) diff --git a/examples/quick-start-sumologic-nodejs/collector.config.yaml b/examples/quick-start-sumologic-nodejs/collector.config.yaml new file mode 100644 index 0000000000..d045e30da3 --- /dev/null +++ b/examples/quick-start-sumologic-nodejs/collector.config.yaml @@ -0,0 +1,20 @@ +receivers: + otlp: + protocols: + grpc: + http: + +exporters: + sumologic: + +extensions: + sumologic: + installation_token: U1VNT1E1VHl0TFgwMEE2eUZ2d21iYUdqWXpjSXRKTlRodHRwczovL2NvbGxlY3RvcnMuc3Vtb2xvZ2ljLmNvbQ== + # installation_token: your-sumologic-installation-token + +service: + extensions: [sumologic] + pipelines: + traces: + receivers: [otlp] + exporters: [sumologic] diff --git a/examples/quick-start-sumologic-nodejs/docker-compose.yaml b/examples/quick-start-sumologic-nodejs/docker-compose.yaml new file mode 100644 index 0000000000..3a03c2c992 --- /dev/null +++ b/examples/quick-start-sumologic-nodejs/docker-compose.yaml @@ -0,0 +1,21 @@ +version: '3' +services: + app: + image: quick-start-nodejs + build: . + ports: + - "8080:8080" + environment: + # Local Tracetest Agent: GRPC + - OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://host.docker.internal:4317 + # Local Tracetest Agent: HTTP + # - OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://host.docker.internal:4318/v1/traces + # Tracetest Core: GRPC + # - OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://otel-collector:4317 + # Tracetest Core: HTTP + # - OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://otel-collector:4318/v1/traces + + otel-collector: + image: public.ecr.aws/sumologic/sumologic-otel-collector:0.75.0-sumo-0 + volumes: + - ./collector.config.yaml:/etc/otel/config.yaml diff --git a/examples/quick-start-sumologic-nodejs/package.json b/examples/quick-start-sumologic-nodejs/package.json new file mode 100644 index 0000000000..600ffa8b29 --- /dev/null +++ b/examples/quick-start-sumologic-nodejs/package.json @@ -0,0 +1,20 @@ +{ + "name": "quick-start-nodejs", + "version": "1.0.0", + "description": "", + "main": "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" + }, + "keywords": [], + "author": "", + "license": "ISC", + "dependencies": { + "@opentelemetry/auto-instrumentations-node": "^0.33.1", + "@opentelemetry/exporter-trace-otlp-grpc": "^0.34.0", + "@opentelemetry/exporter-trace-otlp-http": "^0.33.0", + "@opentelemetry/sdk-node": "^0.33.0", + "express": "^4.18.2" + } +} diff --git a/examples/quick-start-sumologic-nodejs/readme.md b/examples/quick-start-sumologic-nodejs/readme.md new file mode 100644 index 0000000000..87f5e14ba5 --- /dev/null +++ b/examples/quick-start-sumologic-nodejs/readme.md @@ -0,0 +1,57 @@ +# Quick Start - Node.js app with SumoLogic and Tracetest + +> [Read the detailed recipe for setting up Tempo with Tractest in our documentation.](https://docs.tracetest.io/examples-tutorials/recipes/running-tracetest-with-sumologic) + +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 the OpenTelemetry Collector to receive traces from the Node.js app and send them to Sumo Logic. + +## Steps to run Tracetest + +### 1. Start the Tracetest Agent locally + +```bash +tracetest start +``` + +Once started, Tracetest Agent will: + +- Expose OTLP ports 4317 (gRPC) and 4318 (HTTP) for trace ingestion. +- Be able to trigger test runs in the environment where it is running. +- Be able to connect to a trace data store that is not accessible outside of your environment. Eg. a Sumo Logic OpenTelemetry Collector instance running in the cluster without an ingress controller. + +### 2. Start Node.js App + +You can run the example with Docker. + +#### Docker Compose + +Set the env vars in `docker-compose.yaml` as follows: + +- `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://host.docker.internal:4317` + +```bash +docker compose up --build +``` + +### 3. Run tests + +Create and run a test against `http://localhost:8080` on [`https://app.tracetest.io/`](https://app.tracetest.io/). View the `./test-api.yaml` for reference. + +## Steps to run Tracetest Core + +### 1. Start Node.js App and Tracetest Core with Docker Compose + +Set the env vars in `docker-compose.yaml` as follows: + +- `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://otel-collector:4317` + +```bash +docker compose -f ./docker-compose.yaml -f ./tracetest/docker-compose.yaml up --build +``` + +### 2. Run tests + +Once started, you will need to make sure to trigger tests with correct service names since both the Node.js app and Tracetest Core are running in the same Docker Network. In this example the Node.js app would be at `http://app:8080`. View the `./test-api.yaml` for reference. + +--- + +Feel free to check out the [docs](https://docs.tracetest.io/), and join our [Discord Community](https://discord.gg/8MtcMrQNbX) for more info! diff --git a/examples/quick-start-sumologic-nodejs/test-api.yaml b/examples/quick-start-sumologic-nodejs/test-api.yaml new file mode 100644 index 0000000000..d3ca43aaaf --- /dev/null +++ b/examples/quick-start-sumologic-nodejs/test-api.yaml @@ -0,0 +1,18 @@ +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 diff --git a/examples/quick-start-sumologic-nodejs/tracetest/docker-compose.yaml b/examples/quick-start-sumologic-nodejs/tracetest/docker-compose.yaml new file mode 100644 index 0000000000..bec4ab18ae --- /dev/null +++ b/examples/quick-start-sumologic-nodejs/tracetest/docker-compose.yaml @@ -0,0 +1,38 @@ +version: "3" +services: + tracetest: + image: kubeshop/tracetest:${TAG:-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 + 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 diff --git a/examples/quick-start-sumologic-nodejs/tracetest/tracetest-config.yaml b/examples/quick-start-sumologic-nodejs/tracetest/tracetest-config.yaml new file mode 100644 index 0000000000..5e732f6d38 --- /dev/null +++ b/examples/quick-start-sumologic-nodejs/tracetest/tracetest-config.yaml @@ -0,0 +1,7 @@ +postgres: + host: postgres + user: postgres + password: postgres + port: 5432 + dbname: postgres + params: sslmode=disable diff --git a/examples/quick-start-sumologic-nodejs/tracetest/tracetest-provision.yaml b/examples/quick-start-sumologic-nodejs/tracetest/tracetest-provision.yaml new file mode 100644 index 0000000000..404c2fe1e1 --- /dev/null +++ b/examples/quick-start-sumologic-nodejs/tracetest/tracetest-provision.yaml @@ -0,0 +1,22 @@ +--- +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" + # accessID: "your-access-id" + # accessKey: "your-access-key" + accessID: "suIbNBmOea3Sty" + accessKey: "qo7L9JvHNuIQNRZSIDdpUdjsXDJoVFgJhWqky6MjfrZZ7CDE2NRj6PRK3j7SVsX8" + diff --git a/examples/quick-start-sumologic-nodejs/tracing.otel.grpc.js b/examples/quick-start-sumologic-nodejs/tracing.otel.grpc.js new file mode 100644 index 0000000000..caf1377d10 --- /dev/null +++ b/examples/quick-start-sumologic-nodejs/tracing.otel.grpc.js @@ -0,0 +1,11 @@ +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()], + serviceName: 'quick-start-nodejs', +}) +sdk.start() diff --git a/examples/quick-start-sumologic-nodejs/tracing.otel.http.js b/examples/quick-start-sumologic-nodejs/tracing.otel.http.js new file mode 100644 index 0000000000..473e3edc0b --- /dev/null +++ b/examples/quick-start-sumologic-nodejs/tracing.otel.http.js @@ -0,0 +1,11 @@ +const opentelemetry = require('@opentelemetry/sdk-node') +const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node') +const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-http') + +const sdk = new opentelemetry.NodeSDK({ + // OTEL_EXPORTER_OTLP_TRACES_ENDPOINT is passed into "new OTLPTraceExporter" automatically + traceExporter: new OTLPTraceExporter(), + instrumentations: [getNodeAutoInstrumentations()], + serviceName: 'quick-start-nodejs', +}) +sdk.start()