Documentation
Observability
Traces

Traces

The agentgateway integrates with Jaeger as the tracing platform. Jaeger is an open source tool that helps you follow the path of a request as it is forwarded between agents. The chain of events and interactions are captured by an OpenTelemetry pipeline that is configured to send traces to the Jaeger agent. You can then visualize the traces by using the Jaeger UI.

Set up Jaeger

Use docker compose to spin up a Jaeger instance with the following components:

  • An OpenTelemetry collector that receives traces from the agentgateway. The collector is exposed on http://localhost:4317.
  • A Jaeger agent that receives the collected traces. The agent is exposed on http://localhost:14268.
  • A Jaeger UI that is exposed on http://localhost:16686.
docker compose -f - up -d <<EOF
services:
  jaeger:
    container_name: jaeger
    restart: unless-stopped
    image: jaegertracing/all-in-one:latest
    ports:
    - "127.0.0.1:16686:16686"
    - "127.0.0.1:14268:14268"
    - "127.0.0.1:4317:4317"
    environment:
    - COLLECTOR_OTLP_ENABLED=true

EOF

Configure the agentgateway

  1. Download a telemetry configuration for your agentgateway.

    curl -L https://raw.githubusercontent.com/agentgateway/agentgateway/refs/heads/main/examples/telemetry/config.yaml -o config.yaml

  2. Review the configuration file.

    cat config.yaml
    config.yaml
    config:
  tracing:
    otlpEndpoint: http://localhost:4317
binds:
- port: 3000
  listeners:
  - routes:
    - backends:
      - mcp:
          name: default
          targets:
          - name: everything
            stdio:
              cmd: npx
              args: ["@modelcontextprotocol/server-everything"]
    • Listener: An HTTP listener that listens for incoming traffic on port 3000.
    • Traces: The agentgateway is configured to send traces to the OpenTelemetry collector that you exposed on http://localhost:4317.
    • Backend: The agentgateway targets a sample, open source MCP test server, server-everything.

  3. Optional: To use the agentgateway UI playground later, add the following CORS policy to your config.yaml file. The config automatically reloads when you save the file.

    binds:
- post: 3000
  listeners:
  - routes:
    - policies:
        cors:
          allowOrigins:
            - "*"
          allowHeaders:
            - "*"
      backends:
...

  4. Run the agentgateway.

    agentgateway -f config.json

Verify traces

  1. Open the agentgateway UI to view your listener and target configuration.

  2. Connect to the MCP server with the agentgateway UI playground.

    1. From the navigation menu, click Playground.

    2. In the Testing card, review your Connection details and click Connect. The agentgateway UI connects to the target that you configured and retrieves the tools that are exposed on the target.

    3. Verify that you see a list of Available Tools.

  3. Verify access to a tool.

    1. From the Available Tools list, select the echo tool.

    2. In the message field, enter any string, such as hello world, and click Run Tool.

    3. Verify that you see your message echoed in the Response card.

  4. Open the Jaeger UI.

  5. View traces.

    1. From the Service drop down, select agentgateway.
    2. Click Find Traces.
    3. Verify that you can see trace spans for listing the MCP tools (list_tools) and calling a tool (call_tool).

Cleanup

Stop and remove the Jaeger container.

docker stop jaeger
docker rm jaeger
Metrics