docs(recipes): clean up updated recipes (#3978)

* docs(concepts): update tbt page * docs(recipes): cleanup * docs(examples): remove redundant signoz example * Update docs/docs/concepts/what-is-trace-based-testing.mdx Co-authored-by: Julianne Fermi <[email protected]> --------- Co-authored-by: Julianne Fermi <[email protected]>
kubeshop · Aug 21, 2024 · 678bb8c · 678bb8c
1 parent 7a16cd8
commit 678bb8c
Show file tree

Hide file tree

Showing 45 changed files with 320 additions and 2,741 deletions.
diff --git a/docs/docs/concepts/what-is-trace-based-testing.mdx b/docs/docs/concepts/what-is-trace-based-testing.mdx
@@ -13,6 +13,24 @@ image: https://res.cloudinary.com/djwdcmwdz/image/upload/v1698686403/docs/Blog_T
 
 **Trace-based testing** is a means of conducting deep integration or system tests by utilizing the rich data contained in a distributed system trace.
 
+## Why Trace-based Testing?
+
+In traditional testing, the focus is primarily on verifying that inputs and outputs match an expected result. While this approach is useful, it often overlooks critical issues such as race conditions, performance bottlenecks, failing interactions between services, broken 3rd party services, an many other issues.
+
+Trace-based testing validates entire application flows and transactions. It ensures that each step in the process is executed as intended as well as the final result. This is particularly important in microservices architectures, where complex interdependencies can make it difficult to detect and diagnose issues.
+
+| Traditional Testing                                                    | Trace-based Testing                                                                  |
+|------------------------------------------------------------------------|--------------------------------------------------------------------------------------|
+| Validates outputs                                                      | Validates entire transactions                                                        |
+| Limited to input/output validation                                     | Detailed insight into each step in the transaction                                   |
+| Can miss race conditions, bottlenecks, service-to-service interactions | Identifies race conditions, bottlenecks, etc.                                        |
+| Only suited for testing isolated components and functions              | Ideal for testing full transactions in complex distributed systems and microservices |
+
+| Manual correlation of issues across components                         | Contextually links issues in a transaction                                           |
+| Cannot find issues caused by service dependencies                      | Finds and validates issues between services                                          |
+| Cannot find performance bottlenecks unless specifically tested         | Validates trace span duration and performance                                        |
+
+
 ## What is a Distributed Trace?
 
 A Distributed Trace, more commonly known as a Trace, records the paths taken by requests (made by an application or end-user) take as they propagate through multi-service architectures, like microservice and serverless applications. [Source - OpenTelemetry.io](https://opentelemetry.io/docs/concepts/observability-primer/)

diff --git a/...rials/recipes/running-python-app-with-opentelemetry-collector-and-tracetest.mdx b/...rials/recipes/running-python-app-with-opentelemetry-collector-and-tracetest.mdx
@@ -2,7 +2,7 @@
 id: running-python-app-with-opentelemetry-collector-and-tracetest
 title: Python with OpenTelemetry manual instrumention
 description: Quick start how to configure a Python app to use OpenTelemetry instrumentation with traces, and Tracetest for enhancing your e2e and integration tests with trace-based testing.
-hide_table_of_contents: true
+hide_table_of_contents: false
 keywords:
   - tracetest
   - trace-based testing
@@ -124,14 +124,6 @@ trace.set_tracer_provider(provider)
 tracer = trace.get_tracer(__name__)
 ```
 
-## Running the Python App
-
-To start the full setup, run the following command:
-
-```bash
-docker compose up -d
-```
-
 There are 3 endpoints in the Flask app. To see manual instrumentation, trigger the `"/manual"` endpoint. To see the automatic instrumentation, trigger the `"/automatic"` endpoint respectively.
 
 ```python
@@ -154,7 +146,7 @@ def home():
     return "App works."
 ```
 
-## Run Tracetest Tests
+## Running the Python App and Tracetest
 
 To execute the tests, run this command:
 
@@ -163,12 +155,24 @@ docker compose run tracetest-run
 ```
 
 This will:
-1. Start the Node.js app, the OpenTelemetry Collector, and send the traces to the Tracetest Agent.
+1. Start the Python app, the OpenTelemetry Collector, and send the traces to the Tracetest Agent.
 2. Start the Tracetest Agent.
 3. Configure the tracing backend and create tests in your environment.
 4. Run the tests.
 
-Here's a sample of a failed test run, which happens if you use this selector and assertion pair.
+The output of the test will look similar to this:
+
+```bash
+Configuring Tracetest
+ SUCCESS  Successfully configured Tracetest CLI
+Running Trace-Based Tests...
+✔ RunGroup: #E1qhw_jIg (https://app.tracetest.io/organizations/xxx/environments/xxx/run/E1qhw_jIg)
+ Summary: 1 passed, 0 failed, 0 pending
+  ✔ Python API (https://app.tracetest.io/organizations/xxx/environments/xxx/test/W656Q0c4g/run/2/test) - trace id: c0eaebfe3ab66360a98d5cd443760a3c
+	✔ It should return status 200.
+```
+
+Here's what that looks like in the WebUI.
 
 Selector:
 

diff --git a/docs/docs/examples-tutorials/recipes/running-tracetest-with-aws-x-ray-adot.mdx b/docs/docs/examples-tutorials/recipes/running-tracetest-with-aws-x-ray-adot.mdx
@@ -2,7 +2,7 @@
 id: running-tracetest-with-aws-x-ray-adot
 title: Node.js with AWS X-Ray (Node.js SDK) and AWS Distro for OpenTelemetry
 description: Quick start on how to configure a Node.js app with OpenTelemetry traces, AWS X-Ray as a trace data store, including AWS Distro for OpenTelemetry, and Tracetest for enhancing your E2E and integration tests with trace-based testing.
-hide_table_of_contents: true
+hide_table_of_contents: false
 keywords:
   - tracetest
   - trace-based testing
@@ -101,9 +101,7 @@ The [`docker-compose.yaml` file](https://github.com/kubeshop/tracetest/blob/main
 
 The [`docker-compose.yaml` file](https://github.com/kubeshop/tracetest/blob/main/examples/tracetest-amazon-x-ray-adot/docker-compose.yaml) also contains the Tracetest Agent and ADOT.
 
-### Run Tracetest Tests
-
-To execute the tests, run this command:
+To run everything including Tracetest tests, run this command:
 
 ```bash
 docker compose run tracetest-run

diff --git a/docs/docs/examples-tutorials/recipes/running-tracetest-with-aws-x-ray-pokeshop.mdx b/docs/docs/examples-tutorials/recipes/running-tracetest-with-aws-x-ray-pokeshop.mdx
@@ -2,7 +2,7 @@
 id: running-tracetest-with-aws-x-ray-pokeshop
 title: Pokeshop API with AWS X-Ray (Node.js SDK) and AWS Distro for OpenTelemetry
 description: Quick start on how to configure the Pokeshop API Demo with OpenTelemetry traces, AWS X-Ray as a trace data store, and Tracetest for enhancing your E2E and integration tests with trace-based testing.
-hide_table_of_contents: true
+hide_table_of_contents: false
 keywords:
   - tracetest
   - trace-based testing
@@ -105,9 +105,7 @@ The [`docker-compose.yaml` file](https://github.com/kubeshop/tracetest/blob/main
 
 The [`docker-compose.yaml` file](https://github.com/kubeshop/tracetest/blob/main/examples/tracetest-amazon-x-ray-pokeshop/docker-compose.yaml) also contains the Tracetest Agent and ADOT.
 
-### Run Tracetest Tests
-
-To execute the tests, run this command:
+To run everything including Tracetest tests, run this command:
 
 ```bash
 docker compose run tracetest-run

diff --git a/docs/docs/examples-tutorials/recipes/running-tracetest-with-aws-x-ray.mdx b/docs/docs/examples-tutorials/recipes/running-tracetest-with-aws-x-ray.mdx
@@ -2,7 +2,7 @@
 id: running-tracetest-with-aws-x-ray
 title: Node.js and AWS X-Ray (Node.js SDK)
 description: Quick start on how to configure a Node.js app with OpenTelemetry traces, AWS X-Ray as a trace data store, and Tracetest for enhancing your E2E and integration tests with trace-based testing.
-hide_table_of_contents: true
+hide_table_of_contents: false
 keywords:
   - tracetest
   - trace-based testing
@@ -97,9 +97,7 @@ The [`docker-compose.yaml` file](https://github.com/kubeshop/tracetest/blob/main
 
 The [`docker-compose.yaml` file](https://github.com/kubeshop/tracetest/blob/main/examples/tracetest-amazon-x-ray/docker-compose.yaml) also contains the Tracetest Agent and X-Ray Daemon.
 
-### Run Tracetest Tests
-
-To execute the tests, run this command:
+To run everything including Tracetest tests, run this command:
 
 ```bash
 docker compose run tracetest-run

diff --git a/...mples-tutorials/recipes/running-tracetest-with-azure-app-insights-collector.mdx b/...mples-tutorials/recipes/running-tracetest-with-azure-app-insights-collector.mdx
@@ -2,7 +2,7 @@
 id: running-tracetest-with-azure-app-insights-collector
 title: Node.js and Azure Application Insights with OpenTelemetry Collector
 description: Quick start on how to configure a Node.js app with OpenTelemetry traces, Azure Application Insights as a trace data store, including the OpenTelemetry Collector, and Tracetest for enhancing your E2E and integration tests with trace-based testing.
-hide_table_of_contents: true
+hide_table_of_contents: false
 keywords:
   - tracetest
   - trace-based testing
@@ -81,7 +81,7 @@ The `docker-compose.yaml` file in the root directory of the quick start runs the
 
 ## Configuring the Node.js App
 
-The Node.js app is a simple Express app, contained in [the `app.js` file](https://github.com/kubeshop/tracetest/blob/main/examples/tracetest-azure-app-insights/src/app.js).
+The Node.js app is a simple Express app, contained in [the `app.js` file](https://github.com/kubeshop/tracetest/blob/main/examples/tracetest-azure-app-insights-collector/src/app.js).
 
 Configure the `.env` like shown below.
 
@@ -124,6 +124,20 @@ APP_INSIGHTS_INSTRUMENTATION_STRING="InstrumentationKey=14f0532a-aad4-4cb1-9bdb-
 
 ## Running the Tests
 
+The [`docker-compose.yaml` file](https://github.com/kubeshop/tracetest/blob/main/examples/tracetest-azure-app-insights-collector/docker-compose.yaml) in the root directory contains the Node.js app, OpenTelemetry Collector and Tracetest Agent.
+
+To run everything including Tracetest tests, run this command:
+
+```bash
+docker compose run tracetest-run
+```
+
+This will:
+1. Start the Node.js app and send the traces to Azure App Insights.
+2. Start the Tracetest Agent.
+3. Configure the Azure App Insights tracing backend and create tests in your environment.
+4. Run the tests.
+
 ### The Test File
 
 Check out the `resources/test.yaml` file.
@@ -150,19 +164,6 @@ spec:
         - attr:tracetest.span.duration  <  500ms
 ```
 
-To run the test, run this command in the terminal:
-
-```bash
-docker compose run tracetest-run
-```
-
-This will:
-
-1. Start the Node.js app, the OpenTelemetry Collector and send the traces to both Azure App Insights and the Tracetest Agent.
-2. Start the Tracetest Agent.
-3. Configure the tracing backend and create tests in your environment.
-4. Run the tests.
-
 ## Learn More
 
 Please visit our [examples in GitHub](https://github.com/kubeshop/tracetest/tree/main/examples) and join our [Slack Community](https://dub.sh/tracetest-community) for more info!