From 81666422d9b8a8c13d592c597602b2837619de75 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Adnan=20Rahi=C4=87?= Date: Tue, 9 Apr 2024 18:26:44 +0200 Subject: [PATCH] docs(config): total rework (#3780) * docs(config): fix agent config, fix config root page, add connecting to tracing backends overview page * Update docs/docs/configuration/connecting-to-data-stores/overview.mdx Co-authored-by: Daniel Baptista Dias --------- Co-authored-by: Daniel Baptista Dias --- docs/docs/concepts/agent.mdx | 2 +- docs/docs/configuration/agent.mdx | 17 +++--- docs/docs/configuration/cloud-agent.mdx | 30 ++++++++++ .../connecting-to-data-stores/overview.mdx | 56 +++++++++++++++++++ docs/docs/configuration/overview.mdx | 43 ++++++-------- docs/docs/examples-tutorials/recipes.mdx | 4 +- docs/sidebars.js | 21 +++++-- 7 files changed, 127 insertions(+), 46 deletions(-) create mode 100644 docs/docs/configuration/cloud-agent.mdx create mode 100644 docs/docs/configuration/connecting-to-data-stores/overview.mdx diff --git a/docs/docs/concepts/agent.mdx b/docs/docs/concepts/agent.mdx index 797c4532c7..ebf0fdea8b 100644 --- a/docs/docs/concepts/agent.mdx +++ b/docs/docs/concepts/agent.mdx @@ -21,7 +21,7 @@ If you have a [publicly accessible application, then view this page](/concepts/c ## Get Started -Go to your Environment Agent Settings page. +Go to your Environment Access Settings page. ![Agent Settings](https://res.cloudinary.com/djwdcmwdz/image/upload/v1712586955/docs/app.tracetest.io_organizations_ttorg_2179a9cd8ba8dfa5_environments_ttenv_597cf82c754c2a01_settings_ykn53w.png) diff --git a/docs/docs/configuration/agent.mdx b/docs/docs/configuration/agent.mdx index 91803fa430..e8970f7281 100644 --- a/docs/docs/configuration/agent.mdx +++ b/docs/docs/configuration/agent.mdx @@ -1,6 +1,6 @@ --- id: agent -title: Configuring the Tracetest Agent +title: Configuring the Tracetest Agent (Private Access) description: The Tracetest Agent enables Tracetest to access your application under test and to ingest trace data from your OpenTelemetry Collector or tracing backend. Learn how to configure the Tracetest Agent that runs in your environment as an executable, Docker container, or in your Cloud Native infrastructure. keywords: - tracetest @@ -17,20 +17,17 @@ The Tracetest Agent enables Tracetest to access your application under test and Tracetest Agent connects to Tracetest via an API Key. -[Start Tracetest Agent](../getting-started/installation.mdx) in your environment to begin testing! +[Sign in to Tracetest](https://app.tracetest.io/) and follow the instructions on the `Settings > Access` page. -Or, [sign in to Tracetest](https://app.tracetest.io/) and follow the instructions on the `Settings > Agent` page. +Select `Application is in a private environment`. -![](https://res.cloudinary.com/djwdcmwdz/image/upload/v1696941536/docs/app.tracetest.io_organizations_ttorg_e66318ba6544b856_environments_ttenv_0e807879e2e38d28_settings_j4zt1b.png) +![](https://res.cloudinary.com/djwdcmwdz/image/upload/v1712586955/docs/app.tracetest.io_organizations_ttorg_2179a9cd8ba8dfa5_environments_ttenv_597cf82c754c2a01_settings_ykn53w.png) ## Configure Tracetest Agent -Once started, Tracetest Agent exposes OTLP ports `4317` and `4318` to ingest traces via `gRPC` and `HTTP` and is responsible for running tests. Read the detailed concepts [here](../concepts/agent). +Once started, Tracetest Agent exposes OTLP ports `4317` and `4318` to ingest traces via `gRPC` and `HTTP` and is responsible for running tests. [Read the detailed concepts here](/concepts/agent). :::note -Unlike with [Tracetest Core](/core/getting-started/overview.mdx), you are not required to run a dedicated [Tracetest Server](/core/configuration/server.mdx). Running Tracetest Agent and using Tracetest as the remote server requires no configuration or infrastructure management. -::: - -If you are running the agent on a server and want to see detailed information about its execution, you can start the agent with the `--mode=verbose` flag: - +If you want to see detailed information about an isntance of Tracetest Agent, you can use the `--mode=verbose` flag: ![](https://res.cloudinary.com/djwdcmwdz/image/upload/v1701300172/docs/verbose-mode_ddv3ql.png) +::: diff --git a/docs/docs/configuration/cloud-agent.mdx b/docs/docs/configuration/cloud-agent.mdx new file mode 100644 index 0000000000..38f11f44fe --- /dev/null +++ b/docs/docs/configuration/cloud-agent.mdx @@ -0,0 +1,30 @@ +--- +id: cloud-agent +title: Configuring the Tracetest Cloud Agent (Public Access) +description: The Tracetest Agent enables Tracetest to access your application under test and to ingest trace data from your OpenTelemetry Collector or tracing backend. Learn how to configure the Tracetest Agent that runs in your environment as an executable, Docker container, or in your Cloud Native infrastructure. +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 Cloud Agent allows you to run Tracetest tests against public facing endpoints without deploying the Tracetest Agent locally. This allows you to trigger tests against public endpoints and collect trace data from either public tracing backends or, alternatively, directly receive incoming OTLP data. + +Tracetest Cloud Agent is the same as Tracetest Agent but is managed and running as part of your Tracetest account. + +## Start Tracetest Cloud Agent + +Tracetest Cloud Agent runs in your Tracetest account. + +[Sign in to Tracetest](https://app.tracetest.io/) and follow the instructions on the `Settings > Access` page. + +Select `Application is publicly accessible`. + +![](https://res.cloudinary.com/djwdcmwdz/image/upload/v1712602150/docs/app.tracetest.io_organizations_ttorg_2179a9cd8ba8dfa5_environments_ttenv_597cf82c754c2a01_settings_2_bs2zc9.png) + +## Configure Tracetest Cloud Agent + +Once started, Tracetest Cloud Agent exposes TLS port `443` to ingest traces via `gRPC` and `HTTP` and is responsible for running tests. [Read the detailed concepts here](/concepts/cloud-agent). diff --git a/docs/docs/configuration/connecting-to-data-stores/overview.mdx b/docs/docs/configuration/connecting-to-data-stores/overview.mdx new file mode 100644 index 0000000000..904438243b --- /dev/null +++ b/docs/docs/configuration/connecting-to-data-stores/overview.mdx @@ -0,0 +1,56 @@ +--- +id: overview +title: Connecting to Tracing Backends +description: Tracetest allows you to quickly build integration and end-to-end tests, powered by your OpenTelemetry traces. Learn how to connect tracing backends. +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 supports two types of tracing backend integrations. + +## 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. + +## OTLP Ingest Endpoint + +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. + +## Supported Tracing Backends + +Currently, Tracetest supports the following data stores. Click on the respective data store to view configuration examples: + +- [AWS X-Ray](/configuration/connecting-to-data-stores/awsxray) +- [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) + +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. + +View [configuration for OpenTelemetry Collector](/configuration/connecting-to-data-stores/opentelemetry-collector) for more details. + +## Tracing Backend Configuration Examples + +- View the [`examples` folder of the Tracetest GitHub repo](https://github.com/kubeshop/tracetest/tree/main/examples). +- Follow the [**Recipes**](/examples-tutorials/recipes) for guided walkthroughs of sample use cases. + +We will be adding new data stores over the next couple of months - [let us know](https://github.com/kubeshop/tracetest/issues/new/choose) any additional data stores you would like to see us support. diff --git a/docs/docs/configuration/overview.mdx b/docs/docs/configuration/overview.mdx index 8d1ae430b2..2dea8d6f28 100644 --- a/docs/docs/configuration/overview.mdx +++ b/docs/docs/configuration/overview.mdx @@ -1,7 +1,7 @@ --- id: overview title: Configuration -description: Tracetest allows you to quickly build integration and end-to-end tests, powered by your OpenTelemetry traces. Learn how to get started with creating tests once you open Tracetest. +description: Tracetest allows you to quickly build integration and end-to-end tests, powered by your OpenTelemetry traces. Learn how to configure Tracetest. keywords: - tracetest - trace-based testing @@ -11,40 +11,29 @@ keywords: image: https://res.cloudinary.com/djwdcmwdz/image/upload/v1698686403/docs/Blog_Thumbnail_14_rsvkmo.jpg --- -There is one configuration option with Tracetest: +To enable Tracetest to run end-to-end tests against trace data, you need to configure access. Tracetest is designed to work with tracing backends, or to ingest trace data via an OTLP ingest endpoint. -- [Agent configuration](/configuration/agent) to run it locally, in Docker, or Kubernetes. +## Enable Tracetest to Access Your Application -## Supported Trace Data Stores +There are two configuration options for triggering tests and ingesting trace data into Tracetest: -Tracetest is designed to work with different trace data stores. To enable Tracetest to run end-to-end tests against trace data, you need to configure Tracetest to access trace data. +- [Tracetest Agent configuration (private access)](/configuration/agent): You run an agent locally in your environment, as a process, or in Docker/Kubernetes as a container. Prefferred option if you are using a VPC, firewall, etc. +- [Tracetest Cloud Agent configuration (public access)](/configuration/cloud-agent): We run an agent in your Tracetest account with publicly accesible endpoints. You manage nothing. Prefferred option if you are using serverless architectures. -Currently, Tracetest supports the following data stores. Click on the respective data store to view configuration examples: +## Connecting Tracetest to Tracing Backends -- [AWS X-Ray](/configuration/connecting-to-data-stores/awsxray) -- [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) -- [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) +Tracetest supports [two types of tracing backend integrations](/configuration/connecting-to-data-stores/overview): -## Using Tracetest without a Trace Data Store +- Native connection (polling) +- OTLP ingest endpoint -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. +:::note Want to see your options? +[View the list of supported tracing backends, here.](/configuration/connecting-to-data-stores/overview#supported-tracing-backends) +::: -View [configuration for OpenTelemetry Collector](/configuration/connecting-to-data-stores/opentelemetry-collector) for more details. +## Access and Tracing Backend Configuration Examples -## Trace Data Store Configuration Examples - -Examples of configuring Tracetest to access different data stores can be found in the [`examples` folder of the Tracetest GitHub repo](https://github.com/kubeshop/tracetest/tree/main/examples). Check out the [**Recipes**](../examples-tutorials/recipes.mdx) for guided walkthroughs of sample use cases. +- View the [`examples` folder of the Tracetest GitHub repo](https://github.com/kubeshop/tracetest/tree/main/examples). +- Follow the [**Recipes**](/examples-tutorials/recipes) for guided walkthroughs of sample use cases. We will be adding new data stores over the next couple of months - [let us know](https://github.com/kubeshop/tracetest/issues/new/choose) any additional data stores you would like to see us support. diff --git a/docs/docs/examples-tutorials/recipes.mdx b/docs/docs/examples-tutorials/recipes.mdx index 84ae85820c..28b99a02ce 100644 --- a/docs/docs/examples-tutorials/recipes.mdx +++ b/docs/docs/examples-tutorials/recipes.mdx @@ -56,9 +56,9 @@ These recipes show how to run performance tests with distributed traces. - [Performance Testing with Distributed Tracing using Artillery, Playwright and Tracetest](/examples-tutorials/recipes/running-playwright-performance-tests-with-artillery-and-tracetest) -## Trace Data Stores +## Tracing Backends -These recipes show integrations with trace data stores and tracing vendors/providers. +These recipes show integrations with tracing backends and vendors/providers. ### OpenTelemetry Collector diff --git a/docs/sidebars.js b/docs/sidebars.js index 566c31f243..54e04a566a 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -566,9 +566,23 @@ const sidebars = { id: "configuration/overview", }, items: [ + { + type: "doc", + id: "configuration/agent", + label: "Tracetest Agent (Private Access)", + }, + { + type: "doc", + id: "configuration/cloud-agent", + label: "Tracetest Cloud Agent (Public Access)", + }, { type: "category", - label: "Connecting to Data Stores", + label: "Connecting to Tracing Backends", + link: { + type: "doc", + id: "configuration/connecting-to-data-stores/overview", + }, items: [ { type: "doc", @@ -652,11 +666,6 @@ const sidebars = { }, ], }, - { - type: "doc", - id: "configuration/agent", - label: "Tracetest Agent", - }, { type: "doc", id: "configuration/tracetest-analyzer",