diff --git a/docs/docs/index.md b/docs/docs/index.md index f62cb2eff0..e4786d4952 100644 --- a/docs/docs/index.md +++ b/docs/docs/index.md @@ -13,19 +13,19 @@ Tracetest allows you to quickly build integration and end-to-end tests, powered ## In a Nutshell -Tracetest uses your existing [OpenTelemetry](https://opentelemetry.io/docs/getting-started/) traces to power trace-based testing with assertions against your trace data at every point of the request transaction. You only need to point Tracetest to your existing trace data source, or send traces to Tracetest directly! +Tracetest uses your existing [OpenTelemetry](https://opentelemetry.io/docs/getting-started/) traces to power trace-based testing with assertions against your trace data at every point of the request transaction. You only need to point Tracetest to your existing trace data source or send traces to Tracetest directly! We make it possible to: - Define tests and assertions against every single microservice that a request goes through. -- Use your preferred trace back-end, like Jaeger or Tempo, or OpenTelemetry Collector. +- Use your preferred trace back-end, like Jaeger or Tempo or OpenTelemetry Collector. - Define multiple transaction triggers, such as a GET against an API endpoint, a GRPC request, etc. - Return both the response data and a full trace. -- Define assertions against both the response and trace data, ensuring both your response and the underlying processes worked correctly, quickly, and without errors. +- Define assertions against both the response and trace data, ensuring both your response and the underlying processes worked correctly, quickly and without errors. - Save tests. - Run the tests manually or via CI build jobs with the Tracetest CLI. -New to trace-based testing? Read more about the concepts, [here](./concepts/what-is-trace-based-testing). +New to trace-based testing? Read more about the concepts [here](./concepts/what-is-trace-based-testing). ## Prerequisites @@ -33,7 +33,7 @@ You need to add [OpenTelemetry instrumentation](https://opentelemetry.io/docs/in ## Who Uses Tracetest? -Our users are typically developers or QA engineers building distributed systems with microservices using back-end languages like Go, Rust, Node.js, and Python. +Our users are typically developers or QA engineers building distributed systems with microservices using back-end languages like Go, Rust, Node.js and Python. Tracetest enables you to write detailed trace-based tests, primarily: diff --git a/docs/docs/live-examples/opentelemetry-store/overview.md b/docs/docs/live-examples/opentelemetry-store/overview.md index 7eb1c8c36d..3101ce8c36 100644 --- a/docs/docs/live-examples/opentelemetry-store/overview.md +++ b/docs/docs/live-examples/opentelemetry-store/overview.md @@ -3,8 +3,8 @@ This system implements an Astronomy shop in a set of microservices in different languages with OpenTelemetry enabled, intended to be used as an example of OpenTelemetry instrumentation and observability. - **Source Code**: https://github.com/open-telemetry/opentelemetry-demo -- **Running it Locally**: [instructions](https://github.com/open-telemetry/opentelemetry-demo/blob/main/docs/docker_deployment.md#run-docker-compose) -- **Running on Kubernetes**: [instructions](https://github.com/open-telemetry/opentelemetry-demo/blob/main/docs/kubernetes_deployment.md) +- **Running it Locally**: [Instructions](https://github.com/open-telemetry/opentelemetry-demo/blob/main/docs/docker_deployment.md#run-docker-compose) +- **Running on Kubernetes**: [Instructions](https://github.com/open-telemetry/opentelemetry-demo/blob/main/docs/kubernetes_deployment.md) ## Running with Tracetest @@ -13,7 +13,7 @@ To run the this demo locally with Tracetest, first clone OpenTelemetry demo repo git clone https://github.com/open-telemetry/opentelemetry-demo.git ``` -And then, run on that folder: +And then, run in that folder: ```sh docker compose up --no-build ``` @@ -26,14 +26,14 @@ After that, Tracetest will start on [http://localhost:11633](http://localhost:11 ## Use Cases -- [Add item into shopping cart](./use-cases/add-item-into-shopping-cart.md): Simulate a user choosing an item and adding it to the shopping cart -- [Check shopping cart content](./use-cases/check-shopping-cart-contents.md): Simulate a user choosing different products and checking the shopping cart later -- [Checkout](./use-cases/checkout.md): Simulates a user choosing a product and later doing a checkout of that product, with billing and shipping info -- [Get recommended products](./use-cases/get-recommended-products.md): Simulates a user querying for recommended products +- [Add item into shopping cart](./use-cases/add-item-into-shopping-cart.md): Simulate a user choosing an item and adding it to the shopping cart. +- [Check shopping cart content](./use-cases/check-shopping-cart-contents.md): Simulate a user choosing different products and checking the shopping cart later. +- [Checkout](./use-cases/checkout.md): Simulates a user choosing a product and later doing a checkout of that product, with billing and shipping info. +- [Get recommended products](./use-cases/get-recommended-products.md): Simulates a user querying for recommended products. ## System Architecture This demonstration environment consists of a series of microservices, handling each aspect of the store, such as Product Catalog, Payment, Currency, etc. -A detailed description of these services can be seen [here](https://github.com/open-telemetry/opentelemetry-demo/tree/main/docs#service-documentation) -and the architecture diagrams can be seen [here](https://github.com/open-telemetry/opentelemetry-demo/blob/main/docs/current_architecture.md). +A detailed description of these services can be seen [here](https://opentelemetry.io/docs/demo/services/) +and the architecture diagrams can be seen [here](https://opentelemetry.io/docs/demo/architecture/). diff --git a/docs/docs/live-examples/opentelemetry-store/use-cases/add-item-into-shopping-cart.md b/docs/docs/live-examples/opentelemetry-store/use-cases/add-item-into-shopping-cart.md index 663f7645ab..c4c8572d87 100644 --- a/docs/docs/live-examples/opentelemetry-store/use-cases/add-item-into-shopping-cart.md +++ b/docs/docs/live-examples/opentelemetry-store/use-cases/add-item-into-shopping-cart.md @@ -41,7 +41,7 @@ Using Tracetest, we can [create a test](../../../web-ui/creating-tests.md) that ### Traces -Running these tests for the first time will create an Observability trace like the image below, where you can see spans for the API calls (HTTP and gRPC), and database calls: +Running these tests for the first time will create an Observability trace like the image below, where you can see spans for the API calls (HTTP and gRPC) and database calls: ![](../images/add-item-into-shopping-cart-trace.png) ### Assertions diff --git a/docs/docs/live-examples/opentelemetry-store/use-cases/checkout.md b/docs/docs/live-examples/opentelemetry-store/use-cases/checkout.md index 93cca145b0..a6a2124a6e 100644 --- a/docs/docs/live-examples/opentelemetry-store/use-cases/checkout.md +++ b/docs/docs/live-examples/opentelemetry-store/use-cases/checkout.md @@ -65,7 +65,7 @@ Using Tracetest, we can [create a test](../../../web-ui/creating-tests.md) that ### Traces -Running these tests for the first time will create an Observability trace like the image below, where you can see spans for the API calls (HTTP and gRPC), and database calls: +Running these tests for the first time will create an Observability trace like the image below, where you can see spans for the API calls (HTTP and gRPC) and database calls: ![](../images/checkout-trace.png) ### Assertions diff --git a/docs/docs/live-examples/opentelemetry-store/use-cases/get-recommended-products.md b/docs/docs/live-examples/opentelemetry-store/use-cases/get-recommended-products.md index 8eafed1b65..b7245ed0cb 100644 --- a/docs/docs/live-examples/opentelemetry-store/use-cases/get-recommended-products.md +++ b/docs/docs/live-examples/opentelemetry-store/use-cases/get-recommended-products.md @@ -38,7 +38,7 @@ Using Tracetest, we can [create a test](../../../web-ui/creating-tests.md) that ### Traces -Running these tests for the first time will create an Observability trace like the image below, where you can see spans for the API calls (HTTP and gRPC), and database calls: +Running these tests for the first time will create an Observability trace like the image below, where you can see spans for the API calls (HTTP and gRPC) and database calls: ![](../images/get-recommended-products-trace.png) ### Assertions diff --git a/docs/docs/live-examples/opentelemetry-store/use-cases/user-purchasing-products.md b/docs/docs/live-examples/opentelemetry-store/use-cases/user-purchasing-products.md index a52c5216ed..ea043153b7 100644 --- a/docs/docs/live-examples/opentelemetry-store/use-cases/user-purchasing-products.md +++ b/docs/docs/live-examples/opentelemetry-store/use-cases/user-purchasing-products.md @@ -24,7 +24,7 @@ We can do that by creating the tests and transactions through the Web UI or usin ### Mapping Environment Variables -The first thing that we need to think about is to map the variables are needed in this process. At first glance, we can identify the vars to the API address and the user ID: +The first thing that we need to think about is to map the variables that are needed in this process. At first glance, we can identify the vars to the API address and the user ID: With these variables, we can create the following definition file as saving as `user-buying-products.env`: ```sh @@ -90,7 +90,7 @@ spec: - attr:tracetest.selected_spans.count >= 1 ``` -After that, we will [Check Shopping Cart Contents](./check-shopping-cart-contents.md) (on `check-shopping-cart-contents.yaml`), simulating a user validating its products before finishing its purchase: +After that, we will [Check Shopping Cart Contents](./check-shopping-cart-contents.md) (on `check-shopping-cart-contents.yaml`), simulating a user validating the products selected before finishing the purchase: ```yaml type: Test diff --git a/docs/docs/live-examples/pokeshop/overview.md b/docs/docs/live-examples/pokeshop/overview.md index 4665836c0f..f05b590b86 100644 --- a/docs/docs/live-examples/pokeshop/overview.md +++ b/docs/docs/live-examples/pokeshop/overview.md @@ -2,13 +2,13 @@ As a testing ground, the team at Tracetest has implemented a sample instrumented API around the [PokeAPI](https://pokeapi.co/). -The idea is to have a microservice-divided system that behaves like a typical scenario by having async processes ([RabbitMQ](https://www.rabbitmq.com/)), cache layers ([Redis](https://redis.io/)), database storage ([Postgres](https://www.postgresql.org/)), and simple CRUD interfaces for Pokemons. +The idea is to have a microservice-divided system that behaves like a typical scenario by having async processes ([RabbitMQ](https://www.rabbitmq.com/)), cache layers ([Redis](https://redis.io/)), database storage ([Postgres](https://www.postgresql.org/)) and simple CRUD interfaces for Pokemons. -With this, users can get familiar with the Tracetest tool by focusing on creating assertions, visualizing the trace, and identifying the different data that comes from the Collector ([Jaeger](https://www.jaegertracing.io/)). Users will learn about basic instrumentation practices like what tools to use, what data to send, when, and what suggested standards need to be followed. +With this, users can get familiar with the Tracetest tool by focusing on creating assertions, visualizing the trace and identifying the different data that comes from the Collector ([Jaeger](https://www.jaegertracing.io/)). Users will learn about basic instrumentation practices: what tools to use, what data to send, when, and what suggested standards need to be followed. - **Source Code**: https://github.com/kubeshop/pokeshop -- **Running it locally**: [instructions](https://github.com/kubeshop/pokeshop/blob/master/docs/installing.md#run-it-locally) -- **Running on Kubernetes**: [instructions](https://github.com/kubeshop/pokeshop/blob/master/docs/installing.md#run-on-a-kubernetes-cluster) +- **Running it locally**: [Instructions](https://github.com/kubeshop/pokeshop/blob/master/docs/installing.md#run-it-locally) +- **Running on Kubernetes**: [Instructions](https://github.com/kubeshop/pokeshop/blob/master/docs/installing.md#run-on-a-kubernetes-cluster) ## Use Cases diff --git a/docs/docs/live-examples/pokeshop/use-cases/add-pokemon.md b/docs/docs/live-examples/pokeshop/use-cases/add-pokemon.md index 85aae3e7df..e88bc130d2 100644 --- a/docs/docs/live-examples/pokeshop/use-cases/add-pokemon.md +++ b/docs/docs/live-examples/pokeshop/use-cases/add-pokemon.md @@ -49,7 +49,7 @@ Using Tracetest, we can [create a test](../../../web-ui/creating-tests.md) that ### Traces -Running these tests for the first time will create an Observability trace like the image above, where you can see spans for the API call, validation (an API internal operation), and database calls: +Running these tests for the first time will create an Observability trace like the image above, where you can see spans for the API call, validation (an API internal operation) and database calls: ![](../images/add-pokemon-trace.png) ### Assertions @@ -66,7 +66,7 @@ Now you can validate this entire use case. ### Test Definition -If you want to replicate this entire test on Tracetest see by yourself, you can replicate these steps on our Web UI or using our CLI, saving the following test definition as the file `test-definition.yml` and later running: +If you want to replicate this entire test on Tracetest, you can replicate these steps on our Web UI or using our CLI, saving the following test definition as the file `test-definition.yml` and later running: ```sh tracetest test run -d test-definition.yml --wait-for-results diff --git a/docs/docs/live-examples/pokeshop/use-cases/get-pokemon-by-id.md b/docs/docs/live-examples/pokeshop/use-cases/get-pokemon-by-id.md index 3e5c89379f..b3dbcf9110 100644 --- a/docs/docs/live-examples/pokeshop/use-cases/get-pokemon-by-id.md +++ b/docs/docs/live-examples/pokeshop/use-cases/get-pokemon-by-id.md @@ -1,6 +1,6 @@ # Pokeshop API - Get Pokemon by ID -This use case retrieves a specific Pokemon from the cache if it is cached, or from the database (Postgres) also populating the cache. The idea of this query is to showcase a straightforward scenario, where the API layer receives a request from the outside and needs to evaluate a different behavior depending of its dependencies. +This use case retrieves a specific Pokemon from the cache if it is cached or from the database (Postgres) also populating the cache. The idea of this query is to showcase a straightforward scenario, where the API layer receives a request from the outside and needs to evaluate a different behavior depending of its dependencies. ```mermaid sequenceDiagram diff --git a/docs/docs/live-examples/pokeshop/use-cases/import-pokemon.md b/docs/docs/live-examples/pokeshop/use-cases/import-pokemon.md index 858abc44ba..07397ae23c 100644 --- a/docs/docs/live-examples/pokeshop/use-cases/import-pokemon.md +++ b/docs/docs/live-examples/pokeshop/use-cases/import-pokemon.md @@ -1,6 +1,6 @@ # Pokeshop API - Import Pokemon -This use case showcases a more complex scenario involving an async process. Usually, when working with microservices, there are use cases where some of the processing needs to happen asynchronously, for example, when triggering a user notification, generating reports, or processing a payment order. With this endpoint, we provide an example of how users can implement trace-based testing for such scenarios. +This use case showcases a more complex scenario involving an async process. Usually, when working with microservices, there are use cases where some of the processing needs to happen asynchronously, for example, when triggering a user notification, generating reports or processing a payment order. With this endpoint, we provide an example of how users can implement trace-based testing for such scenarios. Here the process is split into two phases: 1. An API call that enqueues an import request to a queue. @@ -69,7 +69,7 @@ Using Tracetest, we can [create a test](../../../web-ui/creating-tests.md) that ### Traces -Running these tests for the first time will create an Observability trace like the image above, where you can see spans for the API call, the queue messaging, the PokeAPI (external API) call, and database calls. One interesting thing about this trace is that **you can observe the entire use case, end to end**: +Running these tests for the first time will create an Observability trace like the image below, where you can see spans for the API call, the queue messaging, the PokeAPI (external API) call and database calls. One interesting thing about this trace is that **you can observe the entire use case, end to end**: ![](../images/import-pokemon-trace.png) diff --git a/docs/docs/live-examples/pokeshop/use-cases/list-pokemon.md b/docs/docs/live-examples/pokeshop/use-cases/list-pokemon.md index 2f0bf59c90..cdf49cc1ee 100644 --- a/docs/docs/live-examples/pokeshop/use-cases/list-pokemon.md +++ b/docs/docs/live-examples/pokeshop/use-cases/list-pokemon.md @@ -46,7 +46,7 @@ Using Tracetest, we can [create a test](../../../web-ui/creating-tests.md) that ### Traces -Running these tests for the first time will create an Observability trace like the image above, where you can see spans for the API call and database calls: +Running these tests for the first time will create an Observability trace like the image below, where you can see spans for the API call and database calls: ![](../images/list-pokemons-trace.png) ### Assertions diff --git a/docs/sidebars.js b/docs/sidebars.js index a67362bb39..70e00c90f8 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -452,7 +452,7 @@ const sidebars = { { type: "doc", id: "examples-tutorials/recipes/running-tracetest-with-testkube", - label: "Tracetest and Testkube - Running scheduled trace-based tests", + label: "Tracetest and Testkube - Running Scheduled Trace-based Tests", }, ], }, @@ -513,12 +513,12 @@ const sidebars = { { type: "doc", id: "live-examples/opentelemetry-store/use-cases/add-item-into-shopping-cart", - label: "Add item into shopping cart", + label: "Add Item into Shopping Cart", }, { type: "doc", id: "live-examples/opentelemetry-store/use-cases/check-shopping-cart-contents", - label: "Check shopping cart contents", + label: "Check Shopping Cart Contents", }, { type: "doc", @@ -528,12 +528,12 @@ const sidebars = { { type: "doc", id: "live-examples/opentelemetry-store/use-cases/get-recommended-products", - label: "Get recommended products", + label: "Get Recommended Products", }, { type: "doc", id: "live-examples/opentelemetry-store/use-cases/user-purchasing-products", - label: "User purchasing products", + label: "User Purchasing Products", }, ], }, @@ -543,7 +543,7 @@ const sidebars = { }, { type: "link", - label: "Tracetest Open API definition", + label: "Tracetest Open API Definition", href: "/openapi", }, ],