Skip to main content

Prometheus Definitions

Metric types​

For Prometheus, there is still no difference between metric types. It converts all metrics to time series.

  • Counter
    • A counter is a cumulative metric that represents a single monotonically increasing counter whose value can only increase or be reset to zero on restart.
  • Gauge
    • A gauge is a metric that represents a single numerical value that can arbitrarily go up and down.
  • Histogram
    • A histogram samples observations (usually things like request durations or response sizes) and counts them in configurable buckets. It also provides a sum of all observed values.
  • Summary
    • Similar to a histogram, a summary samples observations (usually things like request durations and response sizes). While it also provides a total count of observations and a sum of all observed values, it calculates configurable quantiles over a sliding time window.

Data model​

Each time series is uniquely identified by its metric name and optional key-value pairs called labels. The metric name specifies the general feature of a system that is measured (for example http_requests_total, the total number of HTTP requests received). It can contain ASCII letters and digits, as well as underscores and colons. It must match the regex [a-zA-Z_:][a-zA-Z0-9_:]*.

  1. Only uppercase and lowercase letters, numbers, and underscore (_) can be used.
  2. You should not start a metric with an underscore, as they represent metrics for internal use by Prometheus.
  3. Colons (:) are reserved for user-defined recording rules. They should not be used by exporters or direct instrumentation.
  4. Label values can contain any Unicode character.

Labels enable Prometheus's dimensional data model: any combination of labels for the same metric name identifies a specific dimensional instantiation of that metric (for example: all HTTP requests that used the POST method to the /api/tracks handler). The query language allows filtering and aggregation based on these dimensions. Changing any label value, including adding or removing a label, will create a new time series.

A label with an empty value is considered non-existent.

Samples form the actual time series data. Each sample consists of:

  • a float64 value
  • a millisecond-precision timestamp

Given a metric name and a set of labels, time series are often identified using this notation:

<metric name>{<label name>=<label value>, ...}

For example, a time series with the metric name api_http_requests_total and the labels method="POST" and handler="/messages" could be written like this:

api_http_requests_total{method="POST", handler="/messages"}

This is the same notation that OpenTSDB uses.

Jobs vs Instances​

In Prometheus terms, an endpoint you can scrape is called an instance, usually corresponding to a single process. A collection of instances with the same purpose, a replicated process for scalability or reliability, for example, is called a job.

For example, an API server job with four replicated instances:

  • job: api-server
    • instance 1: 1.2.3.4:5670
    • instance 2: 1.2.3.4:5671
    • instance 3: 5.6.7.8:5670
    • instance 4: 5.6.7.8:5671

When Prometheus scrapes a target, it automatically attaches some labels to the scraped time series that serve to identify the target:

  • job: The configured job name that the target belongs to.
  • instance: The <host>:<port> part of the URL that was scraped.