| title | Analyze Azure Files metrics with Azure Monitor |
|---|---|
| description | Learn to use Azure Monitor to monitor workload performance, throughput, and IOPS. Analyze Azure Files metrics such as availability, latency, and utilization. |
| author | khdownie |
| services | storage |
| ms.service | azure-file-storage |
| ms.topic | how-to |
| ms.date | 03/10/2026 |
| ms.author | kendownie |
| ms.custom | monitoring, devx-track-azurepowershell |
✔️ Applies to: Classic SMB and NFS file shares created with the Microsoft.Storage resource provider
✖️ Doesn't apply to: File shares created with the Microsoft.FileShares resource provider (preview)
Understanding how to monitor file share performance is critical to ensuring that your application is running as efficiently as possible. This article shows you how to use Azure Monitor to analyze Azure Files metrics such as availability, latency, and utilization.
See Monitor Azure Files for details on the monitoring data you can collect for Azure Files and how to use it.
Metrics for Azure Files are in these namespaces:
- Microsoft.Storage/storageAccounts
- Microsoft.Storage/storageAccounts/fileServices
For a list of available metrics for Azure Files, see Azure Files monitoring data reference.
For a list of all Azure Monitor supported metrics, which includes Azure Files, see Azure Monitor supported metrics.
You can view Azure Files metrics by using the Azure portal, PowerShell, Azure CLI, or .NET.
You can analyze metrics for Azure Storage with metrics from other Azure services by using Azure Monitor Metrics Explorer. Open metrics explorer by choosing Metrics from the Azure Monitor menu. For details on using this tool, see Analyze metrics with Azure Monitor metrics explorer.
For metrics that support dimensions, you can filter the metric with the desired dimension value. For a complete list of the dimensions that Azure Storage supports, see Metrics dimensions.
You can list the metric definition of your storage account or the Azure Files service. Use the Get-AzMetricDefinition cmdlet.
In this example, replace the <resource-ID> placeholder with the resource ID of the entire storage account or the resource ID of the Azure Files service. You can find these resource IDs on the Properties pages of your storage account in the Azure portal.
$resourceId = "<resource-ID>"
Get-AzMetricDefinition -ResourceId $resourceIdYou can read account-level metric values of your storage account or the Azure Files service. Use the Get-AzMetric cmdlet.
$resourceId = "<resource-ID>"
Get-AzMetric -ResourceId $resourceId -MetricNames "UsedCapacity" -TimeGrain 01:00:00When a metric supports dimensions, you can read metric values and filter them by using dimension values. Use the Get-AzMetric cmdlet.
$resourceId = "<resource-ID>"
Get-AzMetric -ResourceId $resourceId -MetricNames "UsedCapacity" -TimeGrain 01:00:00$resourceId = "<resource-ID>"
$dimFilter = [String](New-AzMetricFilter -Dimension ApiName -Operator eq -Value "GetFile" 3> $null)
Get-AzMetric -ResourceId $resourceId -MetricName Transactions -TimeGrain 01:00:00 -MetricFilter $dimFilter -AggregationType "Total"You can list the metric definition of your storage account or the Azure Files service. Use the az monitor metrics list-definitions command.
In this example, replace the <resource-ID> placeholder with the resource ID of the entire storage account or the resource ID of the Azure Files service. You can find these resource IDs on the Properties pages of your storage account in the Azure portal.
az monitor metrics list-definitions --resource <resource-ID>
You can read the metric values of your storage account or the Azure Files service. Use the az monitor metrics list command.
az monitor metrics list --resource <resource-ID> --metric "UsedCapacity" --interval PT1H
When a metric supports dimensions, you can read metric values and filter them by using dimension values. Use the az monitor metrics list command.
az monitor metrics list --resource <resource-ID> --metric "Transactions" --interval PT1H --filter "ApiName eq 'GetFile' " --aggregation "Total"
Azure Monitor provides the Azure.Monitor.Query .NET SDK to read metric definitions and values. Use Azure.Identity for passwordless authentication with DefaultAzureCredential. For more information, see Passwordless connections for Azure services.
First, install the required NuGet packages:
dotnet add package Azure.Identity
dotnet add package Azure.Monitor.Query
In these examples, replace the <resource-ID> placeholder with the resource ID of the entire storage account or the resource ID of the Azure Files service. You can find these resource IDs on the Properties pages of your storage account in the Azure portal.
The following example shows how to list a metric definition at the account level:
using Azure;
using Azure.Identity;
using Azure.Monitor.Query;
using Azure.Monitor.Query.Models;
public static async Task ListStorageMetricDefinition()
{
var resourceId = "<resource-ID>";
var client = new MetricsQueryClient(new DefaultAzureCredential());
AsyncPageable<MetricDefinition> metricDefinitions = client.GetMetricDefinitionsAsync(resourceId, metricsNamespace);
await foreach (var metricDefinition in metricDefinitions)
{
Console.WriteLine(metricDefinition.Id);
Console.WriteLine(metricDefinition.ResourceId);
Console.WriteLine(metricDefinition.Name);
Console.WriteLine(metricDefinition.Unit);
}
}The following example shows how to read UsedCapacity data at the account level:
public static async Task ReadStorageMetricValue()
{
var resourceId = "<resource-ID>";
var client = new MetricsQueryClient(new DefaultAzureCredential());
Response<MetricsQueryResult> result = await client.QueryResourceAsync(
resourceId,
new[] { "UsedCapacity" },
new MetricsQueryOptions
{
Granularity = TimeSpan.FromHours(1),
Aggregations = { MetricAggregationType.Average },
TimeRange = new QueryTimeRange(TimeSpan.FromHours(3))
});
foreach (MetricResult metric in result.Value.Metrics)
{
Console.WriteLine(metric.Name);
Console.WriteLine(metric.Unit);
foreach(var item in metric.TimeSeries)
{
Console.WriteLine("Metadata:");
foreach(var metadata in item.Metadata)
{
Console.WriteLine($"{metadata.Key}: {metadata.Value}");
}
Console.WriteLine("Values:");
foreach(var value in item.Values)
{
Console.WriteLine($"TimeStamp: {value.TimeStamp}, Average: {value.Average}");
}
}
}
}For multidimensional metrics, you need to define metadata filters if you want to read metric data on specific dimension values.
The following example shows how to read metric data on the metric supporting multidimensional values:
public static async Task ReadStorageMetricValueTest()
{
// Resource ID for Azure Files
var resourceId = "<resource-ID>";
var client = new MetricsQueryClient(new DefaultAzureCredential());
// Define a dimension filter to read metric data on specific dimension values
// More conditions can be added with the 'or' and 'and' operators, example: BlobType eq 'BlockBlob' or BlobType eq 'PageBlob'
Response<MetricsQueryResult> result = await client.QueryResourceAsync(
resourceId,
new[] { "BlobCapacity" },
new MetricsQueryOptions
{
Granularity = TimeSpan.FromHours(1),
Aggregations = { MetricAggregationType.Average },
TimeRange = new QueryTimeRange(TimeSpan.FromHours(3)),
Filter = "BlobType eq 'BlockBlob'"
});
foreach (MetricResult metric in result.Value.Metrics)
{
Console.WriteLine(metric.Name);
Console.WriteLine(metric.Unit);
foreach(var item in metric.TimeSeries)
{
Console.WriteLine("Metadata:");
foreach(var metadata in item.Metadata)
{
Console.WriteLine($"{metadata.Key}: {metadata.Value}");
}
Console.WriteLine("Values:");
foreach(var value in item.Values)
{
Console.WriteLine($"TimeStamp: {value.TimeStamp}, Average: {value.Average}");
}
}
}You can use Azure Monitor to analyze workloads that utilize Azure Files. Follow these steps.
- Navigate to your storage account in the Azure portal.
- In the service menu, under Monitoring, select Metrics.
- Under Metric namespace, select File.
:::image type="content" source="media/analyze-files-metrics/add-metric-namespace-file.png" alt-text="Screenshot showing how to select the Files metric namespace." lightbox="media/analyze-files-metrics/add-metric-namespace-file.png":::
Now you can select a metric depending on what you want to monitor.
In Azure Monitor, the Availability metric can be useful when something is visibly wrong from either an application or user perspective, or when troubleshooting alerts.
When using this metric with Azure Files, it's important to always view the aggregation as Average as opposed to Max or Min. Using Average shows you what percentage of your requests are experiencing errors, and if they are within the SLA for Azure Files.
:::image type="content" source="media/analyze-files-metrics/transaction-metrics-menu.png" alt-text="Screenshot showing the available transaction metrics in Azure Monitor." lightbox="media/analyze-files-metrics/transaction-metrics-menu.png":::
The two most important latency metrics are Success E2E Latency and Success Server Latency. These are ideal metrics to select when starting any performance investigation. Average is the recommended aggregation. As previously mentioned, Max and Min can sometimes be misleading.
In the following charts, the blue line indicates how much time is spent in total latency (Success E2E Latency), and the pink line indicates time spent only in the Azure Files service (Success Server Latency).
This chart shows an on-premises client with a mounted Azure file share, representing, for example, a typical user connecting from a remote location. The physical distance between the client and Azure region is closely correlated to the corresponding client-side latency, which represents the difference between the E2E and Server latency.
:::image type="content" source="media/analyze-files-metrics/latency-remote.png" alt-text="Screenshot showing latency metrics with a remote user connecting to an Azure file share." lightbox="media/analyze-files-metrics/latency-remote.png" border="false":::
In comparison, the following chart shows a situation where both the client and the Azure file share are located within the same region. Note that the client-side latency is only 0.17ms compared to 43.9ms in the first chart. This illustrates why minimizing client-side latency is imperative in order to achieve optimal performance.
:::image type="content" source="media/analyze-files-metrics/latency-same-region.png" alt-text="Screenshot showing latency metrics when the client and Azure file share are located in the same region." lightbox="media/analyze-files-metrics/latency-same-region.png" border="false":::
Another latency indicator to look that for might suggest a problem is an increased frequency or abnormal spikes in Success Server Latency. This is commonly due to throttling due to exceeding the provisioned limit for a provisioned file share (or an overall scale limit a pay-as-you-go file share). See Understanding Azure Files billing and the Scalability and performance targets for Azure Files.
For more information, see Troubleshoot high latency, low throughput, or low IOPS.
Utilization metrics that measure the amount of data being transmitted (throughput) or operations being serviced (IOPS) are commonly used to determine how much work is being performed by the application or workload. Transaction metrics can determine the number of operations or requests against the Azure Files service over various time granularity.
If you're using the Egress or Ingress metrics to determine the volume of inbound or outbound data, use the Sum aggregation to determine the total amount of data being transmitted to and from the file share over a 1 minute to 1 day time granularity. Other aggregations such as Average, Max, and Min only display the value of the individual I/O size. This is why most customers typically see 1 MiB when using the Max aggregation. While it can be useful to understand the size of your largest, smallest, or even average I/O size, it isn't possible to display the distribution of I/O size generated by the workload's usage pattern.
You can also select Apply splitting on response types (success, failures, errors) or API operations (read, write, create, close) to display additional details as shown in the following chart.
:::image type="content" source="media/analyze-files-metrics/utilization-apply-splitting.png" alt-text="Screenshot showing utilization metrics split by API name." lightbox="media/analyze-files-metrics/utilization-apply-splitting.png" border="false":::
To determine the average I/O per second (IOPS) for your workload, first determine the total number of transactions over a minute and then divide that number by 60 seconds. For example, 120,000 transactions in 1 minute / 60 seconds = 2,000 average IOPS.
To determine the average throughput for your workload, take the total amount of transmitted data by combining the Ingress and Egress metrics (total throughput) and divide that by 60 seconds. For example, 1 GiB total throughput over 1 minute / 60 seconds = 17 MiB average throughput.
Provisioned file shares provide Transactions by Max IOPS and Bandwidth by Max MiB/s metrics to display what your workload is achieving at peak times. Using these metrics to analyze your workload help you understand true capability at scale, as well as establish a baseline to understand the impact of more throughput and IOPS so you can optimally provision your Azure file share.
The following chart shows a workload that generated 2.63 million transactions over 1 hour. When 2.63 million transactions is divided by 3,600 seconds, we get an average of 730 IOPS.
:::image type="content" source="media/analyze-files-metrics/transactions-sum.png" alt-text="Screenshot showing the transactions generated by a workload over one hour." lightbox="media/analyze-files-metrics/transactions-sum.png" border="false":::
Now when we compare the average IOPS against the Transactions by Max IOPS, we see that under peak load we were achieving 1,840 IOPS, which is a better representation of the workload's ability at scale.
:::image type="content" source="media/analyze-files-metrics/transactions-by-max-iops.png" alt-text="Screenshot showing transactions by max IOPS." lightbox="media/analyze-files-metrics/transactions-by-max-iops.png" border="false":::
Select Add metric to combine the Ingress and Egress metrics on a single graph. This displays that 76.2 GiB (78,028 MiB) was transferred over one hour, which gives us an average throughput of 21.67 MiB over that same hour.
:::image type="content" source="media/analyze-files-metrics/ingress-egress-sum.png" alt-text="Screenshot showing how to combine ingress and egress metrics into a single graph." lightbox="media/analyze-files-metrics/ingress-egress-sum.png" border="false":::
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":::
On Azure file shares 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 provisioned IOPS.
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 never fail and eventually succeed after retries, latency is impacted during throttling.
To view in Azure Monitor, select the Transactions metric and Apply splitting on response types. The Metadata response types 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/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 Success with Metadata Throttling response types, consider implementing one or more of the following recommendations:
- For SSD SMB file shares, enable Metadata Caching.
- Distribute (shard) your workload across multiple file shares.
- Reduce the volume of metadata IOPS.