Skip to content

Adapt data model for 3.x #2622

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Adapt data model for 3.x #2622

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 12 additions & 12 deletions content/docs/concepts/data_model.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,22 +17,22 @@ Every time series is uniquely identified by its metric name and optional key-val

***Metric names:***

* Specify the general feature of a system that is measured (e.g. `http_requests_total` - the total number of HTTP requests received).
* Metric names may contain ASCII letters, digits, underscores, and colons. It must match the regex `[a-zA-Z_:][a-zA-Z0-9_:]*`.

Note: The colons are reserved for user defined recording rules. They should not be used by exporters or direct instrumentation.

* Specify the general feature of a system that is measured (e.g. `http_requests_total` - the total number of HTTP requests received).
* In Prometheus 2.x, metric names must contain only ASCII letters, digits, underscores, and colons, matching `[a-zA-Z_:][a-zA-Z0-9_:]*`.
* In Prometheus 3.x, it is still recommended to use ASCII, but Unicode letters and special characters are also allowed in metric names. That include dashes `-` and dots `.`.
* To use metric names with Unicode characters or special characters in Prometheus 3.0 queries, you can reference the metric name between double quotes in curly braces. For example, to query a metric named `foo-bar`, use `{"foo-bar"}`. Other labels must be specified in the same curly braces: `{"goo-bar", foo="bar"}`.

Note: Colons are reserved for user-defined recording rules. They should not be used by exporters or in direct instrumentation code.

***Metric labels:***

* Enable Prometheus's dimensional data model to identify any given combination of labels for the same metric name. It identifies a particular dimensional instantiation of that metric (for example: all HTTP requests that used the method `POST` to the `/api/tracks` handler). The query language allows filtering and aggregation based on these dimensions.
* The change of any label's value, including adding or removing labels, will create a new time series.
* Labels may contain ASCII letters, numbers, as well as underscores. They must match the regex `[a-zA-Z_][a-zA-Z0-9_]*`.
* Label names beginning with `__` (two "_") are reserved for internal use.
* Label values may contain any Unicode characters.
* Labels with an empty label value are considered equivalent to labels that do not exist.

* Labels allow Prometheus to track different dimensions for the same metric name (for example, all HTTP POST requests to `/api/tracks`).
* A new time series is created whenever you add, remove, or change any label values.
* In Prometheus 2.x, label names use the regex `[a-zA-Z_][a-zA-Z0-9_]*`.
* In Prometheus 3.x, Unicode characters and special characters are also allowed. That include dashes `-` and dots `.`.
* Label names starting with `__` (two underscores) remain reserved for internal usage.
* Label values may contain any Unicode characters in both Prometheus 2.x and 3.0.
* To query label names with Unicode and special characters in Prometheus 3.0, simply specify them between double quotes: `sum by ("my-instance") (my_metric)`.

See also the [best practices for naming metrics and labels](/docs/practices/naming/).

Expand Down