Google Cloud Managed Service for Prometheus 只能注入附加到直方图指标的范例。无法注入附加到计数器指标的范例。Prometheus 直方图指标会转换为类似的 Cloud Monitoring Distribution 类型，该类型支持范例。Cloud Monitoring 中的非分布指标不支持范例。
范例在 24 个月内均可查询。将此保留期限与上游 Prometheus 进行比较，其中范例仅在数据位于内存中时保留（通常少于 14 天）。Managed Service for Prometheus 将范例与时序一起存储，因此根据时序的保留政策保留范例。如需详细了解 Cloud Monitoring 中的数据保留，请参阅数据保留。
启用范例注入
如果您将 Managed Service for Prometheus 与代管式集合版本 0.7.0 或更高版本搭配使用，则系统会自动启用范例注入。
如果您将 Managed Service for Prometheus 与自部署收集搭配使用，则必须在启动服务器时通过指定以下功能标志来启用范例注入：
[[["易于理解","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-09-04。"],[],[],null,["# Use Prometheus exemplars\n\nThis document describes how you can use Google Cloud Managed Service for Prometheus to\ningest [Prometheus exemplars](https://prometheus.io/docs/prometheus/latest/feature_flags/#exemplars-storage)\non histogram metrics. You must use one of the following:\n\n- Managed Service for Prometheus managed collection version 0.7.0 or higher\n- Managed Service for Prometheus self-deployed collection version 2.35.0-gmp.5-gke.0 or higher\n- The [OpenTelemetry Collector](https://opentelemetry.io/docs/collector/)\n\nExemplars are typically used to associate trace identifiers with metric\ndata collected in a time interval, but they can be used to associate any\nnon-metric data with the collected metrics. Storing trace information with\nthe metric data lets you quickly\nidentify the traces associated with a sudden change in metric values; you\ndon't have to manually cross-reference trace information and metric\ndata by using timestamps to identify what was happening in the application\nwhen the metric data was recorded.\n\nManaged Service for Prometheus exemplars are compatible both with [Cloud\nTrace](#trace-compatibility) and with 3rd-party trace tools such as Grafana\nTempo.\n\nThe following screenshot shows a Grafana chart of sets of histogram buckets and\nassociated exemplars, with one exemplar expanded:\n\nPrometheus exemplars in Managed Service for Prometheus\n------------------------------------------------------\n\nExemplars are supported in Prometheus by using the [OpenMetrics\nexposition format](https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md).\nAn OpenMetrics exemplar has the following structure:\n\n- The value of the exemplar: must be either an integer or a 64-bit float.\n- (Optional) A timestamp: must be [Unix Epoch\n seconds](https://timezonedb.com/unix-time), can be negative.\n- A number of labels for the exemplar, typically including `trace_id` and `span_id` values; the total length of all label names and values must not exceed 128 UTF-8 characters, or 128 [runes](https://go.dev/blog/strings) in Go applications.\n\nGoogle Cloud Managed Service for Prometheus can only ingest exemplars attached to histogram\nmetrics. **Exemplars attached to counter metrics can't be ingested.** Prometheus\nhistogram metrics are converted to the analogous Cloud Monitoring\n[`Distribution`](/monitoring/api/ref_v3/rest/v3/TypedValue#Distribution) type, which supports exemplars.\nNon-distribution metrics in Cloud Monitoring do not support\nexemplars.\n\nExemplars remain available for querying for\n24 months. Compare this retention period to\nupstream Prometheus, where exemplars are retained only while the data is\nin-memory, typically less than 14 days. Managed Service for Prometheus stores\nexemplars with the time series, so the exemplars are retained according to the\nretention policy for the time series. For more information about data retention\nin Cloud Monitoring, see\n[Data retention](/monitoring/quotas#data_retention_policy).\n\nEnable ingestion of exemplars\n-----------------------------\n\nIf you are using Managed Service for Prometheus with\n[managed collection](/stackdriver/docs/managed-prometheus/setup-managed) version 0.7.0\nor higher, then ingestion of exemplars is automatically enabled.\n\nIf you are using Managed Service for Prometheus with [self-deployed\ncollection](/stackdriver/docs/managed-prometheus/setup-unmanaged), then you must enable ingestion of exemplars when\nyou start\nthe server by specifying the following [feature\nflag](https://prometheus.io/docs/prometheus/latest/feature_flags/#exemplars-storage): \n\n```\n--enable-feature=exemplar-storage\n```\n\nWrite metrics with exemplars\n----------------------------\n\nEach Prometheus client has its own instructions for properly using\nexemplars in that client. Follow these instructions so that your application\nexposes metrics in the OpenMetrics format for Prometheus to scrape\nfrom the application's `/metrics` endpoint. For examples, see the following:\n\n- OpenTelemetry [Java example](https://github.com/open-telemetry/opentelemetry-java-docs/tree/main/prometheus#prometheus-example)\n- Prometheus [Java client](https://github.com/prometheus/client_java/blob/main/examples/example-exemplars-tail-sampling/README.md)\n- Prometheus [Python client](https://github.com/prometheus/client_python#exemplars)\n- Prometheus [Go client](https://github.com/prometheus/client_golang/blob/main/examples/exemplars/main.go)\n\nIntegrate with Cloud Trace\n--------------------------\n\nYou can write Prometheus histograms with exemplars that are compatible\nwith Cloud Trace. You can display the data, including the exemplars,\non a Cloud Monitoring heatmap chart, where you can use the exemplars to view\ndetails about the related trace spans. You can also analyze the trace data\nin Trace. For more information, see [Show exemplars on a heatmap\nchart](/monitoring/charts/working-with-charts#show-exemplars).\n\nTo create exemplars that are compatible with Trace, your\nPrometheus exemplars must contain the following labels:\n\n- `project_id`\n- `trace_id`\n- `span_id`\n\nIf your exemplar includes these three labels, then the labels are used to create\na Trace-compatible [`SpanContext`](/monitoring/api/ref_v3/rpc/google.monitoring.v3#spancontext) object\nthat is attached to the exemplar created for the Cloud Monitoring\n[`Distribution`](/monitoring/api/ref_v3/rest/v3/TypedValue#Distribution) bucket.\n\nAll labels other than those that make up a complete `SpanContext`\nare added to a [`DroppedLabels`](/monitoring/api/ref_v3/rpc/google.monitoring.v3#droppedlabels) object attached\nto the exemplar for a `Distribution` bucket.\n\nQuery metrics with exemplars\n----------------------------\n\nThe Prometheus API exposes the\n[`api/v1/query_exemplars`](https://prometheus.io/docs/prometheus/latest/querying/api/#querying-exemplars) endpoint for\nquerying exemplars.\n\nQuery interfaces set up to interact with Google Cloud Managed Service for Prometheus\nautomatically include exemplar querying. For information about setting\nup query interfaces, see [Query using Grafana](/stackdriver/docs/managed-prometheus/query) or [Query using the\nPrometheus API or UI](/stackdriver/docs/managed-prometheus/query-api-ui)."]]
