docs(migrate to mdx): Update live examples section (#3333)

docs(migrate to mdx): live examples section
kubeshop · Nov 6, 2023 · 7144a92 · 7144a92
1 parent 72a9e3d
commit 7144a92
Show file tree

Hide file tree

Showing 13 changed files with 188 additions and 42 deletions.
diff --git a/...-examples/opentelemetry-store/overview.md → ...examples/opentelemetry-store/overview.mdx b/...-examples/opentelemetry-store/overview.md → ...examples/opentelemetry-store/overview.mdx
@@ -1,4 +1,16 @@
-# OpenTelemetry Astronomy Shop Demo
+---
+id: overview
+title: OpenTelemetry Astronomy Shop Demo
+description: The OpenTelemetry Demo is an example application published by the OpenTelemtry CNCF project. The Tracetest team has made several key contributions to this project, including providing a full suite of end to end tests.
+hide_table_of_contents: false
+keywords:
+  - tracetest
+  - trace-based testing
+  - observability
+  - distributed tracing
+  - testing
+image: https://res.cloudinary.com/djwdcmwdz/image/upload/v1698686403/docs/Blog_Thumbnail_14_rsvkmo.jpg
+---
 
 The OpenTelemetry Demo is an example application published by the OpenTelemtry CNCF project. It 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. The Tracetest team has made several key contributions to this project, including providing a full suite of end to end tests.
 
@@ -106,10 +118,10 @@ Tracetest will be started on [http://localhost:11633](http://localhost:11633) as
 
 ## 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](/live-examples/opentelemetry-store/use-cases/add-item-into-shopping-cart): Simulate a user choosing an item and adding it to the shopping cart.
+- [Check shopping cart content](/live-examples/opentelemetry-store/use-cases/check-shopping-cart-contents): Simulate a user choosing different products and checking the shopping cart later. 
+- [Checkout](/live-examples/opentelemetry-store/use-cases/checkout): Simulates a user choosing a product and later doing a checkout of that product, with billing and shipping info.
+- [Get recommended products](/live-examples/opentelemetry-store/use-cases/get-recommended-products): Simulates a user querying for recommended products.
 
 ## System Architecture
 

diff --git a/.../use-cases/add-item-into-shopping-cart.md → ...use-cases/add-item-into-shopping-cart.mdx b/.../use-cases/add-item-into-shopping-cart.md → ...use-cases/add-item-into-shopping-cart.mdx
@@ -1,4 +1,16 @@
-# OpenTelemetry Store - Add item into the shopping cart
+---
+id: add-item-into-shopping-cart
+title: OpenTelemetry Store - Add item into the shopping cart
+description: The OpenTelemetry Demo is an example application published by the OpenTelemtry CNCF project. This use case covers adding a product from the catalog into a shopping cart.
+hide_table_of_contents: false
+keywords:
+  - tracetest
+  - trace-based testing
+  - observability
+  - distributed tracing
+  - testing
+image: https://res.cloudinary.com/djwdcmwdz/image/upload/v1698686403/docs/Blog_Thumbnail_14_rsvkmo.jpg
+---
 
 In this use case, we want to validate the following story:
 

diff --git a/...use-cases/check-shopping-cart-contents.md → ...se-cases/check-shopping-cart-contents.mdx b/...use-cases/check-shopping-cart-contents.md → ...se-cases/check-shopping-cart-contents.mdx
@@ -1,4 +1,16 @@
-# OpenTelemetry Store - Check shopping cart contents
+---
+id: check-shopping-cart-contents
+title: OpenTelemetry Store - Check shopping cart contents
+description: The OpenTelemetry Demo is an example application published by the OpenTelemtry CNCF project. This use case covers seeing all the products in the shopping cart.
+hide_table_of_contents: false
+keywords:
+  - tracetest
+  - trace-based testing
+  - observability
+  - distributed tracing
+  - testing
+image: https://res.cloudinary.com/djwdcmwdz/image/upload/v1698686403/docs/Blog_Thumbnail_14_rsvkmo.jpg
+---
 
 In this use case, we want to validate the following story:
 
@@ -36,7 +48,7 @@ You can trigger this use case by calling the endpoint `GET /api/cart?sessionId={
 }
 ```
 
-If it is the first time that you are calling this endpoint, to see an item into the shopping cart you need first to [Add item into shopping cart](./add-item-into-shopping-cart.md).
+If it is the first time that you are calling this endpoint, to see an item into the shopping cart you need first to [Add item into shopping cart](/live-examples/opentelemetry-store/use-cases/add-item-into-shopping-cart).
 
 ## Building a Test for This Scenario
 

diff --git a/...opentelemetry-store/use-cases/checkout.md → ...pentelemetry-store/use-cases/checkout.mdx b/...opentelemetry-store/use-cases/checkout.md → ...pentelemetry-store/use-cases/checkout.mdx
@@ -1,4 +1,16 @@
-# OpenTelemetry Store - Checkout
+---
+id: checkout
+title: OpenTelemetry Store - Checkout
+description: The OpenTelemetry Demo is an example application published by the OpenTelemtry CNCF project. This use case covers paying for products in a shopping cart.
+hide_table_of_contents: false
+keywords:
+  - tracetest
+  - trace-based testing
+  - observability
+  - distributed tracing
+  - testing
+image: https://res.cloudinary.com/djwdcmwdz/image/upload/v1698686403/docs/Blog_Thumbnail_14_rsvkmo.jpg
+---
 
 In this use case, we want to validate the following story:
 
@@ -53,7 +65,7 @@ It should return a payload similar to this:
 }
 ```
 
-If it is the first time that you are calling this endpoint, to see an item into the shopping cart you need first to [Add item into shopping cart](./add-item-into-shopping-cart.md).
+If it is the first time that you are calling this endpoint, to see an item into the shopping cart you need first to [Add item into shopping cart](/live-examples/opentelemetry-store/use-cases/add-item-into-shopping-cart).
 
 ## Building a Test for This Scenario
 

diff --git a/...ore/use-cases/get-recommended-products.md → ...re/use-cases/get-recommended-products.mdx b/...ore/use-cases/get-recommended-products.md → ...re/use-cases/get-recommended-products.mdx
@@ -1,4 +1,16 @@
-# OpenTelemetry Store - Get recommended products
+---
+id: get-recommended-products
+title: OpenTelemetry Store - Get recommended products
+description: The OpenTelemetry Demo is an example application published by the OpenTelemtry CNCF project. This use case covers viewing recommended products before adding them to the shopping cart.
+hide_table_of_contents: false
+keywords:
+  - tracetest
+  - trace-based testing
+  - observability
+  - distributed tracing
+  - testing
+image: https://res.cloudinary.com/djwdcmwdz/image/upload/v1698686403/docs/Blog_Thumbnail_14_rsvkmo.jpg
+---
 
 In this use case, we want to validate the following story:
 

diff --git a/...ore/use-cases/user-purchasing-products.md → ...re/use-cases/user-purchasing-products.mdx b/...ore/use-cases/user-purchasing-products.md → ...re/use-cases/user-purchasing-products.mdx
@@ -1,4 +1,16 @@
-# OpenTelemetry Store - User Purchasing Products
+---
+id: user-purchasing-products
+title: OpenTelemetry Store - User Purchasing Products
+description: The OpenTelemetry Demo is an example application published by the OpenTelemtry CNCF project. This use case covers viewing recommended products before adding them to the shopping cart.
+hide_table_of_contents: false
+keywords:
+  - tracetest
+  - trace-based testing
+  - observability
+  - distributed tracing
+  - testing
+image: https://res.cloudinary.com/djwdcmwdz/image/upload/v1698686403/docs/Blog_Thumbnail_14_rsvkmo.jpg
+---
 
 In this use case, we want to validate the following story:
 
@@ -9,10 +21,10 @@ So I can have it shipped to my home
 ```
 
 Something interesting about this process is that it is a composition of many of the previous use cases, executed in sequence:
-1. [Get Recommended Products](./get-recommended-products.md)
-2. [Add Item into Shopping Cart](./add-item-into-shopping-cart.md)
-3. [Check Shopping Cart Contents](./check-shopping-cart-contents.md)
-4. [Checkout](./checkout.md)
+1. [Get Recommended Products](/live-examples/opentelemetry-store/use-cases/get-recommended-products)
+2. [Add Item into Shopping Cart](/live-examples/opentelemetry-store/use-cases/add-item-into-shopping-cart)
+3. [Check Shopping Cart Contents](/live-examples/opentelemetry-store/use-cases/check-shopping-cart-contents)
+4. [Checkout](/live-examples/opentelemetry-store/use-cases/checkout)
 
 So in this case, we need to trigger four tests in sequence to achieve test the entire scenario and make these tests share data.
 
@@ -34,7 +46,7 @@ USER_ID=2491f868-88f1-4345-8836-d5d8511a9f83
 
 ### Creating Tests
 
-After creating the environment file, we will create a test for each step, starting with [Get Recommended Products](./get-recommended-products.md), which will be saved as `get-recommended-products.yaml`:
+After creating the environment file, we will create a test for each step, starting with [Get Recommended Products](/live-examples/opentelemetry-store/use-cases/get-recommended-products), which will be saved as `get-recommended-products.yaml`:
 
 ```yaml
 type: Test
@@ -63,7 +75,7 @@ spec:
 
 Note that we have one important changes here: we are now using environment variables on the definition, like `${var:OTEL_API_URL}` and `${var:USER_ID}` on the trigger section and an output to fetch the first `${var:PRODUCT_ID}` that the user chose. This new environment variable will be used in the next tests.
 
-The next step is to define the [Add Item into Shopping Cart](./add-item-into-shopping-cart.md) test, which will be saved as `add-product-into-shopping-cart.yaml`:
+The next step is to define the [Add Item into Shopping Cart](/live-examples/opentelemetry-store/use-cases/add-item-into-shopping-cart) test, which will be saved as `add-product-into-shopping-cart.yaml`:
 
 ```yaml
 type: Test
@@ -90,7 +102,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 the products selected before finishing the purchase:
+After that, we will [Check Shopping Cart Contents](/live-examples/opentelemetry-store/use-cases/check-shopping-cart-contents) (on `check-shopping-cart-contents.yaml`), simulating a user validating the products selected before finishing the purchase:
 
 ```yaml
 type: Test
@@ -115,7 +127,7 @@ spec:
     - attr:tracetest.response.body | json_path '$.items.length' >= 1
 ```
 
-And finally, we have the [Checkout](./checkout.md) action (`checkout.yaml`), where the user inputs the billing and shipping info and finishes buying the item in the shopping cart:
+And finally, we have the [Checkout](/live-examples/opentelemetry-store/use-cases/checkout) action (`checkout.yaml`), where the user inputs the billing and shipping info and finishes buying the item in the shopping cart:
 
 ```yaml
 type: Test

diff --git a/docs/docs/live-examples/pokeshop/overview.md → .../docs/live-examples/pokeshop/overview.mdx b/docs/docs/live-examples/pokeshop/overview.md → .../docs/live-examples/pokeshop/overview.mdx
@@ -1,4 +1,16 @@
-# Pokeshop API
+---
+id: overview
+title: Pokeshop API Demo
+description: As a testing ground, the Tracetest team has implemented a sample API instrumented with OpenTelemetry around the PokeAPI. The reason is to provide a microservice-based system that contains message queues, cache layers, databases, and CRUD operations.
+hide_table_of_contents: false
+keywords:
+  - tracetest
+  - trace-based testing
+  - observability
+  - distributed tracing
+  - testing
+image: https://res.cloudinary.com/djwdcmwdz/image/upload/v1698686403/docs/Blog_Thumbnail_14_rsvkmo.jpg
+---
 
 As a testing ground, the team at Tracetest has implemented a sample instrumented API around the [PokeAPI](https://pokeapi.co/).
 
@@ -20,11 +32,11 @@ Want to run tests against the Pokeshop Demo without installing it locally? Click
 
 We have three use cases that use each component of this structure and that can be observed via Open Telemetry and tested with Tracetest. Each one is triggered by an API call to their respective endpoint:
 
-- [Add Pokemon](./use-cases/add-pokemon.md): Add a new Pokemon only relying on user input into the database.
-- [Get Pokemon by ID](./use-cases/get-pokemon-by-id.md): Given a Pokemon ID, this endpoint returns the data of a Pokemon. If the same Pokemon was queried, the API will use its cache to return it.
-- [List Pokemon](./use-cases/list-pokemon.md): Lists all Pokemons registered into Pokeshop.
-- [Import Pokemon](./use-cases/import-pokemon.md): Given a Pokemon ID, this endpoint does an async process, going to PokeAPI to get Pokemon data and adding it to the database.
-- [Import Pokemon from Stream](./use-cases/import-pokemon-from-stream.md): Listening to a Stream, this use case also does an async process, going to PokeAPI to get Pokemon data and adding it to the database.
+- [Add Pokemon](/live-examples/pokeshop/use-cases/add-pokemon): Add a new Pokemon only relying on user input into the database.
+- [Get Pokemon by ID](/live-examples/pokeshop/use-cases/get-pokemon-by-id): Given a Pokemon ID, this endpoint returns the data of a Pokemon. If the same Pokemon was queried, the API will use its cache to return it.
+- [List Pokemon](/live-examples/pokeshop/use-cases/list-pokemon): Lists all Pokemons registered into Pokeshop.
+- [Import Pokemon](/live-examples/pokeshop/use-cases/import-pokemon): Given a Pokemon ID, this endpoint does an async process, going to PokeAPI to get Pokemon data and adding it to the database.
+- [Import Pokemon from Stream](/live-examples/pokeshop/use-cases/import-pokemon-from-stream): Listening to a Stream, this use case also does an async process, going to PokeAPI to get Pokemon data and adding it to the database.
 
 ## System Architecture
 

diff --git a/...xamples/pokeshop/use-cases/add-pokemon.md → ...amples/pokeshop/use-cases/add-pokemon.mdx b/...xamples/pokeshop/use-cases/add-pokemon.md → ...amples/pokeshop/use-cases/add-pokemon.mdx
@@ -1,4 +1,16 @@
-# Pokeshop API - Add Pokemon
+---
+id: add-pokemon
+title: Pokeshop API - Add Pokemon
+description: As a testing ground, the Tracetest team has implemented a sample API instrumented with OpenTelemetry around the PokeAPI. This use case showcases a simple example of an API call where call data is validated and persisted into a database.
+hide_table_of_contents: false
+keywords:
+  - tracetest
+  - trace-based testing
+  - observability
+  - distributed tracing
+  - testing
+image: https://res.cloudinary.com/djwdcmwdz/image/upload/v1698686403/docs/Blog_Thumbnail_14_rsvkmo.jpg
+---
 
 This use case showcases a simple example of an API call where call data is validated and persisted into a database.
 

diff --git a/...s/pokeshop/use-cases/get-pokemon-by-id.md → .../pokeshop/use-cases/get-pokemon-by-id.mdx b/...s/pokeshop/use-cases/get-pokemon-by-id.md → .../pokeshop/use-cases/get-pokemon-by-id.mdx
@@ -1,4 +1,16 @@
-# Pokeshop API - Get Pokemon by ID
+---
+id: get-pokemon-by-id
+title: Pokeshop API - Get Pokemon by ID
+description: As a testing ground, the Tracetest team has implemented a sample API instrumented with OpenTelemetry around the PokeAPI. This use case retrieves a specific Pokemon from the cache if it is cached or from the database (Postgres) also populating the cache.
+hide_table_of_contents: false
+keywords:
+  - tracetest
+  - trace-based testing
+  - observability
+  - distributed tracing
+  - testing
+image: https://res.cloudinary.com/djwdcmwdz/image/upload/v1698686403/docs/Blog_Thumbnail_14_rsvkmo.jpg
+---
 
 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.
 

diff --git a/...p/use-cases/import-pokemon-from-stream.md → .../use-cases/import-pokemon-from-stream.mdx b/...p/use-cases/import-pokemon-from-stream.md → .../use-cases/import-pokemon-from-stream.mdx
@@ -1,8 +1,21 @@
-# Pokeshop API - Import Pokemon from Stream
+---
+id: import-pokemon-from-stream
+title: Pokeshop API - Import Pokemon from Stream
+description: As a testing ground, the Tracetest team has implemented a sample API instrumented with OpenTelemetry around the PokeAPI. This use case showcases a more complex scenario involving an async process.
+hide_table_of_contents: false
+keywords:
+  - tracetest
+  - trace-based testing
+  - observability
+  - distributed tracing
+  - testing
+image: https://res.cloudinary.com/djwdcmwdz/image/upload/v1698686403/docs/Blog_Thumbnail_14_rsvkmo.jpg
+---
 
 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 listens to a stream, and whenever an event is read from it, the following process is triggered:
+
 ```mermaid
 sequenceDiagram
     participant Stream as Kafka
@@ -20,6 +33,7 @@ sequenceDiagram
 ```
 
 You can trigger this use case by sending a message to Kafka on the `pokemon` topic with the following message value:
+
 ```json
 {
   "id":  143
@@ -29,6 +43,7 @@ You can trigger this use case by sending a message to Kafka on the `pokemon` top
 ## Building a Test for This Scenario
 
 Using Tracetest, we can [create a test](/web-ui/creating-tests) that will produce a message to Kafka on `pokemon` topic and validate the following properties:
+
 - The worker should read the import task.
 - PokeAPI should return a valid response.
 - The database should respond with low latency (< 200ms).

diff --git a/...ples/pokeshop/use-cases/import-pokemon.md → ...les/pokeshop/use-cases/import-pokemon.mdx b/...ples/pokeshop/use-cases/import-pokemon.md → ...les/pokeshop/use-cases/import-pokemon.mdx
@@ -1,8 +1,21 @@
-# Pokeshop API - Import Pokemon
+---
+id: import-pokemon
+title: Pokeshop API - Import Pokemon
+description: As a testing ground, the Tracetest team has implemented a sample API instrumented with OpenTelemetry around the PokeAPI. This use case showcases a more complex scenario involving an async process.
+hide_table_of_contents: false
+keywords:
+  - tracetest
+  - trace-based testing
+  - observability
+  - distributed tracing
+  - testing
+image: https://res.cloudinary.com/djwdcmwdz/image/upload/v1698686403/docs/Blog_Thumbnail_14_rsvkmo.jpg
+---
 
 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: 
+Here the process is split into two phases:
+
 1. An API call that enqueues an import request to a queue.
 ```mermaid
 sequenceDiagram

diff --git a/...amples/pokeshop/use-cases/list-pokemon.md → ...mples/pokeshop/use-cases/list-pokemon.mdx b/...amples/pokeshop/use-cases/list-pokemon.md → ...mples/pokeshop/use-cases/list-pokemon.mdx
@@ -1,4 +1,16 @@
-# Pokeshop API - List Pokemon
+---
+id: list-pokemon
+title: Pokeshop API - List Pokemon
+description: As a testing ground, the Tracetest team has implemented a sample API instrumented with OpenTelemetry around the PokeAPI. This use case retrieves the list of Pokemon directly from the database (Postgres) based on the provided query through the API.
+hide_table_of_contents: false
+keywords:
+  - tracetest
+  - trace-based testing
+  - observability
+  - distributed tracing
+  - testing
+image: https://res.cloudinary.com/djwdcmwdz/image/upload/v1698686403/docs/Blog_Thumbnail_14_rsvkmo.jpg
+---
 
 This use case retrieves the list of Pokemon directly from the database (Postgres) based on the provided query through the API. The purpose of this query is to showcase a straightforward scenario, where the API layer receives a request from the outside and needs to trigger a database query to get some data and return it to the client.
 

diff --git a/docs/sidebars.js b/docs/sidebars.js
@@ -26,12 +26,11 @@ const sidebars = {
     {
       type: "category",
       label: "OpenTelemetry Store Demo",
+      link: {
+        type: "doc",
+        id: "live-examples/opentelemetry-store/overview"
+      },
       items: [
-        {
-          type: "doc",
-          id: "live-examples/opentelemetry-store/overview",
-          label: "Overview",
-        },
         {
           type: "category",
           label: "Use Cases",
@@ -68,12 +67,11 @@ const sidebars = {
     {
       type: "category",
       label: "Pokeshop API Demo",
+      link: {
+        type: "doc",
+        id: "live-examples/pokeshop/overview"
+      },
       items: [
-        {
-          type: "doc",
-          id: "live-examples/pokeshop/overview",
-          label: "Overview",
-        },
         {
           type: "category",
           label: "Use Cases",