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 搭配 managed collection 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"]],["上次更新時間：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)."]]
