From 9ee7a082ded8e46a46dbe9917e0bbb22541c50e7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Adnan=20Rahi=C4=87?= Date: Tue, 17 Oct 2023 16:38:35 +0200 Subject: [PATCH] docs(agent): add more explanations about tracetest agent (#3271) * docs(agent): add more explanations about tracetest agent * Update docs/docs/concepts/agent.mdx Co-authored-by: Julianne Fermi * Update docs/docs/concepts/agent.mdx Co-authored-by: Julianne Fermi * Update docs/docs/configuration/agent.mdx Co-authored-by: Julianne Fermi * docs(agent): added another bullet --------- Co-authored-by: Julianne Fermi --- docs/docs/concepts/agent.mdx | 29 ++++++++++++++++++++++ docs/docs/configuration/agent.mdx | 16 +++++++++--- docs/docs/getting-started/installation.mdx | 4 +-- docs/sidebars.js | 7 +++++- 4 files changed, 49 insertions(+), 7 deletions(-) create mode 100644 docs/docs/concepts/agent.mdx diff --git a/docs/docs/concepts/agent.mdx b/docs/docs/concepts/agent.mdx new file mode 100644 index 0000000000..868916175f --- /dev/null +++ b/docs/docs/concepts/agent.mdx @@ -0,0 +1,29 @@ +--- +id: agent +title: Tracetest Agent +description: Tracetest allows you to quickly build integration and end-to-end tests, powered by your OpenTelemetry traces. +keywords: + - tracetest + - trace-based testing + - observability + - distributed tracing + - testing +image: https://res.cloudinary.com/djwdcmwdz/image/upload/v1689693872/docs/Blog_Thumbnail_28_ugy2yy.png +--- + +Tracetest Agent is a lightweight, dependency-free agent that runs locally in your development environment, or as a Docker container in your Cloud Native infrastructure. + +## How It Works + +- Tracetest Agent listens for new tests you run from [Tracetest](https://app.tracetest.io). It executes tests in the environment where it is running and returns the response from the trigger. The environment can be either `localhost`, Docker, or Kubernetes. +- Tracetest Agent listens on OTLP ports `4317` (gRPC) and `4318` (HTTP) for OpenTelemetry trace spans to capture distributed trace data and relay it to [Tracetest](https://app.tracetest.io). +- Be able to connect to a trace data store that is not accessible outside of your environment. Eg. a Jaeger instance running in the cluster without an ingress controller. +- With both the response and trace, you build tests and create assertions with data from either or both of them. + +## Architecture + +![](https://res.cloudinary.com/djwdcmwdz/image/upload/v1697464028/docs/agent-saas-oct-16-whitebg_i4stow.png) + +:::note +Want to start Tracetest Agent? Check out [this page to get started](../getting-started/installation). +::: diff --git a/docs/docs/configuration/agent.mdx b/docs/docs/configuration/agent.mdx index 0e67f08a4b..8bde8707b5 100644 --- a/docs/docs/configuration/agent.mdx +++ b/docs/docs/configuration/agent.mdx @@ -13,12 +13,20 @@ image: https://res.cloudinary.com/djwdcmwdz/image/upload/v1689693872/docs/Blog_T Tracetest Agent is a lightweight, dependency-free, agent that runs locally in your development environment, or as a Docker container in your Cloud Native infrastructure. -Once started, Tracetest Agent exposes OTLP ports `4317` and `4318` to ingest traces via gRCP and HTTP. Tracetest Agent connects to Tracetest via an API Key. +## Start Tracetest Agent -Unlike with Tracetest Core, you are not required to run a dedicated Tracetest Server. Running Tracetest Agent and using Tracetest as the remote server requires no configuration or infrastructure management. +Tracetest Agent connects to Tracetest via an API Key. -[Start Tracetest Agent](../getting-started/installation.mdx) in your environment to get started. +[Start Tracetest Agent](../getting-started/installation.mdx) in your environment to begin testing! -Or, [sign in to Tracetest](https://app.tracetest.io/) and follow the instructions on the Agent Settings page. +Or, [sign in to Tracetest](https://app.tracetest.io/) and follow the instructions on the `Settings > Agent` page. ![](https://res.cloudinary.com/djwdcmwdz/image/upload/v1696941536/docs/app.tracetest.io_organizations_ttorg_e66318ba6544b856_environments_ttenv_0e807879e2e38d28_settings_j4zt1b.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). + +:::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. +::: diff --git a/docs/docs/getting-started/installation.mdx b/docs/docs/getting-started/installation.mdx index fb969287a2..a79c2ad6e4 100644 --- a/docs/docs/getting-started/installation.mdx +++ b/docs/docs/getting-started/installation.mdx @@ -16,7 +16,7 @@ import TabItem from '@theme/TabItem'; import CodeBlock from '@theme/CodeBlock'; import GtagInstallCliTabs from '@site/src/components/GtagInstallCliTabs'; -This page showcases getting started with Tracetest by using the Tracetest CLI and Agent. +This page showcases getting started with [Tracetest](https://app.tracetest.io/) by using the Tracetest CLI and Tracetest Agent. ## Install the Tracetest CLI @@ -24,7 +24,7 @@ This page showcases getting started with Tracetest by using the Tracetest CLI an ## Install the Tracetest Agent -Tracetest Agent runs as a standalone process. It runs either locally on your machine or as a container. Once started the Agent exposes OTLP ports `4317` (gRPC) and `4318` (HTTP) for trace ingestion. +[Tracetest Agent](../concepts/agent) runs as a standalone process. It runs either locally on your machine or as a container. Once started, Tracetest Agent exposes OTLP ports `4317` (gRPC) and `4318` (HTTP) for trace ingestion. It executes tests in the environment where it is running and returns the response from triggered tests. diff --git a/docs/sidebars.js b/docs/sidebars.js index 5c2461a2d3..08b09bcba4 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -557,7 +557,7 @@ const sidebars = { { type: "doc", id: "configuration/agent", - label: "Tracetest Agent Configuration", + label: "Tracetest Agent", }, { type: "doc", @@ -600,6 +600,11 @@ const sidebars = { // id: "concepts/what-is-tracing", // label: "What is tracing", // }, + { + type: "doc", + id: "concepts/agent", + label: "Agent", + }, { type: "doc", id: "concepts/architecture",