Start Tracetest Agent

Tracetest Agent runs alongside your apps, in the same environment/network, to do two things:

1. Run tests against your apps.
2. Ingest traces from your apps.

This page explains (1), how to start Tracetest Agent to enable running tests against your apps. Tracetest Agent can run either locally on your machine or as a container in Docker or Kubernetes.

Tracetest CLI

Terminal

tracetest start --api-key <TRACETEST_API_KEY> --environment <TRACETEST_ENVIRONMENT_ID>

Expected output:

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...
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

Docker

Terminal

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

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 <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

Docker Compose

docker-compose.yaml

tracetest-agent:
  image: kubeshop/tracetest-agent
  environment:
    - TRACETEST_API_KEY=<TRACETEST_API_KEY>
    - TRACETEST_ENVIRONMENT_ID=<TRACETEST_ENVIRONMENT_ID>
  ports:
    - 4317:4317
    - 4318:4318

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 <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

tracetest-agent.yaml

---
# Service
apiVersion: v1
kind: Service
metadata:
  name: tracetest-agent
  labels:
    app.kubernetes.io/name: tracetest-agent
    app.kubernetes.io/instance: tracetest-agent
spec:
  selector:
    app.kubernetes.io/name: tracetest-agent
    app.kubernetes.io/instance: tracetest-agent
  ports:
    - name: grpc-collector-entrypoint
      protocol: TCP
      port: 4317
      targetPort: 4317
    - name: http-collector-entrypoint
      protocol: TCP
      port: 4318
      targetPort: 4318
---
# Deployment
apiVersion: apps/v1
kind: Deployment
metadata:
  name: tracetest-agent
  labels:
    app: tracetest-agent
    app.kubernetes.io/name: tracetest-agent
    app.kubernetes.io/instance: tracetest-agent
spec:
  selector:
    matchLabels:
      app.kubernetes.io/name: tracetest-agent
      app.kubernetes.io/instance: tracetest-agent
  template:
    metadata:
      labels:
        app.kubernetes.io/name: tracetest-agent
        app.kubernetes.io/instance: tracetest-agent
    spec:
      containers:
        - name: agent
          image: "kubeshop/tracetest-agent:latest"
          imagePullPolicy: Always
          args: [
            "--environment",
            "<TRACETEST_ENVIRONMENT_ID>", # Add your env id
            "--api-key",
            "$TRACETEST_API_KEY",
            "--server-url",
            "https://app.tracetest.io",
          ]
          env:
          - name: TRACETEST_API_KEY
            value: "<TRACETEST_API_KEY>" # Add your API key

Terminal

kubectl apply -f ./tracetest-agent.yaml

K8s Network

Make sure to check use the correct <service-name> if you edit the Tracetest Agent service name.

Running a test against localhost will resolve as 127.0.0.1 inside the Tracetest Agent container. Make sure to run tests using the internal Kubernetes service networking eg: http://api.default.svc.cluster.local:port.

Helm

Terminal

helm repo add tracetestcloud https://kubeshop.github.io/tracetest-cloud-charts --force-update && \

helm install agent tracetestcloud/tracetest-agent \
--set agent.apiKey=<TRACETEST_API_KEY> --set agent.environmentId=<TRACETEST_ENVIRONMENT_ID>

K8s Network

Running a test against localhost will resolve as 127.0.0.1 inside the Tracetest Agent container. Make sure to run tests using the internal Kubernetes service networking eg: http://pokeshop-pokemon-api:8081.