# jaegertracing/jaeger architecture

> Architecture diagram of the GitHub repository jaegertracing/jaeger, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jaegertracing/jaeger
- Repository: https://github.com/jaegertracing/jaeger
- Video tour (about a minute): https://gitdiagram.com/jaegertracing/jaeger/video

## Overview

Jaeger is a distributed tracing platform. The main documented workflow sends application traces to the collector, stores them, and exposes trace search through the query service and UI; sampling strategies can also flow back to applications. The repository additionally contains remote-storage serving, AI/MCP query tools, storage backends, and a Python query SDK. Edges use README statements or source-index references; unsampled implementation details are not inferred beyond those references.

Main entry points: [`cmd/jaeger/internal/extension/jaegerquery/internal/server.go`](https://github.com/jaegertracing/jaeger/blob/main/cmd/jaeger/internal/extension/jaegerquery/internal/server.go) (Query handlers), [`internal/storage/v1/api/spanstore/interface.go`](https://github.com/jaegertracing/jaeger/blob/main/internal/storage/v1/api/spanstore/interface.go) (Trace storage), [`cmd/jaeger/internal/components.go`](https://github.com/jaegertracing/jaeger/blob/main/cmd/jaeger/internal/components.go) (Collector), [`cmd/jaeger/internal/extension/jaegerquery/server.go`](https://github.com/jaegertracing/jaeger/blob/main/cmd/jaeger/internal/extension/jaegerquery/server.go) (Query service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Trace ingestion"]
  node_collector["Collector<br/>[components.go]"]
end

subgraph group_query["Query and exploration"]
  node_query_service["Query service<br/>[server.go]"]
  node_query_server["Query handlers<br/>[server.go]"]
  node_v3_parser["Trace query parser<br/>[query_parser.go]"]
  node_querysvc["Query service logic<br/>[service.go]"]
  node_ai_mcp["AI and MCP tools<br/>[routes.go]"]
  node_ui["Jaeger UI<br/>[assets.go]"]
end

subgraph group_storage["Storage"]
  node_storage[("Trace storage<br/>[interface.go]")]
  node_remote_storage["Remote storage server<br/>[server.go]"]
  node_cassandra_sampling[("Cassandra sampling store<br/>[storage.go]")]
end

subgraph group_sampling["Sampling"]
  node_sampling_api["Remote sampling<br/>[extension.go]"]
  node_adaptive_sampling["Adaptive sampling<br/>[processor.go]"]
end

subgraph group_tools["Operations and SDK"]
  node_python_query["Python query builder<br/>[query.py]"]
  node_python_client["Python query client<br/>[client.py]"]
  node_es_tools["Elasticsearch utilities<br/>[main.go]"]
end

node_app(("Instrumented app"))

node_app -->|"sends traces"| node_collector
node_collector -->|"stores traces"| node_storage
node_collector -->|"requests sampling"| node_sampling_api
node_sampling_api -->|"returns strategies"| node_app
node_query_service -->|"queries traces"| node_storage
node_ui -->|"uses HTTP"| node_query_service
node_query_server -->|"registers API"| node_v3_parser
node_v3_parser -->|"uses query logic"| node_querysvc
node_query_server -->|"uses service"| node_querysvc
node_query_server -->|"registers routes"| node_ai_mcp
node_query_service -->|"configures handlers"| node_query_server
node_python_client -->|"uses builder"| node_python_query
node_remote_storage -->|"serves storage API"| node_storage
node_es_tools -.->|"manages indices"| node_storage

click node_collector "https://github.com/jaegertracing/jaeger/blob/main/cmd/jaeger/internal/components.go"
click node_sampling_api "https://github.com/jaegertracing/jaeger/blob/main/cmd/jaeger/internal/extension/remotesampling/extension.go"
click node_query_service "https://github.com/jaegertracing/jaeger/blob/main/cmd/jaeger/internal/extension/jaegerquery/server.go"
click node_query_server "https://github.com/jaegertracing/jaeger/blob/main/cmd/jaeger/internal/extension/jaegerquery/internal/server.go"
click node_v3_parser "https://github.com/jaegertracing/jaeger/blob/main/cmd/jaeger/internal/extension/jaegerquery/internal/apiv3/query_parser.go"
click node_querysvc "https://github.com/jaegertracing/jaeger/blob/main/cmd/jaeger/internal/extension/jaegerquery/querysvc/service.go"
click node_ai_mcp "https://github.com/jaegertracing/jaeger/blob/main/cmd/jaeger/internal/extension/jaegerquery/internal/jaegerai/routes.go"
click node_ui "https://github.com/jaegertracing/jaeger/blob/main/cmd/jaeger/internal/extension/jaegerquery/internal/ui/assets.go"
click node_storage "https://github.com/jaegertracing/jaeger/blob/main/internal/storage/v1/api/spanstore/interface.go"
click node_remote_storage "https://github.com/jaegertracing/jaeger/blob/main/cmd/remote-storage/app/server.go"
click node_cassandra_sampling "https://github.com/jaegertracing/jaeger/blob/main/internal/storage/v1/cassandra/samplingstore/storage.go"
click node_adaptive_sampling "https://github.com/jaegertracing/jaeger/blob/main/cmd/jaeger/internal/processors/adaptivesampling/processor.go"
click node_python_query "https://github.com/jaegertracing/jaeger/blob/main/sdk/python/src/jaeger_query/query.py"
click node_python_client "https://github.com/jaegertracing/jaeger/blob/main/sdk/python/src/jaeger_query/client.py"
click node_es_tools "https://github.com/jaegertracing/jaeger/blob/main/cmd/es-rollover/main.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_collector toneBlue
class node_query_service,node_query_server,node_v3_parser,node_querysvc,node_ai_mcp,node_ui toneAmber
class node_storage,node_remote_storage,node_cassandra_sampling toneMint
class node_sampling_api,node_adaptive_sampling toneRose
class node_python_query,node_python_client,node_es_tools,node_app toneIndigo
```

## Components

### Trace ingestion

- [Collector](https://github.com/jaegertracing/jaeger/blob/main/cmd/jaeger/internal/components.go): `cmd/jaeger/internal/components.go`

### Query and exploration

- [Query service](https://github.com/jaegertracing/jaeger/blob/main/cmd/jaeger/internal/extension/jaegerquery/server.go): `cmd/jaeger/internal/extension/jaegerquery/server.go`
- [Query handlers](https://github.com/jaegertracing/jaeger/blob/main/cmd/jaeger/internal/extension/jaegerquery/internal/server.go): `cmd/jaeger/internal/extension/jaegerquery/internal/server.go`
- [Trace query parser](https://github.com/jaegertracing/jaeger/blob/main/cmd/jaeger/internal/extension/jaegerquery/internal/apiv3/query_parser.go): `cmd/jaeger/internal/extension/jaegerquery/internal/apiv3/query_parser.go`
- [Query service logic](https://github.com/jaegertracing/jaeger/blob/main/cmd/jaeger/internal/extension/jaegerquery/querysvc/service.go): `cmd/jaeger/internal/extension/jaegerquery/querysvc/service.go`
- [AI and MCP tools](https://github.com/jaegertracing/jaeger/blob/main/cmd/jaeger/internal/extension/jaegerquery/internal/jaegerai/routes.go): `cmd/jaeger/internal/extension/jaegerquery/internal/jaegerai/routes.go`
- [Jaeger UI](https://github.com/jaegertracing/jaeger/blob/main/cmd/jaeger/internal/extension/jaegerquery/internal/ui/assets.go): `cmd/jaeger/internal/extension/jaegerquery/internal/ui/assets.go`

### Storage

- [Trace storage](https://github.com/jaegertracing/jaeger/blob/main/internal/storage/v1/api/spanstore/interface.go): `internal/storage/v1/api/spanstore/interface.go`
- [Remote storage server](https://github.com/jaegertracing/jaeger/blob/main/cmd/remote-storage/app/server.go): `cmd/remote-storage/app/server.go`
- [Cassandra sampling store](https://github.com/jaegertracing/jaeger/blob/main/internal/storage/v1/cassandra/samplingstore/storage.go): `internal/storage/v1/cassandra/samplingstore/storage.go`

### Sampling

- [Remote sampling](https://github.com/jaegertracing/jaeger/blob/main/cmd/jaeger/internal/extension/remotesampling/extension.go): `cmd/jaeger/internal/extension/remotesampling/extension.go`
- [Adaptive sampling](https://github.com/jaegertracing/jaeger/blob/main/cmd/jaeger/internal/processors/adaptivesampling/processor.go): `cmd/jaeger/internal/processors/adaptivesampling/processor.go`

### Operations and SDK

- [Python query builder](https://github.com/jaegertracing/jaeger/blob/main/sdk/python/src/jaeger_query/query.py): `sdk/python/src/jaeger_query/query.py`
- [Python query client](https://github.com/jaegertracing/jaeger/blob/main/sdk/python/src/jaeger_query/client.py): `sdk/python/src/jaeger_query/client.py`
- [Elasticsearch utilities](https://github.com/jaegertracing/jaeger/blob/main/cmd/es-rollover/main.go): `cmd/es-rollover/main.go`

### Other components

- **Instrumented app**

## Connections

- Instrumented app → Collector: sends traces (evidence: `README.md`)
- Collector → Trace storage: stores traces (evidence: `README.md`)
- Collector → Remote sampling: requests sampling (evidence: `README.md`)
- Remote sampling → Instrumented app: returns strategies (evidence: `README.md`)
- Query service → Trace storage: queries traces (evidence: `README.md`)
- Jaeger UI → Query service: uses HTTP (evidence: `README.md`)
- Query handlers → Trace query parser: registers API (evidence: `cmd/jaeger/internal/extension/jaegerquery/internal/server.go`)
- Trace query parser → Query service logic: uses query logic (evidence: `cmd/jaeger/internal/extension/jaegerquery/internal/apiv3/query_parser.go`)
- Query handlers → Query service logic: uses service (evidence: `cmd/jaeger/internal/extension/jaegerquery/internal/server.go`)
- Query handlers → AI and MCP tools: registers routes (evidence: `cmd/jaeger/internal/extension/jaegerquery/internal/server.go`)
- Query service → Query handlers: configures handlers (evidence: `cmd/jaeger/internal/extension/jaegerquery/server.go`)
- Python query client → Python query builder: uses builder (evidence: `sdk/python/src/jaeger_query/client.py`)
- Remote storage server → Trace storage: serves storage API (evidence: `cmd/remote-storage/app/server.go`)
- Elasticsearch utilities → Trace storage: manages indices
