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..ff0566c756 --- /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 that 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/getting-started/no-otel.mdx b/docs/docs/getting-started/no-otel.mdx index 074af2c5bd..15ee7a33f1 100644 --- a/docs/docs/getting-started/no-otel.mdx +++ b/docs/docs/getting-started/no-otel.mdx @@ -29,7 +29,23 @@ This page will explain getting started with OpenTelemetry: You can also find more ways to instrument OpenTelemetry in their [documentation](https://opentelemetry.io/docs/instrumentation/). - + + +[Zero-code instrumentation adds the OpenTelemetry](https://opentelemetry.io/docs/concepts/instrumentation/zero-code/) API and SDK capabilities to your application typically as an agent or agent-like installation. + +Below we provide quick links to all key docs and samples. + +| Language | Docs | +|---|---| +| **C#/.NET** | https://opentelemetry.io/docs/zero-code/net/ | +| **Java** | https://opentelemetry.io/docs/zero-code/java/ | +| **JavaScript** | https://opentelemetry.io/docs/zero-code/js/ | +| **PHP** | https://opentelemetry.io/docs/zero-code/php/ | +| **Python** | https://opentelemetry.io/docs/zero-code/python/ | +| **Go** | https://opentelemetry.io/docs/zero-code/go/ | + + + You can install the OpenTelemetry Operator in any existing Kubernetes environment in under 5 minutes by running the following set of commands. @@ -145,12 +161,6 @@ Check the [official OpenTelemetry docs](https://opentelemetry.io/docs/k8s-operat - - -#### [Odigos](https://docs.odigos.io/intro), is a new open source project that can do this for you without a single line of code. - - - Below we provide quick links to all key docs and samples. 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/docusaurus.config.js b/docs/docusaurus.config.js index 91016d4c00..0e77b851ac 100644 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -127,8 +127,10 @@ const config = { // content: // '🎉 Test Observability for Platform & Observability Teams with Tracetest v1.3 is here! 🔥', // isCloseable: false, + // content: + // '🎉 Self-Hosted Tracetest is here: Get a license key and try it for free for 30 days! 🔥', content: - '🎉 Self-Hosted Tracetest is here: Get a license key and try it for free for 30 days! 🔥', + '📚 Get started with Trace-based Testing: Embrace test-driven development with observability, using real data, and skip the hassle of mocks and black box testing 🔥', isCloseable: false, }, navbar: { diff --git a/docs/sidebars.js b/docs/sidebars.js index f760a732d3..65ea69f725 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",