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 <[email protected]> * Update docs/docs/concepts/agent.mdx Co-authored-by: Julianne Fermi <[email protected]> * Update docs/docs/configuration/agent.mdx Co-authored-by: Julianne Fermi <[email protected]> * docs(agent): added another bullet --------- Co-authored-by: Julianne Fermi <[email protected]>
kubeshop · Oct 17, 2023 · 9ee7a08 · 9ee7a08
1 parent a91e7a8
commit 9ee7a08
Show file tree

Hide file tree

Showing 4 changed files with 49 additions and 7 deletions.
diff --git a/docs/docs/concepts/agent.mdx 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
@@ -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
@@ -16,15 +16,15 @@ 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
 
 <GtagInstallCliTabs></GtagInstallCliTabs>
 
 ## 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.
 
 <Tabs groupId="installation">
   <TabItem value="cli" label="Tracetest CLI" default>

diff --git 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",