Installing Tracetest

This page showcases getting started with Tracetest by using the Tracetest CLI and Tracetest Agent.

Install the Tracetest CLI

MAC

Terminal

brew install kubeshop/tracetest/tracetest

LINUX

Terminal

curl -L https://raw.githubusercontent.com/kubeshop/tracetest/main/install-cli.sh | bash

WINDOWS

Terminal

choco source add --name=kubeshop_repo --source=https://chocolatey.kubeshop.io/chocolatey ; choco install tracetest

Install the Tracetest Agent

Tracetest 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, and get your Tracetest Agent API Key.

Tracetest CLI

Terminal

tracetest start --api-key <your_api_key>

Expected output:

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

The Tracetest Agent is running and ready to accept traces.

gRPC: http://localhost:4317

HTTP: http://localhost:4318/v1/traces

Docker

Terminal

docker run \
-p 4317:4317 \
-p 4318:4318 \
-e TRACETEST_API_KEY="<your_api_key>" \
kubeshop/tracetest-agent

Expected output:

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

The Tracetest Agent is running in Docker and ready to accept traces.

gRPC: http://<service-name>:4317

HTTP: http://<service-name>:4318/v1/traces

note

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 <service-name>: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

Kubernetes

Terminal

curl https://raw.githubusercontent.com/kubeshop/tracetest/main/k8s/agent/deploy-agent.sh | bash -s -- default <your_api_key>

Expected output:

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

The Tracetest Agent is running in Kubernetes and ready to accept traces.

gRPC: http://<service-name>:4317

HTTP: http://<service-name>:4318/v1/traces

note

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 <service-name>: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

Don't have OpenTelemetry installed?

Follow these instructions to install OpenTelemetry in 5 minutes without any code changes!