| id | title | description | hide_table_of_contents | keywords | image | |||||
|---|---|---|---|---|---|---|---|---|---|---|
running-tracetest-with-lightstep |
OpenTelemetry Demo and Lightstep |
Quick start how to configure the OpenTelemetry Demo to use Tracetest for enhancing your E2E and integration tests with trace-based testing with Lightstep as a trace data store. |
false |
|
:::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.
Lightstep is a distributed tracing solution created by the founders of the OpenTelemetry (and OpenTracing) projects. It provides integrated distributed tracing, logs and metrics solution and fully supports OpenTelemetry standards.
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 Lightstep as a trace data store.
You will need Docker and Docker Compose installed on your machine to run this sample app! Additionally, you will need a Lightstep account and access token. Sign up to use Lightstep here.
The project is built with Docker Compose. It contains two distinct docker-compose.yaml files.
The docker-compose.yaml file and .env file in the root directory are for the OpenTelemetry Demo.
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 Lightstep.
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.
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 upThis 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 Lightstep and 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.
To start both the OpenTelemetry Demo and Tracetest, run this command:
docker-compose -f docker-compose.yaml -f tracetest/docker-compose.yaml up # add --build if the images are not built alreadyThe 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 lightstep meaning the traces will be received by Tracetest OTLP API and stored in Tracetest itself.
# tracetest-provision.yaml
---
type: DataStore
spec:
name: Lightstep
type: lightstep
---
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 Lightstep
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 Lightstep in another.
Make sure to add your Lightstep access token in the headers of the otlp/lightstep exporter.
receivers:
otlp:
protocols:
grpc:
http:
processors:
batch:
timeout: 100ms
exporters:
logging:
logLevel: debug
# OTLP for Tracetest
otlp/tracetest:
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 Lightstep
otlp/lightstep:
endpoint: ingest.lightstep.com:443
headers:
"lightstep-access-token": "<your-lightstep-access-token>" # Send traces to Lightstep. Read more in docs here: https://docs.lightstep.com/otel/otel-quick-start
service:
pipelines:
traces/tracetest:
receivers: [otlp]
processors: [batch]
exporters: [otlp/tracetest]
traces/lightstep:
receivers: [otlp]
processors: [batch]
exporters: [logging, otlp/lightstep]To start both the OpenTelemetry and Tracetest, run this command:
docker-compose -f docker-compose.yaml -f tracetest/docker-compose.yaml up # add --build if the images are not built alreadyThis will start your Tracetest instance on http://localhost:11633/.
Open the URL and 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
demosection in thetracetest.config.yamlto 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.
First, install the CLI. Then, configure the CLI:
tracetest configure --server-url http://localhost:11633Once configured, 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 = 0This 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 run test -f ./http-test.yamlThis 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!
To access a historical overview of all the trace spans the OpenTelemetry Demo generates, jump over to your Lightstep account.
You can also drill down into a particular trace.
With Lightstep 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 Lightstep to get a historical overview of all traces your distributed application generates.
Feel free to check out our examples in GitHub and join our Slack Community for more info!