From a02c37089c915efba6a4c8f6d4d85334432a015a Mon Sep 17 00:00:00 2001 From: John Votta Date: Tue, 16 Jun 2026 21:26:24 -0700 Subject: [PATCH 1/3] cloud: document monitoring provisioned capacity utilization Adds customer-facing guidance for the lower bound of provisioned capacity - detecting when a Namespace is paying for reserved capacity it isn't using (the 20% per-TRU minimum) - which today's docs don't cover. - service-health: new "Provisioned capacity utilization" subsection under Monitoring Trends Against Limits (the canonical, linked-to home): the metrics, the 20% floor, the under-utilization alert threshold, the intentional-headroom nuance, and that Usage/billing is the source of truth - capacity-modes: short pointer subsection linking to the above Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/cloud/capacity-modes.mdx | 6 ++++++ docs/cloud/service-health.mdx | 21 +++++++++++++++++++++ 2 files changed, 27 insertions(+) diff --git a/docs/cloud/capacity-modes.mdx b/docs/cloud/capacity-modes.mdx index bb55307799..55bae49a56 100644 --- a/docs/cloud/capacity-modes.mdx +++ b/docs/cloud/capacity-modes.mdx @@ -174,6 +174,12 @@ Provisioned Capacity works well when you’re aware of specific increases in loa Depending on your usage patterns and your system monitoring, you can use Provisioned Capacity to quickly remedy rate limiting without contacting support. You can also automate changes in capacity if you have a known event or a recurring usage pattern that produces predictable usage spikes. +### Monitoring provisioned capacity utilization + +Because provisioned capacity is reserved by the hour whether or not you use it, it is worth tracking how much of it you actually consume. +Sustained usage well below your provisioned limit can mean you are paying for capacity you are not using, since each TRU beyond the first carries a minimum hourly charge (see [Capacity Mode Pricing](/cloud/pricing#capacity-modes-pricing)). +For the metrics to watch and how to alert on utilization, see [Monitoring Trends Against Limits](/cloud/service-health#rps-aps-rate-limits). + ## Setting Capacity Modes Capacity Modes and TRUs can be set via the Temporal Cloud UI, CLI, or API. Capacity modes can be set and adjusted by Global Admin and Namespace Admin. diff --git a/docs/cloud/service-health.mdx b/docs/cloud/service-health.mdx index fb9560a61b..ea06058596 100644 --- a/docs/cloud/service-health.mdx +++ b/docs/cloud/service-health.mdx @@ -180,6 +180,27 @@ for `temporal_cloud_v1_total_action_count` at a 50% threshold of the `temporal_c or directly when throttling is detected as a value greater than zero for `temporal_cloud_v1_total_action_throttled_count`. This logic can also be used to automatically scale [Temporal Resource Units](/cloud/capacity-modes#provisioned-capacity) up or down as needed. Some workloads choose to exceed limits and accept throttling because they are not latency sensitive. +### Provisioned capacity utilization + +For Namespaces in [provisioned capacity](/cloud/capacity-modes#provisioned-capacity) mode, the limit and count metrics also reveal the lower bound: how much of your reserved capacity you are actually using. +This matters because provisioned capacity is reserved by the hour whether or not you use it. +Each TRU beyond the first carries a minimum hourly Action charge of 360,000 Actions, which is 20% of that TRU's 500 APS, so a Namespace that runs well below its limit can accrue charges for capacity it never uses. +See [Capacity Mode Pricing](/cloud/pricing#capacity-modes-pricing) for how the minimum is calculated. + +Utilization is the ratio of `temporal_cloud_v1_total_action_count` to `temporal_cloud_v1_action_limit`. +Sustained utilization well below 20% while provisioned indicates you may be paying for reserved capacity you are not using; consider alerting when the ratio stays under 20% over a sustained window, such as several hours, so you can reduce TRUs or return to on-demand mode. +The [Grafana dashboard example](https://github.com/grafana/jsonnet-libs/blob/master/temporal-mixin/dashboards/temporal-overview.json) includes provisioned-capacity panels for utilization and limits. + +Low utilization is not always a problem. +If your traffic is spiky or unpredictable, you may intentionally keep capacity provisioned so it is ready the moment you need it. + +:::note + +These metrics are an approximate, real-time view at one-minute granularity, while provisioned capacity is billed per calendar hour using the highest TRU value set during that hour. +Use the Usage page in the Temporal Cloud UI and your invoice as the source of truth for billed capacity. + +::: + ### Why does throttling occur when count metrics stay below the limit? For spiky workloads, the throttle metric can be non-zero even though the count metric never rises above the limit. This looks contradictory, but both values are correct. They describe the workload at different time resolutions. From 7056d68ed26ad71cb04b46d95352895f076ee746 Mon Sep 17 00:00:00 2001 From: John Votta Date: Wed, 17 Jun 2026 09:54:58 -0700 Subject: [PATCH 2/3] cloud: drop intro sentence, link to provisioned capacity utilization section Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/cloud/capacity-modes.mdx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/cloud/capacity-modes.mdx b/docs/cloud/capacity-modes.mdx index 55bae49a56..f4bf3ab8f2 100644 --- a/docs/cloud/capacity-modes.mdx +++ b/docs/cloud/capacity-modes.mdx @@ -176,9 +176,8 @@ You can also automate changes in capacity if you have a known event or a recurri ### Monitoring provisioned capacity utilization -Because provisioned capacity is reserved by the hour whether or not you use it, it is worth tracking how much of it you actually consume. Sustained usage well below your provisioned limit can mean you are paying for capacity you are not using, since each TRU beyond the first carries a minimum hourly charge (see [Capacity Mode Pricing](/cloud/pricing#capacity-modes-pricing)). -For the metrics to watch and how to alert on utilization, see [Monitoring Trends Against Limits](/cloud/service-health#rps-aps-rate-limits). +For the metrics to watch and how to alert on utilization, see [Monitoring provisioned capacity utilization](/cloud/service-health#provisioned-capacity-utilization). ## Setting Capacity Modes Capacity Modes and TRUs can be set via the Temporal Cloud UI, CLI, or API. From 870a132e47e772641cf8211fc467e9ab6aa06d33 Mon Sep 17 00:00:00 2001 From: John Votta Date: Thu, 18 Jun 2026 11:15:43 -0700 Subject: [PATCH 3/3] Reword provisioned-capacity note; link Usage and Billing as source of truth Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/cloud/service-health.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/cloud/service-health.mdx b/docs/cloud/service-health.mdx index ea06058596..b299d174e8 100644 --- a/docs/cloud/service-health.mdx +++ b/docs/cloud/service-health.mdx @@ -196,8 +196,8 @@ If your traffic is spiky or unpredictable, you may intentionally keep capacity p :::note -These metrics are an approximate, real-time view at one-minute granularity, while provisioned capacity is billed per calendar hour using the highest TRU value set during that hour. -Use the Usage page in the Temporal Cloud UI and your invoice as the source of truth for billed capacity. +These metrics are approximate measures of TRU capacity based on real-time TRU quotas, and do not capture the fact that TRUs are billed by the calendar hour. +Please use [Usage](/cloud/actions-usage) and [Billing](/cloud/billing) as the source of truth for TRU and action accounting. :::