Architecture

This page maps the major pieces of the Prometheus server and how a sample flows from a scrape target through to a query response. Drill into the subsystems section for code-level detail on each component.

High-level component diagram

graph TD
    subgraph Targets["Scrape targets"]
        APP[Instrumented apps<br/>/metrics endpoint]
    end

    subgraph SDProviders["Service discovery"]
        K8S[Kubernetes SD]
        EC2[AWS EC2 SD]
        FILE[file_sd]
        OTHER[~25 other SDs]
    end

    subgraph Server["prometheus server (cmd/prometheus)"]
        DM[discovery.Manager]
        SM[scrape.Manager]
        SP[scrapePool / scrapeLoop]
        STO[storage.Storage<br/>fanoutStorage]
        TSDB[(TSDB / Agent WAL)]
        QM[remote.QueueManager]
        RW[remote write target]
        RM[rules.Manager]
        ENG[promql.Engine]
        NTF[notifier.Manager]
        WEB[web.Handler<br/>HTTP API + UI]
    end

    subgraph External["External"]
        AM[Alertmanager]
        REMOTE[Remote write receiver<br/>e.g. Mimir, Thanos]
        UI[Browser / Grafana]
    end

    SDProviders -->|target groups| DM
    DM -->|targets| SM
    SM --> SP
    APP -->|HTTP scrape| SP
    SP -->|samples| STO
    STO --> TSDB
    STO --> QM
    QM -->|HTTP/protobuf| REMOTE
    RM -->|PromQL| ENG
    ENG -->|reads| TSDB
    RM -->|alerts| NTF
    NTF -->|HTTP| AM
    UI -->|/api/v1/...| WEB
    WEB -->|queries| ENG
    WEB -->|admin| TSDB

How a sample reaches the database

The cmd/prometheus/main.go entry point wires together the whole graph. The data path for a single scraped sample looks like this:

1. Service discovery resolves targets. Each configured *_sd_config block in prometheus.yml is parsed into a discovery.Config, registered via discovery.RegisterConfig (see discovery/registry.go), and managed by discovery.Manager in discovery/manager.go. Target groups flow over channels to subscribers.
2. The scrape manager turns target groups into scrape pools. scrape.Manager (scrape/manager.go) creates a scrapePool per scrape_config, which spawns a scrapeLoop goroutine per target. Loops are reconciled when new target groups arrive.
3. A scrape loop fetches and parses metrics. scrapeLoop in scrape/scrape.go makes the HTTP request, decompresses the response, and hands the body to a parser from model/textparse/ (Prometheus text, OpenMetrics, Prometheus protobuf, or OpenMetrics 1.0 protobuf).
4. Samples are appended through storage.Appender. The interface lives in storage/interface.go. The fanout storage (storage/fanout.go) splits writes between the local TSDB and any configured remote write queues.
5. The TSDB writes to the WAL and the head block. tsdb.DB.Appender() returns a headAppender (tsdb/head_append.go). On Commit(), samples are written to the WAL (tsdb/wlog/) and inserted into the in-memory Head (tsdb/head.go). Every two hours the head is compacted into an immutable on-disk block (tsdb/block.go, tsdb/compact.go).
6. Remote write batches and ships samples. storage/remote/queue_manager.go shards series across shards, batches into prompb.WriteRequest/writev2.Request payloads, and posts them over HTTP to remote endpoints.

How a query is evaluated

sequenceDiagram
    participant Client
    participant Web as web.Handler
    participant API as web/api/v1.API
    participant Engine as promql.Engine
    participant Q as storage.Querier
    participant TSDB

    Client->>Web: GET /api/v1/query_range?query=rate(...)
    Web->>API: route -> api.queryRange
    API->>Engine: NewRangeQuery(qs, start, end, step)
    Engine->>Engine: parser.ParseExpr (promql/parser)
    Engine->>Q: Querier(mint, maxt)
    Q->>TSDB: blockQuerier + headQuerier (fanout)
    Engine->>Engine: walk AST, evaluate at each step
    TSDB-->>Engine: ChunkSeriesSet
    Engine-->>API: Result (Matrix/Vector/Scalar)
    API-->>Web: JSON-encoded Response
    Web-->>Client: HTTP 200

The HTTP routing layer in web/web.go and web/api/v1/api.go accepts the request, the engine in promql/engine.go (~4,700 lines) parses and walks the AST, and querier implementations in tsdb/querier.go and storage/remote/read.go produce iterators over chunks.

Two server modes

Prometheus can run in either of two storage modes, selected by the --agent CLI flag:

• Server mode (default) uses tsdb.DB for full local storage with queries, rule evaluation, alerting, and remote-write fan-out.
• Agent mode uses tsdb/agent.DB (tsdb/agent/db.go), which keeps only a WAL and ships samples via remote write. The local TSDB, query engine, and rule evaluator are all disabled. See Agent mode.

Top-level directories

Directory	Purpose
cmd/	Server (prometheus) and CLI (promtool) main packages.
config/	prometheus.yml schema, parsing, and reloading (config/config.go).
discovery/	Service discovery framework and ~25 individual SD plugins.
model/	Domain primitives: labels, histograms, exemplars, relabel, textparse parsers.
notifier/	Alert dispatcher to Alertmanager (notifier/manager.go).
plugins/	Build-tag-controlled SD registration (plugins/plugin_*.go).
prompb/	Generated protobuf for remote write/read; v1 and v2 in prompb/io/....
promql/	Lexer, yacc parser, AST, and engine.
rules/	Recording and alerting rule manager (rules/manager.go, rules/group.go).
schema/	Metric type/unit metadata helpers shared by ingestion and OTLP.
scrape/	Scrape manager, scrape pools, and scrape loops.
storage/	Storage and Appender interfaces, fanout, and remote/ write/read.
template/	Go-template helpers used in alert templates and the console UI.
tracing/	OpenTelemetry tracing setup for the server.
tsdb/	The full local time series database: head, WAL, blocks, index, chunks, compaction.
util/	Shared utilities (annotations, compression, features registry, logging, pool, stats…).
web/	HTTP API v1, federation, and embedded UI assets.
documentation/	User-facing prom docs, examples, and the prometheus-mixin Jsonnet alerts/dashboards.

See Reference: Configuration for the YAML schema and Reference: Data models for the on-disk and wire formats.