diff --git a/docs/docs/configuration/overview.md b/docs/docs/configuration/overview.md index 3fd311cb34..bfa2828b8f 100644 --- a/docs/docs/configuration/overview.md +++ b/docs/docs/configuration/overview.md @@ -34,7 +34,7 @@ View [configuration for OpenTelemetry Collector](./connecting-to-data-stores/ope ## Trace Data Store Configuration Examples -Examples of configuring Tracetest to access different data stores can be found in the [`examples` folder of the Tracetest GitHub repo](https://github.com/kubeshop/tracetest/tree/main/examples). Check out the [**Recipes**](../examples-tutorials/recipes.md) for guided walkthroughs of sample use cases. +Examples of configuring Tracetest to access different data stores can be found in the [`examples` folder of the Tracetest GitHub repo](https://github.com/kubeshop/tracetest/tree/main/examples). Check out the [**Recipes**](../examples-tutorials/recipes.mdx) for guided walkthroughs of sample use cases. We will be adding new data stores over the next couple of months - [let us know](https://github.com/kubeshop/tracetest/issues/new/choose) any additional data stores you would like to see us support. diff --git a/docs/docs/examples-tutorials/overview.mdx b/docs/docs/examples-tutorials/overview.mdx new file mode 100644 index 0000000000..3d7068928a --- /dev/null +++ b/docs/docs/examples-tutorials/overview.mdx @@ -0,0 +1,24 @@ +--- +id: overview +title: Welcome to Tracetest Examples & Tutorials! 👋 +description: Here you can find examples, recipes, tutorials, and video content to help you get started with Tracetest. +hide_table_of_contents: false +keywords: + - tracetest + - trace-based testing + - observability + - distributed tracing + - testing +image: https://res.cloudinary.com/djwdcmwdz/image/upload/v1689693872/docs/Blog_Thumbnail_28_ugy2yy.png +breadcrumb_label: Nothing +--- + +import CodeBlock from '@theme/CodeBlock'; + +Find tutorials and guides to help you get started with Tracetest. + +```mdx-code-block +import {ExamplesTutorialsOverviewRow} from '@site/src/components/ExamplesTutorialsOverview'; + + +``` diff --git a/docs/docs/examples-tutorials/recipes.md b/docs/docs/examples-tutorials/recipes.mdx similarity index 78% rename from docs/docs/examples-tutorials/recipes.md rename to docs/docs/examples-tutorials/recipes.mdx index c743d2e5af..9eacfd1f77 100644 --- a/docs/docs/examples-tutorials/recipes.md +++ b/docs/docs/examples-tutorials/recipes.mdx @@ -1,6 +1,25 @@ -# Recipes +--- +id: recipes +title: 🍱 Recipes +description: Here you can find tutorials to help you get started with Tracetest. +hide_table_of_contents: false +keywords: + - tracetest + - trace-based testing + - observability + - distributed tracing + - testing +image: https://res.cloudinary.com/djwdcmwdz/image/upload/v1689693872/docs/Blog_Thumbnail_28_ugy2yy.png +breadcrumb_label: Nothing +--- -These recipes will show you the best practices for using Tracetest. +If you're already building something with Tracetest, explore these Recipes. They're short, self-contained, and runnable solutions to popular use cases. + +## Streams and Message Queues + +These recipes show how to trigger Tracetest test runs with message queues like Kafka. + +- [Testing Kafka in a Go API with OpenTelemetry](./recipes/testing-kafka-go-api-with-opentelemetry-tracetest.mdx) ## Trace Data Stores @@ -8,16 +27,22 @@ These recipes show integrations with trace data stores and tracing vendors/provi ### OpenTelemetry Collector -This integration point uses the OpenTelemetry Collector as a router to send trace data to both Tracetest and tracing vendors/providers. +This integration point uses the OpenTelemetry Collector as a router to send trace data to Tracetest. - [Sending traces directly to Tracetest from a Node.js app using OpenTelemetry Collector](./recipes/running-tracetest-without-a-trace-data-store.md) - [Sending traces with manual instrumentation directly to Tracetest from a Node.js app using OpenTelemetry Collector](./recipes/running-tracetest-without-a-trace-data-store-with-manual-instrumentation.md) - [Sending traces with manual instrumentation directly to Tracetest from a Python app using OpenTelemetry Collector](./recipes/running-python-app-with-opentelemetry-collector-and-tracetest.md) + +### OpenTelemetry Collector + Tracing Vendors + +This integration point uses the OpenTelemetry Collector as a router to send trace data to both Tracetest and tracing vendors/providers. + - [Sending traces to Lightstep and Tracetest from the OpenTelemetry Demo with OpenTelemetry Collector](./recipes/running-tracetest-with-lightstep.md) - [Sending traces to New Relic and Tracetest from the OpenTelemetry Demo with OpenTelemetry Collector](./recipes/running-tracetest-with-new-relic.md) - [Sending traces to Datadog and Tracetest from the OpenTelemetry Demo with OpenTelemetry Collector](./recipes/running-tracetest-with-datadog.md) - [Sending traces to Honeycomb and Tracetest from a Node.js app using the OpenTelemetry Collector](./recipes/running-tracetest-with-honeycomb.md) - [Sending traces to Dynatrace and Tracetest from the OpenTelemetry Demo with OpenTelemetry Collector](./recipes/running-tracetest-with-dynatrace.md) +- [Sending traces to SigNoz and Tracetest from the Pokeshop API with OpenTelemetry Collector](./recipes/running-tracetest-with-signoz-pokeshop.md) ### Jaeger diff --git a/docs/docs/examples-tutorials/recipes/testing-kafka-go-api-with-opentelemetry-tracetest.mdx b/docs/docs/examples-tutorials/recipes/testing-kafka-go-api-with-opentelemetry-tracetest.mdx new file mode 100644 index 0000000000..163f7cddd5 --- /dev/null +++ b/docs/docs/examples-tutorials/recipes/testing-kafka-go-api-with-opentelemetry-tracetest.mdx @@ -0,0 +1,331 @@ +--- +id: testing-kafka-go-api-with-opentelemetry-tracetest +title: Testing Kafka in a Go API with OpenTelemetry and Tracetest +description: Use Tracetest to run trace-based tests against Kafka in a Go API. +hide_table_of_contents: false +keywords: + - tracetest + - trace-based testing + - observability + - distributed tracing + - testing +image: https://res.cloudinary.com/djwdcmwdz/image/upload/v1689693872/docs/Blog_Thumbnail_28_ugy2yy.png +--- + +:::note +[Check out the source code on GitHub here.](https://github.com/kubeshop/tracetest/tree/main/examples/quick-start-go-and-kafka) +::: + +[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. + +## Sample Go APIs with OpenTelemetry Collector, Jaeger and Tracetest + +This is a simple quick start on how to configure two Go APIs to communicate via Kafka. They use OpenTelemetry instrumentation with traces, Jaeger as a trace data store, and Tracetest for enhancing your E2E and integration tests with trace-based testing. + +## 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 one `docker-compose.yaml` file that configures Tracetest, Jaeger, OpenTelemetry Collector, and both Go apps. + +### 1. Go APIs + +The `docker-compose.yaml` file references two Go apps, and one Kafka stream. + +- Producer API: Builds the `./producer-api/Dockerfile` +- Consumer Worker: Builds the `./consumer-worker/Dockerfile` + +The producer publishes a message to Kafka when receiving a POST request to the `/publish` endpoint. + +The consumer accepts a message through Kafka. + + +### 2. Tracetest + +The `collector.config.yaml`, `tracetest-provision.yaml`, and `tracetest-config.yaml` in the `tracetest` directory are for the setting up Tracetest and the OpenTelemetry 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. `jaeger:4317` in the `collector.config.yaml` will map to the `jaeger` service, where the port `4317` is the port where Jaeger accepts traces. + +## Go Producer API + +The Go API is a simple HTTP server, [contained in the `main.go` file](https://github.com/kubeshop/tracetest/blob/main/examples/quick-start-go-and-kafka/producer-api/main.go). + +The OpenTelemetry tracing is [contained in the `./telemetry/telemetry.go` file](https://github.com/kubeshop/tracetest/blob/main/examples/quick-start-go-and-kafka/producer-api/telemetry/telemetry.go). +Traces will be sent to the OpenTelemetry Collector, and forwarded to Jaeger. + +Traces will be sent to either the `grpc` endpoint. The hostname and port as seen in the env section of the `producer-api` in the `docker-compose.yaml` is: + +- `OTEL_EXPORTER_OTLP_ENDPOINT=otel-collector:4317` + +The server starts by running the `main.go` file. + +As you can see [in the `Dockerfile`](https://github.com/kubeshop/tracetest/blob/main/examples/quick-start-go-and-kafka/producer-api/Dockerfile). + +```Dockerfile +FROM golang:alpine as builder +ENV GO111MODULE=on +RUN apk update && apk add --no-cache git + +WORKDIR /app +COPY go.mod ./ +COPY go.sum ./ +RUN go mod download +COPY . . +RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o ./bin/main . + +FROM scratch +COPY --from=builder /app/bin/main . +CMD ["./main"] +``` + +And, [the `docker-compose.yaml` contains one service](https://github.com/kubeshop/tracetest/blob/3caff14247d745035f7cbbb68a7208f6da4e51fd/examples/quick-start-go-and-kafka/docker-compose.yaml#L3C3-L21C1) for the Go Producer API. + +```yaml + producer-api: + image: quick-start-producer-api + platform: linux/amd64 + build: ./producer-api + extra_hosts: + - "host.docker.internal:host-gateway" + ports: + - 8080:8080 + environment: + - OTEL_EXPORTER_OTLP_ENDPOINT=otel-collector:4317 + - OTEL_SERVICE_NAME=producer-api + - KAFKA_BROKER_URL=kafka:9092 + - KAFKA_TOPIC=messaging + depends_on: + otel-collector: + condition: service_started + kafka: + condition: service_healthy +``` + +## Go Consumer Worker + +The Go API is a simple HTTP server, [contained in the `main.go` file](https://github.com/kubeshop/tracetest/blob/main/examples/quick-start-go-and-kafka/producer-api/main.go). + +The OpenTelemetry tracing is [contained in the `./telemetry/telemetry.go` file](https://github.com/kubeshop/tracetest/blob/main/examples/quick-start-go-and-kafka/producer-api/telemetry/telemetry.go). +Traces will be sent to the OpenTelemetry Collector, and forwarded to Jaeger. + +Traces will be sent to either the `grpc` endpoint. The hostname and port as seen in the env section of the `producer-api` in the `docker-compose.yaml` is: + +- `OTEL_EXPORTER_OTLP_ENDPOINT=otel-collector:4317` + +The server starts by running the `main.go` file. + +As you can see [in the `Dockerfile`](https://github.com/kubeshop/tracetest/blob/main/examples/quick-start-go-and-kafka/producer-api/Dockerfile). + +```Dockerfile +FROM golang:alpine as builder +ENV GO111MODULE=on +RUN apk update && apk add --no-cache git + +WORKDIR /app +COPY go.mod ./ +COPY go.sum ./ +RUN go mod download +COPY . . +RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o ./bin/main . + +FROM scratch +COPY --from=builder /app/bin/main . +CMD ["./main"] +``` + +And, [the `docker-compose.yaml` contains one service](https://github.com/kubeshop/tracetest/blob/3caff14247d745035f7cbbb68a7208f6da4e51fd/examples/quick-start-go-and-kafka/docker-compose.yaml#L3C3-L21C1) for the Go Producer API. + +```yaml + producer-api: + image: quick-start-producer-api + platform: linux/amd64 + build: ./producer-api + extra_hosts: + - "host.docker.internal:host-gateway" + ports: + - 8080:8080 + environment: + - OTEL_EXPORTER_OTLP_ENDPOINT=otel-collector:4317 + - OTEL_SERVICE_NAME=producer-api + - KAFKA_BROKER_URL=kafka:9092 + - KAFKA_TOPIC=messaging + depends_on: + otel-collector: + condition: service_started + kafka: + condition: service_healthy +``` + +## Tracetest + +The `docker-compose.yaml` configures four services more including Tracetest. + +- **Postgres** - Postgres is a prerequisite for Tracetest to work. It stores trace data when running the trace-based tests. +- [**OpenTelemetry Collector**](https://opentelemetry.io/docs/collector/) - A vendor-agnostic implementation of how to receive, process and export telemetry data. +- [**Jaeger**](https://www.jaegertracing.io/) - Open source, distributed tracing platform. Monitor and troubleshoot workflows in complex distributed systems. +- [**Tracetest**](https://tracetest.io/) - Trace-based testing that generates end-to-end tests automatically from traces. + +```yaml + 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 + jaeger: + 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 + ports: + - 5432:5432 + + otel-collector: + image: otel/opentelemetry-collector-contrib:0.59.0 + command: + - "--config" + - "/otel-local-config.yaml" + volumes: + - ./tracetest/collector.config.yaml:/otel-local-config.yaml + ports: + - 4317:4317 + depends_on: + jaeger: + condition: service_started + + jaeger: + image: jaegertracing/all-in-one:latest + restart: unless-stopped + ports: + - 16686:16686 + - 16685:16685 + environment: + - COLLECTOR_OTLP_ENABLED=true + healthcheck: + test: ["CMD", "wget", "--spider", "localhost:16686"] + interval: 1s + timeout: 3s + retries: 60 +``` + +Tracetest depends on all three services, Postgres, Jaeger, 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. + +[The `tracetest-config.yaml` file](https://github.com/kubeshop/tracetest/blob/main/examples/quick-start-go-and-kafka/tracetest/tracetest-config.yaml) 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](https://github.com/kubeshop/tracetest/blob/main/examples/quick-start-go-and-kafka/tracetest/tracetest-provision.yaml) provisions the trace data store and polling to store in the Postgres database. The data store is set to OTLP, meaning the traces will be stored in Tracetest itself. + +```yaml +--- +type: PollingProfile +spec: + name: Default + strategy: periodic + default: true + periodic: + retryDelay: 5s + timeout: 10m + +--- +type: DataStore +spec: + name: Jaeger + type: jaeger + default: true + jaeger: + endpoint: jaeger:16685 + tls: + insecure: true +``` + +But how are traces sent to Tracetest? + +[The `collector.config.yaml` explains that](https://github.com/kubeshop/tracetest/blob/main/examples/quick-start-go-and-kafka/tracetest/collector.config.yaml). It receives traces via the `grpc` or `http`. Then, exports them to Jaeger's OLTP endpoint `jaeger:4317`. + +```yaml +receivers: + otlp: + protocols: + grpc: + http: + +processors: + batch: + timeout: 100ms + +exporters: + logging: + loglevel: debug + otlp/jaeger: + endpoint: jaeger:4317 + tls: + insecure: true + +service: + pipelines: + traces/1: + receivers: [otlp] + processors: [batch] + exporters: [otlp/jaeger] +``` + +## Run Both the Go Apps and Tracetest + +To start both Go apps and Tracetest we will run this command: + +```bash +docker-compose up # add --build if the images are not built already +``` + +This will start your Tracetest instance on `http://localhost:11633/`. + +Open the URL and start creating tests! Make sure to use the `http://producer-api:8080/publish` URL in your test creation, because your Go app and Tracetest are in the same network. + +Here are two sample tests you can get started with quickly. + +- [Testing the Consumer](https://github.com/kubeshop/tracetest/blob/main/examples/quick-start-go-and-kafka/test-consumer.yaml) +- [Testing the Producer](https://github.com/kubeshop/tracetest/blob/main/examples/quick-start-go-and-kafka/test-producer.yaml) + +## 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/docs/examples-tutorials/overview.md b/docs/docs/examples-tutorials/tutorials.mdx similarity index 59% rename from docs/docs/examples-tutorials/overview.md rename to docs/docs/examples-tutorials/tutorials.mdx index 98fc0e5626..c39c0674f3 100644 --- a/docs/docs/examples-tutorials/overview.md +++ b/docs/docs/examples-tutorials/tutorials.mdx @@ -1,67 +1,69 @@ -# Examples & Tutorials +--- +id: tutorials +title: 👨‍💻 Tutorials +description: Here you can find tutorials to help you get started with Tracetest. +hide_table_of_contents: false +keywords: + - tracetest + - trace-based testing + - observability + - distributed tracing + - testing +image: https://res.cloudinary.com/djwdcmwdz/image/upload/v1689693872/docs/Blog_Thumbnail_28_ugy2yy.png +breadcrumb_label: Nothing +--- -Below you can find tutorials to help you get started with Tracetest. - -## Recipes +Check out the following blog posts with Tracetest-related content. -If you're already building something with Tracetest, please explore [Recipes](./recipes.md) — short, self-contained, and runnable solutions to popular use cases. +## Integrations -## Tutorials +### Distributed Tracing Vendors -Check out the following blog posts with Tracetest-related content. +- [Tracetest + Dynatrace: Unified Observability for Testing](https://tracetest.io/blog/tracetest-dynatrace-unified-observability-for-testing) +- [Honeycomb + Tracetest: Observability-driven Development](https://tracetest.io/blog/honeycomb-tracetest-observability-driven-development) +- [Tracetest + Elastic: Trace-based testing meets APM](https://tracetest.io/blog/tracetest-integration-elastic-trace-based-testing-application-performance-monitoring) +- [Monitoring and Testing Cloud Native APIs with Grafana](https://tracetest.io/blog/monitoring-and-testing-cloud-native-apis-with-grafana) +- [Announcing the Tracetest integration with Lightstep](https://tracetest.io/blog/tracetest-integration-with-lightstep) +- [Enabling Tracetest to Work Directly with OpenSearch](https://tracetest.io/blog/tracetest-opensearch-integration) -### Integrations +### Cloud Providers -- [Honeycomb + Tracetest: Observability-driven Development](https://tracetest.io/blog/honeycomb-tracetest-observability-driven-development) - [Trace-based testing cloud-native apps with AWS X-Ray and Tracetest](https://tracetest.io/blog/trace-based-testing-cloud-native-apps-with-aws-x-ray-and-tracetest) +- [Announcing the Tracetest Integration with Azure App Insights](https://tracetest.io/blog/announcing-the-tracetest-integration-with-azure-app-insights) +- [Observability and Trace-based Testing in AWS](https://tracetest.io/blog/observability-trace-based-testing-aws-serverless-opensearch-tracetest) + +### Tools + - [Event-driven Kubernetes testing with Testkube and Tracetest](https://tracetest.io/blog/event-driven-kubernetes-testing-with-testkube-and-tracetest) - [Announcing the Tracetest integration with Keptn](https://tracetest.io/blog/announcing-the-tracetest-integration-with-keptn-the-control-plane-for-cloud-native-application-life-cycle-orchestration) - [Tracetest + k6: Deep Load Testing of your Cloud Native System](https://tracetest.io/blog/announcing-the-tracetest-integration-with-k6-deep-load-testing-of-your-cloud-native-system) -- [Tracetest + Elastic: Trace-based testing meets APM](https://tracetest.io/blog/tracetest-integration-elastic-trace-based-testing-application-performance-monitoring) -- [Announcing the Tracetest integration with Lightstep](https://tracetest.io/blog/tracetest-integration-with-lightstep) -- [Observability and Trace-based Testing in AWS](https://tracetest.io/blog/observability-trace-based-testing-aws-serverless-opensearch-tracetest) -- [Enabling Tracetest to Work Directly with OpenSearch](https://tracetest.io/blog/tracetest-opensearch-integration) - [Integrating Tracetest with GitHub Actions in a CI pipeline](https://tracetest.io/blog/integrating-tracetest-with-github-actions-in-a-ci-pipeline) -### Best Practices +## Best Practices + +### OpenTelemetry +- [Why did OpenTelemetry Ditch Black-box Tests?](https://tracetest.io/blog/why-did-opentelemetry-ditch-black-box-tests) - [Running Trace-Based Tests on the OpenTelemetry Demo App with Nomad](https://tracetest.io/blog/tracetest-in-action-running-trace-based-tests-on-the-opentelemetry-demo-app-with-nomad) + +### Testing Distributed Systems + - [Ad Hoc Testing of Distributed Systems](https://tracetest.io/blog/ad-hoc-testing-of-distributed-systems) - [Chaining API Tests to Handle Complex Distributed System Testing](https://tracetest.io/blog/chaining-api-tests-to-handle-complex-distributed-system-testing) -- [Observability-driven development with Go and Tracetest](https://tracetest.io/blog/observability-driven-development-with-go-and-tracetest) -- [The difference between test-driven & observability-driven development](https://tracetest.io/blog/the-difference-between-tdd-and-odd) - [Integration Tests: Pros and Cons of Doubles vs. Trace-Based Testing](https://tracetest.io/blog/integration-tests-pros-and-cons-of-doubles-vs-trace-based-testing) - [Detect & Fix Performance Issues Using Tracetest](https://tracetest.io/blog/detect-fix-performance-issues-using-tracetest) +- [Where Does Trace-Based Testing Fit in the Testing Pyramid?](https://thenewstack.io/where-does-trace-based-testing-fit-in-the-testing-pyramid/) -### OpenTelemetry Community - -- [Frontend Overhaul of the OpenTelemetry Demo (Go to Next.js)](https://tracetest.io/blog/frontend-overhaul-opentelemetry-demo) -- [Is it Observable? with Henrik Rexed](https://tracetest.io/blog/is-it-observable-with-henrik-rexed) -- [Tracing the History of Distributed Tracing & OpenTelemetry](https://tracetest.io/blog/tracing-the-history-of-distributed-tracing-opentelemetry) +### Observability-driven development -### Webinars - -- [Tracetest Community Call in April 2023 - Tracetest turns 1 year old!](https://www.youtube.com/watch?v=OrstjSvMFio) -- [Tracetest Community Call in March 2023](https://www.youtube.com/watch?v=U_94bEptrrE) -- [Trace-based testing in Kubernetes](https://www.youtube.com/watch?v=nAp3zYgykok) -- [Tracetest Community Call in February 2023](https://www.youtube.com/watch?v=v0lgw6t58YA) -- [Integrating k6 and Tracetest (k6 Office Hours #77)](https://www.youtube.com/watch?v=Dog70D7aVyg) -- [Keptn Community & Developer Meeting - Feb 1, 2023](https://youtu.be/-9X3XTdGK_s?t=767) -- [Tracetest Community Call in January 2023](https://www.youtube.com/watch?v=n5ESTR8vpH8) -- [Tracetest v0.8 Release - Transactions and Environments](https://www.youtube.com/watch?v=mp7f4RVi97g) -- [Tracetest v0.7 Release - Installation & Workflow Updates](https://www.youtube.com/watch?v=iqGYysqNQNk) -- [Is it Observable | Introduction to Tracetest - with Ken Hamric](https://www.youtube.com/watch?v=xj7tS2owRvk) -- [Tracetest v0.6 Release - gRPC, Postman and More](https://www.youtube.com/watch?v=xpEKHK5VXB0) -- [Introduction to Tracetest - E2E Tests Powered by OpenTelemetry](https://youtu.be/mqwJRxqBNCg) - -### Conference Talks +- [Observability-driven development with Go and Tracetest](https://tracetest.io/blog/observability-driven-development-with-go-and-tracetest) +- [The difference between test-driven & observability-driven development](https://tracetest.io/blog/the-difference-between-tdd-and-odd) -- [Observability-driven development with OpenTelemetry - FOSDEM 2023](https://2023.fosdem.sojourner.rocks/event/14490) -- [How Testability Drives Observability - Open Source Summit Dublin 2022](https://www.youtube.com/watch?v=x5sQg4MNFxI) -### Video Courses +### Contributions to the OpenTelemetry Community -- Observability-driven development 3-part video tutorial: - - [Part 1](https://www.youtube.com/watch?v=LXVBnPqxspY) - - [Part 2](https://www.youtube.com/watch?v=gLl_QmIU7UA) - - [Part 3](https://www.youtube.com/watch?v=lHMDDyAtxWE) +- [Trace-based Testing the OpenTelemetry Demo](https://opentelemetry.io/blog/2023/testing-otel-demo/) +- [Creating a Kubernetes Cluster with Runtime Observability](https://opentelemetry.io/blog/2023/k8s-runtime-observability/) +- [Frontend Overhaul of the OpenTelemetry Demo (Go to Next.js)](https://tracetest.io/blog/frontend-overhaul-opentelemetry-demo) +- [Is it Observable? with Henrik Rexed](https://tracetest.io/blog/is-it-observable-with-henrik-rexed) +- [Tracing the History of Distributed Tracing & OpenTelemetry](https://tracetest.io/blog/tracing-the-history-of-distributed-tracing-opentelemetry) diff --git a/docs/docs/examples-tutorials/videos.mdx b/docs/docs/examples-tutorials/videos.mdx new file mode 100644 index 0000000000..fd3b665aca --- /dev/null +++ b/docs/docs/examples-tutorials/videos.mdx @@ -0,0 +1,27 @@ +--- +id: videos +title: 📽️ Videos +description: Check out Tracetest video guides and conference talks! +hide_table_of_contents: false +keywords: + - tracetest + - trace-based testing + - observability + - distributed tracing + - testing +image: https://res.cloudinary.com/djwdcmwdz/image/upload/v1689693872/docs/Blog_Thumbnail_28_ugy2yy.png +breadcrumb_label: Nothing +--- + +### Conference Talks + +- [What is observability-driven development? - Conf42 Observability 2023](https://www.youtube.com/watch?v=xtkgZxNbnPI&list=PLIuxSyKxlQrBCCwdUZP57C0rqM6HmC3GD&index=17) +- [Observability-driven development with OpenTelemetry - FOSDEM 2023](https://2023.fosdem.sojourner.rocks/event/14490) +- [How Testability Drives Observability - Open Source Summit Dublin 2022](https://www.youtube.com/watch?v=x5sQg4MNFxI) + +### Video Courses + +- Observability-driven development 3-part video tutorial: + - [Part 1](https://www.youtube.com/watch?v=LXVBnPqxspY) + - [Part 2](https://www.youtube.com/watch?v=gLl_QmIU7UA) + - [Part 3](https://www.youtube.com/watch?v=lHMDDyAtxWE) diff --git a/docs/docs/examples-tutorials/webinars.mdx b/docs/docs/examples-tutorials/webinars.mdx new file mode 100644 index 0000000000..1038c362c9 --- /dev/null +++ b/docs/docs/examples-tutorials/webinars.mdx @@ -0,0 +1,43 @@ +--- +id: webinars +title: 🎙️ Webinars +description: Here you can find Tracetest on-demand live streams and webinars! +hide_table_of_contents: false +keywords: + - tracetest + - trace-based testing + - observability + - distributed tracing + - testing +image: https://res.cloudinary.com/djwdcmwdz/image/upload/v1689693872/docs/Blog_Thumbnail_28_ugy2yy.png +breadcrumb_label: Nothing +--- + +Watch on-demand webinars and community calls. + +## Live streams + +- [The Power of Traces: Why OpenTelemetry Embraced Trace-Based Testing](https://www.youtube.com/watch?v=2MSDy3XHjtE) +- [Using Traces for Testing - SigNoz Community Call with TraceTest and DevOps Educator Paulo](https://www.youtube.com/watch?v=a4OpEPoQTaE) +- [Let's react with Adriana Villela - New Tracetest Analyzer!](https://www.youtube.com/watch?v=AZiEST7EUhU&list=PL2Vye-us8_x8RYdMBZiXjTpSy3LMXmW-H&index=5) +- [Trace-based testing in Kubernetes](https://www.youtube.com/watch?v=nAp3zYgykok) +- [Integrating k6 and Tracetest (k6 Office Hours #77)](https://www.youtube.com/watch?v=Dog70D7aVyg) +- [Keptn Community & Developer Meeting - Feb 1, 2023](https://youtu.be/-9X3XTdGK_s?t=767) +- [Slight Reliability Episode 41 - Testing with Traces (with Ken Hamric)](https://www.youtube.com/watch?v=fna-5HQfdKA) +- [End-To-End Tests With OpenTelemetry and TraceTest](https://www.youtube.com/watch?v=1fBkclpSzZ8) +- [Is it Observable | Introduction to Tracetest - with Ken Hamric](https://www.youtube.com/watch?v=xj7tS2owRvk) + +## Community calls + +- [Tracetest Community Call in August 2023 - Introducing Kafka test triggers!](https://www.youtube.com/watch?v=uHmuimz39N4&list=PL2Vye-us8_x8RYdMBZiXjTpSy3LMXmW-H&index=2) +- [Tracetest Community Call in July 2023 - Testing the OTel Demo!](https://www.youtube.com/watch?v=gjRSjaW25Vo&list=PL2Vye-us8_x8RYdMBZiXjTpSy3LMXmW-H&index=3) +- [Tracetest Community Call in June 2023 - Let's automate tests!](https://www.youtube.com/watch?v=AA_0cw_jt1U&list=PL2Vye-us8_x8RYdMBZiXjTpSy3LMXmW-H&index=4) +- [Tracetest Community Call in May 2023 - Hackathon Vibes](https://www.youtube.com/watch?v=zsixXVU5cAE&list=PL2Vye-us8_x8RYdMBZiXjTpSy3LMXmW-H&index=6) +- [Tracetest Community Call in April 2023 - Tracetest turns 1 year old!](https://www.youtube.com/watch?v=OrstjSvMFio) +- [Tracetest Community Call in March 2023](https://www.youtube.com/watch?v=U_94bEptrrE) +- [Tracetest Community Call in February 2023](https://www.youtube.com/watch?v=v0lgw6t58YA) +- [Tracetest Community Call in January 2023](https://www.youtube.com/watch?v=n5ESTR8vpH8) +- [Tracetest v0.8 Release - Transactions and Environments](https://www.youtube.com/watch?v=mp7f4RVi97g) +- [Tracetest v0.7 Release - Installation & Workflow Updates](https://www.youtube.com/watch?v=iqGYysqNQNk) +- [Tracetest v0.6 Release - gRPC, Postman and More](https://www.youtube.com/watch?v=xpEKHK5VXB0) +- [Introduction to Tracetest - E2E Tests Powered by OpenTelemetry](https://youtu.be/mqwJRxqBNCg) \ No newline at end of file diff --git a/docs/docs/live-examples/opentelemetry-store/overview.md b/docs/docs/live-examples/opentelemetry-store/overview.md index d2b2f3bffe..f15c34075e 100644 --- a/docs/docs/live-examples/opentelemetry-store/overview.md +++ b/docs/docs/live-examples/opentelemetry-store/overview.md @@ -8,6 +8,15 @@ We will provide a full recipe below for running the full demo as well as running - **Running it locally in Docker**: [Instructions](https://opentelemetry.io/docs/demo/docker-deployment/) - **Running on Kubernetes**: [Instructions](https://opentelemetry.io/docs/demo/kubernetes-deployment/) +:::info +Tracetest is part of the official testing harness in the latest version of the OpenTelemetry Demo. Read more in the OpenTelemetry docs, [here](https://opentelemetry.io/docs/demo/tests/). + +Or, check out the hands-on workshop on YouTube! + + + +::: + ## Running the OpenTelemetry Astronomy Shop Demo in Docker ### Prerequisites @@ -15,22 +24,22 @@ We will provide a full recipe below for running the full demo as well as running - Docker - Docker Compose v2.0.0+ - 4 GB of RAM for the application - + ### Get and run the demo -1. Clone the Demo repository: +1. Clone the Demo repository: ```shell git clone https://github.com/open-telemetry/opentelemetry-demo.git ``` -2. Change to the demo folder: +2. Change to the demo folder: ```shell cd opentelemetry-demo/ ``` -3. Run docker compose[^1] to start the demo: +3. Run docker compose[^1] to start the demo: ```shell docker compose up --no-build @@ -89,7 +98,6 @@ make run-tracetesting SERVICES_TO_TEST="ad-service payment-service" Tracetest will be started on [http://localhost:11633](http://localhost:11633) as part of running these tests and you can view any of the tests, Test Suites, prior runs, or create and run your own tests. It is a great testbed to explore Tracetest! - ## Use Cases - [Add item into shopping cart](./use-cases/add-item-into-shopping-cart.md): Simulate a user choosing an item and adding it to the shopping cart. diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index eb3e11f667..f00042e56a 100644 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -229,6 +229,13 @@ const config = { disableSwitch: false, respectPrefersColorScheme: false, }, + // Use this to add an announcement for a webinar or event. + announcementBar: { + id: 'announcement', + content: + 'Tracetest is the official testing harness for the OpenTelemetry Demo! 🚀', + isCloseable: false, + }, navbar: { hideOnScroll: true, logo: { diff --git a/docs/sidebars.js b/docs/sidebars.js index 926c048931..c9e90413ec 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -25,11 +25,11 @@ const sidebars = { liveExamplesSidebar: [ { type: "category", - label: "Pokemon API Demo", + label: "OpenTelemetry Store Demo", items: [ { type: "doc", - id: "live-examples/pokeshop/overview", + id: "live-examples/opentelemetry-store/overview", label: "Overview", }, { @@ -38,28 +38,28 @@ const sidebars = { items: [ { type: "doc", - id: "live-examples/pokeshop/use-cases/add-pokemon", - label: "Add Pokemon", + id: "live-examples/opentelemetry-store/use-cases/add-item-into-shopping-cart", + label: "Add Item into Shopping Cart", }, { type: "doc", - id: "live-examples/pokeshop/use-cases/list-pokemon", - label: "List Pokemon", + id: "live-examples/opentelemetry-store/use-cases/check-shopping-cart-contents", + label: "Check Shopping Cart Contents", }, { type: "doc", - id: "live-examples/pokeshop/use-cases/get-pokemon-by-id", - label: "Get Pokemon by ID", + id: "live-examples/opentelemetry-store/use-cases/checkout", + label: "Checkout", }, { type: "doc", - id: "live-examples/pokeshop/use-cases/import-pokemon", - label: "Import Pokemon", + id: "live-examples/opentelemetry-store/use-cases/get-recommended-products", + label: "Get Recommended Products", }, { type: "doc", - id: "live-examples/pokeshop/use-cases/import-pokemon-from-stream", - label: "Import Pokemon from Stream", + id: "live-examples/opentelemetry-store/use-cases/user-purchasing-products", + label: "User Purchasing Products", }, ], }, @@ -67,11 +67,11 @@ const sidebars = { }, { type: "category", - label: "OpenTelemetry Store Demo", + label: "Pokemon API Demo", items: [ { type: "doc", - id: "live-examples/opentelemetry-store/overview", + id: "live-examples/pokeshop/overview", label: "Overview", }, { @@ -80,28 +80,28 @@ const sidebars = { items: [ { type: "doc", - id: "live-examples/opentelemetry-store/use-cases/add-item-into-shopping-cart", - label: "Add Item into Shopping Cart", + id: "live-examples/pokeshop/use-cases/add-pokemon", + label: "Add Pokemon", }, { type: "doc", - id: "live-examples/opentelemetry-store/use-cases/check-shopping-cart-contents", - label: "Check Shopping Cart Contents", + id: "live-examples/pokeshop/use-cases/list-pokemon", + label: "List Pokemon", }, { type: "doc", - id: "live-examples/opentelemetry-store/use-cases/checkout", - label: "Checkout", + id: "live-examples/pokeshop/use-cases/get-pokemon-by-id", + label: "Get Pokemon by ID", }, { type: "doc", - id: "live-examples/opentelemetry-store/use-cases/get-recommended-products", - label: "Get Recommended Products", + id: "live-examples/pokeshop/use-cases/import-pokemon", + label: "Import Pokemon", }, { type: "doc", - id: "live-examples/opentelemetry-store/use-cases/user-purchasing-products", - label: "User Purchasing Products", + id: "live-examples/pokeshop/use-cases/import-pokemon-from-stream", + label: "Import Pokemon from Stream", }, ], }, @@ -117,113 +117,187 @@ const sidebars = { }, { type: "doc", - id: "examples-tutorials/recipes", - label: "Recipes", - }, - { - type: "doc", - id: "examples-tutorials/recipes/running-tracetest-without-a-trace-data-store", - label: "Node.js and OpenTelemetry Collector", - }, - { - type: "doc", - id: "examples-tutorials/recipes/running-tracetest-without-a-trace-data-store-with-manual-instrumentation", - label: "Node.js with Manual Instrumentation and OpenTelemetry Collector", + id: "examples-tutorials/tutorials", + label: "Tutorials", }, { - type: "doc", - id: "examples-tutorials/recipes/running-python-app-with-opentelemetry-collector-and-tracetest", - label: "Python with Manual Instrumentation and OpenTelemetry Collector", - }, - { - type: "doc", - id: "examples-tutorials/recipes/running-tracetest-with-jaeger", - label: "Node.js and Jaeger", - }, - { - type: "doc", - id: "examples-tutorials/recipes/running-tracetest-with-opensearch", - label: "Node.js and OpenSearch", - }, - { - type: "doc", - id: "examples-tutorials/recipes/running-tracetest-with-tempo", - label: "Node.js and Tempo", - }, - { - type: "doc", - id: "examples-tutorials/recipes/running-tracetest-with-lightstep", - label: "OpenTelemetry Demo and Lightstep", - }, - { - type: "doc", - 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-aws-x-ray", - label: "X-Ray", - }, - { - type: "doc", - id: "examples-tutorials/recipes/running-tracetest-with-aws-x-ray-adot", - label: "X-Ray and AWS Distro for OpenTelemetry", - }, - { - type: "doc", - id: "examples-tutorials/recipes/running-tracetest-with-aws-x-ray-pokeshop", - label: "X-Ray, AWS Distro for OpenTelemetry and Pokeshop API", - }, - { - type: "doc", - id: "examples-tutorials/recipes/running-tracetest-with-aws-terraform", - label: "AWS Fargate and Terraform", - }, - { - type: "doc", - id: "examples-tutorials/recipes/running-tracetest-with-step-functions-terraform", - label: "AWS Step Functions, AWS X-Ray and Terraform", - }, - { - type: "doc", - id: "examples-tutorials/recipes/running-tracetest-with-datadog", - label: "OpenTelemetry Demo and Datadog", - }, - { - type: "doc", - id: "examples-tutorials/recipes/running-tracetest-with-dynatrace", - label: "OpenTelemetry Demo and Dynatrace", - }, - { - type: "doc", - id: "examples-tutorials/recipes/running-tracetest-with-honeycomb", - label: "Node.js and Honeycomb", - }, - { - type: "doc", - id: "examples-tutorials/recipes/running-tracetest-with-signoz-pokeshop", - label: "SigNoz and Pokeshop API", - }, - { - type: "doc", - id: "examples-tutorials/recipes/running-tracetest-with-azure-app-insights", - label: "Azure App Insights", + type: "category", + link: { + type: "doc", + id: "examples-tutorials/recipes" + }, + label: "Recipes", + items: [ + { + type: "category", + label: "Streams and Message Queues", + items: [ + { + type: "doc", + id: "examples-tutorials/recipes/testing-kafka-go-api-with-opentelemetry-tracetest", + label: "Testing Kafka", + }, + ], + }, + { + type: "category", + label: "OpenTelemetry Collector", + items: [ + { + type: "doc", + id: "examples-tutorials/recipes/running-tracetest-without-a-trace-data-store", + label: "Node.js and OpenTelemetry Collector", + }, + { + type: "doc", + id: "examples-tutorials/recipes/running-tracetest-without-a-trace-data-store-with-manual-instrumentation", + label: "Node.js with Manual Instrumentation and OpenTelemetry Collector", + }, + { + type: "doc", + id: "examples-tutorials/recipes/running-python-app-with-opentelemetry-collector-and-tracetest", + label: "Python with Manual Instrumentation and OpenTelemetry Collector", + }, + ], + }, + { + type: "category", + label: "OpenTelemetry Collector + Tracing Vendors", + items: [ + { + type: "doc", + id: "examples-tutorials/recipes/running-tracetest-with-lightstep", + label: "OpenTelemetry Demo and Lightstep", + }, + { + type: "doc", + 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", + label: "OpenTelemetry Demo and Datadog", + }, + { + type: "doc", + id: "examples-tutorials/recipes/running-tracetest-with-dynatrace", + label: "OpenTelemetry Demo and Dynatrace", + }, + { + type: "doc", + id: "examples-tutorials/recipes/running-tracetest-with-honeycomb", + label: "Node.js and Honeycomb", + }, + { + type: "doc", + id: "examples-tutorials/recipes/running-tracetest-with-signoz-pokeshop", + label: "SigNoz and Pokeshop API", + }, + ], + }, + { + type: "category", + label: "Jaeger", + items: [ + { + type: "doc", + id: "examples-tutorials/recipes/running-tracetest-with-jaeger", + label: "Node.js and Jaeger", + }, + { + type: "doc", + id: "examples-tutorials/recipes/running-tracetest-with-aws-terraform", + label: "AWS Fargate and Terraform", + }, + ], + }, + { + type: "category", + label: "OpenSearch", + items: [ + { + type: "doc", + id: "examples-tutorials/recipes/running-tracetest-with-opensearch", + label: "Node.js and OpenSearch", + }, + ], + }, + { + type: "category", + label: "Grafana Tempo", + items: [ + { + type: "doc", + id: "examples-tutorials/recipes/running-tracetest-with-tempo", + label: "Node.js and Tempo", + }, + ], + }, + { + type: "category", + label: "AWS X-Ray", + items: [ + { + type: "doc", + id: "examples-tutorials/recipes/running-tracetest-with-aws-x-ray", + label: "X-Ray (Node.js SDK)", + }, + { + type: "doc", + id: "examples-tutorials/recipes/running-tracetest-with-aws-x-ray-adot", + label: "X-Ray and AWS Distro for OpenTelemetry", + }, + { + type: "doc", + id: "examples-tutorials/recipes/running-tracetest-with-aws-x-ray-pokeshop", + label: "X-Ray, AWS Distro for OpenTelemetry and Pokeshop API", + }, + + { + type: "doc", + id: "examples-tutorials/recipes/running-tracetest-with-step-functions-terraform", + label: "AWS Step Functions, AWS X-Ray and Terraform", + }, + ], + }, + { + type: "category", + label: "Azure App Insights", + items: [ + { + type: "doc", + id: "examples-tutorials/recipes/running-tracetest-with-azure-app-insights", + label: "Azure App Insights", + }, + { + type: "doc", + id: "examples-tutorials/recipes/running-tracetest-with-azure-app-insights-collector", + label: "Azure App Insights and The OpenTelemetry Collector", + }, + { + type: "doc", + id: "examples-tutorials/recipes/running-tracetest-with-azure-app-insights-pokeshop", + label: "Azure App Insights, The OpenTelemetry Collector and Pokeshop API", + }, + ], + }, + ], }, { type: "doc", - id: "examples-tutorials/recipes/running-tracetest-with-azure-app-insights-collector", - label: "Azure App Insights and The OpenTelemetry Collector", + id: "examples-tutorials/webinars", + label: "Webinars", }, { type: "doc", - id: "examples-tutorials/recipes/running-tracetest-with-azure-app-insights-pokeshop", - label: "Azure App Insights, The OpenTelemetry Collector and Pokeshop API", + id: "examples-tutorials/videos", + label: "Videos", }, ], @@ -770,7 +844,7 @@ const sidebars = { { type: "link", label: "Live Examples", - href: "/live-examples/pokeshop/overview", + href: "/live-examples/opentelemetry-store/overview", }, { type: "link", diff --git a/docs/src/components/ExamplesTutorialsOverview/index.tsx b/docs/src/components/ExamplesTutorialsOverview/index.tsx new file mode 100644 index 0000000000..5236575f2f --- /dev/null +++ b/docs/src/components/ExamplesTutorialsOverview/index.tsx @@ -0,0 +1,87 @@ +/* eslint-disable global-require */ + +import React from 'react'; +import clsx from 'clsx'; +import Link from '@docusaurus/Link'; +import Translate from '@docusaurus/Translate'; +import Heading from '@theme/Heading'; + +const ExamplesTutorialsOverview = [ + { + name: '👨‍💻 Tutorials', + url: './tutorials', + description: ( + + Check out the following blog posts with Tracetest-related content. + + ), + button: 'Learn more', + }, + { + name: '🍱 Recipes', + url: './recipes', + description: ( + + Short, self-contained, and runnable solutions to popular use cases. + + ), + button: 'Start building', + }, + { + name: '🎙️ Webinars', + url: './webinars', + description: ( + + Watch on-demand live streams and community calls! + + ), + button: 'Watch now', + }, + { + name: '📽️ Videos', + url: './videos', + description: ( + + Check out Tracetest video guides and conference talks! + + ), + button: 'Watch now', + }, +]; + +interface Props { + name: string; + url: string; + button: string; + description: JSX.Element; +} + +function ExamplesTutorialsOverviewCard({name, url, description, button}: Props) { + return ( +
+
+
+ {name} +

{description}

+
+
+
+ + {button} + +
+
+
+
+ ); +} + +export function ExamplesTutorialsOverviewRow(): JSX.Element { + return ( +
+ {ExamplesTutorialsOverview.map((gettingStartedGuide) => ( + + ))} +
+ ); +} diff --git a/docs/src/css/custom.css b/docs/src/css/custom.css index 7f5e027876..e879c7963e 100644 --- a/docs/src/css/custom.css +++ b/docs/src/css/custom.css @@ -42,3 +42,20 @@ html[data-theme='dark'] footer { background-color: #242526 !important; } + + +/* Announcement Bar */ +div[class^='announcementBar'] { + background-color: var(--ifm-background-surface-color); + color: var(--ifm-font-color-base); +} + +div[class^='announcementBar'] a { + color: var(--ifm-link-color); + text-decoration: inherit; +} + +div[class^='announcementBar'] a:hover { + color: var(--ifm-link-color); + text-decoration: underline; +}