Deprecate PromQL endpoint, promote OpenMetrics to GA (#4337)

dustin-temporal · claude · brianmacdonald-temporal · web-flow · commit 31dd236feb3e · 2026-03-31T14:35:42.000-05:00
- Add deprecation notices to PromQL-related pages (reference, general-setup,
  prometheus-grafana, promql) with April 2 2026 deprecation and October 5 2026
  disable dates
- Rewrite cloud/metrics landing page: title to "Temporal Cloud Metrics",
  lead with OpenMetrics, move PromQL to deprecated section at bottom
- Remove Public Preview designations from all OpenMetrics pages
- Update migration guide timeline with concrete deprecation dates
- Change OpenMetrics data lookback from 2 minutes to 3 minutes

Co-authored-by: Claude Opus 4.6 &lt;noreply@anthropic.com&gt;
Co-authored-by: Brian MacDonald &lt;brian.macdonald@temporal.io&gt;
Co-authored-by: Nish Krishnan &lt;nishkrishnan@users.noreply.github.com&gt;
diff --git a/docs/cloud/metrics/general-setup.mdx b/docs/cloud/metrics/general-setup.mdx
@@ -23,6 +23,16 @@ tags:
 
 import { RelatedReadContainer, RelatedReadItem } from '@site/src/components';
 
+:::danger PromQL endpoint deprecated
+
+The PromQL endpoint and its `temporal_cloud_v0_*` metrics were deprecated on April 2, 2026 and are no longer accepting new users.
+The PromQL endpoint will be disabled for all users on **October 5, 2026**.
+
+New users should set up the [OpenMetrics endpoint](/cloud/metrics/openmetrics) instead.
+Existing users should follow the [migration guide](/cloud/metrics/openmetrics/migration-guide) to transition to the OpenMetrics endpoint.
+
+:::
+
 You will learn how to do the following:
 
 - [Configure an endpoint using the UI](#configure-via-ui)
diff --git a/docs/cloud/metrics/index.mdx b/docs/cloud/metrics/index.mdx
@@ -1,8 +1,8 @@
 ---
 id: index
-title: Temporal Cloud Observability and Metrics
+title: Temporal Cloud Metrics
 sidebar_label: Metrics
-description: Get detailed insights using the Temporal SDK and Cloud Metrics.
+description: Monitor Temporal Cloud workloads with Cloud metrics and SDK metrics.
 slug: /cloud/metrics/
 toc_max_heading_level: 4
 keywords:
@@ -21,29 +21,42 @@ tags:
   - Temporal Cloud
 ---
 
-Temporal offers two distinct sources of metrics: [Cloud/Server Metrics](/cloud/metrics/reference) and [SDK Metrics](/references/sdk-metrics).
-Each source provides options for levels of granularity and filtering, monitoring-tool integrations, and configuration.
-Before implementing Temporal Cloud observability, decide what you need to measure for your use case. There are two primary use cases for metrics:
+Temporal offers two distinct sources of metrics: [Cloud Metrics](/cloud/metrics/openmetrics/metrics-reference) and [SDK Metrics](/references/sdk-metrics).
+Each source provides different levels of granularity, filtering options, monitoring-tool integrations, and configuration.
 
-- To measure the health and performance of Temporal-backed applications and key business processes.
-- To measure the health and performance of Temporal infrastructure and user provided infrastructure in the form of Temporal Workers and Temporal Clients.
+- **SDK metrics** monitor individual Workers and your code's behavior from the perspective of your application.
+- **Cloud metrics** monitor Temporal Cloud's behavior from the perspective of the Temporal Service.
 
-When measuring the performance of Temporal-backed applications and key business processes, you should rely on Temporal SDK metrics as a source of truth.
-This is because Temporal SDKs provide visibility from the perspective of your application, not from the perspective of the Temporal Service.
+When used together, Cloud and SDK metrics measure the health and performance of your full Temporal infrastructure, including the Temporal Cloud Service and user-supplied Temporal Workers.
 
-SDK metrics monitor individual workers and your code's behavior.
-Cloud metrics monitor Temporal behavior.
-When used together, Temporal Cloud and SDK metrics measure the health and performance of your full Temporal infrastructure, including the Temporal Cloud Service and user-supplied Temporal Workers.
+## Cloud Metrics
 
-Cloud Metrics for all Namespaces in your account are available from two sources:
+Cloud metrics for all Namespaces in your account are available from the [OpenMetrics endpoint](/cloud/metrics/openmetrics), a Prometheus-compatible scrapable endpoint at `metrics.temporal.io`.
 
-- [OpenMetrics Endpoint](/cloud/metrics/openmetrics) - A Prometheus-compatible scrapable endpoint.
-- [PromQL Endpoint](/cloud/metrics/promql) - A Prometheus query endpoint.
+- [OpenMetrics overview](/cloud/metrics/openmetrics) - Getting started and key concepts
+- [Metrics integrations](/cloud/metrics/openmetrics/metrics-integrations) - Datadog, Grafana Cloud, New Relic, ClickStack, and more
+- [API reference](/cloud/metrics/openmetrics/api-reference) - Endpoint specification and advanced configuration
+- [Metrics reference](/cloud/metrics/openmetrics/metrics-reference) - Complete catalog of all `temporal_cloud_v1_*` metrics
 
-:::note
+## SDK Metrics
 
-OpenMetrics is the recommended option for most users.
+SDK metrics are emitted by your Workers and Clients.
+For setup instructions, see [SDK metrics setup](/cloud/metrics/sdk-metrics-setup).
+
+## PromQL Endpoint (Deprecated) {#promql-deprecated}
+
+:::danger PromQL endpoint deprecated
+
+The PromQL endpoint and its `temporal_cloud_v0_*` metrics were deprecated on April 2, 2026 and are no longer accepting new users.
+The PromQL endpoint will be disabled for all users on **October 5, 2026**.
+
+Migrate to the [OpenMetrics endpoint](/cloud/metrics/openmetrics).
+See the [migration guide](/cloud/metrics/openmetrics/migration-guide) for a complete v0-to-v1 metric mapping.
 
 :::
 
-For setting up SDK metrics emitted by your Workers and Clients, see [SDK metrics setup](/cloud/metrics/sdk-metrics-setup).
+The legacy PromQL endpoint uses mTLS certificate authentication and exposes `temporal_cloud_v0_*` metrics via a Prometheus query API.
+
+- [PromQL endpoint](/cloud/metrics/promql)
+- [PromQL metrics reference](/cloud/metrics/reference)
+- [PromQL setup with Grafana](/cloud/metrics/prometheus-grafana)
diff --git a/docs/cloud/metrics/openmetrics/api-reference.mdx b/docs/cloud/metrics/openmetrics/api-reference.mdx
@@ -25,11 +25,6 @@ import { CaptionedImage } from '@site/src/components';
 
 The Temporal Cloud OpenMetrics API provides actionable operational metrics about your Temporal Cloud deployment. This is a scrapable HTTP API that returns metrics in OpenMetrics format, suitable for ingestion by Prometheus-compatible monitoring systems.
 
-:::tip SUPPORT, STABILITY, and DEPENDENCY INFO
-
-Temporal Cloud OpenMetrics support is available in  [Public Preview](/evaluate/development-production-features/release-stages#public-preview).
-
-:::
 
 ## Available Metrics Reference
 
@@ -134,7 +129,7 @@ Implement retry logic in your client to gracefully handle transient API failures
 
 ### Data Latency
 
-Metric data points are available for query within 2 minutes of their origination. This is in line with the freshest metrics [available from any major service provider](https://docs.datadoghq.com/integrations/guide/cloud-metric-delay/). This latency should be accounted for when setting up monitoring alerts.
+Metric data points are available for query within 3 minutes of their origination. This is in line with the freshest metrics [available from any major service provider](https://docs.datadoghq.com/integrations/guide/cloud-metric-delay/). This latency should be accounted for when setting up monitoring alerts.
 
 ## Endpoints
 
@@ -152,7 +147,7 @@ Returns metrics in OpenMetrics format suitable for scraping by Prometheus-compat
 
 #### Timestamp Offset
 
-To account for metric data latency, this endpoint returns metrics from the current timestamp minus a fixed offset.  The current offset is 2 minutes rounded down to the start of the minute. To accommodate this offset, the timestamps in the response should be honored when importing the metrics. For example, in Prometheus this can be controlled using the `honor\_timestamps` flag.
+To account for metric data latency, this endpoint returns metrics from the current timestamp minus a fixed offset.  The current offset is 3 minutes rounded down to the start of the minute. To accommodate this offset, the timestamps in the response should be honored when importing the metrics. For example, in Prometheus this can be controlled using the `honor\_timestamps` flag.
 
 #### Query Parameters
 
diff --git a/docs/cloud/metrics/openmetrics/index.mdx b/docs/cloud/metrics/openmetrics/index.mdx
@@ -22,11 +22,6 @@ tags:
   - Temporal Cloud
 ---
 
-:::tip SUPPORT, STABILITY, and DEPENDENCY INFO
-
-Temporal Cloud OpenMetrics support is available in  [Public Preview](/evaluate/development-production-features/release-stages#public-preview).
-
-:::
 
 :::tip PRICING
 
@@ -43,7 +38,7 @@ Temporal Cloud's [OpenMetrics](https://openmetrics.io/) endpoint provides operat
 * [Migration Guide](/cloud/metrics/openmetrics/migration-guide) - Guide on how to transition from the Prometheus query endpoint
 
 ## Overview
-Temporal Cloud OpenMetrics exposes 50+ metrics covering workflow lifecycles, task queue operations, service performance, and system limits. All metrics are aggregated over one-minute windows and available for scraping within two minutes.
+Temporal Cloud OpenMetrics exposes 50+ metrics covering workflow lifecycles, task queue operations, service performance, and system limits. All metrics are aggregated over one-minute windows and available for scraping within three minutes.
 
 * [Set up authentication and scraping](/cloud/metrics/openmetrics/api-reference#authentication) with the API documentation. 
 * Browse the [complete metrics catalog](/cloud/metrics/openmetrics/metrics-reference) for descriptions and labels. 
diff --git a/docs/cloud/metrics/openmetrics/metrics-integrations.mdx b/docs/cloud/metrics/openmetrics/metrics-integrations.mdx
@@ -27,11 +27,6 @@ Metrics can be exported from Temporal Cloud using the OpenMetrics endpoint. This
 This document is for basic configuration only. For advanced concepts such as label management and high cardinality scenarios see the 
 [general API reference](/cloud/metrics/openmetrics/api-reference).
 
-:::tip SUPPORT, STABILITY, and DEPENDENCY INFO
-
-Temporal Cloud OpenMetrics support is available in  [Public Preview](/evaluate/development-production-features/release-stages#public-preview).
-
-:::
 
 ## Integrations
 
diff --git a/docs/cloud/metrics/openmetrics/metrics-reference.mdx b/docs/cloud/metrics/openmetrics/metrics-reference.mdx
@@ -23,11 +23,6 @@ tags:
 
 This document describes all metrics available from the Temporal Cloud OpenMetrics endpoint.
 
-:::tip SUPPORT, STABILITY, and DEPENDENCY INFO
-
-Temporal Cloud OpenMetrics support is available in  [Public Preview](/evaluate/development-production-features/release-stages#public-preview).
-
-:::
 
 ## Metric Conventions
 
diff --git a/docs/cloud/metrics/openmetrics/migration-guide.mdx b/docs/cloud/metrics/openmetrics/migration-guide.mdx
@@ -29,11 +29,11 @@ Temporal Cloud is transitioning from our Prometheus query endpoint to an industr
 can monitor your Temporal Cloud workloads, bringing enhanced capabilities, better integration with observability tools,
 and access to high-cardinality metrics that were previously unavailable.
 
-:::tip SUPPORT, STABILITY, and DEPENDENCY INFO
+:::danger PromQL endpoint deprecated
 
-The OpenMetrics endpoint is available in
-[Public Preview](/evaluate/development-production-features/release-stages#public-preview) for testing and validation.
-The existing Prometheus query endpoint remains fully operational and supported.
+The PromQL endpoint was deprecated on April 2, 2026 and is no longer accepting new users.
+The PromQL endpoint will be disabled for all users on **October 5, 2026**.
+Complete your migration to the OpenMetrics endpoint before this date.
 
 :::
 
@@ -52,7 +52,7 @@ The existing Prometheus query endpoint remains fully operational and supported.
 4. **Simplified Integration**: Direct scraping from your observability tools without intermediate translation layers.
 
 5. **Enhanced Performance**: Optimized for high-cardinality data with built-in safeguards for system stability. Data is
-   available to scrape two minutes from the time it was emitted, in line with the freshest metrics
+   available to scrape three minutes from the time it was emitted, in line with the freshest metrics
    [available from any major service provider](https://docs.datadoghq.com/integrations/guide/cloud-metric-delay/).
 
 ## What's Changing
@@ -68,30 +68,19 @@ The existing Prometheus query endpoint remains fully operational and supported.
 
 ## Migration Timeline
 
-Here is the current estimated timeline for migrating from the Prometheus query endpoint to the OpenMetrics endpoint.
+**April 2, 2026 - PromQL endpoint deprecated**
 
-:::caution
+- The PromQL endpoint is no longer accepting new users.
+- Existing users should begin migrating to the OpenMetrics endpoint.
 
-Timelines can shift so be sure to stay up to date on upcoming releases.
+**October 5, 2026 - PromQL endpoint disabled**
 
-:::
-
-**Public Preview (Current)**
-
-- OpenMetrics endpoint available for onboarding.
-- Both endpoints run in parallel with no changes required.
-
-**General Availability [TBA]**:
-
-- OpenMetrics endpoint becomes production-ready and the standard for metrics collection.
-
-**Query Endpoint Deprecation (6 months after GA)**:
-
-- Prometheus query endpoint deprecated and eventually removed.
+- The PromQL endpoint will be disabled for all users.
+- All metrics consumption must use the OpenMetrics endpoint by this date.
 
 :::important Action Required
 
-Complete migration before the 6 month deprecation window ends.
+Complete migration before October 5, 2026.
 
 :::
 
diff --git a/docs/cloud/metrics/prometheus-grafana.mdx b/docs/cloud/metrics/prometheus-grafana.mdx
@@ -25,6 +25,15 @@ tags:
 
 import { ZoomingImage } from '@site/src/components';
 
+:::danger PromQL endpoint deprecated
+
+The PromQL endpoint and its `temporal_cloud_v0_*` metrics were deprecated on April 2, 2026 and are no longer accepting new users.
+The PromQL endpoint will be disabled for all users on **October 5, 2026**.
+
+For Grafana setup with the OpenMetrics endpoint, see the [OpenMetrics integrations page](/cloud/metrics/openmetrics/metrics-integrations).
+
+:::
+
 **How to set up Grafana with Temporal Cloud PromQL endpoint to view Cloud metrics.**
 
 Temporal Cloud emits metrics through a [Prometheus HTTP API endpoint](https://prometheus.io/docs/prometheus/latest/querying/api/), which can be directly used as a Prometheus data source in Grafana or to query and export Cloud metrics to any observability platform.
diff --git a/docs/cloud/metrics/promql.mdx b/docs/cloud/metrics/promql.mdx
@@ -21,9 +21,13 @@ tags:
   - Temporal Cloud
 ---
 
-:::tip
+:::danger PromQL endpoint deprecated
 
-Need to scrape metrics into your observability stack? Try out the new [OpenMetrics endpoint](/cloud/metrics/openmetrics).
+The PromQL endpoint and its `temporal_cloud_v0_*` metrics were deprecated on April 2, 2026 and are no longer accepting new users.
+The PromQL endpoint will be disabled for all users on **October 5, 2026**.
+
+Migrate to the [OpenMetrics endpoint](/cloud/metrics/openmetrics).
+See the [migration guide](/cloud/metrics/openmetrics/migration-guide) for a complete v0-to-v1 metric mapping.
 
 :::
 
diff --git a/docs/cloud/metrics/reference.mdx b/docs/cloud/metrics/reference.mdx
@@ -26,10 +26,19 @@ keywords:
   - gRPC error count
 ---
 
+:::danger PromQL endpoint deprecated
+
+The PromQL endpoint and its `temporal_cloud_v0_*` metrics were deprecated on April 2, 2026 and are no longer accepting new users.
+The PromQL endpoint will be disabled for all users on **October 5, 2026**.
+
+Migrate to the [OpenMetrics endpoint](/cloud/metrics/openmetrics) which provides `temporal_cloud_v1_*` metrics with higher cardinality, accurate percentiles, and simplified authentication.
+See the [migration guide](/cloud/metrics/openmetrics/migration-guide) for a complete v0-to-v1 metric mapping.
+
+:::
+
 A metric is a measurement or data point that provides insights into the performance and health of a system.
-This document describes the metrics available on the Temporal Cloud platform.
-Temporal Cloud metrics help you monitor performance and troubleshoot errors.
-They provide insights into different aspects of the Service.
+This document describes the `temporal_cloud_v0_*` metrics available from the deprecated Temporal Cloud PromQL endpoint.
+For the current metrics reference, see the [OpenMetrics metrics reference](/cloud/metrics/openmetrics/metrics-reference).
 
 This document describes:
 
