docs(mdx): Migrate files to .mdx and add meta title + desc (#3323)

* docs(convert mdx): round 1 * docs(migrate to mdx): concepts * docs(migrate to mdx): cli section * docs(migrate to mdx): config section * docs(migrate to mdx): core section * docs(migrate to mdx): examples-tutorials section * docs(migrate to mdx): getting started section * docs(migrate to mdx): tools and integrations * docs(migrating to mdx): web ui * docs(migrate to mdx): fix broken links
kubeshop · Nov 1, 2023 · 586a3a4 · 586a3a4
1 parent 4629c9a
commit 586a3a4
Show file tree

Hide file tree

Showing 147 changed files with 1,481 additions and 785 deletions.
diff --git a/docs/docs/analyzer/concepts.md → docs/docs/analyzer/concepts.mdx b/docs/docs/analyzer/concepts.md → docs/docs/analyzer/concepts.mdx
@@ -1,12 +1,23 @@
-# Trace Analyzer Concepts
+---
+id: concepts
+title: Trace Analyzer Concepts
+description: The Tracetest Analyzer analyzes OpenTelemetry traces to help teams improve instrumentation data, find potential problems, and provide tips to fix the problems.
+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 Tracetest Analyzer is a plugin-based framework used to analyze OpenTelemetry traces to help teams improve their instrumentation data, find potential problems and provide tips to fix the problems.
 
 ## Plugins
 
-- [OpenTelemetry Semantic Conventions](./plugins/otel-semantic-conventions.md)
-- [Security](./plugins/security.md)
-- [Common Problems](./plugins/common-problems.md)
+- [OpenTelemetry Semantic Conventions](./plugins/otel-semantic-conventions)
+- [Security](./plugins/security)
+- [Common Problems](./plugins/common-problems)
 
 ## Problem
 
@@ -40,7 +51,7 @@ There are two main rule types:
 - Single Trace. Encapsulated to the current trace, no external data is required.
 
 :::note
-[This documentation will be focused on single trace rules for timing purposes.](../configuration/tracetest-analyzer.md)
+[This documentation will be focused on single trace rules for timing purposes.](../configuration/tracetest-analyzer)
 :::
 
 ### Analyzer Resource

diff --git a/docs/docs/analyzer/plugins/common-problems.md b/docs/docs/analyzer/plugins/common-problems.md
diff --git a/docs/docs/analyzer/plugins/common-problems.mdx b/docs/docs/analyzer/plugins/common-problems.mdx
@@ -0,0 +1,18 @@
+---
+id: common-problems
+title: Common Problems
+description: The Common Problems plugin analyzes spans part of a trace to identify errors. The Tracetest Analyzer analyzes OpenTelemetry traces.
+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 `Common Problems` plugin is responsible of analyzing the spans that are part of a trace in order to identify frequent mistakes in the distributed system.
+
+## Rules
+
+- [prefer-dns](/analyzer/rules/prefer-dns)
diff --git a/docs/docs/analyzer/plugins/otel-semantic-conventions.md b/docs/docs/analyzer/plugins/otel-semantic-conventions.md
diff --git a/docs/docs/analyzer/plugins/otel-semantic-conventions.mdx b/docs/docs/analyzer/plugins/otel-semantic-conventions.mdx
@@ -0,0 +1,21 @@
+---
+id: otel-semantic-conventions
+title: OTel Semantic Conventions
+description: The OpenTelemetry Semantic Conventions plugin analyzes spans part of a trace in order to identify problematic patterns. The Tracetest Analyzer analyzes OpenTelemetry traces.
+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 Semantic Conventions` plugin analyzes the spans that are part of a trace in order to identify problematic patterns. The set of rules follows the OpenTelemetry conventions to ensure the quality of the telemetry data.
+
+## Rules
+
+- [span-naming](/analyzer/rules/span-naming)
+- [attribute-naming](/analyzer/rules/attribute-naming)
+- [required-attributes](/analyzer/rules/required-attributes)
+- [no-empty-attributes](/analyzer/rules/no-empty-attributes)
diff --git a/docs/docs/analyzer/plugins/security.md b/docs/docs/analyzer/plugins/security.md
diff --git a/docs/docs/analyzer/plugins/security.mdx b/docs/docs/analyzer/plugins/security.mdx
@@ -0,0 +1,19 @@
+---
+id: security
+title: Security
+description: The Security plugin is responsible for analyzing spans part of a trace to identify security problems. The Tracetest Analyzer analyzes OpenTelemetry traces.
+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 `Security` plugin is responsible for analyzing the spans that are part of a trace in order to identify security problems in the distributed system.
+
+## Rules
+
+- [secure-https-protocol](/analyzer/rules/secure-https-protocol)
+- [no-api-key-leak](/analyzer/rules/no-api-key-leak)
diff --git a/docs/docs/analyzer/rules/attribute-naming.md b/docs/docs/analyzer/rules/attribute-naming.md
diff --git a/docs/docs/analyzer/rules/attribute-naming.mdx b/docs/docs/analyzer/rules/attribute-naming.mdx
@@ -0,0 +1,39 @@
+---
+id: attribute-naming
+title: attribute-naming
+description: Enforce attribute keys to follow common specifications  | The Tracetest Analyzer analyzes OpenTelemetry traces
+keywords:
+  - tracetest
+  - trace-based testing
+  - observability
+  - distributed tracing
+  - testing
+image: https://res.cloudinary.com/djwdcmwdz/image/upload/v1698686403/docs/Blog_Thumbnail_14_rsvkmo.jpg
+---
+
+Enforce attribute keys to follow common specifications.
+
+## Rule Details
+
+An `Attribute` is a key-value pair, which is encapsulated as part of a span. The attribute key should follow a set of common specifications to be considered valid.
+
+The following OpenTelemetry Semantic Conventions for attribute keys are defined:
+
+- It must be a non-null and non-empty string.
+- It must be a valid Unicode sequence.
+- It should use namespacing to avoid name clashes. Delimit the namespaces using a dot character. For example `service.version` denotes the service version where `service` is the namespace and `version` is an attribute in that namespace.
+- Namespaces can be nested. For example `telemetry.sdk` is a namespace inside top-level `telemetry` namespace and `telemetry.sdk.name` is an attribute inside `telemetry.sdk` namespace.
+- For each multi-word separate the words by underscores (use snake_case). For example `http.status_code` denotes the status code in the http namespace.
+- Names should not coincide with namespaces. For example if `service.instance.id` is an attribute name then it is no longer valid to have an attribute named `service.instance` because `service.instance` is already a namespace.
+
+## Options
+
+This rule has the following options:
+
+- `"error"` requires attribute keys to follow the OTel semantic convention
+- `"disabled"` disables the attribute keys verification
+- `"warning"` verifies attribute keys to follow the OTel semantic convention but does not impact the analyzer score
+
+## When Not To Use It
+
+If you don’t want to enforce OTel attribute keys, don't enable this rule.
diff --git a/docs/docs/analyzer/rules/no-api-key-leak.md → docs/docs/analyzer/rules/no-api-key-leak.mdx b/docs/docs/analyzer/rules/no-api-key-leak.md → docs/docs/analyzer/rules/no-api-key-leak.mdx
@@ -1,4 +1,15 @@
-# no-api-key-leak
+---
+id: no-api-key-leak
+title: no-api-key-leak
+description: Disallow leaked API keys for HTTP spans | The Tracetest Analyzer analyzes OpenTelemetry traces
+keywords:
+  - tracetest
+  - trace-based testing
+  - observability
+  - distributed tracing
+  - testing
+image: https://res.cloudinary.com/djwdcmwdz/image/upload/v1698686403/docs/Blog_Thumbnail_14_rsvkmo.jpg
+---
 
 Disallow leaked API keys for HTTP spans.
 

diff --git a/...ocs/analyzer/rules/no-empty-attributes.md → ...cs/analyzer/rules/no-empty-attributes.mdx b/...ocs/analyzer/rules/no-empty-attributes.md → ...cs/analyzer/rules/no-empty-attributes.mdx
@@ -1,4 +1,15 @@
-# no-empty-attributes
+---
+id: no-empty-attributes
+title: no-empty-attributes
+description: Disallow empty attribute values | The Tracetest Analyzer analyzes OpenTelemetry traces
+keywords:
+  - tracetest
+  - trace-based testing
+  - observability
+  - distributed tracing
+  - testing
+image: https://res.cloudinary.com/djwdcmwdz/image/upload/v1698686403/docs/Blog_Thumbnail_14_rsvkmo.jpg
+---
 
 Disallow empty attribute values.
 

diff --git a/docs/docs/analyzer/rules/prefer-dns.md → docs/docs/analyzer/rules/prefer-dns.mdx b/docs/docs/analyzer/rules/prefer-dns.md → docs/docs/analyzer/rules/prefer-dns.mdx
@@ -1,4 +1,15 @@
-# prefer-dns
+---
+id: prefer-dns
+title: prefer-dns
+description: Enforce usage of DNS instead of IP addresses | The Tracetest Analyzer analyzes OpenTelemetry traces
+keywords:
+  - tracetest
+  - trace-based testing
+  - observability
+  - distributed tracing
+  - testing
+image: https://res.cloudinary.com/djwdcmwdz/image/upload/v1698686403/docs/Blog_Thumbnail_14_rsvkmo.jpg
+---
 
 Enforce usage of DNS instead of IP addresses.
 
@@ -8,14 +19,14 @@ When connecting to remote servers, ensure the usage of DNS instead of IP address
 
 The following attributes are evaluated:
 
-```
+```yaml
 - http.url
 - db.connection_string
 ```
 
 If span kind is `"client"`, the following attributes are evaluated:
 
-```
+```yaml
 - net.peer.name
 ```
 

diff --git a/...ocs/analyzer/rules/required-attributes.md → ...cs/analyzer/rules/required-attributes.mdx b/...ocs/analyzer/rules/required-attributes.md → ...cs/analyzer/rules/required-attributes.mdx
@@ -1,4 +1,15 @@
-# required-attributes
+---
+id: required-attributes
+title: required-attributes
+description: Enforce required attributes by span type | The Tracetest Analyzer analyzes OpenTelemetry traces
+keywords:
+  - tracetest
+  - trace-based testing
+  - observability
+  - distributed tracing
+  - testing
+image: https://res.cloudinary.com/djwdcmwdz/image/upload/v1698686403/docs/Blog_Thumbnail_14_rsvkmo.jpg
+---
 
 Enforce required attributes by span type.
 

diff --git a/...s/analyzer/rules/secure-https-protocol.md → .../analyzer/rules/secure-https-protocol.mdx b/...s/analyzer/rules/secure-https-protocol.md → .../analyzer/rules/secure-https-protocol.mdx
@@ -1,4 +1,15 @@
-# secure-https-protocol
+---
+id: secure-https-protocol
+title: secure-https-protocol
+description: Enforce usage of secure protocol for HTTP server spans | The Tracetest Analyzer analyzes OpenTelemetry traces
+keywords:
+  - tracetest
+  - trace-based testing
+  - observability
+  - distributed tracing
+  - testing
+image: https://res.cloudinary.com/djwdcmwdz/image/upload/v1698686403/docs/Blog_Thumbnail_14_rsvkmo.jpg
+---
 
 Enforce usage of secure protocol for HTTP server spans.
 

diff --git a/docs/docs/analyzer/rules/span-naming.md → docs/docs/analyzer/rules/span-naming.mdx b/docs/docs/analyzer/rules/span-naming.md → docs/docs/analyzer/rules/span-naming.mdx
@@ -1,10 +1,21 @@
-# span-naming
-
-Enforce span names that identify a class of Spans, rather than individual Span instances.
+---
+id: span-naming
+title: span-naming
+description: Enforce span names that identify a class of Spans, rather than individual Span instances | The Tracetest Analyzer analyzes OpenTelemetry traces
+keywords:
+  - tracetest
+  - trace-based testing
+  - observability
+  - distributed tracing
+  - testing
+image: https://res.cloudinary.com/djwdcmwdz/image/upload/v1698686403/docs/Blog_Thumbnail_14_rsvkmo.jpg
+---
+
+Enforce span names that identify a class of Spans, rather than individual Span instances.
 
 ## Rule Details
 
-The span name concisely identifies the work represented by the Span, for example, an RPC method name, a function name, or the name of a subtask or stage within a larger computation. The span name SHOULD be the most general string that identifies a class of Spans, rather than individual Span instances while still being human-readable.
+The span name concisely identifies the work represented by the Span, for example, an RPC method name, a function name, or the name of a subtask or stage within a larger computation. The span name SHOULD be the most general string that identifies a class of Spans, rather than individual Span instances while still being human-readable.
 
 The following OTel semantic conventions for span names are defined:
 

diff --git a/...-cd-automation/github-actions-pipeline.md → ...cd-automation/github-actions-pipeline.mdx b/...-cd-automation/github-actions-pipeline.md → ...cd-automation/github-actions-pipeline.mdx
@@ -1,4 +1,15 @@
-# GitHub Actions Pipeline
+---
+id: github-actions-pipeline
+title: GitHub Actions Pipeline
+description: Quick start how to configure GitHub Actions to run Tracetest trace-based tests against a Node.js app with OpenTelemetry instrumentation and traces.
+keywords:
+  - tracetest
+  - trace-based testing
+  - observability
+  - distributed tracing
+  - testing
+image: https://res.cloudinary.com/djwdcmwdz/image/upload/v1698686403/docs/Blog_Thumbnail_14_rsvkmo.jpg
+---
 
 :::note
 [Check out the source code on GitHub here.](https://github.com/kubeshop/tracetest/tree/main/examples/quick-start-github-actions)

diff --git a/docs/docs/ci-cd-automation/overview.md → docs/docs/ci-cd-automation/overview.mdx b/docs/docs/ci-cd-automation/overview.md → docs/docs/ci-cd-automation/overview.mdx
@@ -1,12 +1,23 @@
-# CI/CD Automation
+---
+id: overview
+title: CI/CD Automation
+description: Overview of running automated trace-based testing with Tracetest in CI/CD pipelines.
+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 section contains a general overview of running Tracetest in CI/CD pipelines.
 
 You can find guides for:
 
-- [GitHub Actions](./github-actions-pipeline.md)
-- [Testkube](./testkube-pipeline.md)
-- [Tekton](./tekton-pipeline.md)
+- [GitHub Actions](/ci-cd-automation/github-actions-pipeline)
+- [Testkube](/ci-cd-automation/testkube-pipeline)
+- [Tekton](/ci-cd-automation/tekton-pipeline)
 
 :::note
 If you want to see more examples with other CI/CD tools, let us know by [opening an issue in GitHub](https://github.com/kubeshop/tracetest/issues/new/choose)!
@@ -21,7 +32,7 @@ To read more about integrating Tracetest with CI/CD tools, check out tutorials i
 
 ## Running Tracetest CLI from Docker
 
-Many integrations with CI/CD tools can be accomplished by running the [Tracetest CLI](../cli/configuring-your-cli.md) to execute a test against a remote Tracetest server. If you do not want to install the Tracetest CLI in your environment, you can choose to directly execute it from a Docker image.
+Many integrations with CI/CD tools can be accomplished by running the [Tracetest CLI](../cli/configuring-your-cli) to execute a test against a remote Tracetest server. If you do not want to install the Tracetest CLI in your environment, you can choose to directly execute it from a Docker image.
 
 **How to Use**:
 

diff --git a/.../docs/ci-cd-automation/tekton-pipeline.md → ...docs/ci-cd-automation/tekton-pipeline.mdx b/.../docs/ci-cd-automation/tekton-pipeline.md → ...docs/ci-cd-automation/tekton-pipeline.mdx
@@ -1,4 +1,15 @@
-# Tekton Cloud-native Pipeline
+---
+id: tekton-pipeline
+title: Tekton Cloud-native Pipeline
+description: Use Tracetest with Tekton to add trace-based testing to Kubernetes-native CI/CD pipelines. Run scheduled and synthetic tests against trace data.
+keywords:
+  - tracetest
+  - trace-based testing
+  - observability
+  - distributed tracing
+  - testing
+image: https://res.cloudinary.com/djwdcmwdz/image/upload/v1698686403/docs/Blog_Thumbnail_14_rsvkmo.jpg
+---
 
 :::note
 [Check out the source code on GitHub here.](https://github.com/kubeshop/tracetest/tree/main/examples/quick-start-tekton)