Web (HTTP API and UI)

Active contributors: juliusv, nexucis, roidelapluie

Purpose

web/ exposes Prometheus over HTTP. It serves:

• The v1 JSON API at /api/v1/... — queries, series, labels, status, admin.
• The remote write/read endpoints (handlers from storage/remote/).
• The OTLP metrics receiver.
• The federation endpoint at /federate.
• The embedded React UI (Mantine 3.x by default; 2.x available with --enable-feature=old-ui).
• The prometheus/exporter-toolkit config server (TLS + basic auth) when --web.config.file is set.

Directory layout

web/
├── web.go              # web.Handler: router + middleware + lifecycle.
├── web_test.go         # Routing tests.
├── federate.go         # /federate handler.
├── api/
│   ├── testhelpers/    # Test helpers shared with the full repo.
│   └── v1/
│       ├── api.go              # API struct, route registration, handlers (~2,400 lines).
│       ├── codec.go            # Pluggable response codecs.
│       ├── json_codec.go       # The default JSON codec (with NaN/Inf preservation).
│       ├── openapi.go          # Builder for the OpenAPI spec.
│       ├── openapi_paths.go    # Per-route metadata.
│       ├── openapi_schemas.go  # Schemas for inputs and outputs.
│       ├── openapi_examples.go
│       ├── openapi_helpers.go
│       ├── openapi_*_test.go   # Golden + coverage tests.
│       └── translate_ast.go    # Convert ASTs for the parse_query response.
└── ui/
    ├── mantine-ui/             # 3.x React UI (current default).
    ├── react-app/              # 2.x React UI (legacy, behind feature flag).
    ├── module/                 # Shared CodeMirror PromQL packages.
    ├── static/                 # Build output, embedded into the binary.
    ├── assets_embed.go         # `//go:embed static/*` (when builtinassets tag is set).
    ├── ui.go                   # Asset serving.
    └── README.md               # UI build & dev instructions.

API surface

The full route list is registered in web/api/v1/api.go::Register. Selected routes:

Method/Path	Handler	Purpose
GET/POST /query	api.query	Instant query.
GET/POST /query_range	api.queryRange	Range query.
GET/POST /query_exemplars	api.queryExemplars	Query exemplars.
GET/POST /format_query	api.formatQuery	Pretty-print PromQL.
GET/POST /parse_query	api.parseQuery	Return AST as JSON.
GET/POST /series	api.series	Series matchers.
GET/POST /labels	api.labelNames	Label name listing.
GET /label/:name/values	api.labelValues	Label value listing.
GET /scrape_pools	api.scrapePools	List pools (server mode).
GET /targets	api.targets	Active and dropped targets.
GET /targets/metadata	api.targetMetadata	Per-target metric metadata.
GET /targets/relabel_steps	api.targetRelabelSteps	Per-step relabel pipeline output.
GET /metadata	api.metricMetadata	Global metric metadata.
GET /alertmanagers	api.alertmanagers	Discovered AMs.
GET /alerts	api.alerts	Active alerts.
GET /rules	api.rules	Recording + alerting rules.
GET /status/config	api.serveConfig	Live config dump.
GET /status/runtimeinfo	api.serveRuntimeInfo	Runtime info struct.
GET /status/buildinfo	api.serveBuildInfo	Build info.
GET /status/flags	api.serveFlags	CLI flags.
GET /status/tsdb	api.serveTSDBStatus	TSDB cardinality stats (server mode).
GET /status/tsdb/blocks	api.serveTSDBBlocks	Block listing (server mode).
GET /status/walreplay	api.serveWALReplayStatus	WAL replay progress.
GET /features	api.features	Features registered via util/features.
GET /notifications / /notifications/live	api.notifications	UI notifications + SSE feed.
POST /read	remote.NewReadHandler	Remote read.
POST /write	remote.NewWriteHandler	Inbound remote write (v1/v2).
POST /otlp/v1/metrics	remote.NewOTLPWriteHandler	OTLP receiver.
POST/PUT /admin/tsdb/delete_series	api.deleteSeries	Tombstone series.
POST/PUT /admin/tsdb/clean_tombstones	api.cleanTombstones	Force tombstone compaction.
POST/PUT /admin/tsdb/snapshot	api.snapshot	Snapshot blocks (and head).
GET /openapi.yaml	api.openAPIBuilder.ServeOpenAPI	Self-describing API.

Admin endpoints require --web.enable-admin-api. Lifecycle endpoints (/-/reload, /-/quit) require --web.enable-lifecycle.

Codecs

web/api/v1/codec.go lets the API negotiate a response format via Accept. The default is the JSON codec in json_codec.go. Other codecs (e.g. protobuf for streamed reads) can be installed via api.InstallCodec(...). A custom JSON encoder (jsoniter based) is used to preserve NaN/+Inf and to keep the format stable across Go versions.

OpenAPI

The spec is built programmatically: openapi_paths.go, openapi_schemas.go, and openapi_examples.go define metadata per route, and the builder in openapi.go produces the YAML. A golden test (openapi_golden_test.go) compares the generated spec to web/api/v1/testdata/openapi.yaml. Updates to API behaviour must update the metadata; the test fails otherwise.

The 3.10 release added OpenAPI 3.1 + 3.2 support (#17825).

Federation

web/federate.go implements /federate?match[]=.... It runs queries through the engine and returns OpenMetrics text. Federation has its own scrape protocol negotiation (it speaks the same protocol as the upstream scrape configs).

UI assets

By default the binary embeds web/ui/static/{mantine-ui,react-app} via //go:embed (web/ui/assets_embed.go). Without the builtinassets build tag, the UI is served from web/ui/static on disk — useful for development. See web/ui/README.md for the dev server instructions and proxy configuration.

The Mantine UI is the default. Set --enable-feature=old-ui to switch to the legacy 2.x UI.

Agent-mode path allowlist

When --agent is active, several routes return "unavailable with Prometheus Agent". The list is enforced by the wrapAgent helper in api.go. UI routes that would be useless without local data (/graph, /alerts, /rules) are also redirected.

Self-metrics

• prometheus_http_request_duration_seconds{handler} — per-handler latencies.
• prometheus_http_response_size_bytes{handler} — response size histogram.
• prometheus_http_requests_total{code,handler} — counters per HTTP code.
• prometheus_engine_* for query handlers.

Security

The web layer integrates with prometheus/exporter-toolkit/web for TLS and basic auth. Use --web.config.file to point at a YAML config:

tls_server_config:
  cert_file: /etc/prometheus/tls/cert.pem
  key_file: /etc/prometheus/tls/key.pem

basic_auth_users:
  alice: $2y$10$<bcrypt hash>

Bcrypt password hashes only — plain-text passwords are rejected. See docs/configuration/https.md.

Entry points for modification

• New API endpoint: add a handler to api.go, register the route in Register, add metadata to openapi_paths.go/openapi_schemas.go/openapi_examples.go, run the golden test to regenerate.
• New codec: implement the Codec interface and install via api.InstallCodec.
• UI route: add it to oldUIReactRouterPaths or newUIReactRouterPaths in web.go so the React Router serves the SPA.
• Static asset: drop into web/ui/static/ (or its build inputs) and rebuild.

See API: v1 for the per-endpoint detail and Federation for the federation contract.