Skip to content

Latest commit

 

History

History
347 lines (262 loc) · 13.6 KB

running-tracetest-with-new-relic.md

File metadata and controls

347 lines (262 loc) · 13.6 KB
Raw

Running Tracetest With New Relic

:::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 your telemetry data generated by the OpenTelemetry tools to check and assert if your application has the desired behavior defined by your test definitions.

New Relic is an observability platform that helps you build better software. You can bring in data from any digital source so that you can fully understand your system, analyze that data efficiently, and respond to incidents before they become problems.

OpenTelemetry Demo v0.3.4-alpha with New Relic, OpenTelemetry and Tracetest

This is a simple sample app on how to configure the OpenTelemetry Demo v0.3.4-alpha to use Tracetest for enhancing your E2E and integration tests with trace-based testing, and New Relic as a trace data store.

Prerequisites

You will need Docker and Docker Compose installed on your machine to run this sample app! Additionally, you will need a New Relic account and ingest licence key. Sign up to New Relic here.

Project structure

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

1. OpenTelemetry Demo

The docker-compose.yaml file and .env file in the root directory are for the OpenTelemetry Demo.

2. Tracetest

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

The tracetest directory is self-contained and will run all the prerequisites for enabling OpenTelemetry traces and trace-based testing with Tracetest, as well as routing all traces the OpenTelemetry Demo generates to New Relic.

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. tracetest:4317 in the collector.config.yaml will map to the tracetest service, where the port 4317 is the port where Tracetest accepts traces.

OpenTelemetry Demo

The OpenDelemetry Demo is a sample microservice-based app with the purpose to demo how to correctly set up OpenTelemetry distributed tracing.

Read more about the OpenTelemetry Demo here.

The docker-compose.yaml contains 12 services.

To start the OpenTelemetry Demo by itself, run this command:

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

This will start the OpenTelemetry Demo. Open up http://localhost:8084 to make sure it's working. But, you're not sending the traces anywhere.

Let's fix this by configuring Tracetest and OpenTelemetry Collector to forward trace data to both New Relic and Tracetest.

Tracetest

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

  • Postgres - Postgres is a prerequisite for Tracetest to work. It stores trace data when running the trace-based tests.
  • OpenTelemetry Collector - A vendor-agnostic implementation of how to receive, process and export telemetry data.
  • Tracetest - Trace-based testing that generates end-to-end tests automatically from traces.
version: "3.2"
services:
  tracetest:
    restart: unless-stopped
    image: kubeshop/tracetest:${TAG:-latest}
    platform: linux/amd64
    ports:
      - 11633:11633
    extra_hosts:
      - "host.docker.internal:host-gateway"
    volumes:
      - type: bind
        source: ./tracetest/tracetest-config.yaml
        target: /app/tracetest.yaml
      - type: bind
        source: ./tracetest/tracetest-provision.yaml
        target: /app/provision.yaml
    command: --provisioning-file /app/provision.yaml
    healthcheck:
      test: ["CMD", "wget", "--spider", "localhost:11633"]
      interval: 1s
      timeout: 3s
      retries: 60
    depends_on:
      postgres:
        condition: service_healthy
      otel-collector:
        condition: service_started
    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

  otel-collector:
    image: otel/opentelemetry-collector-contrib:0.68.0
    restart: unless-stopped
    command:
      - "--config"
      - "/otel-local-config.yaml"
    volumes:
      - ./tracetest/collector.config.yaml:/otel-local-config.yaml

Tracetest depends on both Postgres and the OpenTelemetry Collector. Both Tracetest and the OpenTelemetry Collector require 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.

Why? To start both the OpenTelemetry Demo and Tracetest we will run this command:

docker-compose -f docker-compose.yaml -f tracetest/docker-compose.yaml up # add --build if the images are not built already

The tracetest-config.yaml file contains the basic setup of connecting Tracetest to the Postgres instance, and defining the exporter. The exporter is set to the OpenTelemetry Collector.

# tracetest-config.yaml
postgres:
  host: postgres
  user: postgres
  password: postgres
  port: 5432
  dbname: postgres
  params: sslmode=disable

telemetry:
  exporters:
    collector:
      serviceName: tracetest
      sampling: 100
      exporter:
        type: collector
        collector:
          endpoint: otel-collector:4317

server:
  telemetry:
    exporter: collector
    applicationExporter: collector

The tracetest-provision.yaml file contains the data store setup. The data store is set to newrelic meaning the traces will be received by Tracetest OTLP API and stored in Tracetest itself.

# tracetest-provision.yaml
---
type: DataStore
spec:
  name: New Relic
  type: newrelic
  default: true

---
type: Demo
spec:
  name: "OpenTelemetry Shop"
  enabled: true
  type: otelstore
  opentelemetryStore:
    frontendEndpoint: http://otel-frontend:8084
    productCatalogEndpoint: otel-productcatalogservice:3550
    cartEndpoint: otel-cartservice:7070
    checkoutEndpoint: otel-checkoutservice:5050

How to send traces to Tracetest and New Relic?

The collector.config.yaml explains that. It receives traces via either grpc or http. Then, exports them to Tracetest's OTLP endpoint tracetest:4317 in one pipeline, and to New Relic in another.

Make sure to add your New Relic ingest licence key in the headers of the otlp/nr exporter. You access the licence key in your New Relic account settings.

You can find which ingest endpoint to use in the New Relic docs, here.

Here's how to configure the OpenTelemetry Collector.

# collector.config.yaml

receivers:
  otlp:
    protocols:
      grpc:
      http:

processors:
  batch:
    timeout: 100ms

exporters:
  logging:
    logLevel: debug
  # OTLP for Tracetest
  otlp/tt:
    endpoint: tracetest:4317 # Send traces to Tracetest. Read more in docs here: https://docs.tracetest.io/configuration/connecting-to-data-stores/opentelemetry-collector
    tls:
      insecure: true
  # OTLP for New Relic
  otlp/nr:
    endpoint: otlp.nr-data.net:443
    headers:
      "api-key": "<new_relic_ingest_licence_key>" # Send traces to New Relic.
      # Read more in docs here: https://docs.newrelic.com/docs/more-integrations/open-source-telemetry-integrations/opentelemetry/opentelemetry-setup/#collector-export
      # And here: https://docs.newrelic.com/docs/more-integrations/open-source-telemetry-integrations/opentelemetry/collector/opentelemetry-collector-basic/

service:
  pipelines:
    traces/tt:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp/tt]
    traces/ls:
      receivers: [otlp]
      processors: [batch]
      exporters: [logging, otlp/nr]

Important! Take a closer look at the sampling configs in both the collector.config.yaml and tracetest.config.yaml. They both set sampling to 100%. This is crucial when running trace-based e2e and integration tests.

Run both the OpenTelemetry Demo app and Tracetest

To start both the OpenTelemetry and Tracetest we will run this command:

docker-compose -f docker-compose.yaml -f tracetest/docker-compose.yaml up # add --build if the images are not built already

This will start your Tracetest instance on http://localhost:11633/. Go ahead and open it up.

Start creating tests in the Web UI! Make sure to use the endpoints within your Docker network like http://otel-frontend:8084/ when creating tests.

This is because your OpenTelemetry Demo and Tracetest are in the same network.

Note: View the demo section in the tracetest.config.yaml to see which endpoints from the OpenTelemetry Demo are available for running tests.

Here's a sample of a failed test run, which happens if you add this assertion:

attr:tracetest.span.duration  < 50ms

Increasing the duration to a more reasonable 500ms will make the test pass.

Run Tracetest tests with the Tracetest CLI

First, install the CLI. Then, configure the CLI:

tracetest configure --endpoint http://localhost:11633 --analytics

Once configure, you can run a test against the Tracetest instance via the terminal.

Check out the http-test.yaml file.

# http-test.yaml

type: Test
spec:
  id: YJmFC7hVg
  name: Otel - List Products
  description: Otel - List Products
  trigger:
    type: http
    httpRequest:
      url: http://otel-frontend:8084/api/products
      method: GET
      headers:
        - key: Content-Type
          value: application/json
  specs:
    - selector:
        span[tracetest.span.type="http" name="API HTTP GET" http.target="/api/products"
        http.method="GET"]
      assertions:
        - attr:http.status_code   =   200
        - attr:tracetest.span.duration  <  50ms
    - selector: span[tracetest.span.type="rpc" name="grpc.hipstershop.ProductCatalogService/ListProducts"]
      assertions:
        - attr:rpc.grpc.status_code = 0
    - selector:
        span[tracetest.span.type="rpc" name="hipstershop.ProductCatalogService/ListProducts"
        rpc.system="grpc" rpc.method="ListProducts" rpc.service="hipstershop.ProductCatalogService"]
      assertions:
        - attr:rpc.grpc.status_code = 0

This file defines the a test the same way you would through the Web UI.

To run the test, run this command in the terminal:

tracetest test run -d ./http-test.yaml -w

This test will fail just like the sample above due to the attr:tracetest.span.duration < 50ms assertion.

✘ Otel - List Products (http://localhost:11633/test/YJmFC7hVg/run/9/test)
	✘ span[tracetest.span.type="http" name="API HTTP GET" http.target="/api/products" http.method="GET"]
		✘ #cb68ccf586956db7
			✔ attr:http.status_code   =   200 (200)
			✘ attr:tracetest.span.duration  <  50ms (72ms) (http://localhost:11633/test/YJmFC7hVg/run/9/test?selectedAssertion=0&selectedSpan=cb68ccf586956db7)
	✔ span[tracetest.span.type="rpc" name="grpc.hipstershop.ProductCatalogService/ListProducts"]
		✔ #634f965d1b34c1fd
			✔ attr:rpc.grpc.status_code = 0 (0)
	✔ span[tracetest.span.type="rpc" name="hipstershop.ProductCatalogService/ListProducts" rpc.system="grpc" rpc.method="ListProducts" rpc.service="hipstershop.ProductCatalogService"]
		✔ #33a58e95448d8b22
			✔ attr:rpc.grpc.status_code = 0 (0)

If you edit the duration as in the Web UI example above, the test will pass!

View trace spans over time in New Relic

To access a historical overview of all the trace spans the OpenTelemetry Demo generates, jump over to your New Relic account.

You can also drill down into a partucular trace as well.

With New Relic and Tracetest, you get the best of both worlds. You can run trace-based tests and automate running E2E and integration tests against real trace data. And, use New Relic to get a historical overview of all traces your distributed application generates.

Learn more

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