From 0f99a2c745870e1635ef1507fcf6565448139451 Mon Sep 17 00:00:00 2001 From: Adnan Rahic Date: Mon, 12 Aug 2024 17:31:02 +0200 Subject: [PATCH] docs(getting-started): updated flow and added on-prem --- docs/docs/getting-started/installation.mdx | 161 +++++++++++++----- docs/docs/getting-started/open.mdx | 58 +------ docs/docs/getting-started/overview.mdx | 12 +- docs/docs/index.mdx | 4 +- .../quick-start-nodejs/docker-compose.yaml | 3 + 5 files changed, 131 insertions(+), 107 deletions(-) diff --git a/docs/docs/getting-started/installation.mdx b/docs/docs/getting-started/installation.mdx index 6d7ecdf2a3..a13cdb33ff 100644 --- a/docs/docs/getting-started/installation.mdx +++ b/docs/docs/getting-started/installation.mdx @@ -17,21 +17,30 @@ import TabItem from '@theme/TabItem'; import CodeBlock from '@theme/CodeBlock'; import GtagInstallCliTabs from '@site/src/components/GtagInstallCliTabs'; -This page showcases getting started with [Tracetest](https://app.tracetest.io/) by using the Tracetest CLI and Tracetest Agent. +This page showcases getting started with [Tracetest](https://app.tracetest.io/). + +You can configure Cloud-based Managed Tracetest by using the Tracetest CLI and Tracetest Agent, or Enterprise Self-hosted Tracetest in your own infrastructure. + + + ## Install the Tracetest CLI +1. [Sign in to Tracetest](https://app.tracetest.io/). +2. Create an [Organization](/concepts/organizations) and [Environment](/concepts/environments). +3. Copy the default [Tracetest Organization API Key/Token](/concepts/organization-tokens) from your Tracetest Organization Tokens page. (Or create a new token.) +4. Copy the Environment ID from your Tracetest Environment Settings page. +5. Configure the CLI with your Organization API Key/Token and Environment ID. - - +```bash title="Terminal" +tracetest configure -t --environment +``` ## Install the Tracetest Agent -[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. - -[Sign in to Tracetest](https://app.tracetest.io/), and get your [Tracetest Agent API Key](/configuration/agent). +[Tracetest Agent](/concepts/agent) runs as a standalone process. It runs either locally on your machine or as a container. @@ -40,23 +49,26 @@ This page showcases getting started with [Tracetest](https://app.tracetest.io/) language="text" title="Terminal" > -{`tracetest start --api-key `} +{`tracetest start --api-key --environment `} -{`Defaulting to only available Environment: localMode - INFO Connecting Agent with name local to Organization org_name and Environment localMode - INFO Starting Agent with name local... -Agent is started! Leave the terminal open so tests can be run and traces gathered from this environment (env_name). -You can: [type to search]: +{`Tracetest start launches a lightweight agent. It enables you to run tests and collect traces with Tracetest. +Once started, Tracetest Agent exposes OTLP ports 4317 and 4318 to ingest traces via gRCP and HTTP. + + INFO Running in desktop mode... + INFO Starting Agent with name Adnans-Air... +Agent is started! Leave the terminal open so tests can be run and traces gathered from this environment. +You can: > Open Tracetest in a browser to this environment + (Experimental) Open Dashboard Stop this agent`} -The Tracetest Agent is running and ready to accept traces. +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. gRPC: `http://localhost:4317` @@ -69,20 +81,46 @@ HTTP: `http://localhost:4318/v1/traces` language="text" title="Terminal" > -{`docker run \\\n-p 4317:4317 \\\n-p 4318:4318 \\\n-e TRACETEST_API_KEY="" \\\nkubeshop/tracetest-agent`} +{`docker run \\\n -p 4317:4317 \\\n -p 4318:4318 \\\n -e TRACETEST_API_KEY="" \\\n -e TRACETEST_ENVIRONMENT_ID="" \\\n kubeshop/tracetest-agent`} +The Tracetest Agent is running in Docker and ready to accept traces. + +gRPC: `http://:4317` + +HTTP: `http://:4318/v1/traces` + +:::note Docker Network +Running a test against `localhost` will resolve as `127.0.0.1` inside the Tracetest Agent container. + +To run tests against apps running on your local machine you have two options: + +1. Run Tracetest Agent locally with the `tracetest start` command. +2. Add Tracetest Agent to the same network and use service name mapping. *Example: Instead of running an app on `localhost:8080`, add it to your Docker Compose file, connect it to the same network as your Tracetest Agent service, and use `:8080` in the URL field when creating a test.* + +You can reach services running on your local machine using: + +- Linux (docker version < 20.10.0): `172.17.0.1:8080` +- MacOS (docker version >= 18.03) and Linux (docker version >= 20.10.0): `host.docker.internal:8080` +::: + + + + -{`Defaulting to only available Environment: localMode - INFO Connecting Agent with name local to Organization org_name and Environment localMode - INFO Starting Agent with name local... -Agent is started! Leave the terminal open so tests can be run and traces gathered from this environment (env_name). -You can: [type to search]: -> Open Tracetest in a browser to this environment - Stop this agent`} +{`tracetest-agent: + image: kubeshop/tracetest-agent + command: + - "--mode=verbose" + environment: + - TRACETEST_API_KEY= + - TRACETEST_ENVIRONMENT_ID= + ports: + - 4317:4317 + - 4318:4318`} The Tracetest Agent is running in Docker and ready to accept traces. @@ -91,7 +129,7 @@ gRPC: `http://:4317` HTTP: `http://:4318/v1/traces` -:::note +:::note Docker Network Running a test against `localhost` will resolve as `127.0.0.1` inside the Tracetest Agent container. To run tests against apps running on your local machine you have two options: @@ -112,20 +150,7 @@ You can reach services running on your local machine using: language="text" title="Terminal" > -{`curl https://raw.githubusercontent.com/kubeshop/tracetest/main/k8s/agent/deploy-agent.sh | bash -s -- default `} - - - -{`Defaulting to only available Environment: localMode - INFO Connecting Agent with name local to Organization org_name and Environment localMode - INFO Starting Agent with name local... -Agent is started! Leave the terminal open so tests can be run and traces gathered from this environment (env_name). -You can: [type to search]: -> Open Tracetest in a browser to this environment - Stop this agent`} +{`curl https://raw.githubusercontent.com/kubeshop/tracetest/main/k8s/agent/deploy-agent.sh | bash -s -- default `} The Tracetest Agent is running in Kubernetes and ready to accept traces. @@ -134,7 +159,7 @@ gRPC: `http://:4317` HTTP: `http://:4318/v1/traces` -:::note +:::note K8s Network Running a test against `localhost` will resolve as `127.0.0.1` inside the Tracetest Agent container. To run tests against apps running on your local machine you have two options: @@ -151,13 +176,69 @@ You can reach services running on your local machine using: +## Start the Sample Pokeshop API + +To create tests quickly, start the official sample called [Pokeshop API](/live-examples/pokeshop/overview). + +```bash title="Terminal" +git clone --depth 1 https://github.com/kubeshop/tracetest.git +cd tracetest/examples/tracetest-agent/pokeshop/ + +docker compose up -d --build +``` + +- [`https://app.tracetest.io/`](https://app.tracetest.io) - Access the Tracetest Web UI. Sign up and create an organization. +- [`http://localhost:8081`](http://localhost:8081) and [`http://localhost:8081`](http://localhost:8081) - Access the Pokeshop API demo to run tests. +- `http://localhost:4317` / `http://localhost:4318` / `http://service-name:4317` / `http://service-name:4318` - Trace ingestion URL where Tracetest Agent will accept traces. + + +
+ + Click to view the sample Pokeshop API architecture + + +Here's the Architecture of the Pokeshop Sample App: + +- an **API** that serves client requests, +- a **Worker** who deals with background processes. + +The communication between the API and Worker is made using a `RabbitMQ` queue, and both services emit telemetry data to OpenTelemetry Collector and communicate with a Postgres database. + +Tracetest triggers tests against the Node.js API. + +```mermaid +flowchart TD + A[(Redis)] + B[(Postgres)] + C(Node.js API) + D(RabbitMQ) + E(Worker) + F(OpenTelemetry Collector) + G(Tracetest) + + G --> C + F --> G + C --> A + C --> B + C --> D + D --> E + E --> B + C --> F + E --> F + + +``` +
+ ## Install Tracetest On-Prem -:::note +:::tip For Development Environment This installation is meant for testing purposes only. It uses self signed certificates, so your browser will show a warning about it. + +For the Production-ready installation, [view the official Helm chart readme](https://github.com/kubeshop/tracetest-cloud-charts/blob/main/README.md). ::: 1. Install [Helm](https://helm.sh/) and [kind](https://kind.sigs.k8s.io/) on your machine. Clone the official Tracetest Helm chart. diff --git a/docs/docs/getting-started/open.mdx b/docs/docs/getting-started/open.mdx index 0d869344dd..638cfdec93 100644 --- a/docs/docs/getting-started/open.mdx +++ b/docs/docs/getting-started/open.mdx @@ -11,63 +11,7 @@ keywords: image: https://res.cloudinary.com/djwdcmwdz/image/upload/v1698686403/docs/Blog_Thumbnail_14_rsvkmo.jpg --- -This page showcases opening the Tracetest Web UI and creating a test against the [microservice sample Pokeshop API](/live-examples/pokeshop/overview). - -Once you've signed in to Tracetest, as explained in the [installation guide](./installation.mdx), the [Tracetest Agent](/concepts/agent) is running in your environment on ports `4317` and `4318`, or you'll get an API endpoint if you're using the [Tracetest Cloud Agent](/concepts/cloud-agent). - -You access the Tracetest Web UI on [`app.tracetest.io`](https://app.tracetest.io). Here's what will greet you after a fresh install. - -![Landing page Tracetest](https://res.cloudinary.com/djwdcmwdz/image/upload/v1688474565/docs/screely-1688474539641_kbhvvc.png) - -## Start the Sample Pokeshop API - -To create tests quickly, start the official sample called Pokeshop API. - -```bash title=Terminal -git clone --depth 1 https://github.com/kubeshop/tracetest.git -cd tracetest/examples/tracetest-agent/pokeshop/ -docker-compose up -``` - -This will start an HTTP API on `localhost:8081` and a GRPC API on `localhost:8082`. - -
- - Click to view the sample Pokeshop API architecture - - -Here's the Architecture of the Pokeshop Sample App: - -- an **API** that serves client requests, -- a **Worker** who deals with background processes. - -The communication between the API and Worker is made using a `RabbitMQ` queue, and both services emit telemetry data to OpenTelemetry Collector and communicate with a Postgres database. - -Tracetest triggers tests against the Node.js API. - -```mermaid -flowchart TD - A[(Redis)] - B[(Postgres)] - C(Node.js API) - D(RabbitMQ) - E(Worker) - F(OpenTelemetry Collector) - G(Tracetest) - - G --> C - F --> G - C --> A - C --> B - C --> D - D --> E - E --> B - C --> F - E --> F - - -``` -
+This page showcases opening [Tracetest](https://app.tracetest.io/) for the first time and creating tests. ## Creating Trace-based Tests diff --git a/docs/docs/getting-started/overview.mdx b/docs/docs/getting-started/overview.mdx index 6b5625b75e..ca6d6f20ca 100644 --- a/docs/docs/getting-started/overview.mdx +++ b/docs/docs/getting-started/overview.mdx @@ -23,25 +23,21 @@ import {TracetestGettingStartedGuideCardsRow, TracetestCoreGettingStartedGuideCa Tracetest is a cloud-native application, designed to run in the cloud. Get started in three ways. - **[Cloud-based Managed Tracetest](https://app.tracetest.io/) (Free to get started!)**: Use managed infrastructure with collaboration for teams, and additional features on top of Tracetest Core. -- **[Enterprise Self-hosted Tracetest](https://tracetest.io/on-prem-installation)**: Same experience as with Cloud-based Managed Tracetest but self-hosted in your own infrastructure. **([Request a demo!](https://dub.sh/tracetest-demo))** +- **[Enterprise Self-hosted Tracetest](https://tracetest.io/on-prem-installation) (Free trial, no credit card required)**: Same experience as with Cloud-based Managed Tracetest but self-hosted in your own infrastructure. **([Request a demo!](https://dub.sh/tracetest-demo))** - **[Hobby Self-hosted Open-source Tracetest Core](/core/getting-started/overview)**: Deploy a hobby instance in your own infrastructure with Docker or Kubernetes. Not suitable for production workloads. -## Cloud-based Managed Tracetest +## Cloud-based Managed Tracetest and Enterprise Self-hosted Tracetest **We recommend using [Cloud-based Managed Tracetest](https://app.tracetest.io/)**. It's the easiest way to test microservices and distributed apps with OpenTelemetry distributed traces. Tracetest provides managed infrastructure, [collaboration for teams](/concepts/environments), [RBAC](/concepts/roles-and-permissions), [organizations](/concepts/organizations), [dependency-free config](/concepts/agent), [agentless serverless config](/concepts/cloud-agent), and much more. Get started with the installation guide below, tailored for microservice and distributed app developers. You may find it insightful even if you have [one of many other supported use cases](/examples-tutorials/recipes). +If your organization requires you to keep data on-prem, you can use Enterprise Self-hosted Tracetest and deploy it in your own infrastructure. It contains the same features as Cloud-based Managed Tracetest. [Request a license key for Enterprise Self-hosted Tracetest, here.](https://tracetest.io/on-prem-installation) + ```mdx-code-block ``` -## Enterprise Self-hosted Tracetest - -If your organization requires you to keep data on-prem, you can use Enterprise Self-hosted Tracetest and deploy it in your own infrastructure. It contains the same features as Cloud-based Managed Tracetest. - -We recommend you try [Cloud-based Managed Tracetest](https://app.tracetest.io/) as a trial, and reach out to us to [request a demo](https://dub.sh/tracetest-demo) for Enterprise Self-hosted Tracetest. - ### Features Available in Cloud-based Managed Tracetest and Enterprise Self-hosted Tracetest #### All Tracetest Core features, plus... diff --git a/docs/docs/index.mdx b/docs/docs/index.mdx index 197637f0fd..c772b3915d 100644 --- a/docs/docs/index.mdx +++ b/docs/docs/index.mdx @@ -108,9 +108,9 @@ Tracetest is a cloud-native application, designed to run in the cloud. [Get star The easiest and most reliable way to test microservices and distributed apps with OpenTelemetry distributed traces is signing up for free at [app.tracetest.io](https://app.tracetest.io/). After creating an account, getting started is as easy as [installing the Tracetest Agent](/getting-started/installation). -### Enterprise Self-hosted Tracetest (Coming soon...) +### Enterprise Self-hosted Tracetest (Free trial, no credit card required) -Get the same experience as with the Cloud-based Managed Tracetest but self-hosted in your own infrastructure. [Book a call](https://dub.sh/tracetest-demo) to get into early access. +Get the same experience as with the Cloud-based Managed Tracetest but self-hosted in your own infrastructure. [Request a license key](https://tracetest.io/on-prem-installation) or [book a call](https://dub.sh/tracetest-demo) to get a trial. ### Hobby Self-hosted Open-source Tracetest Core diff --git a/examples/quick-start-nodejs/docker-compose.yaml b/examples/quick-start-nodejs/docker-compose.yaml index c1e9053c16..47bae6f8af 100644 --- a/examples/quick-start-nodejs/docker-compose.yaml +++ b/examples/quick-start-nodejs/docker-compose.yaml @@ -13,9 +13,12 @@ services: # Cloud-based Managed Tracetest tracetest-agent: image: kubeshop/tracetest-agent:latest + command: + - "--mode=verbose" environment: # Find the Agent API Key here: https://docs.tracetest.io/configuration/agent - TRACETEST_API_KEY=${TRACETEST_API_KEY} + - TRACETEST_ENVIRONMENT_ID=${TRACETEST_ENVIRONMENT_ID} ports: - 4317:4317 - 4318:4318