Prometheus: Metrics Monitoring and Alerting System

What Prometheus is

Prometheus is a systems and service monitoring system and a Cloud Native Computing Foundation project. It collects metrics from configured targets at given intervals, evaluates rule expressions, displays the results and can trigger alerts when specified conditions are observed. The server is written in Go and released under the Apache-2.0 licence.

The README lists the properties that distinguish it from other metrics and monitoring systems: a multi-dimensional data model in which a time series is identified by a metric name and a set of key/value dimensions; PromQL, a query language built to use that dimensionality; no dependency on distributed storage, so single server nodes are autonomous; an HTTP pull model for collecting time series; targets discovered through service discovery or static configuration; multiple modes of graphing and dashboarding; and hierarchical and horizontal federation. Batch jobs that cannot be scraped can push their series through an intermediary gateway.

The audience is anyone who has to watch many services and hosts and alert on them: platform and SRE teams, backend developers who instrument their own services, and operators of infrastructure where the state of hundreds of instances has to be queried and aggregated rather than inspected one by one.

How it works

Prometheus collects metrics from targets by scraping their metrics HTTP endpoints. The server exposes data about itself in the same way, which is why the official getting-started guide begins by configuring Prometheus to scrape its own endpoint on localhost:9090. Every scrape job adds a job label to the series it collects, and groups of targets can carry extra labels, such as group="production" and group="canary" in the guide's Node Exporter example. Those labels become dimensions that queries can filter and aggregate on.

Samples land in a local on-disk time series database. The storage documentation describes the layout: ingested samples are grouped into two-hour blocks, and each block is a directory with a chunks subdirectory, a metadata file and an index that maps metric names and labels to series. The block currently receiving samples is held in memory and protected by a write-ahead log, stored in 128 MB segments and replayed when the server restarts. In the background, compaction merges the two-hour blocks into larger ones spanning up to 10% of the retention time or 31 days, whichever is smaller.

The docs state that Prometheus stores an average of only 1–2 bytes per sample and give a rough capacity formula: needed disk space equals retention time in seconds multiplied by ingested samples per second and bytes per sample. They also note that reducing the number of series is usually more effective than lengthening the scrape interval, because samples within a series compress well.

On top of the stored data the server evaluates recording rules, which pre-compute expensive expressions into new persisted series, and alerting rules. The built-in web UI offers an expression browser and graphing at /query, a target health page and an "Explore metrics" view that lists every available metric name. For data that has to outlive a single node, Prometheus integrates with external systems through its remote read and remote write APIs.

Key features

• Labelled time series: each series is a metric name plus key/value labels, so one metric can be sliced by instance, job, environment or any label attached at scrape time.
• PromQL: a query language for selecting and aggregating series; the getting-started guide uses avg by (job, instance, mode) (rate(node_cpu_seconds_total[5m])) to average CPU rate per instance.
• Pull-based collection: the server scrapes HTTP endpoints on a scrape_interval set globally or overridden per job.
• Push for batch jobs: short-lived jobs can push series through an intermediary gateway instead of being scraped.
• Service discovery: targets come from static configuration or bundled service discovery plugins; builds can drop optional discoverers with Go build tags such as remove_all_sd and re-enable individual ones like enable_kubernetes_sd.
• Recording and alerting rules: rule files listed under rule_files are evaluated every evaluation_interval, turning heavy ad-hoc queries into cheap pre-computed series.
• Autonomous servers: each node runs on its own local storage with no distributed storage dependency.
• Federation and remote storage: hierarchical and horizontal federation, plus remote read/write APIs for external storage systems.
• Retention controls: --storage.tsdb.retention.time defaults to 15 days when no retention flag is set, --storage.tsdb.retention.size caps bytes on disk, and whichever limit triggers first applies.
• Two binaries: building produces the prometheus server and the promtool utility.

Getting started

The fastest way to try Prometheus, per the README, is the container image published on Quay.io and Docker Hub:

docker run --name prometheus -d -p 127.0.0.1:9090:9090 prom/prometheus

Prometheus is then reachable at http://localhost:9090/. For real installations the README recommends the latest production release binary from the download page. The getting-started guide extracts the archive and changes into it:

tar xvfz prometheus-*.tar.gz
cd prometheus-*/

It then saves a minimal prometheus.yml in which Prometheus scrapes itself:

global:
  scrape_interval:     15s # By default, scrape targets every 15 seconds.

  # Attach these labels to any time series or alerts when communicating with
  # external systems (federation, remote storage, Alertmanager).
  external_labels:
    monitor: 'codelab-monitor'

# A scrape configuration containing exactly one endpoint to scrape:
# Here it's Prometheus itself.
scrape_configs:
  # The job name is added as a label `job=<job_name>` to any timeseries scraped from this config.
  - job_name: 'prometheus'

    # Override the global default and scrape targets from this job every 5 seconds.
    scrape_interval: 5s

    static_configs:
      - targets: ['localhost:9090']

and starts the server with that file. By default the database is written to ./data:

./prometheus --config.file=prometheus.yml

From the expression browser, a first query such as prometheus_target_interval_length_seconds returns the actual time between scrapes, and count(prometheus_target_interval_length_seconds) counts the returned series. The guide continues by adding three Node Exporter targets and a recording rule.

Building from source requires the Go version in go.mod, the Node.js version in web/ui/.nvmrc and npm 10 or newer. make build compiles the web assets into the binary so it can run from anywhere:

git clone https://github.com/prometheus/prometheus.git
cd prometheus

make build
./prometheus --config.file=your_config.yml

Use cases

• Service monitoring: instrument services to expose a metrics endpoint, scrape them, and alert when error rates or latencies cross a threshold.
• Host and infrastructure metrics: scrape exporters such as the Node Exporter used in the official guide to track CPU, memory and disk per machine.
• Dynamic environments: let service discovery keep the target list current as instances come and go, for example in Kubernetes.
• Canary comparison: label groups of targets (production versus canary, as in the guide) and compare them side by side in PromQL.
• Pre-aggregated dashboards: use recording rules so dashboards query a cheap pre-computed series instead of aggregating thousands of raw series on every refresh.
• Batch job reporting: push results from cron-style jobs through the intermediary gateway.

How it compares

The README positions Prometheus against "other metrics and monitoring systems" in general rather than naming competitors, and its distinguishing choices are clear. Pull-based scraping means the server decides what to collect and when, and the target health page shows every endpoint as UP or DOWN; push-oriented agents and collectors invert that relationship. The single-node design keeps each server autonomous and simple to run, at the cost of built-in clustering and replication, which systems built on distributed storage provide out of the box. Prometheus's answer for long-term or highly durable storage is the remote read/write APIs, and the storage docs warn that systems behind those APIs "vary greatly in durability, performance, and efficiency" and need careful evaluation.

The project also separates the server from its libraries: repositories such as prometheus/common and prometheus/client_golang are the reusable pieces, while prometheus/prometheus builds a stand-alone program that the maintainers say is not designed to be used as a library.

Things to know before adopting

• Local storage is not clustered or replicated: the docs say it is not arbitrarily scalable or durable against drive or node outages and should be managed like any single-node database.
• Back up with snapshots: backups taken without the snapshot API risk losing data since the last block was cut, typically the last two to three hours.
• No NFS: non-POSIX filesystems are unsupported and NFS, including AWS EFS, is explicitly not supported; a local filesystem is strongly recommended.
• Disk headroom: size-based retention only deletes persisted blocks while counting the WAL and head chunks, compaction can briefly exceed the size limit, and expired blocks can take up to two hours to be removed.
• Go module versioning: v3.y.z releases are tagged as v0.3y.z Go modules, and internal Go APIs may break between minor releases.
• Plugins and images: out-of-tree service discovery plugins are not endorsed, the Remote Write protobuf on buf.build is experimental, and make docker is meant only for the project's CI.
• Licence: Apache-2.0, permissive and suitable for commercial use.

Project activity

As of October 2026 the repository has about 66,900 stars and 10,900 forks. It was created in November 2012, is written in Go and is licensed under Apache-2.0. The latest stable release is v3.15.1, published on October 21, 2026, the same day as a v3.13.5 patch release, and v3.16.0-rc.2 followed on October 28. The project carries CII Best Practices, OpenSSF Scorecard and OSS-Fuzz badges in its README. Source is at github.com/prometheus/prometheus, with documentation and downloads at prometheus.io.