From 415e75977d7749d3cf0bdb9e6c3d4c8e9d677f48 Mon Sep 17 00:00:00 2001 From: Adnan Rahic Date: Fri, 29 Sep 2023 15:20:45 +0200 Subject: [PATCH 01/12] docs(cloud): initial setup --- docs/docs/{ => core}/deployment/docker.md | 0 .../docs/{ => core}/deployment/kubernetes.mdx | 0 docs/docs/{ => core}/deployment/overview.md | 0 .../deployment/production-checklist.md | 0 .../core/getting-started/installation.mdx | 300 ++++++++++++++++++ docs/docs/core/getting-started/no-otel.mdx | 194 +++++++++++ .../open.md => core/getting-started/open.mdx} | 0 docs/docs/core/getting-started/overview.mdx | 21 ++ .../getting-started/detailed-installation.md | 270 ---------------- docs/docs/getting-started/installation.mdx | 285 ++--------------- docs/docs/getting-started/open.mdx | 140 ++++++++ docs/docs/getting-started/overview.mdx | 4 + docs/docusaurus.config.js | 20 +- 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 +- 18 files changed, 880 insertions(+), 617 deletions(-) rename docs/docs/{ => core}/deployment/docker.md (100%) rename docs/docs/{ => core}/deployment/kubernetes.mdx (100%) rename docs/docs/{ => core}/deployment/overview.md (100%) rename docs/docs/{ => core}/deployment/production-checklist.md (100%) create mode 100644 docs/docs/core/getting-started/installation.mdx create mode 100644 docs/docs/core/getting-started/no-otel.mdx rename docs/docs/{getting-started/open.md => core/getting-started/open.mdx} (100%) create mode 100644 docs/docs/core/getting-started/overview.mdx 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 diff --git a/docs/docs/deployment/docker.md b/docs/docs/core/deployment/docker.md similarity index 100% rename from docs/docs/deployment/docker.md rename to docs/docs/core/deployment/docker.md diff --git a/docs/docs/deployment/kubernetes.mdx b/docs/docs/core/deployment/kubernetes.mdx similarity index 100% rename from docs/docs/deployment/kubernetes.mdx rename to docs/docs/core/deployment/kubernetes.mdx diff --git a/docs/docs/deployment/overview.md b/docs/docs/core/deployment/overview.md similarity index 100% rename from docs/docs/deployment/overview.md rename to docs/docs/core/deployment/overview.md diff --git a/docs/docs/deployment/production-checklist.md b/docs/docs/core/deployment/production-checklist.md similarity index 100% rename from docs/docs/deployment/production-checklist.md rename to docs/docs/core/deployment/production-checklist.md diff --git a/docs/docs/core/getting-started/installation.mdx b/docs/docs/core/getting-started/installation.mdx new file mode 100644 index 0000000000..eacff4407b --- /dev/null +++ b/docs/docs/core/getting-started/installation.mdx @@ -0,0 +1,300 @@ +--- +id: installation +title: Installing Tracetest +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 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. + +## Install the Tracetest CLI + + + +:::tip Want more info? +Read the CLI installation reference [here](../cli/cli-installation-reference.md). +::: + +## Install the Tracetest Server + +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: + +- 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 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`.** + + +{`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 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). + + + + + + + +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, 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!](./no-otel.mdx) +::: diff --git a/docs/docs/core/getting-started/no-otel.mdx b/docs/docs/core/getting-started/no-otel.mdx new file mode 100644 index 0000000000..e34658d536 --- /dev/null +++ b/docs/docs/core/getting-started/no-otel.mdx @@ -0,0 +1,194 @@ +--- +id: no-otel +title: What if I don't have OpenTelemetry installed? +hide_table_of_contents: true +description: Tracetest allows you to quickly build integration and end-to-end tests, powered by your OpenTelemetry traces. Learn how to install OpenTelemetry in less than 5 minutes. +keywords: + - tracetest + - trace-based testing + - observability + - distributed tracing + - testing +image: https://res.cloudinary.com/djwdcmwdz/image/upload/v1689693872/docs/Blog_Thumbnail_28_ugy2yy.png +--- + +# 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: + var: + - 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/core/getting-started/open.mdx similarity index 100% rename from docs/docs/getting-started/open.md rename to docs/docs/core/getting-started/open.mdx diff --git a/docs/docs/core/getting-started/overview.mdx b/docs/docs/core/getting-started/overview.mdx new file mode 100644 index 0000000000..8773eb0cc2 --- /dev/null +++ b/docs/docs/core/getting-started/overview.mdx @@ -0,0 +1,21 @@ +--- +id: overview +title: Getting Started with ๐Ÿชจ Tracetest Core +description: Tracetest allows you to quickly 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 a Docker image and designed to run in a containerized environment. + +```mdx-code-block +import {CoreGettingStartedGuideCardsRow} from '@site/src/components/CoreGettingStartedGuide'; + + +``` 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..0db876b3d2 100644 --- a/docs/docs/getting-started/installation.mdx +++ b/docs/docs/getting-started/installation.mdx @@ -16,285 +16,70 @@ 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 Server +## Install the Tracetest Agent -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: - -- 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). +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. -```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. + +tracetest start + -```mermaid -flowchart TD - A[(Redis)] - B[(Postgres)] - C(Node.js API) - D(RabbitMQ) - E(Worker) - F(OpenTelemetry Collector) - G(Tracetest) +The agent will start and open a browser to prompt a signin to Tracetest Cloud. - G --> C - F --> G - C --> A - C --> B - C --> D - D --> E - E --> B - C --> F - E --> F - - -``` -
+![](https://res.cloudinary.com/djwdcmwdz/image/upload/v1695990166/docs/screely-1695990151905_eb8yiw.png) -**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. + +gRPC: `http://localhost:4317` + +HTTP: `http://localhost:4318/v1/traces` - + - {`How do you want to run TraceTest? [type to search]: - Using Docker Compose -> Using Kubernetes`} + TBD - -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). - - - - - - -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, 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). - + + + TBD + :::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..de8473ea11 --- /dev/null +++ b/docs/docs/getting-started/open.mdx @@ -0,0 +1,140 @@ +--- +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), you access the Tracetest Web UI on [`cloud.tracetest.io`](https://cloud.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) + +## 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) + +### 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 run test -f pokeshop_import.yaml -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/getting-started/overview.mdx b/docs/docs/getting-started/overview.mdx index 147c7cf723..92f76b8c5e 100644 --- a/docs/docs/getting-started/overview.mdx +++ b/docs/docs/getting-started/overview.mdx @@ -14,6 +14,10 @@ image: https://res.cloudinary.com/djwdcmwdz/image/upload/v1689693872/docs/Blog_T Tracetest is a cloud-native application, packaged and distributed a Docker image and designed to run in a containerized environment. +We recommend using [Tracetest Cloud](https://cloud.tracetest.io/), our managed platform for Tracetest, because it's the easiest way to build and test with OpenTelemetry. Tracetest Cloud 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/docusaurus.config.js b/docs/docusaurus.config.js index 3eea79f109..04ade11761 100644 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -256,6 +256,12 @@ const config = { sidebarId: 'tutorialSidebar', label: 'Docs' }, + { + type: 'docSidebar', + position: 'left', + sidebarId: 'coreSidebar', + label: 'Core' + }, { type: 'docSidebar', position: 'left', @@ -268,16 +274,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 +281,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..3c60245b6b 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -351,6 +351,54 @@ const sidebars = { }, ], + coreSidebar: [ + { + type: "category", + label: "Getting Started", + link: { + type: "doc", + id: "core/getting-started/overview" + }, + items: [ + { + type: "doc", + id: "core/getting-started/installation", + label: "Installing Tracetest", + }, + { + type: "doc", + id: "core/getting-started/open", + label: "Opening Tracetest", + }, + { + type: "doc", + id: "core/getting-started/no-otel", + label: "What if I don't have OpenTelemetry installed?", + }, + ], + }, + { + 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..360720cb46 --- /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', + url: './installation', + description: ( + + Set up Tracetest and start trace-based testing your distributed system. + + ), + button: 'Set up Tracetest', + }, + { + name: '๐Ÿ™Œ Open Tracetest', + url: './open', + description: ( + + After installing it, open Tracetest start to creating trace-based tests. + + ), + 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', + }, +]; + +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..2cec1c6b8f 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 Cloud', 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 Tractest Core in your 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; +} From a1fecee05f79934e4d1135417774811b894fa4a0 Mon Sep 17 00:00:00 2001 From: Adnan Rahic Date: Tue, 3 Oct 2023 00:47:03 +0200 Subject: [PATCH 02/12] docs(cloud): overhauled cloud vs core onboarding --- docs/docs/configuration/server.md | 20 +- docs/docs/core/deployment/docker.md | 2 +- docs/docs/core/deployment/kubernetes.mdx | 2 +- docs/docs/core/deployment/overview.md | 4 +- .../core/deployment/production-checklist.md | 0 .../core/getting-started/installation.mdx | 32 +-- docs/docs/core/getting-started/no-otel.mdx | 194 ------------------ docs/docs/core/getting-started/open.mdx | 10 +- docs/docs/core/getting-started/overview.mdx | 10 +- docs/docs/getting-started/installation.mdx | 2 +- docs/docs/getting-started/open.mdx | 121 +++++++++-- docs/docs/getting-started/overview.mdx | 6 +- docs/docusaurus.config.js | 16 +- docs/sidebars.js | 14 +- .../CoreGettingStartedGuide/index.tsx | 2 +- .../components/GettingStartedGuide/index.tsx | 6 +- 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 + 22 files changed, 359 insertions(+), 263 deletions(-) delete mode 100644 docs/docs/core/deployment/production-checklist.md delete mode 100644 docs/docs/core/getting-started/no-otel.mdx 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/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/core/deployment/docker.md b/docs/docs/core/deployment/docker.md index 6773f5533c..87c2514be8 100644 --- a/docs/docs/core/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, read more in the [configuration docs](/configuration/overview.md). diff --git a/docs/docs/core/deployment/kubernetes.mdx b/docs/docs/core/deployment/kubernetes.mdx index 3a3370995c..cc57a2fae7 100644 --- a/docs/docs/core/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, read more in the [configuration docs](/configuration/overview.md). diff --git a/docs/docs/core/deployment/overview.md b/docs/docs/core/deployment/overview.md index e38fef4199..30899d701f 100644 --- a/docs/docs/core/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/deployment/production-checklist.md b/docs/docs/core/deployment/production-checklist.md deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/docs/docs/core/getting-started/installation.mdx b/docs/docs/core/getting-started/installation.mdx index eacff4407b..8203bc5d55 100644 --- a/docs/docs/core/getting-started/installation.mdx +++ b/docs/docs/core/getting-started/installation.mdx @@ -1,6 +1,6 @@ --- id: installation -title: Installing Tracetest +title: Installing Tracetest Core description: Tracetest allows you to quickly build integration and end-to-end tests, powered by your OpenTelemetry traces. keywords: - tracetest @@ -16,21 +16,21 @@ 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 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. It shows how to configure OpenTelemetry and Tracetest and the architecture of the Pokeshop sample app. +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). +Read the CLI installation reference [here](/cli/cli-installation-reference.md). ::: ## Install the Tracetest Server -Tracetest runs as a standalone container. It runs a Server and exposes a Web UI on port `11633`. +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: @@ -51,12 +51,12 @@ tracetest server install language="text" title="Terminal" > - {`How do you want to run TraceTest? [type to search]: + {`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. +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]: @@ -66,8 +66,8 @@ Do you have OpenTelemetry based tracing already set up, or would you like us to 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!** +- 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!**
@@ -129,7 +129,7 @@ This will start the Tracetest Server and expose the Web UI on [`http://localhost > Using Kubernetes`} -Choose to install Tracetest with the OpenTelemetry Collector and the [Pokeshop](../live-examples/pokeshop/overview.md) sample app. +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]: @@ -137,10 +137,10 @@ Do you have OpenTelemetry based tracing already set up, or would you like us to > 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. +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 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!** +- 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!**
@@ -239,7 +239,7 @@ First, be sure that you have [Docker](https://docker.com/) installed in your mac 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, the OpenTelemetry Collector, and a sample app called [Pokeshop](../live-examples/pokeshop/overview.md). This allows you to create sample tests right away!** +**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!**
@@ -294,7 +294,7 @@ This will start the Tracetest Server and expose the Web UI on [`http://localhost :::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). +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) +[Follow these instructions to install OpenTelemetry in 5 minutes without any code changes!](/getting-started/no-otel.mdx) ::: diff --git a/docs/docs/core/getting-started/no-otel.mdx b/docs/docs/core/getting-started/no-otel.mdx deleted file mode 100644 index e34658d536..0000000000 --- a/docs/docs/core/getting-started/no-otel.mdx +++ /dev/null @@ -1,194 +0,0 @@ ---- -id: no-otel -title: What if I don't have OpenTelemetry installed? -hide_table_of_contents: true -description: Tracetest allows you to quickly build integration and end-to-end tests, powered by your OpenTelemetry traces. Learn how to install OpenTelemetry in less than 5 minutes. -keywords: - - tracetest - - trace-based testing - - observability - - distributed tracing - - testing -image: https://res.cloudinary.com/djwdcmwdz/image/upload/v1689693872/docs/Blog_Thumbnail_28_ugy2yy.png ---- - -# 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: - var: - - 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/core/getting-started/open.mdx b/docs/docs/core/getting-started/open.mdx index 222123bec1..ddfec33c63 100644 --- a/docs/docs/core/getting-started/open.mdx +++ 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 index 8773eb0cc2..571caf4ed6 100644 --- a/docs/docs/core/getting-started/overview.mdx +++ b/docs/docs/core/getting-started/overview.mdx @@ -1,7 +1,7 @@ --- id: overview -title: Getting Started with ๐Ÿชจ Tracetest Core -description: Tracetest allows you to quickly build integration and end-to-end tests, powered by your OpenTelemetry traces. +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 @@ -12,7 +12,11 @@ keywords: 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 a Docker image and designed to run in a containerized environment. +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://cloud.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/getting-started/installation.mdx b/docs/docs/getting-started/installation.mdx index 0db876b3d2..3af1b231f7 100644 --- a/docs/docs/getting-started/installation.mdx +++ b/docs/docs/getting-started/installation.mdx @@ -36,7 +36,7 @@ Tracetest Agent runs as a standalone process. It runs either locally on your mac tracetest start -The agent will start and open a browser to prompt a signin to Tracetest Cloud. +The Agent will start and open a browser to prompt signing in to Tracetest. ![](https://res.cloudinary.com/djwdcmwdz/image/upload/v1695990166/docs/screely-1695990151905_eb8yiw.png) diff --git a/docs/docs/getting-started/open.mdx b/docs/docs/getting-started/open.mdx index de8473ea11..2a77205d8c 100644 --- a/docs/docs/getting-started/open.mdx +++ b/docs/docs/getting-started/open.mdx @@ -13,10 +13,94 @@ image: https://res.cloudinary.com/djwdcmwdz/image/upload/v1689693872/docs/Blog_T 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), you access the Tracetest Web UI on [`cloud.tracetest.io`](https://cloud.tracetest.io). Here's what will greet you after a fresh install. +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: @@ -44,7 +128,7 @@ Select an **HTTP Request** as the **test trigger**, and choose the **Pokeshop - 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) +![API test against POST endpoint](https://res.cloudinary.com/djwdcmwdz/image/upload/v1696253160/docs/screely-1696253153066_khjz8y.png) ### Trigger @@ -56,12 +140,12 @@ 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. -![test result](https://res.cloudinary.com/djwdcmwdz/image/upload/v1688476389/docs/screely-1688476384678_edcsgx.png) +![test result](https://res.cloudinary.com/djwdcmwdz/image/upload/v1696253230/docs/screely-1696253224366_f62411.png) ### Trace @@ -81,7 +165,7 @@ In the sample below, you see how to assert that all database spans return in les 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) +![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. @@ -98,26 +182,30 @@ You can either download the YAML file test definition, or write one from scratch Using the sample from above, create the Trace-based Test programatically. -```yaml title="pokeshop_import.yaml" +```yaml title="pokeshop-import.yaml" type: Test spec: - id: Yg9sN-94g - name: Pokeshop - Import - description: Import a Pokemon + id: T7-delWIR + name: Pokemon Import trigger: type: http httpRequest: - url: http://demo-api:8081/pokemon/import method: POST + url: http://localhost:8081/pokemon/import + body: "{\"id\":52}" 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"] + - 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:tracetest.span.duration < 100ms + - attr:http.status_code = 200 ``` ### Trigger @@ -125,7 +213,7 @@ spec: Using the CLI, trigger a test run. ```bash title="Terminal" -tracetest run test -f pokeshop_import.yaml -o pretty +tracetest run test -f pokemon-import.yaml --required-gates test-specs --output pretty ``` ### Output @@ -133,8 +221,9 @@ tracetest run test -f pokeshop_import.yaml -o pretty The test run will complete and show a result. ```text title="Output" -โœ” Pokeshop - Import (http://localhost:11633/test/Yg9sN-94g/run/3/test) +โœ” 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 92f76b8c5e..401350188b 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,9 +12,9 @@ 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 [Tracetest Cloud](https://cloud.tracetest.io/), our managed platform for Tracetest, because it's the easiest way to build and test with OpenTelemetry. Tracetest Cloud includes features such as collaboration for teams and comes with a free tier for development. +We recommend using our managed platform for [Tracetest](https://cloud.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. diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index 04ade11761..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')) { diff --git a/docs/sidebars.js b/docs/sidebars.js index 3c60245b6b..bdc458e3b1 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -352,6 +352,11 @@ const sidebars = { ], coreSidebar: [ + { + type: "link", + label: "Welcome! ๐Ÿ‘‹", + href: "/", + }, { type: "category", label: "Getting Started", @@ -363,17 +368,12 @@ const sidebars = { { type: "doc", id: "core/getting-started/installation", - label: "Installing Tracetest", + label: "Installing Tracetest Core", }, { type: "doc", id: "core/getting-started/open", - label: "Opening Tracetest", - }, - { - type: "doc", - id: "core/getting-started/no-otel", - label: "What if I don't have OpenTelemetry installed?", + label: "Opening Tracetest Core", }, ], }, diff --git a/docs/src/components/CoreGettingStartedGuide/index.tsx b/docs/src/components/CoreGettingStartedGuide/index.tsx index 360720cb46..67c08c6913 100644 --- a/docs/src/components/CoreGettingStartedGuide/index.tsx +++ b/docs/src/components/CoreGettingStartedGuide/index.tsx @@ -29,7 +29,7 @@ const CoreGettingStartedGuides = [ }, { name: '๐Ÿค” Don\'t have OpenTelemetry?', - url: './no-otel', + url: '/getting-started/no-otel', description: ( Install OpenTelemetry in 5 minutes without any code changes! diff --git a/docs/src/components/GettingStartedGuide/index.tsx b/docs/src/components/GettingStartedGuide/index.tsx index 2cec1c6b8f..ebd092cdee 100644 --- a/docs/src/components/GettingStartedGuide/index.tsx +++ b/docs/src/components/GettingStartedGuide/index.tsx @@ -8,7 +8,7 @@ import Heading from '@theme/Heading'; const GettingStartedGuides = [ { - name: '๐ŸŒฅ๏ธ Tracetest Cloud', + name: 'Tracetest ๐Ÿš€', url: './installation', description: ( @@ -18,11 +18,11 @@ const GettingStartedGuides = [ button: 'Start', }, { - name: '๐Ÿชจ Tracetest Core', + name: 'Tracetest Core ๐Ÿชจ ', url: '../core/getting-started/installation', description: ( - Use the open-source Tractest Core in your infrastructure. + Use the open-source Tracetest Core in your own infrastructure. ), button: 'Go to Core', 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 From b121d5df8b25bed4a1ee69a7e4223d16538ed745 Mon Sep 17 00:00:00 2001 From: Adnan Rahic Date: Tue, 3 Oct 2023 09:11:41 +0200 Subject: [PATCH 03/12] docs(commercial): updated docker and k8s install --- docs/docs/getting-started/installation.mdx | 108 ++++++++++++++++++--- 1 file changed, 95 insertions(+), 13 deletions(-) diff --git a/docs/docs/getting-started/installation.mdx b/docs/docs/getting-started/installation.mdx index 3af1b231f7..fb969287a2 100644 --- a/docs/docs/getting-started/installation.mdx +++ b/docs/docs/getting-started/installation.mdx @@ -36,7 +36,7 @@ Tracetest Agent runs as a standalone process. It runs either locally on your mac tracetest start -The Agent will start and open a browser to prompt signing in to Tracetest. +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) @@ -63,20 +63,102 @@ HTTP: `http://localhost:4318/v1/traces` - - TBD - + + +{`docker run \\\n-p 4317:4317 \\\n-p 4318:4318 \\\n-e TRACETEST_API_KEY="" \\\nkubeshop/tracetest-agent`} + + +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) + +Once signed in, return to the terminal. + + +{`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. + +gRPC: `http://:4317` + +HTTP: `http://:4318/v1/traces` + +:::note +Running a test against `localhost` will resolve as `127.0.0.1` inside the Tracetest Agent container. + +To run tests against apps running on your local machine you have two options: + +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.* + +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` +::: + - - TBD - + + +{`curl https://raw.githubusercontent.com/kubeshop/tracetest/main/k8s/agent/deploy-agent.sh | bash -s -- default `} + + +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) + +Once signed in, return to the terminal. + + +{`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 Kubernetes and ready to accept traces. + +gRPC: `http://:4317` + +HTTP: `http://:4318/v1/traces` + +:::note +Running a test against `localhost` will resolve as `127.0.0.1` inside the Tracetest Agent container. + +To run tests against apps running on your local machine you have two options: + +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.* + +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` +::: + From b58e87ae4cb324e58c346abf2d5eacfb50d9dbd6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Adnan=20Rahi=C4=87?= Date: Tue, 3 Oct 2023 16:41:45 +0200 Subject: [PATCH 04/12] Update docs/docs/core/deployment/docker.md Co-authored-by: Julianne Fermi --- docs/docs/core/deployment/docker.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/core/deployment/docker.md b/docs/docs/core/deployment/docker.md index 87c2514be8..87f38029db 100644 --- a/docs/docs/core/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). From b6762a23509c103eef2fec67ab5319e763138428 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Adnan=20Rahi=C4=87?= Date: Tue, 3 Oct 2023 16:41:53 +0200 Subject: [PATCH 05/12] Update docs/docs/getting-started/open.mdx Co-authored-by: Julianne Fermi --- docs/docs/getting-started/open.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/getting-started/open.mdx b/docs/docs/getting-started/open.mdx index 2a77205d8c..cd68d5afc4 100644 --- a/docs/docs/getting-started/open.mdx +++ b/docs/docs/getting-started/open.mdx @@ -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) -## Start the sample Pokeshop API +## Start the Sample Pokeshop API To create tests quickly, start the official sample called Pokeshop API. From 8c87aaea4fd64a98997a4c1bf1aa55d37c8066cf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Adnan=20Rahi=C4=87?= Date: Tue, 3 Oct 2023 16:42:00 +0200 Subject: [PATCH 06/12] Update docs/docs/core/deployment/kubernetes.mdx Co-authored-by: Julianne Fermi --- docs/docs/core/deployment/kubernetes.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/core/deployment/kubernetes.mdx b/docs/docs/core/deployment/kubernetes.mdx index cc57a2fae7..943bd94c01 100644 --- a/docs/docs/core/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). From 398f6a8be4f2b120d23514cb49c2d6271a26bf13 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Adnan=20Rahi=C4=87?= Date: Tue, 3 Oct 2023 16:42:08 +0200 Subject: [PATCH 07/12] Update docs/docs/getting-started/open.mdx Co-authored-by: Julianne Fermi --- docs/docs/getting-started/open.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/getting-started/open.mdx b/docs/docs/getting-started/open.mdx index cd68d5afc4..9969050f66 100644 --- a/docs/docs/getting-started/open.mdx +++ b/docs/docs/getting-started/open.mdx @@ -134,7 +134,7 @@ This will populate a sample API test against a POST endpoint in the Pokeshop app 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 +- Test trigger and results. - The entire distributed trace and trace analysis - Test specification and assertions - How to automate the test From 5e16918959427b1d80b8b2a42c208e51ad642466 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Adnan=20Rahi=C4=87?= Date: Tue, 3 Oct 2023 16:42:14 +0200 Subject: [PATCH 08/12] Update docs/docs/getting-started/open.mdx Co-authored-by: Julianne Fermi --- docs/docs/getting-started/open.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/getting-started/open.mdx b/docs/docs/getting-started/open.mdx index 9969050f66..097ac2b3b3 100644 --- a/docs/docs/getting-started/open.mdx +++ b/docs/docs/getting-started/open.mdx @@ -135,7 +135,7 @@ This will populate a sample API test against a POST endpoint in the Pokeshop app 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 +- The entire distributed trace and trace analysis. - Test specification and assertions - How to automate the test From b3faa084ecc3234cbb3d65432fbbaa9c613e05b6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Adnan=20Rahi=C4=87?= Date: Tue, 3 Oct 2023 16:42:21 +0200 Subject: [PATCH 09/12] Update docs/docs/getting-started/open.mdx Co-authored-by: Julianne Fermi --- docs/docs/getting-started/open.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/getting-started/open.mdx b/docs/docs/getting-started/open.mdx index 097ac2b3b3..6f82e14866 100644 --- a/docs/docs/getting-started/open.mdx +++ b/docs/docs/getting-started/open.mdx @@ -136,7 +136,7 @@ You'll be redirected to the test page where you can see four tabs and depending - Test trigger and results. - The entire distributed trace and trace analysis. -- Test specification and assertions +- Test specification and assertions. - How to automate the test :::note From 03c085bb0734993a12353976c71529de303f131c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Adnan=20Rahi=C4=87?= Date: Tue, 3 Oct 2023 16:42:28 +0200 Subject: [PATCH 10/12] Update docs/docs/getting-started/open.mdx Co-authored-by: Julianne Fermi --- docs/docs/getting-started/open.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/getting-started/open.mdx b/docs/docs/getting-started/open.mdx index 6f82e14866..c049cb76a0 100644 --- a/docs/docs/getting-started/open.mdx +++ b/docs/docs/getting-started/open.mdx @@ -137,7 +137,7 @@ You'll be redirected to the test page where you can see four tabs and depending - Test trigger and results. - The entire distributed trace and trace analysis. - Test specification and assertions. -- How to automate the test +- How to automate the test. :::note To view the in-depth guide on test results, [check out this docs page](/web-ui/test-results) From 3d254c9231535eebf8f1c02bde60759fd07e25a6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Adnan=20Rahi=C4=87?= Date: Tue, 3 Oct 2023 16:42:39 +0200 Subject: [PATCH 11/12] Update docs/docs/getting-started/open.mdx Co-authored-by: Julianne Fermi --- docs/docs/getting-started/open.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/getting-started/open.mdx b/docs/docs/getting-started/open.mdx index c049cb76a0..bef79599d8 100644 --- a/docs/docs/getting-started/open.mdx +++ b/docs/docs/getting-started/open.mdx @@ -140,7 +140,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](/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. From 952fbcbfe966d8f8d4a37d8332074d1c9e1f7363 Mon Sep 17 00:00:00 2001 From: Adnan Rahic Date: Wed, 4 Oct 2023 13:24:30 +0200 Subject: [PATCH 12/12] docs(cloud): typos and fixes --- README.md | 2 +- docs/docs/core/getting-started/overview.mdx | 2 +- docs/docs/getting-started/overview.mdx | 2 +- docs/docs/index.mdx | 26 ++++++++++++------- .../CoreGettingStartedGuide/index.tsx | 12 ++++----- 5 files changed, 25 insertions(+), 19 deletions(-) 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/core/getting-started/overview.mdx b/docs/docs/core/getting-started/overview.mdx index 571caf4ed6..dc95f619f0 100644 --- a/docs/docs/core/getting-started/overview.mdx +++ b/docs/docs/core/getting-started/overview.mdx @@ -14,7 +14,7 @@ image: https://res.cloudinary.com/djwdcmwdz/image/upload/v1689693872/docs/Blog_T 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://cloud.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. +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. diff --git a/docs/docs/getting-started/overview.mdx b/docs/docs/getting-started/overview.mdx index 401350188b..bb7bf551e5 100644 --- a/docs/docs/getting-started/overview.mdx +++ b/docs/docs/getting-started/overview.mdx @@ -14,7 +14,7 @@ image: https://res.cloudinary.com/djwdcmwdz/image/upload/v1689693872/docs/Blog_T 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://cloud.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. +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. 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/src/components/CoreGettingStartedGuide/index.tsx b/docs/src/components/CoreGettingStartedGuide/index.tsx index 67c08c6913..567c708861 100644 --- a/docs/src/components/CoreGettingStartedGuide/index.tsx +++ b/docs/src/components/CoreGettingStartedGuide/index.tsx @@ -8,21 +8,21 @@ import Heading from '@theme/Heading'; const CoreGettingStartedGuides = [ { - name: '๐Ÿ‘‡ Install Tracetest', + name: '๐Ÿ‘‡ Install Tracetest Core', url: './installation', description: ( - Set up Tracetest and start trace-based testing your distributed system. + Set up Tracetest Core and start trace-based testing your distributed system. ), - button: 'Set up Tracetest', + button: 'Set up', }, { - name: '๐Ÿ™Œ Open Tracetest', + name: '๐Ÿ™Œ Open Tracetest Core', url: './open', description: ( - After installing it, open Tracetest start to creating trace-based tests. + After installing it, open Tracetest Core start to creating trace-based tests. ), button: 'Create tests', @@ -35,7 +35,7 @@ const CoreGettingStartedGuides = [ Install OpenTelemetry in 5 minutes without any code changes! ), - button: 'Set up OTel', + button: 'Set up OpenTelemetry', }, { name: '๐Ÿคฉ Open Source',