diff --git a/content/docs/concepts/data_model.md b/content/docs/concepts/data_model.md index 674f0d119..6fa583b09 100644 --- a/content/docs/concepts/data_model.md +++ b/content/docs/concepts/data_model.md @@ -17,42 +17,39 @@ 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. - +* Metric names SHOULD 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 use any UTF-8 characters. +* Metric names SHOULD match the regex `[a-zA-Z_:][a-zA-Z0-9_:]*` for the best experience and compatibility (see the warning below). Metric names outside of that set will require quoting e.g. when used in PromQL (see the [UTF-8 guide](../guides/utf8.md#querying)). +NOTE: Colons (':') are reserved for user-defined recording rules. They SHOULD NOT be used by exporters or direct instrumentation. ***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 let you capture different instances of the same metric name. For example: all HTTP requests that used the method `POST` to the `/api/tracks` handler. We refer to this as Prometheus's "dimensional data model". 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. + +* Label names MAY use any UTF-8 characters. +* Label names beginning with `__` (two underscores) MUST be reserved for internal Prometheus use. +* Label names SHOULD match the regex `[a-zA-Z_][a-zA-Z0-9_]*` for the best experience and compatibility (see the warning below). Label names outside of that regex will require quoting e.g. when used in PromQL (see the [UTF-8 guide](../guides/utf8.md#querying)). +* Label values MAY contain any UTF-8 characters. +* Labels with an empty label value are considered equivalent to labels that do not exist. +WARNING: The [UTF-8](../guides/utf8.md) support for metric and label names was added relatively recently in Prometheus v3.0.0. It might take time for the wider ecosystem (downstream PromQL compatible projects and vendors, tooling, third-party instrumentation, collectors, etc.) to adopt new quoting mechanisms, relaxed validation etc. For the best compatibility it's recommended to stick to the recommended ("SHOULD") character set. -See also the [best practices for naming metrics and labels](/docs/practices/naming/). +INFO: See also the [best practices for naming metrics and labels](/docs/practices/naming/). ## Samples Samples form the actual time series data. Each sample consists of: - * a float64 value - * a millisecond-precision timestamp - -NOTE: Beginning with Prometheus v2.40, there is experimental support for native -histograms. Instead of a simple float64, the sample value may now take the form -of a full histogram. +* a float64 or [native histogram](https://prometheus.io/docs/specs/native_histograms/) value +* a millisecond-precision timestamp ## Notation Given a metric name and a set of labels, time series are frequently identified using this notation: - {