When Prometheus scrapes a target, it attaches some labels automatically to the
When Prometheus scrapes a target, it attaches some labels automatically to the
scraped metrics timeseries which serve to identify the scraped target:
scraped metrics timeseries which serve to identify the scraped target:
*`job`: The configured Prometheus job name for which the target was scraped.
*`job`: The configured Prometheus job name for which the target was scraped.
*`instance`: The specific URL of the instance's endpoint that was scraped.
*`instance`: The specific URL of the instance's endpoint that was scraped.
...
@@ -18,9 +18,9 @@ replaced. Instead, Prometheus adds its own labels with `exporter_` prepended to
...
@@ -18,9 +18,9 @@ replaced. Instead, Prometheus adds its own labels with `exporter_` prepended to
the label name: `exporter_job` and `exporter_instance`. The same pattern holds
the label name: `exporter_job` and `exporter_instance`. The same pattern holds
true for any manually supplied base labels supplied for a target group.
true for any manually supplied base labels supplied for a target group.
## Synthetic timeseries
## Synthetic timeseries
Prometheus also generates some timeseries internally which are not directly
Prometheus also generates some timeseries internally which are not directly
taken from the scraped data:
taken from the scraped data:
*`up`: for each endpoint scrape, a sample of the form `up{job="...", instance="..."}` is stored, with a value of `1.0` indicating that the target was successfully scraped (it is up) and `0.0` indicating that the endpoint is down.
*`up`: for each endpoint scrape, a sample of the form `up{job="...", instance="..."}` is stored, with a value of `1.0` indicating that the target was successfully scraped (it is up) and `0.0` indicating that the endpoint is down.
*`ALERTS`: for pending and firing alerts, a timeseries of the form `ALERTS{alertname="...", alertstate="pending|firing",...alertlabels...}` is written out. The sample value is 1.0 as long as the alert is in the indicated active (pending/firing) state, but a single 0.0 value gets written out when an alert transitions from active to inactive state.
*`ALERTS`: for pending and firing alerts, a timeseries of the form `ALERTS{alertname="...", alertstate="pending|firing",...alertlabels...}` is written out. The sample value is 1.0 as long as the alert is in the indicated active (pending/firing) state, but a single 0.0 value gets written out when an alert transitions from active to inactive state.
Prometheus provides a functional expression language that lets the user select
Prometheus provides a functional expression language that lets the user select
and aggregate timeseries data in real-time. The result of an expression can
and aggregate timeseries data in real-time. The result of an expression can
either be shown as a graph, viewed as data in the expression browser, or
either be shown as a graph, viewed as data in the expression browser, or
consumed and further processed by external systems via the HTTP API.
consumed and further processed by external systems via the HTTP API.
...
@@ -19,25 +19,25 @@ start with a couple of [examples](/docs/using/querying/examples).
...
@@ -19,25 +19,25 @@ start with a couple of [examples](/docs/using/querying/examples).
## Basic Concepts
## Basic Concepts
### Timeseries
### Timeseries
Data in Prometheus is stored as timeseries, which are uniquely identified by a
Data in Prometheus is stored as timeseries, which are uniquely identified by a
metric name and a set of arbitrary label/value pairs. Each timeseries can have
metric name and a set of arbitrary label/value pairs. Each timeseries can have
one or more data points attached to it. Data points are timestamp/value pairs.
one or more data points attached to it. Data points are timestamp/value pairs.
#### Metric name
#### Metric name
The metric name of a timeseries (e.g. `http_requests_total`) specifies the
The metric name of a timeseries (e.g. `http_requests_total`) specifies the
general feature of a system that is measured. It may contain alpha-numeric
general feature of a system that is measured. It may contain alpha-numeric
characters, plus underscores and colons.
characters, plus underscores and colons.
#### Labels
#### Labels
The label/value pairs which identify a timeseries allow later filtering and
The label/value pairs which identify a timeseries allow later filtering and
aggregation by these dimensions (e.g. `endpoint`, `response_code`, `instance`). Label keys
aggregation by these dimensions (e.g. `endpoint`, `response_code`, `instance`). Label keys
are identifiers (alpha-numeric characters plus underscores, but no colons),
are identifiers (alpha-numeric characters plus underscores, but no colons),
while their values may be arbitrary strings.
while their values may be arbitrary strings.
#### Data points
#### Data points
Each timeseries can have one or more data points attached to it, which are
Each timeseries can have one or more data points attached to it, which are
timestamp/value pairs. Values are always encoded as floating-point numbers
timestamp/value pairs. Values are always encoded as floating-point numbers
(currently 64-bit precision).
(currently 64-bit precision).
...
@@ -48,8 +48,8 @@ evaluate to one of four types:
...
@@ -48,8 +48,8 @@ evaluate to one of four types:
***string**
***string**
***scalar** - simple numeric floating point value
***scalar** - simple numeric floating point value
***instant vector** - vector of multiple timeseries, containing a single sample for each timeseries, with all samples sharing the same (instant) timestamp
***instant vector** - vector of multiple time series, containing a single sample for each time series, with all samples sharing the same (instant) timestamp
***range vector** - vector of multiple timeseries, containing a range of data points over time for each timeseries
***range vector** - vector of multiple time series, containing a range of data points over time for each time series
Depending on the use-case (e.g. when graphing vs. displaying the output of an
Depending on the use-case (e.g. when graphing vs. displaying the output of an
expression), only some of these types are legal as the result from a
expression), only some of these types are legal as the result from a
...
@@ -73,24 +73,24 @@ Scalar float values can be literally written as numbers of the form
...
@@ -73,24 +73,24 @@ Scalar float values can be literally written as numbers of the form
-2.43
-2.43
## Timeseries Selectors
## Timeseries Selectors
### Instant Vector Selectors
### Instant Vector Selectors
Instant vector selectors allow the selection of a set of timeseries and a
Instant vector selectors allow the selection of a set of timeseries and a
single sample value for each at a given timestamp (instant): in the simplest
single sample value for each at a given timestamp (instant): in the simplest
form, only a metric name is specified. This results in an instant vector
form, only a metric name is specified. This results in an instant vector
containing elements for all timeseries that have this metric name.
containing elements for all timeseries that have this metric name.
This example selects all timeseries that have the `http_requests_total` metric
This example selects all timeseries that have the `http_requests_total` metric
name:
name:
http_requests_total
http_requests_total
It is possible to filter these timeseries further by appending a set of labels
It is possible to filter these timeseries further by appending a set of labels
to match in curly braces (`{}`).
to match in curly braces (`{}`).
This example selects only those timeseries with the `http_requests_total`
This example selects only those timeseries with the `http_requests_total`
metric name that also have the `job` label set to `prometheus` and their
metric name that also have the `job` label set to `prometheus` and their
`group` label set to `canary`:
`group` label set to `canary`:
...
@@ -104,7 +104,7 @@ again regular expressions. The following label matching operators exist:
...
@@ -104,7 +104,7 @@ again regular expressions. The following label matching operators exist:
*`=~`: Select labels that regex-match the provided string (or substring).
*`=~`: Select labels that regex-match the provided string (or substring).
*`!~`: Select labels that do not regex-match the provided string (or substring).
*`!~`: Select labels that do not regex-match the provided string (or substring).
For example, this selects all `http_requests_total` timeseries for `staging`,
For example, this selects all `http_requests_total` timeseries for `staging`,
`testing`, and `development` environments and HTTP methods other than `GET`.
`testing`, and `development` environments and HTTP methods other than `GET`.
<pclass="desc">A flexible query languge allows slicing and dicing of collected timeseries data in order to generate ad-hoc graphs, tables, and alerts.</p>
<pclass="desc">A flexible query languge allows slicing and dicing of collected timeseries data in order to generate ad-hoc graphs, tables, and alerts.</p>
<pclass="desc">Prometheus stores timeseries in memory and on local disk in an efficient custom format. Scaling is achieved by functional sharding and federation.</p>
<pclass="desc">Prometheus stores timeseries in memory and on local disk in an efficient custom format. Scaling is achieved by functional sharding and federation.</p>