temporalio · bechols · Jun 8, 2026 · Jun 8, 2026
@@ -448,44 +448,8 @@ Enabling this configuration will require a restart of your history pods.
 
 ## How to gather self-hosted metrics
 
-Temporal Server (version > 1.17) provides an [action](/cloud/pricing#action) metric. You may use Grafana to capture and
-display this metric. Use this [sample](https://github.com/temporalio/dashboards/blob/master/server/server-general.json)
-dashboard as a reference. To determine actions per second (APS) you may use the following promql queries.
-
-`sum (rate(action{service_name="frontend"}[1m]))`
-
-`sum (rate(action{service_name="frontend"}[1m]))  by (exported_namespace)`
-
-The first query will calculate total APS. The second will isolate the metric per Namespace.
-
-For Datadog, the following widget will calculate actions per second:
-
-```
-{
-    "title": "Average Actions per Second",
-    "type": "query_value",
-    "requests": [
-        {
-            "formulas": [
-                {
-                    "formula": "query1"
-                }
-            ],
-            "queries": [
-                {
-                    "name": "query1",
-                    "data_source": "metrics",
-                    "query": "sum:io.temporal.server.action.count{$server-name}.as_rate()",
-                    "aggregator": "avg"
-                }
-            ],
-            "response_format": "scalar"
-        }
-    ],
-    "autoscale": true,
-    "precision": 2
-}
-```
+To collect peak Actions per second (APS), fixed-range Action counts, and representative Workflow Action estimates from
+your self-hosted Temporal Service, see [Estimate Actions for migration](/cloud/migrate/estimate-actions).
 
 ## Frequently asked questions
 

@@ -0,0 +1,124 @@
+---
+id: estimate-actions
+title: Estimate Actions for migration
+sidebar_label: Estimate Actions
+description: Estimate Temporal Cloud Actions and Actions per second from a self-hosted Temporal Service before migrating to Temporal Cloud.
+toc_max_heading_level: 4
+keywords:
+  - migration
+  - temporal cloud
+  - actions
+  - self-hosted
+tags:
+  - Temporal Service
+  - Temporal Cloud
+  - Self-hosting
+  - Production
+---
+
+Before you migrate from a self-hosted Temporal Service to Temporal Cloud, you can measure your current Action usage to help predict your Cloud usage and costs.
+
+Use server metrics to estimate Actions per second (APS) and peak load.
+Use representative Workflow Execution Histories to understand how many Actions a typical Workflow Execution creates.
+Estimate storage separately from Actions.
+
+For details about which operations count as Actions in Temporal Cloud, see [Temporal Cloud Actions](/cloud/actions).
+
+## Choose an estimation method
+
+Use one or more of the following methods depending on what you need to estimate.
+
+| Method | Use it to estimate | Notes |
+| --- | --- | --- |
+| Self-hosted server metrics | APS, peak APS, and Action counts over a fixed time range | Best for sizing Namespace limits and understanding usage patterns. |
+| Workflow Execution History samples | Actions per representative Workflow Execution | Best for understanding workload shape by Workflow Type. Some [Actions do not appear](/cloud/actions) in Event History. |
+| Storage estimates | Event History storage | Storage is [priced separately](/cloud/pricing#pricing-model) from Actions. |
+
+## Estimate APS from self-hosted server metrics
+
+Temporal Server versions later than 1.17 provide an `action` metric.
+Use this metric to estimate Actions per second from a self-hosted Temporal Service.
+
+Temporal Server versions 1.22.3 and later provide an `action` metric that more closely reflects current Temporal Cloud Action pricing, including Local Activity metering.
+For Temporal Server versions from 1.17 through 1.22.2, use the `action` metric to understand server load, but do not treat it as a precise billable Action estimate.
+
+To calculate total APS, use the following PromQL query:
+
+```promql
+sum(rate(action{service_name="frontend"}[1m]))
+```
+
+To calculate APS by Namespace, use the following PromQL query:
+
+```promql
+sum(rate(action{service_name="frontend"}[1m])) by (exported_namespace)
+```
+
+Depending on your metrics exporter setup, the Namespace label might be `namespace` instead of `exported_namespace`.
+
+For a Grafana dashboard example, see the [`server-general.json`](https://github.com/temporalio/dashboards/blob/master/server/server-general.json) dashboard in the Temporal dashboards repository.
+
+For Datadog, use a query like the following to calculate Actions per second:
+
+```text
+sum:io.temporal.server.action.count{$server-name}.as_rate()
+```
+
+## Estimate Action counts over a fixed time range
+
+To estimate total Actions during a fixed time range, use `increase()` over the range you want to measure.
+
+For example, to estimate total Actions over 30 days, use the following PromQL query:
+
+```promql
+sum(increase(action{service_name="frontend"}[30d]))
+```
+
+To estimate Actions for one Namespace, add the Namespace label:
+
+```promql
+sum(increase(action{service_name="frontend", exported_namespace="default"}[30d]))
+```
+
+When you run fixed-range queries in Grafana, set the end of the dashboard time window to the end of the date range that you want to measure.
+For example, to measure Actions for the 30-day period ending March 31, set the dashboard end time to March 31.
+
+## Estimate Actions from Workflow Execution Histories
+
+You can estimate Actions per Workflow Execution by counting billable events in representative Workflow Execution Histories.
+This method is useful when you need to understand how much Action usage a Workflow Type creates.
+
+1. Choose representative Workflow Executions for each Workflow Type.
+2. Download the Event History for each Workflow Execution from the Web UI or API.
+3. Count the events that map to Temporal Cloud Actions.
+   For the list of Action types and corresponding History Event types, see [Temporal Cloud Actions](/cloud/actions).
+4. Multiply the Action count by the expected number of Workflow Executions in the period you want to estimate.
+
+This method produces an estimate.
+Some Actions do not appear directly in Event History, including Queries and some Activity Heartbeat Actions.
+If you use Global Namespaces, account for the additional Action and storage cost.
+Estimate storage separately from Workflow Action counts.
+
+## Estimate storage separately
+
+Temporal Cloud storage is priced separately from Actions.
+To estimate storage, collect the following information:
+
+- Event History size for representative Workflow Executions.
+- Retention Period for closed Workflow Executions.
+- Duration for open Workflow Executions.
+- Expected number of Workflow Executions.
+
+For current storage pricing, see [Temporal Cloud pricing](/cloud/pricing).
+
+## Share estimates with Temporal
+
+When planning an [automated migration](/cloud/migrate/automated), share the following information with your Temporal account team:
+
+- Peak APS for each Namespace.
+- Average APS for each Namespace, if available.
+- Fixed-range Action counts, such as total Actions over the last 30 days.
+- Representative Workflow Types and their estimated Actions per Workflow Execution.
+- Retention Periods and storage estimates.
+
+These estimates help Temporal plan capacity, Namespace limits, and migration timing.
@@ -12,3 +12,4 @@ Learn how to migrate your Temporal workflows with zero downtime:
 - [Manual Migration](/cloud/migrate/manual) - This process enables transitions from self-hosted Temporal instances to Temporal Cloud by updating clients
   and workflows to utilize new resources within Temporal Cloud.
 - [Migrate between regions](/cloud/migrate/migrate-within-cloud) - This process allows you to migrate a Temporal Cloud Namespace between regions or providers.
+- [Estimate Actions](/cloud/migrate/estimate-actions) - This process helps you estimate Actions and Actions per second from a self-hosted Temporal Service before migrating to Temporal Cloud.
@@ -86,7 +86,7 @@ The volume of these requests might be high to execute against all the matches to
 - Have you added an mTLS certificate to your Temporal Namespace? Review our [documentation for adding a certificate to your Temporal Cloud account](/cloud/certificates) for more information.
 - There are differences in how metrics are generated in self-hosted Temporal and Temporal Cloud. Review the [documentation on Temporal Cloud metrics](/cloud/metrics/) for more information.
 - Consider the implications for [security and access to your Temporal Service](/cloud/security).
-- Review your current load (actions per second) and speak to your Account Executive and Solutions Architect so we can set appropriate [Namespace limits](/cloud/limits).
+- Review your current load with [Action estimates](/cloud/migrate/estimate-actions) and speak to your Account Executive and Solutions Architect so we can set appropriate [Namespace limits](/cloud/limits).
 
 ### Multi-Cluster Replication
 

@@ -125,7 +125,7 @@ A Side Effect does not re-execute upon replay, but instead returns the recorded
 Do not ever have a Side Effect that could fail, because failure could result in the Side Effect function executing more than once.
 If there is any chance that the code provided to the Side Effect could fail, use an Activity.
 
-## What is a Principal Attribution? {/* #principal-attribution */}
+## What is Principal Attribution? {/* #principal-attribution */}
 
 :::tip SUPPORT, STABILITY, and DEPENDENCY INFO
 

@@ -1242,7 +1242,7 @@ module.exports = {
             type: 'doc',
             id: 'cloud/migrate/index',
           },
-          items: ['cloud/migrate/automated', 'cloud/migrate/manual', 'cloud/migrate/migrate-within-cloud'],
+          items: ['cloud/migrate/automated', 'cloud/migrate/manual', 'cloud/migrate/migrate-within-cloud', 'cloud/migrate/estimate-actions'],
         },
         'cloud/capacity-modes',
         'cloud/worker-health',