From ea91af26b6daba982e8fa5308ac9c39e96c32bd0 Mon Sep 17 00:00:00 2001 From: Adnan Rahic Date: Tue, 8 Oct 2024 15:36:34 +0200 Subject: [PATCH] docs(trace mode): added trace mode and improved misc pages --- docs/docs/cli/creating-tests.mdx | 2 + docs/docs/concepts/traces.mdx | 37 +++++++++++++ docs/docs/concepts/triggers.mdx | 55 +++++++++++++++++++ .../otlp-ingestion-endpoint.mdx | 50 +++++++++++++++++ .../connecting-to-data-stores/overview.mdx | 42 ++++++++------ docs/docs/configuration/trace-mode.mdx | 27 +++++++++ docs/docs/web-ui/creating-tests.mdx | 2 + docs/sidebars.js | 25 +++++++++ 8 files changed, 222 insertions(+), 18 deletions(-) create mode 100644 docs/docs/concepts/traces.mdx create mode 100644 docs/docs/concepts/triggers.mdx create mode 100644 docs/docs/configuration/connecting-to-data-stores/otlp-ingestion-endpoint.mdx create mode 100644 docs/docs/configuration/trace-mode.mdx diff --git a/docs/docs/cli/creating-tests.mdx b/docs/docs/cli/creating-tests.mdx index 5654afc221..0d9a0f7478 100644 --- a/docs/docs/cli/creating-tests.mdx +++ b/docs/docs/cli/creating-tests.mdx @@ -94,6 +94,8 @@ Choose the kind of trigger to initiate the trace: - [HTTP Request - Create a basic HTTP request.](/cli/creating-tests-http) - [GRPC Request - Test and debug your GRPC request.](/cli/creating-tests-grpc) - [Kafka - Test consumers with Kafka messages.](/cli/creating-tests-kafka) +- [Playwright Engine - Run Playwright tests natively in Tracetest.](/cli/creating-tests-playwright-engine) +- [GraphQL - Test and debug your GraphQL request.](/cli/creating-tests-graphql) - [TraceID - Define your test via a TraceID.](/cli/creating-tests-traceid) Or, choose to use an external integration to trigger Tracetest: diff --git a/docs/docs/concepts/traces.mdx b/docs/docs/concepts/traces.mdx new file mode 100644 index 0000000000..902057b17e --- /dev/null +++ b/docs/docs/concepts/traces.mdx @@ -0,0 +1,37 @@ +--- +id: traces +title: Traces +description: Tracetest uses the concept of Traces to enable previewing ingested traces. While in trace mode you can view all traces your apps are exporting. You can select traces to test and start creating assertions right away! +keywords: + - tracetest + - trace-based testing + - observability + - distributed tracing + - testing + - traces + - tracing +image: https://res.cloudinary.com/djwdcmwdz/image/upload/v1698686403/docs/Blog_Thumbnail_14_rsvkmo.jpg +--- + +Tracetest uses the concept of Traces to enable previewing ingested traces. On the Traces screen you can view all traces your apps are exporting. You can select traces to test and start creating assertions right away! + +:::note trace retention +Ingested traces will be deleted after 96 hours. +::: + +- [Tests](/concepts/tests) +- [Assertions](/concepts/assertions) + +![Traces](https://res.cloudinary.com/djwdcmwdz/image/upload/v1728327048/docs/app.tracetest.io_organizations_ttorg_e66318ba6544b856_environments_ttenv_1931fbfb43cc96c1_traces_page_1_a9znan.png) + +A trace allows you to: + +- Preview spans in distributed traces your distributed system is exporting. +- Analyze traces and span attributes. +- Create tests from traces that are ingested in your Tracetest account via a trace ID. +- Create assertions for particular spans to verify the behavior of the system at every step of the request transaction. +- Create test triggers automatically based on span attributes and metadata. + +![Open a Trace to create a test](https://res.cloudinary.com/djwdcmwdz/image/upload/v1728327049/docs/app.tracetest.io_organizations_ttorg_e66318ba6544b856_environments_ttenv_1931fbfb43cc96c1_traces_page_1_1_zovlo4.png) + +A trace in Tracetest helps you get insight into what your system is doing. It will guide you to define trace-based assertions that validate the end-to-end behavior of a distributed system, going beyond just UI or API-level testing. diff --git a/docs/docs/concepts/triggers.mdx b/docs/docs/concepts/triggers.mdx new file mode 100644 index 0000000000..2995b22c08 --- /dev/null +++ b/docs/docs/concepts/triggers.mdx @@ -0,0 +1,55 @@ +--- +id: triggers +title: Triggers +description: Tracetest uses the concept of Tests to define how to trigger a test against your application, define assertions against its trace data, and automate its execution. Every time a Test is triggered it will create a Run. +keywords: + - tracetest + - trace-based testing + - observability + - distributed tracing + - testing +image: https://res.cloudinary.com/djwdcmwdz/image/upload/v1698686403/docs/Blog_Thumbnail_14_rsvkmo.jpg +--- + +Tracetest uses the concept of Triggers to define how to initiate a test run. + +## Native Triggers + +Triggers define how Tracetest interacts with your application. + +### Web UI + +- [HTTP Request - Create a basic HTTP request.](/web-ui/creating-tests-http) +- [GRPC Request - Test and debug your GRPC request.](/web-ui/creating-tests-gRPC) +- [Kafka - Test consumers with Kafka messages.](/web-ui/creating-tests-kafka) +- [Playwright Engine - Run Playwright tests natively in Tracetest.](/web-ui/creating-tests-playwright-engine) +- [GraphQL - Test and debug your GraphQL request.](/web-ui/creating-tests-graphql) +- [TraceID - Define your test via a TraceID.](/web-ui/creating-tests-traceid) + +![webui triggers](https://res.cloudinary.com/djwdcmwdz/image/upload/v1728388264/docs/Screenshot_2024-10-08_at_13.50.45_ng1lfg.png) + +### CLI + +The attribute `type` defines which trigger method you are going to use to interact with your application. + +```yaml +trigger: + type: http|grpc|kafka|traceid|cypress|playwright|k6|artillery +... +``` + +- [HTTP Request - Create a basic HTTP request.](/cli/creating-tests-http) +- [GRPC Request - Test and debug your GRPC request.](/cli/creating-tests-grpc) +- [Kafka - Test consumers with Kafka messages.](/cli/creating-tests-kafka) +- [Playwright Engine - Run Playwright tests natively in Tracetest.](/cli/creating-tests-playwright-engine) +- [GraphQL - Test and debug your GraphQL request.](/cli/creating-tests-graphql) +- [TraceID - Define your test via a TraceID.](/cli/creating-tests-traceid) + +## Integrations + +Initiate test runs from triggers outside of Tracetest. + +- [Cypress](/web-ui/creating-tests-cypress) +- [Playwright](/web-ui/creating-tests-playwright) +- [k6](/web-ui/creating-tests-k6) +- [Artillery](/web-ui/creating-tests-artillery) diff --git a/docs/docs/configuration/connecting-to-data-stores/otlp-ingestion-endpoint.mdx b/docs/docs/configuration/connecting-to-data-stores/otlp-ingestion-endpoint.mdx new file mode 100644 index 0000000000..7f5fca000a --- /dev/null +++ b/docs/docs/configuration/connecting-to-data-stores/otlp-ingestion-endpoint.mdx @@ -0,0 +1,50 @@ +--- +id: otlp-ingestion-endpoint +title: OTLP Ingestion Endpoint +description: Configure the Tracetest Agent to ingest traces and sync them with Tracetest. +keywords: + - tracetest + - trace-based testing + - observability + - distributed tracing + - testing +image: https://res.cloudinary.com/djwdcmwdz/image/upload/v1698686403/docs/Blog_Thumbnail_14_rsvkmo.jpg +--- + +Tracetest Agent receives trace data on port `4317` and `4318`. The OTLP endpoint might look like: + +```bash +http://tracetest-agent:4317 +``` + +:::tip +Examples of configuring Tracetest can be found in the [`examples` folder of the Tracetest GitHub repo](https://github.com/kubeshop/tracetest/tree/main/examples). +::: + +## Connect Tracetest to Ingest OpenTelemetry Traces with the Web UI + +In the Web UI, (1) open Settings, and, on the (2) Trace Ingestion tab, select (3) OpenTelemetry. + +![Trace Ingestion Settings](../../img/08132024/app.tracetest.io_organizations_at4CxvjIg_environments_ttenv_172de56e3dcbba9b_settings_tab=dataStore_otel.png) + +## Connect Tracetest to OpenTelemetry Collector with the CLI + +Or, if you prefer using the CLI, you can use this file config. + +```yaml +type: DataStore +spec: + name: Opentelemetry Collector pipeline + type: otlp + default: true +``` + +Proceed to run this command in the terminal, and specify the file above. + +```bash +tracetest apply datastore -f my/data-store/file/location.yaml +``` + +:::tip +To learn more, [read the recipe on running a sample app with OpenTelemetry Collector and Tracetest](/examples-tutorials/recipes/running-tracetest-without-a-trace-data-store). +::: diff --git a/docs/docs/configuration/connecting-to-data-stores/overview.mdx b/docs/docs/configuration/connecting-to-data-stores/overview.mdx index 6085ddda37..af06be70de 100644 --- a/docs/docs/configuration/connecting-to-data-stores/overview.mdx +++ b/docs/docs/configuration/connecting-to-data-stores/overview.mdx @@ -13,40 +13,46 @@ image: https://res.cloudinary.com/djwdcmwdz/image/upload/v1698686403/docs/Blog_T Tracetest allows you to connect your Tracing Backend to unlock the full potential of trace-based testing. Tracetest supports two types of tracing backend integrations. -## Native Connection (Polling) +## OTLP Ingest Endpoint -When using a tracing backend integration that supports the native connection, Tracetest will pull telemetry data directly from your tracing backend for every test run. +When not using a tracing backend, the OpenTelemetry Collector, or using a tracing backend integration that does not support a native connection, you'll use the Tracetest OTLP ingest endpoint. -## OTLP Ingest Endpoint +Configure Tracetest Agent: +- [Tracetest Agent](/configuration/agent) exposes an OTLP endpoint that listens for trace data on ports `4317` (gRPC) and `4318` (HTTP). +- [Tracetest Cloud Agent](/configuration/cloud-agent) exposes an OTLP endpoint that listens for trace data on TLS port `443` (both HTTP and gRPC). -When using a tracing backend integration that does not support a native connection, or no tracing backend at all, you'll resort to using the Tracetest OTLP ingest endpoint. [Tracetest Agent](/configuration/agent) exposes an OTLP endpoint that listens for trace data on ports `4317` (gRPC) and `4318` (HTTP). As does [Tracetest Cloud Agent](/configuration/cloud-agent), but uses the same TLS port `443` for OTLP ingestion. +Configure trace ingestion: +- [OTLP Ingestion Endpoint](/configuration/connecting-to-data-stores/otlp-ingestion-endpoint) is used to ingest OpenTelemetry traces. -## Supported Tracing Backends +### Supported OTLP Ingest Tracing Backends -Currently, Tracetest supports the following data stores. Click on the respective data store to view configuration examples: +Currently, Tracetest integrates with the following OTLP tracing backends. Click on the respective tracing backend to view configuration examples: -- [AWS X-Ray](/configuration/connecting-to-data-stores/awsxray) +- [OpenTelemetry Collector](/configuration/connecting-to-data-stores/opentelemetry-collector) - [Azure App Insights](/configuration/connecting-to-data-stores/azure-app-insights) - [Datadog](/configuration/connecting-to-data-stores/datadog) - [Dynatrace](/configuration/connecting-to-data-stores/dynatrace) -- [Elastic APM](/configuration/connecting-to-data-stores/elasticapm) -- [Grafana Tempo](/configuration/connecting-to-data-stores/tempo) -- [Honeycomb](/configuration/connecting-to-data-stores/honeycomb) - [Instana](/configuration/connecting-to-data-stores/instana) -- [Jaeger](/configuration/connecting-to-data-stores/jaeger) - [Lightstep](/configuration/connecting-to-data-stores/lightstep) - [New Relic](/configuration/connecting-to-data-stores/new-relic) -- [OpenSearch](/configuration/connecting-to-data-stores/opensearch) -- [OpenTelemetry Collector](/configuration/connecting-to-data-stores/opentelemetry-collector) -- [SignalFX](/configuration/connecting-to-data-stores/signalfx) - [SigNoz](/configuration/connecting-to-data-stores/signoz) -- [Sumo Logic](/configuration/connecting-to-data-stores/sumologic) -## Using Tracetest without a Tracing Backend (OTLP ingest endpoint) +## Native Connection (Polling) + +When using a tracing backend integration that supports the native connection, Tracetest will pull telemetry data directly from your tracing backend for every test run. -Another option is to send traces directly to Tracetest using the OpenTelemetry Collector. And, you don't have to change your existing pipelines to do so. +### Supported Native Tracing Backends -View [configuration for OpenTelemetry Collector](/configuration/connecting-to-data-stores/opentelemetry-collector) for more details. +Currently, Tracetest supports the following tracing backends. Click on the respective tracing backend to view configuration examples: + +- [AWS X-Ray](/configuration/connecting-to-data-stores/awsxray) +- [Azure App Insights](/configuration/connecting-to-data-stores/azure-app-insights) +- [Elastic APM](/configuration/connecting-to-data-stores/elasticapm) +- [Grafana Tempo](/configuration/connecting-to-data-stores/tempo) +- [Jaeger](/configuration/connecting-to-data-stores/jaeger) +- [OpenSearch](/configuration/connecting-to-data-stores/opensearch) +- [SignalFX](/configuration/connecting-to-data-stores/signalfx) +- [Sumo Logic](/configuration/connecting-to-data-stores/sumologic) ## Tracing Backend Configuration Examples diff --git a/docs/docs/configuration/trace-mode.mdx b/docs/docs/configuration/trace-mode.mdx new file mode 100644 index 0000000000..84ffd43df2 --- /dev/null +++ b/docs/docs/configuration/trace-mode.mdx @@ -0,0 +1,27 @@ +--- +id: trace-mode +title: Trace Mode +description: Trace Mode is provided in Tracetest to help preview all ingested traces to simplify in pinpointing traces to speed up creating tests. +keywords: + - tracetest + - trace-based testing + - observability + - distributed tracing + - testing +image: https://res.cloudinary.com/djwdcmwdz/image/upload/v1698686403/docs/Blog_Thumbnail_14_rsvkmo.jpg +--- + +Trace Mode is provided in Tracetest to help preview all ingested traces. This simplifies pinpointing which spans to use for creating tests. + +:::tip +[Read more about Trace Mode concepts here.](/concepts/traces) +::: + +## View Traces + +1. Start [Tracetest Agent](/configuration/agent). +2. Configure [Trace Ingestion](/configuration/connecting-to-data-stores/otlp-ingestion-endpoint). +3. Send traces to Tracetest Agent. +4. View traces in Tracetest. + +![Traces](https://res.cloudinary.com/djwdcmwdz/image/upload/v1728327048/docs/app.tracetest.io_organizations_ttorg_e66318ba6544b856_environments_ttenv_1931fbfb43cc96c1_traces_page_1_a9znan.png) diff --git a/docs/docs/web-ui/creating-tests.mdx b/docs/docs/web-ui/creating-tests.mdx index 8bf3017560..6e0b0af26b 100644 --- a/docs/docs/web-ui/creating-tests.mdx +++ b/docs/docs/web-ui/creating-tests.mdx @@ -26,6 +26,8 @@ Choose the kind of trigger to initiate the trace: - [HTTP Request - Create a basic HTTP request.](/web-ui/creating-tests-http) - [GRPC Request - Test and debug your GRPC request.](/web-ui/creating-tests-gRPC) - [Kafka - Test consumers with Kafka messages.](/web-ui/creating-tests-kafka) +- [Playwright Engine - Run Playwright tests natively in Tracetest.](/web-ui/creating-tests-playwright-engine) +- [GraphQL - Test and debug your GraphQL request.](/web-ui/creating-tests-graphql) - [TraceID - Define your test via a TraceID.](/web-ui/creating-tests-traceid) Or, choose to use an external integration to trigger Tracetest: diff --git a/docs/sidebars.js b/docs/sidebars.js index 7d729ac299..61a20c5f0c 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -668,6 +668,11 @@ const sidebars = { id: "concepts/cloud-agent", label: "Tracetest Cloud Agent (Public Access)", }, + { + type: "doc", + id: "concepts/traces", + label: "Traces", + }, { type: "doc", id: "concepts/polling-profiles", @@ -703,6 +708,11 @@ const sidebars = { id: "concepts/environment-tokens", label: "Environment Tokens", }, + { + type: "doc", + id: "concepts/triggers", + label: "Triggers", + }, { type: "doc", id: "concepts/tests", @@ -886,6 +896,11 @@ const sidebars = { id: "configuration/connecting-to-data-stores/overview", }, items: [ + { + type: "doc", + id: "configuration/connecting-to-data-stores/otlp-ingestion-endpoint", + label: "OTLP Ingestion Endpoint", + }, { type: "doc", id: "configuration/connecting-to-data-stores/awsxray", @@ -921,6 +936,11 @@ const sidebars = { id: "configuration/connecting-to-data-stores/honeycomb", label: "Honeycomb", }, + { + type: "doc", + id: "configuration/connecting-to-data-stores/instana", + label: "Instana", + }, { type: "doc", id: "configuration/connecting-to-data-stores/jaeger", @@ -968,6 +988,11 @@ const sidebars = { }, ], }, + { + type: "doc", + id: "configuration/trace-mode", + label: "Trace Mode", + }, { type: "doc", id: "configuration/tracetest-analyzer",