metadata limits

Author: khdownie

articles/storage/files/analyze-files-metrics.md

@@ -5,7 +5,7 @@ author: khdownie
 services: storage
 ms.service: azure-file-storage
 ms.topic: how-to
-ms.date: 08/19/2024
+ms.date: 03/10/2025
 ms.author: kendownie
 ms.custom: monitoring, devx-track-azurepowershell
 ---
@@ -324,6 +324,30 @@ Compared against the **Bandwidth by Max MiB/s**, we achieved 123 MiB/s at peak.
 
 :::image type="content" source="media/analyze-files-metrics/bandwidth-by-max-mibs.png" alt-text="Screenshot showing bandwidth by max MIBS." lightbox="media/analyze-files-metrics/bandwidth-by-max-mibs.png" border="false":::
 
+### Monitor utilization by metadata IOPS
+
+On Premium SSD and Standard HDD file shares, our current metadata capabilities scale up to 12K metadata IOPS. This means that running a metadata-heavy workload with a high volume of open, close, or delete operations increases the likelihood of metadata IOPS throttling. This limitation is independent of the file share's overall IOPS capacity on Standard or IOPS provisioning on Premium.
+
+Because no two metadata-heavy workloads follow the same usage pattern, it can be challenging for customers to proactively monitor their workload and set accurate alerts.
+
+To address this, we've introduced two metadata-specific metrics for Azure file shares:
+
+- **Success with Metadata Warning:** Indicates that metadata IOPS are approaching their limit and might be throttled if they remain high or continue increasing. A rise in the volume or frequency of these warnings suggests an increasing risk of metadata throttling.
+
+- **Success with Metadata Throttling:** Indicates that metadata IOPS have exceeded the file share’s capacity, resulting in throttling. While IOPS operations will never fail and will eventually succeed after retries, latency will be impacted during throttling.
+
+To view in Azure Monitor, select the **Transactions** metric and **Apply splitting** on response types. The Metadata response types will only appear in the drop-down if the activity occurs within the timeframe selected.
+
+The following chart illustrates a workload that experienced a sudden increase in metadata IOPS (transactions), triggering Success with Metadata Warnings, which indicates a risk of metadata throttling. In this example, the workload subsequently reduced its transaction volume, preventing metadata throttling from occurring.
+
+:::image type="content" source="media/analyze-files-metrics/analyze-files-metrics/metadata-warnings.png" alt-text="Screenshot showing Metadata Warnings by response type." lightbox="media/analyze-files-metrics/metadata-warnings.png" border="false":::
+
+If your workload encounters **Success with Metadata Warnings** or **Sucess with Metadata Throttling** response types, consider implementing one or more of the following recommendations:
+
+- For Premium SMB file shares, enable [Metadata Caching](smb-performance.md#metadata-caching-for-premium-smb-file-shares).
+- Distribute (shard) your workload across multiple file shares.
+- Reduce the volume of metadata IOPS.
+
 ## Related content
 
 - [Monitor Azure Files](storage-files-monitoring.md)

articles/storage/files/media/analyze-files-metrics/metadata-warnings.png

@@ -4,12 +4,13 @@ description: Learn about the scalability and performance targets for Azure Files
 author: khdownie
 ms.service: azure-file-storage
 ms.topic: conceptual
-ms.date: 03/04/2025
+ms.date: 03/10/2025
 ms.author: kendownie
 ms.custom: references_regions
 ---
 
 # Scalability and performance targets for Azure Files and Azure File Sync
+
 [Azure Files](storage-files-introduction.md) offers fully managed file shares in the cloud that are accessible via the Server Message Block (SMB) and Network File System (NFS) file system protocols. This article discusses the scalability and performance targets for Azure Files and Azure File Sync.
 
 The targets listed here might be affected by other variables in your deployment. For example, the performance of I/O for a file might be impacted by your SMB client's behavior and by your available network bandwidth. You should test your usage pattern to determine whether the scalability and performance of Azure Files meet your requirements.
@@ -98,16 +99,18 @@ Azure file share scale targets apply at the file share level.
 | Minimum storage size | 100 GiB (provisioned) | 32 GiB (provisioned) | 0 bytes |
 | Maximum storage size | 100 TiB | 256 TiB | 100 TiB |
 | Maximum number of files | Unlimited | Unlimited | Unlimited |
-| Maximum IOPS | 102,400 IOPS (dependent on provisioning) | 50,000 IOPS (dependent on provisioning) | 20,000 IOPS |
+| Maximum IOPS (Data) | 102,400 IOPS (dependent on provisioning) | 50,000 IOPS (dependent on provisioning) | 20,000 IOPS |
+| Maximum IOPS (Metadata<sup>1</sup>) | Up to 12,000 IOPS | Up to 12,000 IOPS | Up to 12,000 IOPS |
 | Maximum throughput | 10,340 MiB / sec (dependent on provisioning) | 5,120 MiB / sec (dependent on provisioning) | Up to storage account limits |
 | Maximum number of share snapshots | 200 snapshots | 200 snapshots | 200 snapshots |
-| Maximum filename length<sup>3</sup> (full pathname including all directories, file names, and backslash characters) | 2,048 characters | 2,048 characters | 2,048 characters |
-| Maximum length of individual pathname component<sup>2</sup> (in the path \A\B\C\D, each letter represents a directory or file that is an individual component) | 255 characters | 255 characters | 255 characters |
+| Maximum filename length<sup>2</sup> (full pathname including all directories, file names, and backslash characters) | 2,048 characters | 2,048 characters | 2,048 characters |
+| Maximum length of individual pathname component (in the path \A\B\C\D, each letter represents a directory or file that is an individual component) | 255 characters | 255 characters | 255 characters |
 | Hard link limit (NFS only) | 178 | N/A | N/A |
 | Maximum number of SMB Multichannel channels | 4 | N/A | N/A |
 | Maximum number of stored access policies per file share | 5 | 5 | 5 |
 
-<sup>3</sup> Azure Files enforces certain [naming rules](/rest/api/storageservices/naming-and-referencing-shares--directories--files--and-metadata#directory-and-file-names) for directory and file names.
+<sup>1</sup> Metadata IOPS (i.e., open/close/delete). See [Monitor Metdata IOPS](analyze-files-metrics.md#monitor-utilization-by-metadata-iops) for additional guidenance.<br>
+<sup>2</sup> Azure Files enforces certain [naming rules](/rest/api/storageservices/naming-and-referencing-shares--directories--files--and-metadata#directory-and-file-names) for directory and file names.
 
 ### File scale targets
 File scale targets apply to individual files stored in Azure file shares.