From 0f6e82751325cc3500b9372c3c72aa0c0c009f38 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Adnan=20Rahi=C4=87?= Date: Wed, 4 Oct 2023 23:57:25 +0200 Subject: [PATCH] docs(commercial): Add new docs for commercial vs core (#3203) * docs(cloud): initial setup * docs(cloud): overhauled cloud vs core onboarding * docs(commercial): updated docker and k8s install * Update docs/docs/core/deployment/docker.md Co-authored-by: Julianne Fermi * Update docs/docs/getting-started/open.mdx Co-authored-by: Julianne Fermi * Update docs/docs/core/deployment/kubernetes.mdx Co-authored-by: Julianne Fermi * Update docs/docs/getting-started/open.mdx Co-authored-by: Julianne Fermi * Update docs/docs/getting-started/open.mdx Co-authored-by: Julianne Fermi * Update docs/docs/getting-started/open.mdx Co-authored-by: Julianne Fermi * Update docs/docs/getting-started/open.mdx Co-authored-by: Julianne Fermi * Update docs/docs/getting-started/open.mdx Co-authored-by: Julianne Fermi * docs(cloud): typos and fixes --------- Co-authored-by: Julianne Fermi --- README.md | 2 +- docs/docs/configuration/server.md | 20 +- docs/docs/{ => core}/deployment/docker.md | 2 +- .../docs/{ => core}/deployment/kubernetes.mdx | 2 +- docs/docs/{ => core}/deployment/overview.md | 4 +- .../core/getting-started/installation.mdx | 300 ++++++++++++++++ .../open.md => core/getting-started/open.mdx} | 10 +- docs/docs/core/getting-started/overview.mdx | 25 ++ docs/docs/deployment/production-checklist.md | 0 .../getting-started/detailed-installation.md | 270 --------------- docs/docs/getting-started/installation.mdx | 325 ++++++------------ docs/docs/getting-started/open.mdx | 229 ++++++++++++ docs/docs/getting-started/overview.mdx | 8 +- docs/docs/index.mdx | 26 +- docs/docusaurus.config.js | 36 +- docs/sidebars.js | 73 ++-- .../CoreGettingStartedGuide/index.tsx | 87 +++++ .../components/GettingStartedGuide/index.tsx | 51 +-- docs/src/components/WelcomeGuide/index.tsx | 24 +- docs/src/css/custom.css | 28 +- examples/tracetest-agent/otel-demo/readme.md | 3 + .../pokeshop/collector.config.yaml | 27 ++ .../pokeshop/docker-compose.yaml | 110 ++++++ examples/tracetest-agent/pokeshop/readme.md | 8 + .../pokeshop/tests/pokemon-import.yaml | 23 ++ .../pokeshop/tracetest-provision.yaml | 10 + 26 files changed, 1075 insertions(+), 628 deletions(-) rename docs/docs/{ => core}/deployment/docker.md (94%) rename docs/docs/{ => core}/deployment/kubernetes.mdx (96%) rename docs/docs/{ => core}/deployment/overview.md (86%) create mode 100644 docs/docs/core/getting-started/installation.mdx rename docs/docs/{getting-started/open.md => core/getting-started/open.mdx} (89%) create mode 100644 docs/docs/core/getting-started/overview.mdx delete mode 100644 docs/docs/deployment/production-checklist.md delete mode 100644 docs/docs/getting-started/detailed-installation.md create mode 100644 docs/docs/getting-started/open.mdx create mode 100644 docs/src/components/CoreGettingStartedGuide/index.tsx create mode 100644 examples/tracetest-agent/otel-demo/readme.md create mode 100644 examples/tracetest-agent/pokeshop/collector.config.yaml create mode 100644 examples/tracetest-agent/pokeshop/docker-compose.yaml create mode 100644 examples/tracetest-agent/pokeshop/readme.md create mode 100644 examples/tracetest-agent/pokeshop/tests/pokemon-import.yaml create mode 100644 examples/tracetest-agent/pokeshop/tracetest-provision.yaml diff --git a/README.md b/README.md index f1cf54668a..1ab3e8a7c0 100644 --- a/README.md +++ b/README.md @@ -264,7 +264,7 @@ tracetest run test --file /path/to/pokeshop_import.yaml Check out the [CI/CD docs](https://docs.tracetest.io/ci-cd-automation/overview) to learn more about test automation. -# Tests +# ๐Ÿงช Tests We strive to produce quality code and improve Tracetest rapidly and safely. Therefore, we have a full suite of both front-end and back-end tests. Cypress tests are running against the front-end code and (surprise, surprise) Tracetest against the back-end code. You can see the [test runs here](https://github.com/kubeshop/tracetest/actions/workflows/pull-request.yaml), and a blog post describing our [testing pipelines here](https://tracetest.io/blog/50-faster-ci-pipelines-with-github-actions). diff --git a/docs/docs/configuration/server.md b/docs/docs/configuration/server.md index 9ba6f4ccb7..3672757347 100644 --- a/docs/docs/configuration/server.md +++ b/docs/docs/configuration/server.md @@ -15,14 +15,28 @@ postgres: dbname: postgres params: sslmode=disable -server: +telemetry: + exporters: + collector: + serviceName: tracetest + sampling: 100 # 100% + exporter: + type: collector + collector: + endpoint: otel-collector:4317 + +server: httpPort: 11633 pathPrefix: / + telemetry: + exporter: collector + applicationExporter: collector ``` Alternatively, we support setting a series of environment variables which can contain the connection information for the Postgres instance. If these environment variables are set, they will be used by the Tracetest server to connect to the database. The list of environment variables and example values is: + - `TRACETEST_POSTGRES_HOST: "postgres"` - `TRACETEST_POSTGRES_PORT: "5432"` - `TRACETEST_POSTGRES_DBNAME: "postgres"` @@ -35,6 +49,4 @@ You can also change the defaults for the Tracetest server, altering the port and - `TRACETEST_SERVER_HTTPPORT=11633` - `TRACETEST_SERVER_PATHPREFIX="/"` - -You can also intitalize the server with a number of resources the first time it is launched by using [provisioning](./provisioning). - +You can also initialize the server with a number of resources the first time it is launched by using [provisioning](./provisioning). diff --git a/docs/docs/deployment/docker.md b/docs/docs/core/deployment/docker.md similarity index 94% rename from docs/docs/deployment/docker.md rename to docs/docs/core/deployment/docker.md index 6773f5533c..87f38029db 100644 --- a/docs/docs/deployment/docker.md +++ b/docs/docs/core/deployment/docker.md @@ -56,4 +56,4 @@ Starting tracetest ... Then launch a browser to [http://localhost:11633/](http://localhost:11633/). -For more configuration options, read more in the [configuration docs](../configuration/overview.md). +For more configuration options, visit the [configuration docs](/configuration/overview.md). diff --git a/docs/docs/deployment/kubernetes.mdx b/docs/docs/core/deployment/kubernetes.mdx similarity index 96% rename from docs/docs/deployment/kubernetes.mdx rename to docs/docs/core/deployment/kubernetes.mdx index 3a3370995c..943bd94c01 100644 --- a/docs/docs/deployment/kubernetes.mdx +++ b/docs/docs/core/deployment/kubernetes.mdx @@ -89,4 +89,4 @@ kubectl apply -f ./tracetest-kubernetes-manifests.yaml -For more configuration options, read more in the [configuration docs](../configuration/overview.md). +For more configuration options, visit the [configuration docs](/configuration/overview.md). diff --git a/docs/docs/deployment/overview.md b/docs/docs/core/deployment/overview.md similarity index 86% rename from docs/docs/deployment/overview.md rename to docs/docs/core/deployment/overview.md index e38fef4199..30899d701f 100644 --- a/docs/docs/deployment/overview.md +++ b/docs/docs/core/deployment/overview.md @@ -5,7 +5,7 @@ This section contains a general overview of deploying Tracetest in production. Y - [Docker](./docker) - [Kubernetes](./kubernetes) -As shown in the diagram below, a typical production Tracetest deployment consists of Postgres, an OpenTelemetry Colletor and a [trace data store](../configuration/overview). But, if you do not want to use a trace data store, you can rely entirely on OpenTelemetry Collector. +As shown in the diagram below, a typical production Tracetest deployment consists of Postgres, an OpenTelemetry Colletor and a [trace data store](/configuration/overview.md). But, if you do not want to use a trace data store, you can rely entirely on OpenTelemetry Collector. @@ -46,6 +46,6 @@ postgres: params: sslmode=disable ``` -Read more in the [configuration docs](../configuration/overview.md). +Read more in the [configuration docs](/configuration/overview.md). Or, continue reading to see how to run Tracetest in production with [Docker](./docker) or [Kubernetes](./kubernetes). diff --git a/docs/docs/core/getting-started/installation.mdx b/docs/docs/core/getting-started/installation.mdx new file mode 100644 index 0000000000..8203bc5d55 --- /dev/null +++ b/docs/docs/core/getting-started/installation.mdx @@ -0,0 +1,300 @@ +--- +id: installation +title: Installing Tracetest Core +description: Tracetest allows you to quickly build integration and end-to-end tests, powered by your OpenTelemetry traces. +keywords: + - tracetest + - trace-based testing + - observability + - distributed tracing + - testing +image: https://res.cloudinary.com/djwdcmwdz/image/upload/v1689693872/docs/Blog_Thumbnail_28_ugy2yy.png +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; +import GtagInstallCliTabs from '@site/src/components/GtagInstallCliTabs'; + +This page showcases getting started with Tracetest Core by using the Tracetest CLI, Docker, or Kubernetes. + +This simple installation includes a demo app called [Pokeshop](/live-examples/pokeshop/overview.md) that will be installed alongside Tracetest Core. It shows how to configure OpenTelemetry and Tracetest Core and the architecture of the Pokeshop sample app. + +## Install the Tracetest CLI + + + +:::tip Want more info? +Read the CLI installation reference [here](/cli/cli-installation-reference.md). +::: + +## Install the Tracetest Server + +Tracetest Core runs as a standalone container. It runs a Server and exposes a Web UI on port `11633`. + +You have three options to install Tracetest Server: + +- Using the Tracetest CLI to guide your installation in Docker and Kubernetes. +- Using the official [Helm chart](https://github.com/kubeshop/helm-charts/tree/main/charts/tracetest). +- Using the [Docker Compose Quick Start with the Pokeshop Sample App](https://github.com/kubeshop/tracetest/tree/main/examples/quick-start-pokeshop). + + + + +```bash title="Terminal" +tracetest server install +``` + + + + + {`How do you want to run Tracetest? [type to search]: +> Using Docker Compose + Using Kubernetes`} + + +Choose to install Tracetest with the OpenTelemetry Collector and the [Pokeshop](/live-examples/pokeshop/overview.md) sample app. + +```text title="Expected output:" +Do you have OpenTelemetry based tracing already set up, or would you like us to install a demo tracing environment and app? [type to search]: + I have a tracing environment already. - Just install Tracetest. +> Just learning tracing! Install Tracetest, OpenTelemetry Collector and the sample app. +``` + +Choosing any option, this installer will create a `tracetest` directory in the current directory and add a `docker-compose.yaml` file to it. + +- If you choose the first option, the `docker-compose.yaml` will have only Tracetest Core and its dependencies. +- **By choosing the second option, a sample app called [Pokeshop](/live-examples/pokeshop/overview.md) will be installed with Tracetest Core, allowing you to create sample tests right away!** + +
+ + Click to view Pokeshop Sample App Architecture + + +Here's the Architecture of the Pokeshop Sample App: + +- an **API** that serves client requests, +- a **Worker** who deals with background processes. + +The communication between the API and Worker is made using a `RabbitMQ` queue, and both services emit telemetry data to OpenTelemetry Collector and communicate with a Postgres database. + +Tracetest triggers tests against the Node.js API. + +```mermaid +flowchart TD + A[(Redis)] + B[(Postgres)] + C(Node.js API) + D(RabbitMQ) + E(Worker) + F(OpenTelemetry Collector) + G(Tracetest) + + G --> C + F --> G + C --> A + C --> B + C --> D + D --> E + E --> B + C --> F + E --> F + + +``` +
+ +**Start Docker Compose from the directory where you ran `tracetest server install`.** + + +{`docker compose -f tracetest/docker-compose.yaml up -d`} + + +This will start the Tracetest Server and expose the Web UI on [`http://localhost:11633`](http://localhost:11633). + + + + + {`How do you want to run TraceTest? [type to search]: + Using Docker Compose +> Using Kubernetes`} + + +Choose to install Tracetest Core with the OpenTelemetry Collector and the [Pokeshop](/live-examples/pokeshop/overview.md) sample app. + +```text title="Expected output:" +Do you have OpenTelemetry based tracing already set up, or would you like us to install a demo tracing environment and app? [type to search]: + I have a tracing environment already - Just install Tracetest. +> Just learning tracing! Install Tracetest, OpenTelemetry Collector and the sample app. +``` + +Choosing any option, this installer will create a `tracetest` namespace in the Kubernetes context you choose and create deployments for Tracetest Core and its dependencies. + +- If you choose the first option, the `tracetest` namespace will only contain Tracetest Core and its dependencies. +- **By choosing the second option, a sample app called [Pokeshop](/live-examples/pokeshop/overview.md) will be installed in a `demo` namespace alongside Tracetest Core, allowing you to create sample tests right away!** + +
+ + Click to view Pokeshop Sample App Architecture + + +Here's the Architecture of the Pokeshop Sample App: + +- an **API** that serves client requests, +- a **Worker** who deals with background processes. + +The communication between the API and Worker is made using a `RabbitMQ` queue, and both services emit telemetry data to OpenTelemetry Collector and communicate with a Postgres database. + +Tracetest triggers tests against the Node.js API. + +```mermaid +flowchart TD + A[(Redis)] + B[(Postgres)] + C(Node.js API) + D(RabbitMQ) + E(Worker) + F(OpenTelemetry Collector) + G(Tracetest) + + G --> C + F --> G + C --> A + C --> B + C --> D + D --> E + E --> B + C --> F + E --> F + + +``` +
+ +**Access the Tracetest Server by port forwarding to the Tracetest `service`.** + +```bash title=Terminal +export POD_NAME=$(kubectl get pods --namespace demo -l "app.kubernetes.io/name=pokemon-api,app.kubernetes.io/instance=demo" -o jsonpath="{.items[0].metadata.name}") +export CONTAINER_PORT=$(kubectl get pod --namespace demo $POD_NAME -o jsonpath="{.spec.containers[0].ports[0].containerPort}") +kubectl --namespace demo port-forward $POD_NAME 8080:$CONTAINER_PORT +echo "Open http://127.0.0.1:8080 to view the Pokeshop demo app" + +kubectl --kubeconfig /.kube/config --context --namespace tracetest port-forward svc/tracetest 11633 +echo "Open http://127.0.0.1:11633 to view the Tracetest Web UI" +``` + +Access the Tracetest Web UI on [`http://localhost:11633`](http://localhost:11633). + + + + + + + +First, be sure that you have [Helm](https://helm.sh/) installed in your machine. + +The Tracetest Helm charts are located [here](https://github.com/kubeshop/helm-charts/tree/main/charts/tracetest). + +You can install them locally on your machine with the command: + +```bash title=Terminal +helm repo add kubeshop https://kubeshop.github.io/helm-charts +helm repo update +``` + +After that, you can install Tracetest with `helm install`: + +```bash title=Terminal +helm install tracetest kubeshop/tracetest --namespace=tracetest --create-namespace +``` + +Or, generate a manifest file and apply it manually in your Kubernetes cluster: + +```bash title=Terminal +helm template tracetest kubeshop/tracetest > tracetest-kubernetes-manifests.yaml +kubectl apply -f ./tracetest-kubernetes-manifests.yaml +``` + +**Access the Tracetest Server by port forwarding to the Tracetest `service`.** + +```bash title=Terminal +kubectl --kubeconfig /.kube/config --context --namespace tracetest port-forward svc/tracetest 11633 +``` + +Access the Tracetest Web UI on [`http://localhost:11633`](http://localhost:11633). + + + + +First, be sure that you have [Docker](https://docker.com/) installed in your machine. + +The Quick Start with the Pokeshop Sample App is located [here](https://github.com/kubeshop/tracetest/tree/main/examples/quick-start-pokeshop). + +**The [`docker-compose.yaml`](https://github.com/kubeshop/tracetest/blob/main/examples/quick-start-pokeshop/docker-compose.yml) contains Tracetest Core, the OpenTelemetry Collector, and a sample app called [Pokeshop](/live-examples/pokeshop/overview.md). This allows you to create sample tests right away!** + +
+ + Click to view Pokeshop Sample App Architecture + + +Here's the Architecture of the Pokeshop Sample App: + +- an **API** that serves client requests, +- a **Worker** who deals with background processes. + +The communication between the API and Worker is made using a `RabbitMQ` queue, and both services emit telemetry data to OpenTelemetry Collector and communicate with a Postgres database. + +Tracetest triggers tests against the Node.js API. + +```mermaid +flowchart TD + A[(Redis)] + B[(Postgres)] + C(Node.js API) + D(RabbitMQ) + E(Worker) + F(OpenTelemetry Collector) + G(Tracetest) + + G --> C + F --> G + C --> A + C --> B + C --> D + D --> E + E --> B + C --> F + E --> F + + +``` +
+ +**Start Docker Compose.** + + +{`docker compose -f docker-compose.yaml up -d`} + + +This will start the Tracetest Server and expose the Web UI on [`http://localhost:11633`](http://localhost:11633). + + + + +:::tip Don't have OpenTelemetry installed? +Tracetest requires that you have [OpenTelemetry instrumentation](https://opentelemetry.io/docs/instrumentation/) added in your code, and configured [sending traces to a trace data store](/configuration/connecting-to-data-stores/jaeger.md), or [Tracetest directly](/configuration/connecting-to-data-stores/opentelemetry-collector.md). + +[Follow these instructions to install OpenTelemetry in 5 minutes without any code changes!](/getting-started/no-otel.mdx) +::: diff --git a/docs/docs/getting-started/open.md b/docs/docs/core/getting-started/open.mdx similarity index 89% rename from docs/docs/getting-started/open.md rename to docs/docs/core/getting-started/open.mdx index 222123bec1..ddfec33c63 100644 --- a/docs/docs/getting-started/open.md +++ b/docs/docs/core/getting-started/open.mdx @@ -1,6 +1,6 @@ --- id: open -title: Opening Tracetest +title: Opening Tracetest Core description: Tracetest allows you to quickly build integration and end-to-end tests, powered by your OpenTelemetry traces. Learn how to get started with creating tests once you open Tracetest. keywords: - tracetest @@ -17,7 +17,7 @@ Once you've installed Tracetest, as explained in the [installation guide](./inst ![Landing page Tracetest](https://res.cloudinary.com/djwdcmwdz/image/upload/v1688474565/docs/screely-1688474539641_kbhvvc.png) -By following the [installation guide](./installation.mdx) your Tracetest instance will have a `demo` Pokeshop app installed that generates distributed traces when triggered. +By following the [installation guide](./installation.mdx) your Tracetest Core instance will have a `demo` Pokeshop app installed that generates distributed traces when triggered. ## Creating Trace-based Tests @@ -31,7 +31,7 @@ You can create tests in two ways: This guide will show how to create end-to-end and integration tests in less than 5 minutes via the Web UI. :::note -To view the in-depth guide on creating tests visually, [check out this docs page](../web-ui/creating-tests.md). +To view the in-depth guide on creating tests visually, [check out this docs page](../../web-ui/creating-tests.md). ::: ### Create @@ -49,7 +49,7 @@ This will populate a sample API test against a POST endpoint in the Pokeshop app ![API test against POST endpoint](https://res.cloudinary.com/djwdcmwdz/image/upload/v1688475680/docs/screely-1688475676524_vvtxsu.png) :::info -Running a test against `localhost` will resolve as `127.0.0.1` inside the Tracetest container. To run tests against apps running on your local machine, add them to the same network and use service name mapping instead. Example: Instead of running an app on `localhost:8080`, add it to your Docker Compose file, connect it to the same network as your Tracetest service, and use `service-name:8080` in the URL field when creating an app. +Running a test against `localhost` will resolve as `127.0.0.1` inside the Tracetest Core container. To run tests against apps running on your local machine, add them to the same network and use service name mapping instead. Example: Instead of running an app on `localhost:8080`, add it to your Docker Compose file, connect it to the same network as your Tracetest service, and use `service-name:8080` in the URL field when creating an app. You can reach services running on your local machine using: @@ -67,7 +67,7 @@ You'll be redirected to the test page where you can see four tabs and depending - How to automate the test :::note -To view the in-depth guide on test results, [check out this docs page](http://localhost:3000/web-ui/test-results) +To view the in-depth guide on test results, [check out this docs page](../../web-ui/test-results) ::: The **Trigger** tab shows how the test was triggered and what the API response was. diff --git a/docs/docs/core/getting-started/overview.mdx b/docs/docs/core/getting-started/overview.mdx new file mode 100644 index 0000000000..dc95f619f0 --- /dev/null +++ b/docs/docs/core/getting-started/overview.mdx @@ -0,0 +1,25 @@ +--- +id: overview +title: Getting Started with Tracetest Core +description: Tracetest Core is the open-core version of Tracetest. With Tracetest Core you can build integration and end-to-end tests, powered by your OpenTelemetry traces. +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 +--- + +Tracetest Core is an open-source, cloud-native application, packaged and distributed as a Docker image and designed to run in a containerized environment. + +We recommend using our managed platform for [Tracetest](https://app.tracetest.io/), because it's the easiest way to build and test with OpenTelemetry. Tracetest includes features such as collaboration for teams and comes with a free tier for development. + +However, if you wish to run Tracetest Core in your own infrastructure, check out the guides below. + +```mdx-code-block +import {CoreGettingStartedGuideCardsRow} from '@site/src/components/CoreGettingStartedGuide'; + + +``` diff --git a/docs/docs/deployment/production-checklist.md b/docs/docs/deployment/production-checklist.md deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/docs/docs/getting-started/detailed-installation.md b/docs/docs/getting-started/detailed-installation.md deleted file mode 100644 index 58fdf90ae9..0000000000 --- a/docs/docs/getting-started/detailed-installation.md +++ /dev/null @@ -1,270 +0,0 @@ -# Detailed Instructions on Installing Tracetest Using the CLI - -This page contains detailed instructions for all installation options the Tracetest CLI provides. - -Tracetest has a command line interface (CLI) which includes an **install wizard** that helps to install the Tracetest server into Docker or Kubernetes. The CLI can also be used to run tests, download or upload tests, and manage much of the capability of Tracetest. - -This page provides a step-by-step guide to install Tracetest using the Tracetest CLI. - -## Prerequisites - -:::info -Make sure you have the Tracetest CLI installed. Read the installation reference [here](../cli/cli-installation-reference.md). -::: - -:::info -Make sure you have [Docker](https://docs.docker.com/get-docker/) and [Docker Compose](https://docs.docker.com/compose/install/), or [Kubernetes](https://kubernetes.io/) installed. -::: - -:::info -In this quick start, OpenTelemetry Collector is used to send traces directly to Tracetest. If you have an existing trace data source, [read here](../configuration/overview.md). -::: - -## Docker Compose - -This guide showcases using the Docker Compose option in the Tracetest CLI. - -### 1. Run the `server install` Command - -Once you've installed the CLI you can install a Tracetest server by running: - -```bash -tracetest server install -``` - -```text title="Expected output:" -โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ - โ–ˆโ–ˆ โ–ˆโ–ˆ โ–ˆโ–ˆ โ–ˆโ–ˆ โ–ˆโ–ˆ โ–ˆโ–ˆ โ–ˆโ–ˆ โ–ˆโ–ˆ โ–ˆโ–ˆ โ–ˆโ–ˆ โ–ˆโ–ˆ - โ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆ - โ–ˆโ–ˆ โ–ˆโ–ˆ โ–ˆโ–ˆ โ–ˆโ–ˆ โ–ˆโ–ˆ โ–ˆโ–ˆ โ–ˆโ–ˆ โ–ˆโ–ˆ โ–ˆโ–ˆ โ–ˆโ–ˆ โ–ˆโ–ˆ - โ–ˆโ–ˆ โ–ˆโ–ˆ โ–ˆโ–ˆ โ–ˆโ–ˆ โ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆ - -Version: v0.10.1 - - -Hi! Welcome to the TraceTest server installer. I'll help you set up your TraceTest server by asking you a few questions -and configuring your system with all the requirements, so you can start TraceTesting right away! - -To get more info about TraceTest, you can check our docs at https://kubeshop.github.io/tracetest/ - -If you have any issues, please let us know by creating an issue (https://github.com/kubeshop/tracetest/issues/new/choose) -or reach us on Discord https://discord.gg/6zupCZFQbe - - -How do you want to run TraceTest? [type to search]: -> Using Docker Compose - Using Kubernetes -``` - -### 2. Select Docker Compose - -This prompts you to select if you want to get either a Docker Compose or Kubernetes setup generated for you. - -Select `Using Docker Compose`. - -```text title="Expected output:" -... - -How do you want to run TraceTest?: - > Using Docker Compose - - --> Let's check if your system has everything we need - -โœ” docker already installed -โœ” docker is ready -โœ” docker compose already installed - --> Your system is ready! Now, let's configure TraceTest - -Do you have OpenTelemetry based tracing already set up, or would you like us to install a demo tracing environment and app? [type to search]: -> I have a tracing environment already. Just install Tracetest - Just learning tracing! Install Tracetest, OpenTelemetry Collector and the sample app. -``` - -After choosing this option, the installer will check if your Docker installation is ok on your machine and will proceed to the next step. - -### 3. Select a default installation or an installation with sample app - -In this step, you can choose to install just Tracetest alone or install it with a sample app. By seeing the following options: - -```text title="Expected output:" -Do you have OpenTelemetry based tracing already set up, or would you like us to install a demo tracing environment and app? [type to search]: - I have a tracing environment already - Just install Tracetest. -> Just learning tracing! Install Tracetest, OpenTelemetry Collector and the sample app. -``` - -By choosing any option, this installer will create a `tracetest` directory in the current directory and will add a `docker-compose.yaml` file to it. -If you choose the first one, the `docker-compose.yaml` will have only Tracetest and its dependencies. By choosing the second, a sample app called [Pokeshop](../live-examples/pokeshop/overview.md) will be installed with Tracetest, allowing you to create some tests against it in the future. - -For demonstration purposes, we will choose `Just learning tracing! Install Tracetest, OpenTelemetry Collector and the sample app.` option. - -### 4. Finish the installation - -Tracetest will proceed with the installation and show how to start it. - -```text title="Expected output:" --> Thanks! We are ready to install TraceTest now - - SUCCESS Install successful! - -To start tracetest: - - docker compose -f tracetest/docker-compose.yaml up -d - -Then, use your browser to navigate to: - - http://localhost:11633 - -Happy TraceTesting =) -``` - -### 5. Start Docker Compose - -```bash -docker compose -f tracetest/docker-compose.yaml up -d -``` - -```bash title="Condensed expected output from the Tracetest container:" -Starting tracetest ... -... -2022/11/28 18:24:09 HTTP Server started -... -``` - -### 6. Open the Tracetest Web UI - -Open [`http://localhost:11633`](http://localhost:11633) in your browser. - -Create a [test](../web-ui/creating-tests.md). - -:::info -Running a test against `localhost` will resolve as `127.0.0.1` inside the Tracetest container. To run tests against apps running on your local machine, add them to the same network and use service name mapping instead. Example: Instead of running an app on `localhost:8080`, add it to your Docker Compose file, connect it to the same network as your Tracetest service, and use `service-name:8080` in the URL field when creating an app. - -You can reach services running on your local machine using: - -- Linux (docker version < 20.10.0): `172.17.0.1:8080` -- MacOS (docker version >= 18.03) and Linux (docker version >= 20.10.0): `host.docker.internal:8080` -::: - -## Kubernetes - -This guide showcases using the Kubernetes option in the Tracetest CLI. - -### 1. Run the `server install` Command - -Once you've installed the CLI you can install a Tracetest server by running: - -```bash -tracetest server install -``` - -```text title="Expected output:" -โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ - โ–ˆโ–ˆ โ–ˆโ–ˆ โ–ˆโ–ˆ โ–ˆโ–ˆ โ–ˆโ–ˆ โ–ˆโ–ˆ โ–ˆโ–ˆ โ–ˆโ–ˆ โ–ˆโ–ˆ โ–ˆโ–ˆ โ–ˆโ–ˆ - โ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆ - โ–ˆโ–ˆ โ–ˆโ–ˆ โ–ˆโ–ˆ โ–ˆโ–ˆ โ–ˆโ–ˆ โ–ˆโ–ˆ โ–ˆโ–ˆ โ–ˆโ–ˆ โ–ˆโ–ˆ โ–ˆโ–ˆ โ–ˆโ–ˆ - โ–ˆโ–ˆ โ–ˆโ–ˆ โ–ˆโ–ˆ โ–ˆโ–ˆ โ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆ - -Version: v0.10.1 - - -Hi! Welcome to the TraceTest server installer. I'll help you set up your TraceTest server by asking you a few questions -and configuring your system with all the requirements, so you can start TraceTesting right away! - -To get more info about TraceTest, you can check our docs at https://kubeshop.github.io/tracetest/ - -If you have any issues, please let us know by creating an issue (https://github.com/kubeshop/tracetest/issues/new/choose) -or reach us on Discord https://discord.gg/6zupCZFQbe - - -How do you want to run TraceTest? [type to search]: - Using Docker Compose -> Using Kubernetes -``` - -### 2. Select Kubernetes - -This prompts you to select if you want to get either a Docker Compose or Kubernetes setup generated for you. - -Select `Using Kubernetes`. - -```text title="Expected output:" -... - -How do you want to run TraceTest?: - > Using Kubernetes - - --> Let's check if your system has everything we need - -โœ” kubectl already installed -โœ” helm already installed - --> Your system is ready! Now, let's configure TraceTest - -Do you have OpenTelemetry based tracing already set up, or would you like us to install a demo tracing environment and app? [type to search]: -> I have a tracing environment already. Just install Tracetest - Just learning tracing! Install Tracetest, OpenTelemetry Collector and the sample app. -``` - -After choosing this option, the installer will check if your kubectl and Helm installations are okay on your machine and will proceed to the next step. - -### 3. Select a default installation or an installation with sample app - -In this step, you can choose to install just Tracetest alone or install it with a sample app. By seeing the following options: - -```text title="Expected output:" -Do you have OpenTelemetry based tracing already set up, or would you like us to install a demo tracing environment and app? [type to search]: - I have a tracing environment already. Just install Tracetest -> Just learning tracing! Install Tracetest, OpenTelemetry Collector and the sample app. -``` - -By choosing any option, this installer will create a `tracetest` namespace with all Tracetest related containers. -If you choose the first one, the `tracetest` namespace will have only Tracetest and its dependencies. By choosing the second, two things will be added. First, a sample app called [Pokeshop](../live-examples/pokeshop/overview.md) will be installed in a `demo` namespace, allowing you to create some tests against it. Second, an OpenTelemetry Collector will be installed in the `tracetest` namespace to receive traces from the demo app and forward them to Tracetest. - -For demonstration purposes, we will choose `Just learning tracing! Install Tracetest, OpenTelemetry Collector and the sample app.` option. - -### 4. Finish the installation - -Tracetest will proceed with the installation and show how to start it. - -```text title="Expected output:" -SUCCESS Install successful! - -To access tracetest: - - kubectl --kubeconfig /.kube/config --context --namespace tracetest port-forward svc/tracetest 11633 - -Then, use your browser to navigate to: - - http://localhost:11633 - -Happy TraceTesting =) -``` - -### 5. Port forward the Tracetest service - -```bash -kubectl --kubeconfig /.kube/config --context --namespace tracetest port-forward svc/tracetest 11633 -``` - -```bash title="Expected output..." -Forwarding from 127.0.0.1:11633 -> 11633 -Forwarding from [::1]:11633 -> 11633 -``` - -### 6. Open the Tracetest Web UI - -Open [`http://localhost:11633`](http://localhost:11633) in your browser. - -Create a [test](../web-ui/creating-tests.md). - -:::info -Running a test against `localhost` will resolve as `127.0.0.1` inside the Tracetest container. To run tests against apps running on your local machine, add them to the same network and use service name mapping instead. Example: Instead of running an app on `localhost:8080`, add it to your Docker Compose file, connect it to the same network as your Tracetest service, and use `service-name:8080` in the URL field when creating an app. - -You can reach services running on your local machine using: - -- Linux (docker version < 20.10.0): `172.17.0.1:8080` -- MacOS (docker version >= 18.03) and Linux (docker version >= 20.10.0): `host.docker.internal:8080` -::: diff --git a/docs/docs/getting-started/installation.mdx b/docs/docs/getting-started/installation.mdx index eacff4407b..fb969287a2 100644 --- a/docs/docs/getting-started/installation.mdx +++ b/docs/docs/getting-started/installation.mdx @@ -16,285 +16,152 @@ import TabItem from '@theme/TabItem'; import CodeBlock from '@theme/CodeBlock'; import GtagInstallCliTabs from '@site/src/components/GtagInstallCliTabs'; -This page showcases getting started with Tracetest by using the Tracetest CLI, Docker, or Kubernetes. - -This simple installation includes a demo app called [Pokeshop](../live-examples/pokeshop/overview.md) that will be installed alongside Tracetest. It shows how to configure OpenTelemetry and Tracetest and the architecture of the Pokeshop sample app. +This page showcases getting started with Tracetest by using the Tracetest CLI and Agent. ## Install the Tracetest CLI -:::tip Want more info? -Read the CLI installation reference [here](../cli/cli-installation-reference.md). -::: +## Install the Tracetest Agent -## Install the Tracetest Server +Tracetest Agent runs as a standalone process. It runs either locally on your machine or as a container. Once started the Agent exposes OTLP ports `4317` (gRPC) and `4318` (HTTP) for trace ingestion. -Tracetest runs as a standalone container. It runs a Server and exposes a Web UI on port `11633`. + + -You have three options to install Tracetest Server: + +tracetest start + -- Using the Tracetest CLI to guide your installation in Docker and Kubernetes. -- Using the official [Helm chart](https://github.com/kubeshop/helm-charts/tree/main/charts/tracetest). -- Using the [Docker Compose Quick Start with the Pokeshop Sample App](https://github.com/kubeshop/tracetest/tree/main/examples/quick-start-pokeshop). +The Agent will start and open a browser. Sign in to Tracetest. - - +![](https://res.cloudinary.com/djwdcmwdz/image/upload/v1695990166/docs/screely-1695990151905_eb8yiw.png) -```bash title="Terminal" -tracetest server install -``` - - - - - {`How do you want to run TraceTest? [type to search]: -> Using Docker Compose - Using Kubernetes`} - - -Choose to install Tracetest with the OpenTelemetry Collector and the [Pokeshop](../live-examples/pokeshop/overview.md) sample app. - -```text title="Expected output:" -Do you have OpenTelemetry based tracing already set up, or would you like us to install a demo tracing environment and app? [type to search]: - I have a tracing environment already. - Just install Tracetest. -> Just learning tracing! Install Tracetest, OpenTelemetry Collector and the sample app. -``` - -Choosing any option, this installer will create a `tracetest` directory in the current directory and add a `docker-compose.yaml` file to it. - -- If you choose the first option, the `docker-compose.yaml` will have only Tracetest and its dependencies. -- **By choosing the second option, a sample app called [Pokeshop](../live-examples/pokeshop/overview.md) will be installed with Tracetest, allowing you to create sample tests right away!** - -
- - Click to view Pokeshop Sample App Architecture - - -Here's the Architecture of the Pokeshop Sample App: - -- an **API** that serves client requests, -- a **Worker** who deals with background processes. - -The communication between the API and Worker is made using a `RabbitMQ` queue, and both services emit telemetry data to OpenTelemetry Collector and communicate with a Postgres database. - -Tracetest triggers tests against the Node.js API. - -```mermaid -flowchart TD - A[(Redis)] - B[(Postgres)] - C(Node.js API) - D(RabbitMQ) - E(Worker) - F(OpenTelemetry Collector) - G(Tracetest) - - G --> C - F --> G - C --> A - C --> B - C --> D - D --> E - E --> B - C --> F - E --> F - - -``` -
- -**Start Docker Compose from the directory where you ran `tracetest server install`.** +Once signed in, return to the terminal. -{`docker compose -f tracetest/docker-compose.yaml up -d`} +{`Defaulting to only available Environment: localMode + INFO Connecting Agent with name local to Organization org_name and Environment localMode + INFO Starting Agent with name local... +Agent is started! Leave the terminal open so tests can be run and traces gathered from this environment (env_name). +You can: [type to search]: +> Open Tracetest in a browser to this environment + Stop this agent`} -This will start the Tracetest Server and expose the Web UI on [`http://localhost:11633`](http://localhost:11633). +The Tracetest Agent is running and ready to accept traces. - - - - {`How do you want to run TraceTest? [type to search]: - Using Docker Compose -> Using Kubernetes`} - - -Choose to install Tracetest with the OpenTelemetry Collector and the [Pokeshop](../live-examples/pokeshop/overview.md) sample app. - -```text title="Expected output:" -Do you have OpenTelemetry based tracing already set up, or would you like us to install a demo tracing environment and app? [type to search]: - I have a tracing environment already - Just install Tracetest. -> Just learning tracing! Install Tracetest, OpenTelemetry Collector and the sample app. -``` - -Choosing any option, this installer will create a `tracetest` namespace in the Kubernetes context you choose and create deployments for Tracetest and its dependencies. - -- If you choose the first option, the `tracetest` namespace will only contain Tracetest and its dependencies. -- **By choosing the second option, a sample app called [Pokeshop](../live-examples/pokeshop/overview.md) will be installed in a `demo` namespace alongside Tracetest, allowing you to create sample tests right away!** - -
- - Click to view Pokeshop Sample App Architecture - - -Here's the Architecture of the Pokeshop Sample App: - -- an **API** that serves client requests, -- a **Worker** who deals with background processes. - -The communication between the API and Worker is made using a `RabbitMQ` queue, and both services emit telemetry data to OpenTelemetry Collector and communicate with a Postgres database. - -Tracetest triggers tests against the Node.js API. - -```mermaid -flowchart TD - A[(Redis)] - B[(Postgres)] - C(Node.js API) - D(RabbitMQ) - E(Worker) - F(OpenTelemetry Collector) - G(Tracetest) - - G --> C - F --> G - C --> A - C --> B - C --> D - D --> E - E --> B - C --> F - E --> F - - -``` -
- -**Access the Tracetest Server by port forwarding to the Tracetest `service`.** - -```bash title=Terminal -export POD_NAME=$(kubectl get pods --namespace demo -l "app.kubernetes.io/name=pokemon-api,app.kubernetes.io/instance=demo" -o jsonpath="{.items[0].metadata.name}") -export CONTAINER_PORT=$(kubectl get pod --namespace demo $POD_NAME -o jsonpath="{.spec.containers[0].ports[0].containerPort}") -kubectl --namespace demo port-forward $POD_NAME 8080:$CONTAINER_PORT -echo "Open http://127.0.0.1:8080 to view the Pokeshop demo app" - -kubectl --kubeconfig /.kube/config --context --namespace tracetest port-forward svc/tracetest 11633 -echo "Open http://127.0.0.1:11633 to view the Tracetest Web UI" -``` - -Access the Tracetest Web UI on [`http://localhost:11633`](http://localhost:11633). +gRPC: `http://localhost:4317` - - +HTTP: `http://localhost:4318/v1/traces` - + -First, be sure that you have [Helm](https://helm.sh/) installed in your machine. + +{`docker run \\\n-p 4317:4317 \\\n-p 4318:4318 \\\n-e TRACETEST_API_KEY="" \\\nkubeshop/tracetest-agent`} + -The Tracetest Helm charts are located [here](https://github.com/kubeshop/helm-charts/tree/main/charts/tracetest). +The Agent will start and open a browser. Sign in to Tracetest. -You can install them locally on your machine with the command: +![](https://res.cloudinary.com/djwdcmwdz/image/upload/v1695990166/docs/screely-1695990151905_eb8yiw.png) -```bash title=Terminal -helm repo add kubeshop https://kubeshop.github.io/helm-charts -helm repo update -``` +Once signed in, return to the terminal. -After that, you can install Tracetest with `helm install`: + +{`Defaulting to only available Environment: localMode + INFO Connecting Agent with name local to Organization org_name and Environment localMode + INFO Starting Agent with name local... +Agent is started! Leave the terminal open so tests can be run and traces gathered from this environment (env_name). +You can: [type to search]: +> Open Tracetest in a browser to this environment + Stop this agent`} + + +The Tracetest Agent is running in Docker and ready to accept traces. -```bash title=Terminal -helm install tracetest kubeshop/tracetest --namespace=tracetest --create-namespace -``` +gRPC: `http://:4317` -Or, generate a manifest file and apply it manually in your Kubernetes cluster: +HTTP: `http://:4318/v1/traces` -```bash title=Terminal -helm template tracetest kubeshop/tracetest > tracetest-kubernetes-manifests.yaml -kubectl apply -f ./tracetest-kubernetes-manifests.yaml -``` +:::note +Running a test against `localhost` will resolve as `127.0.0.1` inside the Tracetest Agent container. -**Access the Tracetest Server by port forwarding to the Tracetest `service`.** +To run tests against apps running on your local machine you have two options: -```bash title=Terminal -kubectl --kubeconfig /.kube/config --context --namespace tracetest port-forward svc/tracetest 11633 -``` +1. Run Tracetest Agent locally with the `tracetest start` command. +2. Add Tracetest Agent to the same network and use service name mapping. *Example: Instead of running an app on `localhost:8080`, add it to your Docker Compose file, connect it to the same network as your Tracetest Agent service, and use `:8080` in the URL field when creating a test.* -Access the Tracetest Web UI on [`http://localhost:11633`](http://localhost:11633). +You can reach services running on your local machine using: + +- Linux (docker version < 20.10.0): `172.17.0.1:8080` +- MacOS (docker version >= 18.03) and Linux (docker version >= 20.10.0): `host.docker.internal:8080` +::: - + -First, be sure that you have [Docker](https://docker.com/) installed in your machine. + +{`curl https://raw.githubusercontent.com/kubeshop/tracetest/main/k8s/agent/deploy-agent.sh | bash -s -- default `} + -The Quick Start with the Pokeshop Sample App is located [here](https://github.com/kubeshop/tracetest/tree/main/examples/quick-start-pokeshop). +The Agent will start and open a browser. Sign in to Tracetest. -**The [`docker-compose.yaml`](https://github.com/kubeshop/tracetest/blob/main/examples/quick-start-pokeshop/docker-compose.yml) contains Tracetest, the OpenTelemetry Collector, and a sample app called [Pokeshop](../live-examples/pokeshop/overview.md). This allows you to create sample tests right away!** +![](https://res.cloudinary.com/djwdcmwdz/image/upload/v1695990166/docs/screely-1695990151905_eb8yiw.png) -
- - Click to view Pokeshop Sample App Architecture - +Once signed in, return to the terminal. -Here's the Architecture of the Pokeshop Sample App: + +{`Defaulting to only available Environment: localMode + INFO Connecting Agent with name local to Organization org_name and Environment localMode + INFO Starting Agent with name local... +Agent is started! Leave the terminal open so tests can be run and traces gathered from this environment (env_name). +You can: [type to search]: +> Open Tracetest in a browser to this environment + Stop this agent`} + -- an **API** that serves client requests, -- a **Worker** who deals with background processes. +The Tracetest Agent is running in Kubernetes and ready to accept traces. -The communication between the API and Worker is made using a `RabbitMQ` queue, and both services emit telemetry data to OpenTelemetry Collector and communicate with a Postgres database. +gRPC: `http://:4317` -Tracetest triggers tests against the Node.js API. +HTTP: `http://:4318/v1/traces` -```mermaid -flowchart TD - A[(Redis)] - B[(Postgres)] - C(Node.js API) - D(RabbitMQ) - E(Worker) - F(OpenTelemetry Collector) - G(Tracetest) +:::note +Running a test against `localhost` will resolve as `127.0.0.1` inside the Tracetest Agent container. - G --> C - F --> G - C --> A - C --> B - C --> D - D --> E - E --> B - C --> F - E --> F - - -``` -
+To run tests against apps running on your local machine you have two options: -**Start Docker Compose.** +1. Run Tracetest Agent locally with the `tracetest start` command. +2. Add Tracetest Agent to the same network and use service name mapping. *Example: Instead of running an app on `localhost:8080`, add it to your Docker Compose file, connect it to the same network as your Tracetest Agent service, and use `:8080` in the URL field when creating a test.* - -{`docker compose -f docker-compose.yaml up -d`} - +You can reach services running on your local machine using: -This will start the Tracetest Server and expose the Web UI on [`http://localhost:11633`](http://localhost:11633). +- Linux (docker version < 20.10.0): `172.17.0.1:8080` +- MacOS (docker version >= 18.03) and Linux (docker version >= 20.10.0): `host.docker.internal:8080` +::: :::tip Don't have OpenTelemetry installed? -Tracetest requires that you have [OpenTelemetry instrumentation](https://opentelemetry.io/docs/instrumentation/) added in your code, and configured [sending traces to a trace data store](../configuration/connecting-to-data-stores/jaeger.md), or [Tracetest directly](../configuration/connecting-to-data-stores/opentelemetry-collector.md). - [Follow these instructions to install OpenTelemetry in 5 minutes without any code changes!](./no-otel.mdx) ::: diff --git a/docs/docs/getting-started/open.mdx b/docs/docs/getting-started/open.mdx new file mode 100644 index 0000000000..bef79599d8 --- /dev/null +++ b/docs/docs/getting-started/open.mdx @@ -0,0 +1,229 @@ +--- +id: open +title: Opening Tracetest +description: Tracetest allows you to quickly build integration and end-to-end tests, powered by your OpenTelemetry traces. Learn how to get started with creating tests once you open Tracetest. +keywords: + - tracetest + - trace-based testing + - observability + - distributed tracing + - testing +image: https://res.cloudinary.com/djwdcmwdz/image/upload/v1689693872/docs/Blog_Thumbnail_28_ugy2yy.png +--- + +This page showcases opening the Tracetest Web UI and creating a test against the [sample Pokeshop API](../live-examples/pokeshop/overview.md). + +Once you've installed Tracetest, as explained in the [installation guide](./installation.mdx), the Tracetest Agent is running on `localhost` ports `4317` and `4318`. You then access the Tracetest Web UI on [`app.tracetest.io`](https://app.tracetest.io). Here's what will greet you after a fresh install. + +![Landing page Tracetest](https://res.cloudinary.com/djwdcmwdz/image/upload/v1688474565/docs/screely-1688474539641_kbhvvc.png) + +## Start the Sample Pokeshop API + +To create tests quickly, start the official sample called Pokeshop API. + +```bash title=Terminal +git clone https://github.com/kubeshop/tracetest.git +cd tracetest/examples/tracetest-agent/pokeshop/ +docker-compose up +``` + +This will start an HTTP API on `localhost:8081` and a GRPC API on `localhost:8082`. + +
+ + Click to view the sample Pokeshop API architecture + + +Here's the Architecture of the Pokeshop Sample App: + +- an **API** that serves client requests, +- a **Worker** who deals with background processes. + +The communication between the API and Worker is made using a `RabbitMQ` queue, and both services emit telemetry data to OpenTelemetry Collector and communicate with a Postgres database. + +Tracetest triggers tests against the Node.js API. + +```mermaid +flowchart TD + A[(Redis)] + B[(Postgres)] + C(Node.js API) + D(RabbitMQ) + E(Worker) + F(OpenTelemetry Collector) + G(Tracetest) + + G --> C + F --> G + C --> A + C --> B + C --> D + D --> E + E --> B + C --> F + E --> F + + +``` +
+ + +### Configure the Pokeshop API Demo resource + +Configure the `demo` [resource](/configuration/provisioning) to quickly create tests either in the Web UI or with the CLI. + +In the Web UI go to **Settings > Demo**, toggle **Enable Pokeshop**, and add: + +- HTTP Endpoint: `http://localhost:8081` +- GRPC Endpoint: `localhost:8082` + +![Settings](https://res.cloudinary.com/djwdcmwdz/image/upload/v1696251763/docs/screely-1696251756346_ptxb9m.png) + +With the CLI, create a file called `tracetest-provision.yaml`. + +```yaml title=tracetest-provision.yaml +--- +type: Demo +spec: + type: pokeshop + enabled: true + name: pokeshop + pokeshop: + httpEndpoint: http://localhost:8081 + grpcEndpoint: localhost:8082 +``` + +Run the command below to enable the `demo` resource. + +```bash +tracetest apply demo -f tracetest-provision.yaml +``` + +You can now quickly create tests against the Pokeshop API. + +## Creating Trace-based Tests + +You can create tests in two ways: + +- Visually, in the Web UI +- Programmatically, in YAML + +## Creating Trace-based Tests Visually + +This guide will show how to create end-to-end and integration tests in less than 5 minutes via the Web UI. + +:::note +To view the in-depth guide on creating tests visually, [check out this docs page](../web-ui/creating-tests.md). +::: + +### Create + +On the top right, click the **Create** button and select **Create New Test** in the drop down. + +![Create a new test](https://res.cloudinary.com/djwdcmwdz/image/upload/v1688475179/docs/screely-1688475174365_ckq3cn.png) + +Select an **HTTP Request** as the **test trigger**, and choose the **Pokeshop - Import** example. + +![Select Pokeshop example](https://res.cloudinary.com/djwdcmwdz/image/upload/v1688475514/docs/screely-1688475510090_r6hqmx.png) + +This will populate a sample API test against a POST endpoint in the Pokeshop app demo. Clicking **Create & Run** will save and trigger the test. + +![API test against POST endpoint](https://res.cloudinary.com/djwdcmwdz/image/upload/v1696253160/docs/screely-1696253153066_khjz8y.png) + +### Trigger + +You'll be redirected to the test page where you can see four tabs and depending on which one you select you'll get access to: + +- Test trigger and results. +- The entire distributed trace and trace analysis. +- Test specification and assertions. +- How to automate the test. + +:::note +To view the in-depth guide on test results, [check out this docs page](/web-ui/test-results). +::: + +The **Trigger** tab shows how the test was triggered and what the API response was. + +![test result](https://res.cloudinary.com/djwdcmwdz/image/upload/v1696253230/docs/screely-1696253224366_f62411.png) + +### Trace + +The **Trace** tab shows the entire distributed trace for debugging and a trace analysis score. + +![distributed trace and trace analysis score](https://res.cloudinary.com/djwdcmwdz/image/upload/v1688476460/docs/screely-1688476455986_q24aa2.png) + +### Test + +The **Test** tab shows span attributes. Here you add test specs and assertions on attribute values. You also get a test snippets out-of-the-box for common test cases. + +In the sample below, you see how to assert that all database spans return in less than `100ms`. + +![test specs](https://res.cloudinary.com/djwdcmwdz/image/upload/v1688476657/docs/screely-1688476653521_omxe4r.png) + +### Automate + +The **Automate** tab shows how to automate the test run with the Tracetest CLI and other automation options. + +![automate](https://res.cloudinary.com/djwdcmwdz/image/upload/v1696285049/docs/screely-1696285040458_vjt0qv.png) + +From here you can download a YAML file test definition and run it with the CLI. + +## Creating Trace-based Tests Programatically + +The test definition will contain: + +- The **Trigger** for the test in the `trigger` section. +- The **Test Specifications** in the`specs` section. + +You can either download the YAML file test definition, or write one from scratch. + +### Create + +Using the sample from above, create the Trace-based Test programatically. + +```yaml title="pokeshop-import.yaml" +type: Test +spec: + id: T7-delWIR + name: Pokemon Import + trigger: + type: http + httpRequest: + method: POST + url: http://localhost:8081/pokemon/import + body: "{\"id\":52}" + headers: + - key: Content-Type + value: application/json + specs: + - selector: span[tracetest.span.type="database"] + name: "All Database Spans: Processing time is less than 100ms" + assertions: + - attr:tracetest.span.duration < 100ms + - attr:db.system != "" + - selector: span[tracetest.span.type="http"] + name: "All HTTP Spans: Status code is 200" + assertions: + - attr:http.status_code = 200 +``` + +### Trigger + +Using the CLI, trigger a test run. + +```bash title="Terminal" +tracetest run test -f pokemon-import.yaml --required-gates test-specs --output pretty +``` + +### Output + +The test run will complete and show a result. + +```text title="Output" +โœ” Pokemon Import (https://app.tracetest.io/organizations//environments//test/T7-delWIR/run/7/test) - trace id: + โœ” All Database Spans: Processing time is less than 100ms + โœ” All HTTP Spans: Status code is 200 +``` + +The provided link in the test output will open the test run in the Tracetest Web UI. diff --git a/docs/docs/getting-started/overview.mdx b/docs/docs/getting-started/overview.mdx index 147c7cf723..bb7bf551e5 100644 --- a/docs/docs/getting-started/overview.mdx +++ b/docs/docs/getting-started/overview.mdx @@ -1,6 +1,6 @@ --- id: overview -title: Getting Started with Tracetest ๐Ÿš€ +title: Getting Started with Tracetest description: Tracetest allows you to quickly build integration and end-to-end tests, powered by your OpenTelemetry traces. hide_table_of_contents: false keywords: @@ -12,7 +12,11 @@ keywords: image: https://res.cloudinary.com/djwdcmwdz/image/upload/v1689693872/docs/Blog_Thumbnail_28_ugy2yy.png --- -Tracetest is a cloud-native application, packaged and distributed a Docker image and designed to run in a containerized environment. +Tracetest is a cloud-native application, packaged and distributed as a Docker image and designed to run in a containerized environment. + +We recommend using our managed platform for [Tracetest](https://app.tracetest.io/), because it's the easiest way to build and test with OpenTelemetry. Tracetest includes features such as collaboration for teams and comes with a free tier for development. + +Alternatively, you can run Tracetest Core on your own infrastructure with Docker or Kubernetes. ```mdx-code-block import {GettingStartedGuideCardsRow} from '@site/src/components/GettingStartedGuide'; diff --git a/docs/docs/index.mdx b/docs/docs/index.mdx index e771b6287b..85eb73fab9 100644 --- a/docs/docs/index.mdx +++ b/docs/docs/index.mdx @@ -27,21 +27,27 @@ import {WelcomeGuideCardsRow} from '@site/src/components/WelcomeGuide'; You can: -- Define tests and assertions against every single microservice that a trace goes through. -- Define **assertions against** both the **response and trace data**. -- Ensure both your response and the underlying processes worked correctly, quickly, and without errors. -- Work with your existing distributed tracing solution. -- Build tests based on your already instrumented system. -- Define multiple transaction triggers: +- **Assert** against both the **response and trace data** at every point of a request transaction. +- **Assert** on the **timing of trace spans**. + - Eg. A database span executes within `100ms`. +- **Wildcard assertions** across common types of activities. + - Eg. All gRPC return codes should be `0`. + - Eg. All database calls should happen in less than `100ms`. +- **Assert** against **side-effects** in your distributed system. + - Eg. Message queues, async API calls, external APIs, etc. +- **Integrate** with your **existing distributed tracing solution**. +- Define multiple test triggers: - HTTP requests - - GRPC requests - - trace IDs + - gRPC requests + - Trace IDs - and many more... -- Save and run the tests manually or via CI build jobs. +- Save and run tests manually and via CI build jobs. +- Verify and analyze the quality of your OpenTelemetry instrumentation to enforce rules and standards. +- Test long-running processes. - Write detailed trace-based tests as: - End-to-end tests - Integration tests -- Build tests in minutes. +- **Build tests in minutes**.
diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index 3eea79f109..854b513791 100644 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -122,16 +122,16 @@ const config = { from: ['/advanced-selectors' /*, '/docs/legacyDocFrom2016'*/], }, { - to: '/deployment/docker', - from: ['/deployment/overview/docker' /*, '/docs/legacyDocFrom2016'*/], + to: '/core/deployment/docker', + from: ['/deployment/overview/docker', '/deployment/docker' /*, '/docs/legacyDocFrom2016'*/], }, { - to: '/deployment/kubernetes', - from: ['/deployment/overview/kubernetes' /*, '/docs/legacyDocFrom2016'*/], + to: '/core/deployment/kubernetes', + from: ['/deployment/overview/kubernetes', '/deployment/kubernetes' /*, '/docs/legacyDocFrom2016'*/], }, { - to: '/getting-started/detailed-installation', - from: ['/getting-started/cli' /*, '/docs/legacyDocFrom2016'*/], + to: '/getting-started/installation', + from: ['/getting-started/cli', '/getting-started/detailed-installation' /*, '/docs/legacyDocFrom2016'*/], }, { to: '/configuration/overview', @@ -205,6 +205,10 @@ const config = { to: '/web-ui/creating-test-suites', from: ['/web-ui/creating-transactions'], }, + { + to: '/getting-started/installation', + from: ['/installing'], + }, ], // createRedirects(existingPath) { // if (existingPath.includes('/community')) { @@ -256,6 +260,12 @@ const config = { sidebarId: 'tutorialSidebar', label: 'Docs' }, + { + type: 'docSidebar', + position: 'left', + sidebarId: 'coreSidebar', + label: 'Core' + }, { type: 'docSidebar', position: 'left', @@ -268,16 +278,6 @@ const config = { sidebarId: 'liveExamplesSidebar', label: 'Live Examples' }, - { - href: '/openapi', - // Only one of "to" or "href" should be used - // href: 'https://www.facebook.com', - label: 'Open API', - // Only one of "label" or "html" should be used - // html: 'Introduction' - position: 'left', - target: '_self', - }, { href: "https://tracetest.io/community", label: "Community", @@ -285,8 +285,8 @@ const config = { }, { type: "html", - position: "left", - value: ``, + position: "right", + value: ``, }, { type: "search", diff --git a/docs/sidebars.js b/docs/sidebars.js index 15a0fd4e4b..bdc458e3b1 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -351,6 +351,54 @@ const sidebars = { }, ], + coreSidebar: [ + { + type: "link", + label: "Welcome! ๐Ÿ‘‹", + href: "/", + }, + { + type: "category", + label: "Getting Started", + link: { + type: "doc", + id: "core/getting-started/overview" + }, + items: [ + { + type: "doc", + id: "core/getting-started/installation", + label: "Installing Tracetest Core", + }, + { + type: "doc", + id: "core/getting-started/open", + label: "Opening Tracetest Core", + }, + ], + }, + { + type: "category", + label: "Deployment", + link: { + type: "doc", + id: "core/deployment/overview", + }, + items: [ + { + type: "doc", + id: "core/deployment/docker", + label: "Docker", + }, + { + type: "doc", + id: "core/deployment/kubernetes", + label: "Kubernetes", + }, + ], + }, + ], + tutorialSidebar: [ { type: "doc", @@ -523,31 +571,6 @@ const sidebars = { }, ], }, - { - type: "category", - label: "Deployment", - link: { - type: "doc", - id: "deployment/overview", - }, - items: [ - // { - // type: "doc", - // id: "deployment/production-checklist", - // label: "Production checklist", - // }, - { - type: "doc", - id: "deployment/docker", - label: "Docker", - }, - { - type: "doc", - id: "deployment/kubernetes", - label: "Kubernetes", - }, - ], - }, { type: "category", label: "Concepts", diff --git a/docs/src/components/CoreGettingStartedGuide/index.tsx b/docs/src/components/CoreGettingStartedGuide/index.tsx new file mode 100644 index 0000000000..567c708861 --- /dev/null +++ b/docs/src/components/CoreGettingStartedGuide/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 CoreGettingStartedGuides = [ + { + name: '๐Ÿ‘‡ Install Tracetest Core', + url: './installation', + description: ( + + Set up Tracetest Core and start trace-based testing your distributed system. + + ), + button: 'Set up', + }, + { + name: '๐Ÿ™Œ Open Tracetest Core', + url: './open', + description: ( + + After installing it, open Tracetest Core start to creating trace-based tests. + + ), + button: 'Create tests', + }, + { + name: '๐Ÿค” Don\'t have OpenTelemetry?', + url: '/getting-started/no-otel', + description: ( + + Install OpenTelemetry in 5 minutes without any code changes! + + ), + button: 'Set up OpenTelemetry', + }, + { + name: '๐Ÿคฉ Open Source', + url: 'https://github.com/kubeshop/tracetest', + description: ( + + Check out the Tracetest GitHub repo! Please consider giving us a star! โญ๏ธ + + ), + button: 'Go to GitHub', + }, +]; + +interface Props { + name: string; + url: string; + button: string; + description: JSX.Element; +} + +function CoreGettingStartedGuideCard({name, url, description, button}: Props) { + return ( +
+
+
+ {name} +

{description}

+
+
+
+ + {button} + +
+
+
+
+ ); +} + +export function CoreGettingStartedGuideCardsRow(): JSX.Element { + return ( +
+ {CoreGettingStartedGuides.map((coreGettingStartedGuide) => ( + + ))} +
+ ); +} diff --git a/docs/src/components/GettingStartedGuide/index.tsx b/docs/src/components/GettingStartedGuide/index.tsx index 504379e0fb..ebd092cdee 100644 --- a/docs/src/components/GettingStartedGuide/index.tsx +++ b/docs/src/components/GettingStartedGuide/index.tsx @@ -8,44 +8,24 @@ import Heading from '@theme/Heading'; const GettingStartedGuides = [ { - name: '๐Ÿ‘‡ Install Tracetest', + name: 'Tracetest ๐Ÿš€', url: './installation', description: ( Set up Tracetest and start trace-based testing your distributed system. ), - button: 'Set up Tracetest', + button: 'Start', }, { - name: '๐Ÿ™Œ Open Tracetest', - url: './open', + name: 'Tracetest Core ๐Ÿชจ ', + url: '../core/getting-started/installation', description: ( - After installing it, open Tracetest start to creating trace-based tests. + Use the open-source Tracetest Core in your own infrastructure. ), - button: 'Create tests', - }, - { - name: '๐Ÿค” Don\'t have OpenTelemetry?', - url: './no-otel', - description: ( - - Install OpenTelemetry in 5 minutes without any code changes! - - ), - button: 'Set up OTel', - }, - { - name: '๐Ÿคฉ Open Source', - url: 'https://github.com/kubeshop/tracetest', - description: ( - - Check out the Tracetest GitHub repo! Please consider giving us a star! โญ๏ธ - - ), - button: 'Go to GitHub', + button: 'Go to Core', }, ]; @@ -59,18 +39,15 @@ interface Props { function GettingStartedGuideCard({name, url, description, button}: Props) { return (
-
-
- {name} -

{description}

-
-
-
- - {button} - +
+
+ +
+ {name} +

{description}

-
+ +
); diff --git a/docs/src/components/WelcomeGuide/index.tsx b/docs/src/components/WelcomeGuide/index.tsx index 4254bae7eb..855d1a823e 100644 --- a/docs/src/components/WelcomeGuide/index.tsx +++ b/docs/src/components/WelcomeGuide/index.tsx @@ -8,8 +8,8 @@ import Heading from '@theme/Heading'; const WelcomeGuides = [ { - name: '๐Ÿ‘‡ Install Tracetest', - url: './getting-started/installation', + name: '๐Ÿ‘‡ Getting Started', + url: './getting-started/overview', description: ( Set up Tracetest and start trace-based testing your distributed system. @@ -17,26 +17,6 @@ const WelcomeGuides = [ ), button: 'Set up Tracetest', }, - { - name: '๐Ÿ™Œ Open Tracetest', - url: './getting-started/open', - description: ( - - After installing it, open Tracetest start to creating trace-based tests. - - ), - button: 'Create tests', - }, - { - name: '๐Ÿค” Don\'t have OpenTelemetry?', - url: './getting-started/no-otel', - description: ( - - Install OpenTelemetry in 5 minutes without any code changes! - - ), - button: 'Set up OTel', - }, { name: '๐Ÿคฉ Open Source', url: 'https://github.com/kubeshop/tracetest', diff --git a/docs/src/css/custom.css b/docs/src/css/custom.css index e879c7963e..6f44cb3530 100644 --- a/docs/src/css/custom.css +++ b/docs/src/css/custom.css @@ -7,10 +7,15 @@ /* You can override the default Infima variables here. */ :root { - --ifm-code-font-size: 95%; + --ifm-code-font-size: 90%; + --ifm-font-size-base: 16px; --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.1); } +nav { + font-size: 16px; +} + :root footer { background-color: #fff !important; } @@ -59,3 +64,24 @@ div[class^='announcementBar'] a:hover { color: var(--ifm-link-color); text-decoration: underline; } + +/* Card */ +div[class^='gs__card'] .card { + background-color: var(--ifm-background-surface-color); + color: var(--ifm-font-color-base); + transition-duration: 500ms; +} + +div[class^='gs__card'] .card:hover { + box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19); +} + +div[class^='gs__card'] .card a { + color: var(--ifm-font-color-base); + text-decoration: inherit; +} + +div[class^='gs__card'] .card a:hover { + color: var(--ifm-font-color-base); + text-decoration: inherit; +} diff --git a/examples/tracetest-agent/otel-demo/readme.md b/examples/tracetest-agent/otel-demo/readme.md new file mode 100644 index 0000000000..134cc2636e --- /dev/null +++ b/examples/tracetest-agent/otel-demo/readme.md @@ -0,0 +1,3 @@ +# OpenTelemetry Demo with Tracetest Cloud + +TBD diff --git a/examples/tracetest-agent/pokeshop/collector.config.yaml b/examples/tracetest-agent/pokeshop/collector.config.yaml new file mode 100644 index 0000000000..a473767f39 --- /dev/null +++ b/examples/tracetest-agent/pokeshop/collector.config.yaml @@ -0,0 +1,27 @@ +receivers: + otlp: + protocols: + grpc: + http: + +processors: + batch: + timeout: 100ms + + # Data sources: traces + probabilistic_sampler: + hash_seed: 22 + sampling_percentage: 100 + +exporters: + otlp/tracetestagent: + endpoint: host.docker.internal:4317 + tls: + insecure: true + +service: + pipelines: + traces/tracetestagent: + receivers: [otlp] + processors: [probabilistic_sampler, batch] + exporters: [otlp/tracetestagent] diff --git a/examples/tracetest-agent/pokeshop/docker-compose.yaml b/examples/tracetest-agent/pokeshop/docker-compose.yaml new file mode 100644 index 0000000000..08d763c563 --- /dev/null +++ b/examples/tracetest-agent/pokeshop/docker-compose.yaml @@ -0,0 +1,110 @@ +version: '3' +services: + + api: + image: kubeshop/demo-pokemon-api:latest + restart: unless-stopped + pull_policy: always + environment: + REDIS_URL: cache + DATABASE_URL: postgresql://postgres:postgres@postgres:5432/postgres?schema=public + RABBITMQ_HOST: queue + POKE_API_BASE_URL: https://pokeapi.co/api/v2 + COLLECTOR_ENDPOINT: http://otel-collector:4317 + NPM_RUN_COMMAND: api + ports: + - "8081:8081" + healthcheck: + test: ["CMD", "wget", "--spider", "localhost:8081"] + interval: 1s + timeout: 3s + retries: 60 + depends_on: + postgres: + condition: service_healthy + cache: + condition: service_healthy + queue: + condition: service_healthy + + worker: + image: kubeshop/demo-pokemon-api:latest + restart: unless-stopped + pull_policy: always + environment: + REDIS_URL: cache + DATABASE_URL: postgresql://postgres:postgres@postgres:5432/postgres?schema=public + RABBITMQ_HOST: queue + POKE_API_BASE_URL: https://pokeapi.co/api/v2 + COLLECTOR_ENDPOINT: http://otel-collector:4317 + NPM_RUN_COMMAND: worker + depends_on: + postgres: + condition: service_healthy + cache: + condition: service_healthy + queue: + condition: service_healthy + + rpc: + image: kubeshop/demo-pokemon-api:latest + restart: unless-stopped + pull_policy: always + environment: + REDIS_URL: cache + DATABASE_URL: postgresql://postgres:postgres@postgres:5432/postgres?schema=public + RABBITMQ_HOST: queue + POKE_API_BASE_URL: https://pokeapi.co/api/v2 + COLLECTOR_ENDPOINT: http://otel-collector:4317 + NPM_RUN_COMMAND: rpc + ports: + - 8082:8082 + healthcheck: + test: ["CMD", "lsof", "-i", "8082"] + interval: 1s + timeout: 3s + retries: 60 + depends_on: + postgres: + condition: service_healthy + cache: + condition: service_healthy + queue: + condition: service_healthy + + 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 + + cache: + image: redis:6 + restart: unless-stopped + healthcheck: + test: ["CMD", "redis-cli", "ping"] + interval: 1s + timeout: 3s + retries: 60 + + queue: + image: rabbitmq:3.8-management + restart: unless-stopped + healthcheck: + test: rabbitmq-diagnostics -q check_running + interval: 1s + timeout: 5s + retries: 60 + + otel-collector: + image: otel/opentelemetry-collector:0.54.0 + command: + - "--config" + - "/otel-local-config.yaml" + volumes: + - ./collector.config.yaml:/otel-local-config.yaml diff --git a/examples/tracetest-agent/pokeshop/readme.md b/examples/tracetest-agent/pokeshop/readme.md new file mode 100644 index 0000000000..4874e819d8 --- /dev/null +++ b/examples/tracetest-agent/pokeshop/readme.md @@ -0,0 +1,8 @@ +# Pokeshop with Tracetest Cloud + +> [Read the detailed instructions for setting up Tracetest Cloud in our documentation.](https://docs.tracetest.io/getting-started/installation) + +This examples' objective is to show how you can: + +1. Configure Pokeshop API to export traces to Tracetest Agent. +2. Configure Tracetest Agent to ingest traces. diff --git a/examples/tracetest-agent/pokeshop/tests/pokemon-import.yaml b/examples/tracetest-agent/pokeshop/tests/pokemon-import.yaml new file mode 100644 index 0000000000..774e34bde7 --- /dev/null +++ b/examples/tracetest-agent/pokeshop/tests/pokemon-import.yaml @@ -0,0 +1,23 @@ +type: Test +spec: + id: T7-delWIR + name: Pokemon Import + trigger: + type: http + httpRequest: + method: POST + url: http://localhost:8081/pokemon/import + body: "{\"id\":6}" + headers: + - key: Content-Type + value: application/json + specs: + - selector: span[tracetest.span.type="database"] + name: "All Database Spans: Processing time is less than 100ms" + assertions: + - attr:tracetest.span.duration < 100ms + - attr:db.system != "" + - selector: span[tracetest.span.type="http"] + name: "All HTTP Spans: Status code is 200" + assertions: + - attr:http.status_code = 200 diff --git a/examples/tracetest-agent/pokeshop/tracetest-provision.yaml b/examples/tracetest-agent/pokeshop/tracetest-provision.yaml new file mode 100644 index 0000000000..407576ef77 --- /dev/null +++ b/examples/tracetest-agent/pokeshop/tracetest-provision.yaml @@ -0,0 +1,10 @@ +--- +type: Demo +spec: + id: S7y8puWIg + type: pokeshop + enabled: true + name: pokeshop + pokeshop: + httpEndpoint: http://localhost:8081 + grpcEndpoint: localhost:8082