[[["易于理解","easyToUnderstand","thumb-up"],["解决了我的问题","solvedMyProblem","thumb-up"],["其他","otherUp","thumb-up"]],[["很难理解","hardToUnderstand","thumb-down"],["信息或示例代码不正确","incorrectInformationOrSampleCode","thumb-down"],["没有我需要的信息/示例","missingTheInformationSamplesINeed","thumb-down"],["翻译问题","translationIssue","thumb-down"],["其他","otherDown","thumb-down"]],["最后更新时间 (UTC)：2025-07-21。"],[],[],null,["# PromQL compatibility\n\n[PromQL](https://prometheus.io/docs/prometheus/latest/querying/basics/) queries in\nGoogle Cloud Managed Service for Prometheus are partially evaluated at the\n[Monarch](https://research.google/pubs/pub50652/) backend, and there are some known differences\nin query results. This document describes the differences.\nOther than the differences listed in this document, the PromQL in Managed Service for Prometheus is at parity with the PromQL available in Prometheus version **2.44** .\n\n\u003cbr /\u003e\n\nPromQL functions added after Prometheus version **2.44** might not be\nsupported.\n\n\u003cbr /\u003e\n\nUTF-8 support\n-------------\n\n\u003cbr /\u003e\n\nPromQL for Cloud Monitoring supports [UTF-8 querying](https://prometheus.io/docs/guides/utf8/#querying).\n\nIf your Prometheus metric name only consists of alphanumeric characters plus the\n`_` or `:`\ncharacters, and if your label keys only consist of alphanumeric characters plus\nthe `_` character, then you can query using traditional PromQL syntax.\nFor example, a valid query might look like\n`job:my_metric:sum{label_key=\"label_value\"}`.\n\nHowever, if your Prometheus metric name uses any special characters\nexcept for the `_` or `:` characters, or if your label keys use any special\ncharacter except for the `_` character, then you have to construct your query\naccording to the [UTF-8 spec for PromQL](https://prometheus.io/docs/guides/utf8/#querying).\n\nUTF-8 metric names must be quoted and moved into the braces. Label names must\nalso be quoted if they contain legacy-incompatible characters. The following\nexample valid queries are all equivalent:\n\n- `{\"my.domain.com/metric/name_bucket\", \"label.key\"=\"label.value\"}`\n- `{__name__=\"my.domain.com/metric/name_bucket\", \"label.key\"=\"label.value\"}`\n- `{\"__name__\"=\"my.domain.com/metric/name_bucket\", \"label.key\"=\"label.value\"}`\n\n\u003cbr /\u003e\n\nMatching on metric names\n------------------------\n\n\u003cbr /\u003e\n\nOnly exact matching on metric names is supported. You must include\nan exact match on the metric name in your query.\n\nWe recommend the following workarounds for common scenarios that use a regular\nexpression matcher on the `__name__` label:\n\n- Prometheus adapter configurations often use the `=~` operator to match on multiple metric names. To fix this usage, expand the config to use a separate policy for each metric and name each metric explicitly. This also prevents you from accidentally autoscaling on unexpected metrics.\n- Regular expressions are often used to graph multiple non-dimensional metrics on the same chart. For example, if you have a metric like `cpu_`\u003cvar translate=\"no\"\u003eservicename\u003c/var\u003e`_usage`, you might use a wildcard to graph all your services together. Using non-dimensional metrics like this is an explicitly bad practice in Cloud Monitoring, and this practice leads to extremely poor query performance. To fix this usage, move all dimensionality into metric labels instead of embedding dimensions in the metric name.\n- Querying over multiple metrics is often used to see what metrics are available to query. We recommend you instead use the `/labels/__name__/values` call to discover metrics. You can also discover metrics using the Cloud Monitoring UI.\n- Matching multiple metrics is useful for seeing how many samples were scraped, ingested, and charged on a per-metric basis. Cloud Monitoring provides this information to you on the [Metrics Management](/monitoring/docs/metrics-management) page. You can also access this information as metric data by using the [Samples Ingested metric or the Samples Written by Attribution ID\n metric](/stackdriver/docs/managed-prometheus/cost-controls#identify-cost-sources).\n\n\u003cbr /\u003e\n\nStaleness\n---------\n\n\u003cbr /\u003e\n\n[Staleness](https://prometheus.io/docs/prometheus/latest/querying/basics/#staleness) is not supported in the\nMonarch backend.\n\n\u003cbr /\u003e\n\nCalculation of `irate`\n----------------------\n\n\u003cbr /\u003e\n\nWhen the lookback window for the [`irate`](https://prometheus.io/docs/prometheus/latest/querying/functions/#irate) function\nis less than the step size, we increase the window to the step size.\nMonarch requires this change to ensure that none of the input\ndata is completely ignored in the output. This difference applies to\n`rate` calculations as well.\n\n\u003cbr /\u003e\n\nCalculation of `rate` and `increase`\n------------------------------------\n\n\u003cbr /\u003e\n\nWhen the lookback window for the [`rate`](https://prometheus.io/docs/prometheus/latest/querying/functions/#rate) function\nis less than the step size, we increase the window to the step size.\nMonarch requires this change to ensure that none of the input data\nis completely ignored in the output. This difference applies to\n`irate` calculations as well.\n\nThere are differences in the interpolation and extrapolation calculations.\nMonarch uses a different interpolation algorithm than\nPrometheus, and this difference can lead to slightly different results.\nFor example, Monarch counter samples are stored with a time\nrange rather than the single timestamp that Prometheus uses. Therefore,\ncounter samples in Monarch can be included in a rate calculation\neven though the Prometheus timestamp would exclude them. This generally results\nin more accurate rate results, especially when querying over the beginning\nor end of the underlying time series.\n\n\u003cbr /\u003e\n\nCalculation of `histogram_quantile`\n-----------------------------------\n\n\u003cbr /\u003e\n\nA PromQL [`histogram_quantile`](https://prometheus.io/docs/prometheus/latest/querying/functions/#histogram_quantile)\ncalculation on a histogram with no samples produces a NaN value. The internal\nquery language's calculation produces no value;\nthe point at the timestamp is dropped instead.\n\nThe rate-calculation differences can also affect the input to\n`histogram_quantile` queries.\n\n\u003cbr /\u003e\n\nType-specific functions on\ndifferently typed metrics\n----------------------------------------------------\n\n\u003cbr /\u003e\n\nAlthough upstream Prometheus is weakly typed, Monarch is strongly\ntyped. This means that running functions specific to a single type on a\ndifferently typed metric (for example, running `rate()` on a GAUGE metric or\n`histogram_quantile()` on a COUNTER or untyped metric) doesn't work in\nManaged Service for Prometheus, even though these functions work in upstream\nPrometheus."]]
