Skip to content

Latest commit

聽

History

History
513 lines (394 loc) 路 16.3 KB

running-tracetest-with-sumologic.mdx

File metadata and controls

513 lines (394 loc) 路 16.3 KB
Raw
id title description hide_table_of_contents keywords image
running-tracetest-with-sumologic
Node.js and Sumo Logic
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.
true
tracetest
trace-based testing
observability
distributed tracing
testing

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.

Sumo Logic is a cloud-based machine data analytics company focusing on security, operations and BI use-cases. It provides log management and analytics services that use machine-generated big data.

Node.js App with Sumo Logic, OpenTelemetry, and Tracetest

This is a simple quick start on how to configure a Node.js app to use OpenTelemetry instrumentation with traces and Tracetest for enhancing your E2E and integration tests with trace-based testing. The infrastructure will use Sumo Logic as the trace data store, and the Sumo Logic distribution of OpenTelemetry Collector to receive traces from the Node.js app and send them to Sumo Logic.

<Tabs groupId="running-tracetest-without-a-trace-data-store">
  <TabItem value="Tracetest" label="Tracetest" default>

Prerequisites

You can run this example with Docker.

Project Structure

The project contains Tracetest Agent, Sumo Logic OpenTelemetry Collector, and a Node.js app.

1. Tracetest Agent

Install and run Tracetest Agent locally.

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.

Configure Sumo Logic as a Tracing Backend:

---
type: DataStore
spec:
  name: Sumo Logic
  type: sumologic
  sumologic:
    # The URL will differ based on your location. View this
    # docs page to figure out which URL you need:
    # https://help.sumologic.com/docs/api/getting-started/#which-endpoint-should-i-should-use
    url: "https://api.sumologic.com/api/"
    # Create your ID and Key under Administration > Security > Access Keys
    # in your Sumo Logic account:
    # https://help.sumologic.com/docs/manage/security/access-keys/#create-your-access-key
    accessID: "your-access-id"
    accessKey: "your-access-key"

:::note Configure Sumo Logic API and Access

tracetest apply datastore -f ./tracetest.datastore.yaml

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:

const opentelemetry = require('@opentelemetry/sdk-node')
const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node')
const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-grpc');

const sdk = new opentelemetry.NodeSDK({
  // OTEL_EXPORTER_OTLP_TRACES_ENDPOINT is passed into "new OTLPTraceExporter" automatically
  traceExporter: new OTLPTraceExporter(),
  instrumentations: [getNodeAutoInstrumentations()],
})
sdk.start()

Choosing the tracing.otel.grpc.js file will send traces to Tracetest Agent's GRPC.

Configure it an environment variable:

  • Running in Docker: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://otel-collector:4317

Enabling the tracer is done by preloading the trace file.

node -r ./tracing.otel.grpc.js app.js

In the package.json you will see two npm scripts for running the respective tracers alongside the app.js.

"scripts": {
  "with-grpc-tracer":"node -r ./tracing.otel.grpc.js app.js",
  "with-http-tracer":"node -r ./tracing.otel.http.js app.js"
},

To start the server, run this command:

npm run with-grpc-tracer
# or
npm run with-http-tracer

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.

FROM node:slim
WORKDIR /usr/src/app
COPY package*.json ./
RUN npm install
COPY . .
EXPOSE 8080
CMD [ "npm", "run", "with-grpc-tracer" ]

And, the docker-compose.yaml contains one service for the Node.js app and one service for the Sumo Logic OpenTelemetry Collector.

version: '3'
services:
  app:
    image: quick-start-nodejs
    extra_hosts:
      - "host.docker.internal:host-gateway"
    build: .
    ports:
      - "8080:8080"
    environment:
      - OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://otel-collector:4317

  otel-collector:
    image: public.ecr.aws/sumologic/sumologic-otel-collector:0.75.0-sumo-0
    volumes:
      - ./collector.config.yaml:/etc/otel/config.yaml

Traces sent to Sumo Logic from the OpenTelemetry Collector.

The collector.config.yaml configures the OpenTelemetry Collector. It receives traces via either grpc or http. Then, exports them to Sumo Logic via the Sumo Logic extension and an installation_token.

:::note Configure Sumo Logic Installation Token View the Sumo Logic docs here to learn more about installation tokens. :::

receivers:
  otlp:
    protocols:
      grpc:
      http:

exporters:
  sumologic:

extensions:
  sumologic:
    installation_token: <your-sumologic-installation-token>

service:
  extensions: [sumologic]
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [sumologic]

To start it, run this command:

docker compose build # optional if you haven't already built the image
docker compose up

This will start the Node.js app and Sumo Logic OpenTelemetry Collector and send the traces to Sumo Logic.

Run Tracetest Tests

  1. Open Tracetest

  2. Configure Sumo Logic as a trace data store if you have not already as explained in "1. Tracetest Agent".

  3. Start creating tests! Make sure to use the http://localhost:8080/ URL in your test creation.

    Alternatively, you can import this test as a quick start!

    type: Test
spec:
  id: W656Q0c4g
  name: Test API
  description: Test the App.
  trigger:
    type: http
    httpRequest:
      url: http://localhost: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
  </TabItem>
  <TabItem value="Tracetest Core" label="Tracetest Core">

Prerequisites

You will need Docker and Docker Compose installed on your machine to run this quick start app!

Project Structure

The project is built with Docker Compose. It contains two distinct docker-compose.yaml files.

1. Node.js App

The docker-compose.yaml file and Dockerfile in the root directory are for the Node.js app.

2. Tracetest Core

The docker-compose.yaml file, tracetest-provision.yaml, and tracetest.config.yaml in the tracetest directory are for the setting up Tracetest.

The tracetest directory is self-contained and will run all the prerequisites for enabling trace-based testing with Tracetest.

Docker Compose Network

All services in the docker-compose.yaml are on the same network and will be reachable by hostname from within other services. E.g. app:8080 will map to the app service.

Node.js App

The Node.js app is a simple Express app, contained in the app.js file.

The OpenTelemetry tracing is contained in the tracing.otel.grpc.js or tracing.otel.http.js files. Traces will be sent to the OpenTelemetry Collector.

Here's the content of the tracing.otel.grpc.js file:

const opentelemetry = require('@opentelemetry/sdk-node')
const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node')
const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-grpc');

const sdk = new opentelemetry.NodeSDK({
  // OTEL_EXPORTER_OTLP_TRACES_ENDPOINT is passed into "new OTLPTraceExporter" automatically
  traceExporter: new OTLPTraceExporter(),
  instrumentations: [getNodeAutoInstrumentations()],
})
sdk.start()

Choosing the tracing.otel.grpc.js file will send traces to Tracetest Agent's GRPC.

Configure it an environment variable:

  • Running in Docker: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://otel-collector:4317
node -r ./tracing.otel.grpc.js app.js

In the package.json you will see two npm scripts for running the respective tracers alongside the app.js.

"scripts": {
  "with-grpc-tracer":"node -r ./tracing.otel.grpc.js app.js",
  "with-http-tracer":"node -r ./tracing.otel.http.js app.js"
},

To start the server, run this command:

npm run with-grpc-tracer
# or
npm run with-http-tracer

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

FROM node:slim
WORKDIR /usr/src/app
COPY package*.json ./
RUN npm install
COPY . .
EXPOSE 8080
CMD [ "npm", "run", "with-grpc-tracer" ]

And, the docker-compose.yaml contains one service for the Node.js app and one service for the Sumo Logic OpenTelemetry Collector.

version: '3'
services:
  app:
    image: quick-start-nodejs
    extra_hosts:
      - "host.docker.internal:host-gateway"
    build: .
    ports:
      - "8080:8080"
    environment:
      - OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://otel-collector:4317

  otel-collector:
    image: public.ecr.aws/sumologic/sumologic-otel-collector:0.75.0-sumo-0
    volumes:
      - ./collector.config.yaml:/etc/otel/config.yaml

Traces sent to Sumo Logic from the OpenTelemetry Collector.

The collector.config.yaml configures the OpenTelemetry Collector. It receives traces via either grpc or http. Then, exports them to Sumo Logic via the Sumo Logic extension and an installation_token.

:::note Configure Sumo Logic Installation Token View the Sumo Logic docs here to learn more about installation tokens. :::

receivers:
  otlp:
    protocols:
      grpc:
      http:

exporters:
  sumologic:

extensions:
  sumologic:
    installation_token: <your-sumologic-installation-token>

service:
  extensions: [sumologic]
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [sumologic]

To start it, run this command:

docker compose build # optional if you haven't already built the image
docker compose up

This will start the Node.js app and Sumo Logic OpenTelemetry Collector and send the traces to Sumo Logic.

Let's add trace-based testing by configuring Tracetest.

Tracetest Core

The docker-compose.yaml in the tracetest directory is configured with two services.

  • Postgres - Postgres is a prerequisite for Tracetest to work. It stores trace data when running the trace-based tests.
  • Tracetest Core - Trace-based testing that generates end-to-end tests automatically from traces.
version: "3"
services:
  tracetest:
    image: kubeshop/tracetest:latest
    platform: linux/amd64
    volumes:
      - type: bind
        source: ./tracetest/tracetest-config.yaml
        target: /app/tracetest.yaml
      - type: bind
        source: ./tracetest/tracetest-provision.yaml
        target: /app/provisioning.yaml
    ports:
      - 11633:11633
    command: --provisioning-file /app/provisioning.yaml
    depends_on:
      postgres:
        condition: service_healthy
      otel-collector:
        condition: service_started
    healthcheck:
      test: ["CMD", "wget", "--spider", "localhost:11633"]
      interval: 1s
      timeout: 3s
      retries: 60

  postgres:
    image: postgres:14
    environment:
      POSTGRES_PASSWORD: postgres
      POSTGRES_USER: postgres
    healthcheck:
      test: pg_isready -U "$$POSTGRES_USER" -d "$$POSTGRES_DB"
      interval: 1s
      timeout: 5s
      retries: 60

Tracetest Core depends on both Postgres and the Sumo Logic OpenTelemetry Collector from the root docker-compose.yaml. Tracetest Core requires config files to be loaded via a volume. The volumes are mapped from the root directory into the tracetest directory and the respective config files.

To start both the Node.js app and Tracetest Core we will run this command:

docker-compose -f docker-compose.yaml -f tracetest/docker-compose.yaml build
docker-compose -f docker-compose.yaml -f tracetest/docker-compose.yaml up

The tracetest-config.yaml file contains the basic setup of connecting Tracetest Core to the Postgres instance.

postgres:
  host: postgres
  user: postgres
  password: postgres
  port: 5432
  dbname: postgres
  params: sslmode=disable

The tracetest-provision.yaml file provisions the trace data store and polling to store in the Postgres database. The data store is set to Sumo Logic, meaning the Tracetest Core will fetch traces from Sumo Logic when tests are run.

You'll need to set Sumo Logic:

  • URL
  • Access ID
  • Access Key

:::note Configure Sumo Logic API and Access

---
type: PollingProfile
spec:
  name: Default
  strategy: periodic
  default: true
  periodic:
    retryDelay: 5s
    timeout: 10m

---
type: DataStore
spec:
  name: Sumo Logic
  type: sumologic
  sumologic:
    url: "https://api.sumologic.com/api/"
    accessID: "your-access-id"
    accessKey: "your-access-key"

Run Both the Node.js App and Tracetest

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

docker-compose -f docker-compose.yaml -f tracetest/docker-compose.yaml build
docker-compose -f docker-compose.yaml -f tracetest/docker-compose.yaml up

This will start your Tracetest Core instance on http://localhost:11633/.

Open the URL and start creating tests! Make sure to use the http://app:8080/ URL in your test creation, because your Node.js app and Tracetest Core are in the same network.

  </TabItem>
</Tabs>

Learn More

Feel free to check out our examples in GitHub and join our Slack Community for more info!