Merge pull request #302783 from tehnoonr/patch-15

Updated to Capacity documentation to reflect recent changes

Author: JamesJBarnett

articles/api-management/api-management-capacity.md

@@ -56,6 +56,8 @@ Available aggregations for these metrics are as follows.
 
 In the Developer, Basic, Standard, and Premium tiers, the **Capacity** metric is available for making decisions about scaling or upgrading an API Management instance. Its construction is complex and imposes certain behavior.
 
+[!INCLUDE [capacity-change.md](../../includes/api-management-capacity-change.md)]
+
 Available aggregations for this metric are as follows.
 
 * **Avg** - Average percentage of capacity used across gateway processes in every [unit](upgrade-and-scale.md) of an API Management instance. 
@@ -171,6 +173,7 @@ Use capacity metrics for making decisions whether to scale an API Management ins
 + Ignore sudden spikes that are most likely not related to an increase in load (see [Capacity metric behavior](#capacity-metric-behavior) section for explanation).
 + As a general rule, upgrade or scale your instance when a capacity metric value exceeds **60% - 70%** for a long period of time (for example, 30 minutes). Different values may work better for your service or scenario.
 + If your instance or workspace gateway is configured with only 1 unit, upgrade or scale it when a capacity metric value exceeds **40%** for a long period. This recommendation is based on the need to reserve capacity for guest OS updates in the underlying service platform.
++ Use [available diagnostics](monitor-api-management.md) to monitor the response times of API calls. Consider adjusting scaling thresholds if you notice degraded response times with increasing value of capacity metric. 
 
 > [!TIP]  
 > If you are able to estimate your traffic beforehand, test your API Management instance or workspace gateway on workloads you expect. You can increase the request load gradually and monitor the value of the capacity metric that corresponds to your peak load. Follow the steps from the previous section to use Azure portal to understand how much capacity is used at any given time.

includes/api-management-availability-capacity.md

@@ -8,5 +8,4 @@ ms.author: danlep
 
 
 > [!IMPORTANT]
-> The **Max** aggregation of the capacity metric is only supported in the **Premium** tier of API Management.
->
+> The **Max** aggregation of the capacity metric is only supported in the **Premium** tier of API Management. This aggregation is intended for informational purposes only and should not be used for scaling decisions or alerting. Short-lived spikes in **Max** capacity are expected and typically not a cause for concern. However, if these spikes persist for 15 consecutive minutes or longer, further investigation may be warranted. For more information, refer to [Use capacity for scaling decisions](../articles/api-management/api-management-capacity.md#use-capacity-for-scaling-decisions) mentioned later in this document.

includes/api-management-capacity-change.md

@@ -0,0 +1,12 @@
+---
+author: tehnoonr
+ms.service: azure-api-management
+ms.topic: include
+ms.date: 07/15/2025
+ms.author: tehnoonr
+---
+
+
+> [!IMPORTANT]
+> As part of the [May 2025 service updates](https://github.com/Azure/API-Management/releases/tag/release-service-2025-05), we refined the calculation logic for the capacity metric to enhance accuracy and consistency. After your service receives this update, you may notice higher reported capacity values. This is solely due to improved measurement logic - your service’s actual performance and throughput remain unaffected.
+> To ensure optimal resource management, you may need to revisit and adjust your scaling thresholds. For guidance on using the capacity metric for scaling, refer to [Use capacity for scaling decisions](../articles/api-management/api-management-capacity.md#use-capacity-for-scaling-decisions) mentioned later in this document.