prometheus

Prometheus is a CNCF-graduated monitoring system and time-series database. It scrapes metrics from configured HTTP endpoints on a schedule, stores them locally in its own purpose-built TSDB, and lets you query that data in real time with PromQL — a functional language built around Prometheus’s multi-dimensional label model rather than SQL.

Beyond the core scrape-and-store loop, Prometheus ships native service discovery for Kubernetes, AWS, Azure, GCP, Consul, Docker, Nomad, and a dozen other platforms so target lists track dynamic infrastructure automatically, plus rule-based alerting routed through Alertmanager and a remote-write/read API for federating into long-term stores like Thanos, Cortex, or Mimir. The project explicitly documents that the repository builds a stand-alone server binary and is not designed to be imported as a Go library — you run it, configure it via YAML, and talk to it over HTTP.

What You Get

• A single Go binary combining target discovery, a pull-based scraper, an embedded TSDB, a PromQL query engine, and a bundled web UI
• PromQL for ad-hoc querying, Grafana dashboards, and recording/alerting rule expressions
• Native service discovery for Kubernetes, AWS, Azure, GCP, Consul, Docker, Nomad, and more, in the discovery/ package
• Remote-write/read APIs for long-term storage and federation into systems like Thanos, Cortex, or Mimir
• promtool, a companion CLI for validating configs, unit-testing alerting rules, and inspecting TSDB blocks

Common Use Cases

• Monitoring Kubernetes clusters and containerized workloads via native service discovery
• Alerting on service-level objectives and infrastructure health through Alertmanager
• Long-term metrics retention by remote-writing to Thanos, Cortex, or Mimir
• Instrumenting applications with Prometheus client libraries to expose custom business metrics

Under The Hood

Architecture The binary wired up in cmd/prometheus/main.go composes a set of layered managers behind clear interfaces: discovery.Manager resolves scrape targets from 20+ platform integrations, scrape.Manager pulls metrics into the TSDB head block, storage.Storage is the seam that lets tsdb.DB and storage/remote fan out writes/reads without scrape or query code depending on either directly, promql.Engine executes queries against that storage interface, and rules.Manager evaluates alerting/recording rules and hands firing alerts to notifier.Manager for delivery to Alertmanager. Data flows one direction — discovery to scrape to TSDB to query/rules to web/notifier — which keeps the pipeline easy to reason about despite the large number of pluggable integrations.

Tech Stack Built on Go 1.26 with kingpin for CLI flag parsing, the module vendors extensive platform SDKs (AWS SDK v2, Azure SDK, Google Cloud, Kubernetes client-go, HashiCorp Consul/Nomad APIs) purely to power service discovery integrations. OpenTelemetry collector packages and OTLP exporters support tracing, gRPC and protobuf carry the remote-write v2 wire format, and klauspost/compress/golang/snappy handle chunk and remote-write compression. The bundled web/ui is a React application built with Node/npm and compiled into the Go binary via make assets; releases publish as Docker images to Quay and Docker Hub.

Code Quality Roughly two out of every five Go files in the repository is a test file, spanning unit tests, benchmarks (head_bench_test.go), and a dedicated PromQL golden-test suite (promqltest). Errors are handled explicitly and wrapped rather than swallowed, naming follows consistent Go conventions (Manager, Engine, Appender suffixes for core abstractions), and CI continuously runs go vet, CodeQL, govulncheck, and OSS-Fuzz alongside an OpenSSF Scorecard badge — indicating a mature, heavily gated contribution pipeline.

What Makes It Unique The combination of a multi-dimensional label model with a purpose-built local TSDB (write-ahead log plus immutable, compacted chunk-encoded blocks) is Prometheus’s defining technical choice: rather than depending on a distributed backend, single-server nodes are autonomous, and a pull-based scrape model paired with extensive native service discovery keeps target lists current in dynamic infrastructure without manual configuration. That design has become the reference architecture that later systems (Thanos, Cortex, Mimir, VictoriaMetrics) build on top of rather than replace.