Skip to content

Commit

Permalink
docs(config): total rework (#3780)
Browse files Browse the repository at this point in the history
* 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 <danielbdias@users.noreply.github.com>

---------

Co-authored-by: Daniel Baptista Dias <danielbdias@users.noreply.github.com>
  • Loading branch information
adnanrahic and danielbdias committed Apr 9, 2024
1 parent 823e609 commit 8166642
Show file tree
Hide file tree
Showing 7 changed files with 127 additions and 46 deletions.
2 changes: 1 addition & 1 deletion docs/docs/concepts/agent.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand Down
17 changes: 7 additions & 10 deletions docs/docs/configuration/agent.mdx
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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)
:::
30 changes: 30 additions & 0 deletions docs/docs/configuration/cloud-agent.mdx
Original file line number Diff line number Diff line change
@@ -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).
56 changes: 56 additions & 0 deletions docs/docs/configuration/connecting-to-data-stores/overview.mdx
Original file line number Diff line number Diff line change
@@ -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.
43 changes: 16 additions & 27 deletions docs/docs/configuration/overview.mdx
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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.
4 changes: 2 additions & 2 deletions docs/docs/examples-tutorials/recipes.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
21 changes: 15 additions & 6 deletions docs/sidebars.js
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down Expand Up @@ -652,11 +666,6 @@ const sidebars = {
},
],
},
{
type: "doc",
id: "configuration/agent",
label: "Tracetest Agent",
},
{
type: "doc",
id: "configuration/tracetest-analyzer",
Expand Down

0 comments on commit 8166642

Please sign in to comment.