diff --git a/docs/docs/getting-started/cli-installation-reference.md b/docs/docs/getting-started/cli-installation-reference.md new file mode 100644 index 0000000000..1eb32e5c8a --- /dev/null +++ b/docs/docs/getting-started/cli-installation-reference.md @@ -0,0 +1,77 @@ +# CLI Installation Reference + +This page contains a reference of all options for installing Tracetest CLI. + +## Detailed Instructions on Installing Tracetest Using the CLI + +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. + +## Installing the Tracetest Server via the CLI + +Use the CLI's install wizard to install a Tracetest server locally using Docker Compose or to a local or remote Kubernetes cluster. + +The wizard installs all the tools required to set up the desired environment and creates all the configurations, tailored to your case. + +Every time we release a new version of Tracetest, we generate binaries for Linux, MacOS, and Windows. Supporting both amd64, and ARM64 architectures, in `tar.gz`, `deb`, `rpm` and `exe` formats. + +You can find the latest version [here](https://github.com/kubeshop/tracetest/releases/latest). + +### Linux/MacOS + +Tracetest CLI can be installed automatically using the following script: + +```sh +curl -L https://raw.githubusercontent.com/kubeshop/tracetest/main/install-cli.sh | bash +``` + +It works for systems with Homebrew, `apt-get`, `dpkg`, `yum`, `rpm` installed, and if no package manager is available, it will try to download the build and install it manually. + +You can also manually install it with one of the following methods. + +#### Homebrew + +```sh +brew install kubeshop/tracetest/tracetest +``` + +#### APT + +```sh +# requirements for our deb repo to work +sudo apt-get update && sudo apt-get install -y apt-transport-https ca-certificates + +# add repo +echo "deb [trusted=yes] https://apt.fury.io/tracetest/ /" | sudo tee /etc/apt/sources.list.d/fury.list + +# update and install +sudo apt-get update +sudo apt-get install tracetest +``` + +#### YUM + +```sh +# add repository +cat < I have a tracing environment already. Just install Tracetest - Just learning tracing! Install Tracetest, OpenTelemetry Collector and the sample app. + 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. diff --git a/docs/docs/getting-started/installation.mdx b/docs/docs/getting-started/installation.mdx index 0025295164..41f206b0cc 100644 --- a/docs/docs/getting-started/installation.mdx +++ b/docs/docs/getting-started/installation.mdx @@ -1,4 +1,4 @@ -# Getting Started +# Installing Tracetest @@ -11,15 +11,35 @@ import GtagInstallCliTabs from '@site/src/components/GtagInstallCliTabs'; This page showcases getting started with Tracetest by using the Tracetest CLI, Docker, or Kubernetes. -:::note -You need to add [OpenTelemetry instrumentation](https://opentelemetry.io/docs/instrumentation/) to your code and configure sending traces to a trace data store, or Tracetest directly, to benefit from Tracetest's trace-based testing. +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. + +:::note Prerequisites +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). +::: + +:::tip Don't have OpenTelemetry installed? +[Follow these instructions to install OpenTelemetry in 5 minutes without any code changes!](./no-otel.mdx) ::: ## Install the Tracetest CLI -## Install the Tracetest server +:::tip Want more info? +Read the CLI installation reference [here](./detailed-installation). +::: + +## Install the Tracetest Server + +Tracetest runs as a standalone container. It runs a Server and exposes a Web UI on port `11633`. + +You have two 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). + + + ```bash title="Terminal" tracetest server install @@ -36,14 +56,58 @@ tracetest server install Using Kubernetes`} -:::note -Follow the prompts and continue with all the default settings. -This will generate a `./tracetest/` directory that contains a `docker-compose.yaml` and two more config files. One for Tracetest and one for OpenTelemetry collector. +Choose to install Tracetest with the OpenTelemetry Collector and the [Pokeshop](../live-examples/pokeshop/overview.md) sample app. -To see the output of this command, view [this sample setup](https://github.com/kubeshop/tracetest/tree/main/examples/tracetest-jaeger) from our GitHub examples. -::: +```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`. +**Start Docker Compose from the directory where you ran `tracetest server install`.** {`docker compose -f tracetest/docker-compose.yaml up -d`} - -{`Starting tracetest ... -... -2022/11/28 18:24:09 HTTP Server started -...`} - + +This will start the Tracetest Server and expose the Web UI on [`http://localhost:11633`](http://localhost:11633). + +:::note +View deployment instructions for Docker [here](../deployment/docker). +::: + Using Kubernetes`} -:::note -Follow the prompts and continue with all the default settings. -This will deploy all resources to Kubernetes. -To see exactly what is deployed, view [the deployment instructions](../deployment/kubernetes) in the Deployment section of the docs. -::: +Choose to install Tracetest with the OpenTelemetry Collector and the [Pokeshop](../live-examples/pokeshop/overview.md) sample app. - -{`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}") +```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}") -echo "Visit http://127.0.0.1:8080 to use your application" kubectl --namespace demo port-forward $POD_NAME 8080:$CONTAINER_PORT -kubectl --kubeconfig /.kube/config --context --namespace tracetest port-forward svc/tracetest 11633`} - +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). + +:::note +View deployment instructions for Kubernetes [here](../deployment/kubernetes). +::: + -Open your browser on [`http://localhost:11633`](http://localhost:11633). + + -Create a [test](../web-ui/creating-tests.md). +First, be sure that you have [Helm](https://helm.sh/) installed in your machine. -Need more detailed information about how to install Tracetest? Read the detailed setup on the [CLI installation page](./detailed-installation). +The Tracetest Helm charts are located [here](https://github.com/kubeshop/helm-charts/tree/main/charts/tracetest). -:::note -View deployment instructions for Docker and Kubernetes in the [Deployment section](../deployment/overview). -::: +You can install them locally on your machine with the command: -:::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. +```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 +``` -You can reach services running on your local machine using: +**Access the Tracetest Server by port forwarding to the Tracetest `service`.** -- 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` +```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). + +:::note +View deployment instructions for Kubernetes [here](../deployment/kubernetes). ::: + + + diff --git a/docs/docs/getting-started/no-otel.mdx b/docs/docs/getting-started/no-otel.mdx new file mode 100644 index 0000000000..d16db7f08e --- /dev/null +++ b/docs/docs/getting-started/no-otel.mdx @@ -0,0 +1,184 @@ +--- +hide_table_of_contents: true +--- + +# What if I don't have OpenTelemetry installed? + + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +No worries! You can get started with no code changes at all! + +This page will explain getting started with OpenTelemetry: + +- Injecting auto instrumentation with **no code changes**. +- Auto instrumentation with limited code changes. +- Manual instrumentation with code changes. + +You can also find more ways to instrument OpenTelemetry in their [documentation](https://opentelemetry.io/docs/instrumentation/). + + + + +You can install the OpenTelemetry Operator in any existing Kubernetes environment in under 5 minutes by running the following set of commands. + +## 1. Install [`cert-manager`](https://cert-manager.io/) +#### This is required for the OpenTelemetry Operator to work. + +```bash +kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.11.0/cert-manager.yaml +``` + +## 2. Install the [OpenTelemetry Operator](https://opentelemetry.io/docs/k8s-operator/) +#### Traces will be generated and collected automatically. + +```bash +kubectl apply -f https://github.com/open-telemetry/opentelemetry-operator/releases/latest/download/opentelemetry-operator.yaml +``` + +## 3. Create a file named `otel-collector.yaml` for the OpenTelemetry config + +```yaml title="otel-collector.yaml" +apiVersion: opentelemetry.io/v1alpha1 +kind: Instrumentation +metadata: +name: otel-instrumentation +spec: +exporter: + endpoint: http://otel-collector:4317 +propagators: + - tracecontext + - baggage + - b3 + +--- +apiVersion: opentelemetry.io/v1alpha1 +kind: OpenTelemetryCollector +metadata: +name: otel +spec: +config: | + receivers: + otlp: + protocols: + grpc: + http: + processors: + batch: + timeout: 100ms + exporters: + otlp/tracetest: + endpoint: tracetest:4317 + tls: + insecure: true + service: + pipelines: + traces: + receivers: [otlp] + processors: [batch] + exporters: [otlp/tracetest] +``` + +You configure 2 separate things: + +#### 1. The Instrumentation, which is an init-container that will run on any pod you explictly mark (see step 5). + +#### 2. The OpenTelemetry collector, which will collect the traces from the init-container and send them to Tracetest, and/or your trace data store. + +What's amazing here is that you can add other exporters to this config file to [send the traces to other services as explained here](../configuration/overview.md). + +## 4. Apply the `otel-collector.yaml` config file + +```bash title="Terminal" +kubectl apply -f otel-collector.yaml +``` + +## 5. Update any service you want to instrument + +Use the [following annotations as seen in the OpenTelemetry docs](https://opentelemetry.io/docs/k8s-operator/automatic/): + +- **.NET**: `instrumentation.opentelemetry.io/inject-dotnet: "true"` +- **Java**: `instrumentation.opentelemetry.io/inject-java: "true"` +- **Node.js**: `instrumentation.opentelemetry.io/inject-nodejs: "true"` +- **Python**: `instrumentation.opentelemetry.io/inject-python: "true"` + +:::note +Add an environment variable named `SERVICE_NAME` to your service so that you can +later identify it in the tests. +::: + +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: +name: your-service +spec: +replicas: 1 +template: + annotations: + instrumentation.opentelemetry.io/inject-nodejs: 'true' +spec: + containers: + env: + - name: SERVICE_NAME + value: 'your-service' +``` + +This will automatically instrument your service with OpenTelemetry and send the traces to the OpenTelemetry collector. + +Apply the changes and you're ready! You can start writing integration and end-to-end tests with trace-based testing! + +:::note +Check the [official OpenTelemetry docs](https://opentelemetry.io/docs/k8s-operator/automatic/) explaining how to use the OpenTelemetry Operator. +::: + + + + + +#### [Odigos](https://docs.odigos.io/intro), is a new open source project that can do this for you without a single line of code. + + + + + +Below we provide quick links to all key docs and samples. + +| Language | Docs | GitHub | +|---|---|---| +| **C#/.NET** | https://opentelemetry.io/docs/instrumentation/net/automatic/ | https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation | +| **Java** | https://opentelemetry.io/docs/instrumentation/java/automatic/ | https://github.com/open-telemetry/opentelemetry-java-instrumentation | +| **JavaScript** | https://opentelemetry.io/docs/instrumentation/js/automatic/ | https://github.com/open-telemetry/opentelemetry-js | +| **PHP** | https://opentelemetry.io/docs/instrumentation/php/automatic/ | https://github.com/open-telemetry/opentelemetry-php-instrumentation | +| **Python** | https://opentelemetry.io/docs/instrumentation/python/automatic/ | https://github.com/open-telemetry/opentelemetry-python-contrib | +| **Ruby** | https://opentelemetry.io/docs/instrumentation/ruby/automatic/ | https://github.com/open-telemetry/opentelemetry-ruby | + + + + + +Below we provide quick links to all key docs. + +| Language | Docs | +|---|---| +| **C++** | https://opentelemetry.io/docs/instrumentation/cpp/ | +| **C#/.NET** | https://opentelemetry.io/docs/instrumentation/net/ | +| **Erlang/Elixir** | https://opentelemetry.io/docs/instrumentation/erlang/ | +| **Go** | https://opentelemetry.io/docs/instrumentation/go/ | +| **Java** | https://opentelemetry.io/docs/instrumentation/java/ | +| **JavaScript** | https://opentelemetry.io/docs/instrumentation/js/ | +| **PHP** | https://opentelemetry.io/docs/instrumentation/php/ | +| **Python** | https://opentelemetry.io/docs/instrumentation/python/ | +| **Ruby** | https://opentelemetry.io/docs/instrumentation/ruby/ | +| **Rust** | https://opentelemetry.io/docs/instrumentation/rust/ | +| **Swift** | https://opentelemetry.io/docs/instrumentation/swift/ | +| **Other** | https://opentelemetry.io/docs/instrumentation/other/ | + + + + + +:::tip We suggest you go back to and install Tracetest! +Jump back to the [installation guide](./installation.mdx) once you have OpenTelemetry installed. +::: \ No newline at end of file diff --git a/docs/docs/getting-started/open.md b/docs/docs/getting-started/open.md new file mode 100644 index 0000000000..0793c0f858 --- /dev/null +++ b/docs/docs/getting-started/open.md @@ -0,0 +1,140 @@ +# Opening Tracetest + +This page showcases opening the Tracetest Web UI regardless if you used the Tracetest CLI, Docker, Kubernetes, or Helm to install Tracetest Server. + +Once you've installed Tracetest, as explained in the [installation guide](./installation.mdx), you access the Tracetest Web UI on [`http://localhost:11633`](http://localhost:11633). 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) + +By following the [installation guide](./installation.mdx) your Tracetest instance will have a `demo` Pokeshop app installed that generates distributed traces when triggered. + +## 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/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. + +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` +::: + +### 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](http://localhost:3000/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/v1688476389/docs/screely-1688476384678_edcsgx.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/v1688564019/docs/screely-1688564011617_n5pizv.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: Yg9sN-94g + name: Pokeshop - Import + description: Import a Pokemon + trigger: + type: http + httpRequest: + url: http://demo-api:8081/pokemon/import + method: POST + headers: + - key: Content-Type + value: application/json + body: '{"id":52}' + specs: + - name: 'All Database Spans: Processing time is less than 100ms' + selector: span[tracetest.span.type="database"] + assertions: + - attr:tracetest.span.duration < 100ms +``` + +### Trigger + +Using the CLI, trigger a test run. + +```bash title="Terminal" +tracetest test run -d pokeshop_import.yaml --wait-for-result -o pretty +``` + +### Output + +The test run will complete and show a result. + +```text title="Output" +✔ Pokeshop - Import (http://localhost:11633/test/Yg9sN-94g/run/3/test) + ✔ All Database Spans: Processing time is less than 100ms +``` + +The provided link in the test output will open the test run in the Tracetest Web UI. diff --git a/docs/docs/index.md b/docs/docs/index.md index e4786d4952..b884028e56 100644 --- a/docs/docs/index.md +++ b/docs/docs/index.md @@ -1,35 +1,42 @@ # Tracetest Documentation - +Tracetest requires that you have [OpenTelemetry instrumentation](https://opentelemetry.io/docs/instrumentation/) added in your code. -Tracetest allows you to quickly build integration and end-to-end tests, powered by your OpenTelemetry traces. +:::tip Don't have OpenTelemetry installed? +[Follow these instructions to install OpenTelemetry in 5 minutes without any code changes!](./getting-started/no-otel.mdx) +::: ## In a Nutshell -Tracetest uses your existing [OpenTelemetry](https://opentelemetry.io/docs/getting-started/) traces to power trace-based testing with assertions against your trace data at every point of the request transaction. You only need to point Tracetest to your existing trace data source or send traces to Tracetest directly! +Tracetest uses existing [OpenTelemetry](https://opentelemetry.io/docs/getting-started/) traces to power trace-based testing with assertions against your trace data at every point of a request transaction. + +You only need to point Tracetest to your existing [trace data source](./configuration/connecting-to-data-stores/jaeger.md) or [send traces to Tracetest](./configuration/connecting-to-data-stores/opentelemetry-collector.md) directly! -We make it possible to: +With Tracetest you can: -- Define tests and assertions against every single microservice that a request goes through. -- Use your preferred trace back-end, like Jaeger or Tempo or OpenTelemetry Collector. +- Define tests and assertions against every single microservice that a trace goes through. +- Work with your existing distributed tracing solution, allowing you to build tests based on your already instrumented system. - Define multiple transaction triggers, such as a GET against an API endpoint, a GRPC request, etc. -- Return both the response data and a full trace. -- Define assertions against both the response and trace data, ensuring both your response and the underlying processes worked correctly, quickly and without errors. -- Save tests. -- Run the tests manually or via CI build jobs with the Tracetest CLI. +- Define assertions against both the response and trace data, ensuring both your response and the underlying processes worked correctly, quickly, and without errors. +- Save and run the tests manually or via CI build jobs New to trace-based testing? Read more about the concepts [here](./concepts/what-is-trace-based-testing). -## Prerequisites +## Architecture + +Here you can see how Tracetest interacts with a system under test. -You need to add [OpenTelemetry instrumentation](https://opentelemetry.io/docs/instrumentation/) to your code and configure sending traces to a trace data store, or Tracetest directly, to benefit from Tracetest's trace-based testing. +1. Trigger a test and generate a trace response. +2. Fetch traces to render and analyze them. +3. Add assertions to traces. +4. See test results. +5. Run tests as part of CI/CD pipelines. + +![Marketechture](https://res.cloudinary.com/djwdcmwdz/image/upload/v1686654113/docs/tracetest-marketechture-jun12-v3_ffj2e2.png) ## Who Uses Tracetest? @@ -45,5 +52,3 @@ Tracetest enables you to write detailed trace-based tests, primarily: Tracetest can be compared with Cypress or Selenium; however Tracetest is fundamentally different. Cypress and Selenium are constrained by using the browser for testing. Tracetest bypasses this entirely by using your existing OpenTelemetry instrumentation and trace data to run tests and assertions against traces in every step of a request transaction. - -Move on to the [Quick Start](./getting-started/installation) to hit the ground running! diff --git a/docs/docs/live-examples/pokeshop/overview.md b/docs/docs/live-examples/pokeshop/overview.md index f05b590b86..1bac3f278a 100644 --- a/docs/docs/live-examples/pokeshop/overview.md +++ b/docs/docs/live-examples/pokeshop/overview.md @@ -21,8 +21,9 @@ We have three use cases that use each component of this structure and that can b ## System Architecture -The system is divided into two components: -- an **API** that serves client requests, +The system is divided into two components: + +- 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 Jaeger and communicate with a Postgres database. diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index be6b08db7e..fe53a4992a 100644 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -200,26 +200,45 @@ const config = { respectPrefersColorScheme: false, }, navbar: { - title: 'Tracetest', + title: 'Tracetest Docs', logo: { alt: 'Tracetest Logo', src: 'img/logo.svg', + href: '/', + target: '_self', }, items: [ - // { - // to: "/quick-start", - // label: "Quick Start", - // position: "left", - // }, { - href: "https://discord.gg/6zupCZFQbe", - label: "Join Discord Community", + type: 'docSidebar', + position: 'left', + sidebarId: 'examplesTutorialsSidebar', + label: 'Examples & Tutorials' + }, + { + type: 'docSidebar', + position: 'left', + 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", position: "left", }, { type: "html", position: "left", - value: ``, + value: ``, }, { type: "search", diff --git a/docs/sidebars.js b/docs/sidebars.js index 58480956f4..9a6499f9b2 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -22,24 +22,231 @@ const sidebars = { // But you can create a sidebar manually - tutorialSidebar: [ + liveExamplesSidebar: [ + { + type: "category", + label: "Pokemon API Demo", + items: [ + { + type: "doc", + id: "live-examples/pokeshop/overview", + label: "Overview", + }, + { + type: "category", + label: "Use Cases", + items: [ + { + type: "doc", + id: "live-examples/pokeshop/use-cases/add-pokemon", + label: "Add Pokemon", + }, + { + type: "doc", + id: "live-examples/pokeshop/use-cases/list-pokemon", + label: "List Pokemon", + }, + { + type: "doc", + id: "live-examples/pokeshop/use-cases/get-pokemon-by-id", + label: "Get Pokemon by ID", + }, + { + type: "doc", + id: "live-examples/pokeshop/use-cases/import-pokemon", + label: "Import Pokemon", + }, + ], + }, + ], + }, + { + type: "category", + label: "OpenTelemetry Store Demo", + items: [ + { + type: "doc", + id: "live-examples/opentelemetry-store/overview", + label: "Overview", + }, + { + type: "category", + label: "Use Cases", + items: [ + { + type: "doc", + id: "live-examples/opentelemetry-store/use-cases/add-item-into-shopping-cart", + label: "Add Item into Shopping Cart", + }, + { + type: "doc", + id: "live-examples/opentelemetry-store/use-cases/check-shopping-cart-contents", + label: "Check Shopping Cart Contents", + }, + { + type: "doc", + id: "live-examples/opentelemetry-store/use-cases/checkout", + label: "Checkout", + }, + { + type: "doc", + id: "live-examples/opentelemetry-store/use-cases/get-recommended-products", + label: "Get Recommended Products", + }, + { + type: "doc", + id: "live-examples/opentelemetry-store/use-cases/user-purchasing-products", + label: "User Purchasing Products", + }, + ], + }, + ], + }, + ], + + examplesTutorialsSidebar: [ + { + type: "doc", + id: "examples-tutorials/overview", + label: "Overview", + }, + { + 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", + }, + { + 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 & 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-honeycomb", + label: "Node.js and Honeycomb", + }, + { + 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: "index", - label: "Introduction", + id: "examples-tutorials/recipes/running-tracetest-with-azure-app-insights-collector", + label: "Azure App Insights, The OpenTelemetry Collector & Pokeshop API", }, + ], + + tutorialSidebar: [ { type: "category", label: "Getting Started", - link: { - type: "doc", - id: "getting-started/installation", - }, + collapsed: false, items: [ + { + type: "doc", + id: "index", + label: "Introduction", + }, + { + type: "doc", + id: "getting-started/installation", + label: "Installing Tracetest", + }, + { + type: "doc", + id: "getting-started/open", + label: "Opening Tracetest", + }, + { + type: "doc", + id: "getting-started/no-otel", + label: "What if I don't have OpenTelemetry installed?", + }, + { + type: "doc", + id: "getting-started/cli-installation-reference", + label: "CLI Installation Reference", + }, { type: "doc", id: "getting-started/detailed-installation", - label: "Detailed Installation", + label: "Detailed Server Installation", }, ], }, @@ -451,199 +658,14 @@ const sidebars = { ], }, { - type: "category", + type: "link", label: "Examples & Tutorials", - link: { - type: "doc", - id: "examples-tutorials/overview", - }, - items: [ - { - 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", - }, - { - 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 & 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-honeycomb", - label: "Node.js and Honeycomb", - }, - { - 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-collector", - label: "Azure App Insights, The OpenTelemetry Collector & Pokeshop API", - }, - ], + href: "/examples-tutorials/overview", }, { - type: "category", + type: "link", label: "Live Examples", - items: [ - { - type: "category", - label: "Pokemon API Demo", - items: [ - { - type: "doc", - id: "live-examples/pokeshop/overview", - label: "Overview", - }, - { - type: "category", - label: "Use Cases", - items: [ - { - type: "doc", - id: "live-examples/pokeshop/use-cases/add-pokemon", - label: "Add Pokemon", - }, - { - type: "doc", - id: "live-examples/pokeshop/use-cases/list-pokemon", - label: "List Pokemon", - }, - { - type: "doc", - id: "live-examples/pokeshop/use-cases/get-pokemon-by-id", - label: "Get Pokemon by ID", - }, - { - type: "doc", - id: "live-examples/pokeshop/use-cases/import-pokemon", - label: "Import Pokemon", - }, - ], - }, - ], - }, - { - type: "category", - label: "OpenTelemetry Store Demo", - items: [ - { - type: "doc", - id: "live-examples/opentelemetry-store/overview", - label: "Overview", - }, - { - type: "category", - label: "Use Cases", - items: [ - { - type: "doc", - id: "live-examples/opentelemetry-store/use-cases/add-item-into-shopping-cart", - label: "Add Item into Shopping Cart", - }, - { - type: "doc", - id: "live-examples/opentelemetry-store/use-cases/check-shopping-cart-contents", - label: "Check Shopping Cart Contents", - }, - { - type: "doc", - id: "live-examples/opentelemetry-store/use-cases/checkout", - label: "Checkout", - }, - { - type: "doc", - id: "live-examples/opentelemetry-store/use-cases/get-recommended-products", - label: "Get Recommended Products", - }, - { - type: "doc", - id: "live-examples/opentelemetry-store/use-cases/user-purchasing-products", - label: "User Purchasing Products", - }, - ], - }, - ], - }, - ], + href: "/live-examples/pokeshop/overview", }, { type: "link",