Microsoft Fabric Capacity Metrics App: Install, Read, and Troubleshoot

By A.J. · Documentation review: 5 November 2026 · Independent guide

Learning resources / Fabric Capacity Metrics app

The Capacity Metrics app answers a short list of questions that come up whenever a capacity gets busy:

• Which capacity is under pressure, and during which hours?
• Which workspace, item type, or single item used the most capacity units?
• Was it a refresh, a Spark job, a pipeline, a warehouse query, or people using reports?
• Is the capacity throttling, or is it just bursting and smoothing as designed?
• Can you trace an item down to the operation, its status, its duration, the user, and the operation ID?

This guide follows that order. It covers both reports, gives you a repeatable way to investigate, and says what to do once you find the cause.

1. What the app does

A Fabric capacity is a pool of compute measured in capacity units (CUs). Workspaces assigned to the capacity draw from that pool. The Capacity Metrics app reports how the pool is used over time, by workload, workspace, item, and operation. It supports EM/A and P SKUs as well as Fabric SKUs.

It is a monitoring and investigation tool. It is not an invoice, a request tracer, or an alerting system. What it does well is connect a capacity-level problem to the items behind it.

2. Default report and preview report

After you install or upgrade to version 3.0, the navigation pane lists both reports. The default report stays the default, and you can switch to the preview report from the navigation pane at any time.

Microsoft’s pages use two names for the Spark page: older ones say “Autoscale compute for Spark” and newer ones say “On-demand Compute for Spark”. They are the same page for capacities that bill Spark on demand. If you search the docs, try both.

3. Prerequisites and installation

You need two things:

• You must be a capacity admin to install the app.
• You need a Power BI license (Pro, Premium Per User, or an individual trial) to open and use it.

Microsoft recommends installing the app in a workspace with a Pro license, so the app does not add to the throttling on the capacity it is watching. A monitoring report that runs on the capacity you are investigating can fail at the worst moment.

First-time install

1. Get the app. Open the Microsoft Fabric Capacity Metrics listing and select Get it now. Or open Power BI, select Apps, then Get apps, search for Microsoft Fabric, and pick Microsoft Fabric Capacity Metrics.
2. Sign in. Use your Microsoft account and complete the registration screen. You land back in Fabric.
3. Install. In the Install this Power BI app window, select Install and wait a few seconds.
4. Run it once. Open the app from the Apps area and connect it to your data (next section).

Government cloud tenants use separate install links for GCC, GCC High, DoD, and the China cloud. They are on the install page. OneLake is not supported in GCC.

Upgrade an existing install

When you get the new version from AppSource, you choose one of three options. This list comes from the earlier version of this guide and was not re-checked on the install page this time.

To keep your old workspace for comparison, install a second copy and give the new workspace a clear name.

4. First run, parameters, and data delay

In Fabric, switch to the Power BI experience if needed, open Apps, and open the Capacity Metrics app. When it says you have to connect to your own data, select Connect.

Parameters

UTC_offset = 5.5

The app has other internal parameters. Don’t change them, because that can break the semantic model and the report. On the second screen, pick OAuth2 as the authentication method, which is the only supported one, and set the privacy level to Organizational. Then sign in and choose a capacity. The first load can take a few minutes. If nothing shows, refresh the app.

Data delay

• Usage data usually shows up 10 to 15 minutes after the activity. Microsoft’s example: at 5:15 PM local time, a utilisation chart might show data up to about 5:00 PM.
• Capacities, workspaces, and items refresh with a scheduled semantic model refresh at midnight local time. A new capacity, workspace, or item, or a workspace moved between capacities, appears after the next refresh.
• A new item or workspace also needs at least one operation that used CUs in the past 14 days.
• To see eligible new data sooner, refresh the app’s semantic model manually.
• If your capacities change, for example you get just-in-time tenant admin access, update the RegionName parameter if your version uses it, then refresh the model.

5. Health page: find the capacity that needs attention

Start here if you run more than one capacity. The preview Health page shows the capacities you can access in the region you select.

The summary cards count active capacities, capacities with no throttling, and capacities that spent any time in interactive delay, interactive rejection, background rejection, or active surge protection. A capacity can be counted in more than one card. If a mitigation such as capacity overage stopped throttling, the capacity is not counted as throttled.

At risk means the capacity spent time above 90% of the interactive delay threshold. Read it as an early warning, not as proof that users were affected.

Things that trip people up on this page

• State percentages may not add up to 100% because some states overlap.
• A capacity can show 100% no throttling and still not be green. A very short throttling period can round to 0.00%.
• Storage here counts Fabric item storage but not Power BI storage.
• Deleted capacities do not appear. Paused capacities appear if they were active in the period.

6. Compute page: read CU usage correctly

The Compute page takes you from “the capacity had a problem” to “these items contributed”. The preview report offers three views:

Smoothed or unsmoothed

Fabric spreads the capacity impact of an operation over later timepoints. A background operation might report its usage at 8:00 AM. The unsmoothed view puts all of it at 8:00 AM. The smoothed view spreads it across the period in which it counts against the capacity. Use smoothed for throttling questions and unsmoothed to see how big each workload was when it reported.

CU seconds and CU percentage

The preview Compute page has a CU-seconds view and a percentage view. The seconds view helps when the SKU changed during the period, because you compare actual compute rather than a percentage of a changing budget.

AI Functions

The default report shows AI Functions as its own operation category in Compute and in the Timepoint pages. It is tracked apart from Spark and Dataflows Gen2. Keep it separate when you assign consumption to a team, and compare it on its own when an AI-heavy job lines up with a spike.

On-demand Compute for Spark

This page covers capacities with on-demand billing for Apache Spark. Operations not billed that way stay on the regular Compute page. Spark on-demand data is not smoothed. The usage chart shows billable (blue) and non-billable (red) columns in one-minute periods against a one-minute maximum CU limit line. With no filter it shows the peak timepoint every six minutes, and with a filter it shows every minute. The matrix by item and operation can be sorted by CU seconds, duration, and users, and it has a billing type column. Don’t compare these one-minute values with the 30-second smoothed charts as if they were the same measure.

7. How throttling works

Fabric lets operations burst above the SKU’s compute so they finish fast, then smooths the usage over later timepoints so the capacity is not punished for it. Timepoints are 30 seconds long, which makes 2,880 in 24 hours.

• Interactive operations are smoothed over a minimum of five minutes and up to 64 minutes, depending on how much they use.
• Background operations are smoothed over 24 hours.

Future capacity, meaning the CUs in later timepoints, pays for the smoothed usage. That is why one utilisation percentage cannot tell you the whole story.

The four stages

Even above 100% utilisation Fabric does not throttle at once. Overage protection lets a capacity use 10 minutes of future capacity first. Throttling then comes in steps, and each step is based on how much future capacity is used up.

Microsoft notes it can change the throttling policy, so check the current policy page before you quote these numbers in a runbook.

Rules that explain odd behaviour

• Operations already running are not throttled. Only operations requested after throttling starts are affected, including long jobs submitted earlier, which run to completion.
• Warehouse counts as background. Fabric reports almost all Warehouse operations as background, to get 24-hour smoothing. A chain that starts interactive can still throttle a background step as interactive.
• Real-Time Intelligence skips the delay stage. It waits until the rejection phase at 60 minutes. Eventstreams reduce the CUs held by open streams instead of rejecting new operations.
• Compound throttling protection. Where a workload supports it, a chain of calls is throttled once per capacity. Microsoft lists DirectQuery over other semantic models and DAX queries from paginated reports as supported.
• Classification can shift. An operation can be classed interactive at submission and smoothed as background later. When it is unclear, Fabric treats it as background.
• Only billable operations count. Non-billable preview operations show in the app as a warning of future impact, but throttling calculations ignore them.
• Throttling is per capacity. When one capacity produces OneLake items and another consumes them, the consuming capacity’s state decides whether it throttles the calls.

A worked smoothing example

One background job uses 1 CU hour, which is 3,600 CU seconds. On an F2 (2 CUs), that is smoothed over 24 hours, or 2,880 timepoints. The job adds 3,600 / 2,880 = 1.25 CU seconds to each timepoint. An F2 has 2 x 30 = 60 CU seconds per timepoint, so the job takes about 2.1% of every timepoint. It also takes about 2.1% of the 10-minute and 60-minute limits. The job used six times what the F2 has in 10 minutes, yet the capacity is not throttled, because smoothing spreads it so thin.

Overage, carryforward, and burndown

When operations use more than the SKU supports in a timepoint, the system works out an overage after smoothing. If overages go beyond the 10-minute window, they become carryforward CUs. Later timepoints that are not full burn the carryforward down. Throttling continues until it is paid off. So a capacity can look fine at the moment you check and still be paying for an earlier burst.

Timepoint A: budget 100, used 110, overage added 10
Timepoint B: budget 100, used 93, unused 7
Carryforward left: 10 - 7 = 3

The preview report also has a Capacity Overage view for paid overage. That is separate from carryforward, so read the labels and check any extra charge against your capacity overage settings.

How to tell users are being throttled

Rejected requests return the status code CapacityLimitExceeded or messages such as “Your organization’s Fabric compute capacity has exceeded its limits. Try again later” or “Cannot load model due to reaching capacity limits”. Microsoft also warns that slow performance is often down to how an item is built, and only sometimes down to throttling. Confirm with the System events table and the throttling charts before you blame the capacity.

8. Stopping throttling

A capacity heals itself once the overload ends, so waiting is always an option. If you cannot wait, Microsoft lists these for F SKUs:

For P SKUs, turn on Autoscale. If throttling is constant, Microsoft’s advice is to spread workloads across several capacities or increase the SKU. Fix the workload first when one item is the cause.

9. Workspace and item investigation

Workspace Detail (preview)

Workspace Detail is the step between “the capacity spiked” and “this item did it”. It works on one workspace at a time. Use the capacity, workspace, item, user, operation, and date filters at the top. The cards show active items, CU seconds, duration, and users. The trend views show unsmoothed CU, duration, operations, and users by item kind, and you can drill from day to hour. The tables break CU down by item kind, by item, and by operation, and the Item Details table lists each item with CU, duration, users, and billing type.

1. Open Workspace Detail and choose one capacity and one workspace.
2. Set the date range to match the incident you saw on Compute.
3. Compare CU, duration, operations, and users. A rising CU total with a rising operation count points to a different problem than one long operation.
4. Switch between CU by item kind, by item, and by operation. Sort the Item Details table by CU seconds.
5. Select the suspect item and choose Item Detail to drill through.

Item details (preview)

The Item details page shows the workspace, item type, and total CU seconds for one item, with up to 14 days of history. Its trends cover smoothed CU, unsmoothed CU, duration, and operation status. It breaks consumption down by operation, status, and user, and the operations table lists CU, duration, and operation ID. An operation ID can help you match an event to other telemetry, for example Power BI visual query IDs in workspace monitoring.

10. Storage page

The preview Storage page analyses one capacity. It shows the SKU, number of workspaces, current storage, and average storage, with filters for capacity and billing type.

• Current is the latest reported value. Daily values are the last value that day, with hourly drill-down.
• Average is the daily average, also with hourly drill-down.

The operation breakdown can include OneLake Storage, Allocated SQL Storage, Eventhouse Standard Storage, Eventhouse Cache Storage, and Data Activator Storage. The workspace table shows who holds the most, and splits billable from non-billable.

11. Investigation lab: a slow capacity every morning

A fictional team reports slow reports between 9:00 and 10:00 AM. Overnight Spark and Data Factory jobs share the capacity. The aim is to learn whether this is capacity pressure, which item contributed, and what to do. Resizing is not the first step.

1. Start at Health. Pick the capacity. If the incident was earlier today, use the 24-hour or 14-day views. Write down the window and the last update time.
2. Open Compute. Use Smoothed: Last 24 Hours. Find where the heat map changes colour and select that period to filter everything else.
3. Check throttling and carryforward. Read interactive delay, interactive rejection, background rejection, overage, and any surge protection together. Don’t conclude from a utilisation figure alone.
4. Compare contributors and impacted items. Contributors tell you who used the CUs. Impacted items tell you who was hurt. They are often different items.
5. Drill through to the suspect item. Look at duration, status, user, CU, and operation ID. Is it one long operation, many small ones, or a schedule that repeats?
6. Look at the unsmoothed view. Use Unsmoothed: Last 14 Days to see how the workload reported itself. Don’t use it alone to decide on throttling.
7. Pick the smallest fix. Tune the item or move its schedule first. Scale only when the evidence says the workload cannot run well in the current SKU.
8. Check again. Compare like windows on the same views. Note CU, throttling time, duration, and user impact.

Runbook for a 9:00 AM slowdown

The times are made up for the example. Assume a shared F64 with semantic models, a Lakehouse, notebooks, and pipelines. Users say a report gets slow when the morning refresh starts.

Before you resize

Ask four things. Is the capacity throttling, or only busy? Does one item, one retry loop, or one Spark shuffle account for most of the load? Is it real concurrency? Does the pattern repeat on several business days? If one item dominates, tune or reschedule it first. Resize when tuning is done and the capacity still can’t meet the target, or as a clearly temporary step during an incident.

After the fix

• Compare the same report, date range, and weekday.
• Note the SKU for each period. CU% changes when the SKU changes even if raw usage does not.
• Track CU, duration, operation count, and failures, and also what users saw: delays, failed refreshes, missed deadlines.
• Write down the change and its owner. The app is the evidence, and the incident record is where the decision lives.

What to record for each incident

12. What to fix afterwards

The app shows where to look. It does not say which code change is right, so check the fix with the tool for that workload.

13. Alerts

The Capacity Metrics app does not support alerts or notifications. Use Fabric capacity overview events for capacity health and Fabric capacity operation events for single operations.

Operation events can be very frequent on a busy capacity. Group them by something stable such as capacityId, workspaceId, itemId, or operationName, and filter on fields like itemKind, utilizationType, or status. Useful measures include capacityUnitMs, durationMs, and throttlingDelayMs. An ungrouped per-operation alert will flood you. Responses can go to email, Teams, a Fabric activity, or a custom action. The event consumer must be in the same region as the source, and outbound access protection or private link settings can affect cross-workspace consumption.

Set a capacity alert from Real-Time hub

1. Open Real-Time hub and find the Fabric capacity overview events.
2. Choose an alert template: capacity usage percentage over a threshold, or a capacity metric over a threshold.
3. Select the capacity and set a threshold. The usage template defaults to 80%, which is a starting point and not a rule.
4. Or alert on a state change such as Overloaded, Active, Suspended, or Deleted.
5. Pick the destination, then test that the alert reaches the right owner.

14. Sharing and privacy

Installing the app creates a workspace in your tenant. You must be a capacity admin to share the report. Open the app, go to the workspace where you installed it, and select Share. You can share with people in your organisation or with B2B guests. A guest who is in the tenant still can’t open the report until you share it with them.

The app shows user names and emails. To hide them, turn off Show user data in the Fabric Capacity Metrics app and reports in the admin portal. Check your data governance policy before you give a wide audience user-level activity.

15. Known quirks

These come from the limitations list on Microsoft’s overview page. They explain several things that look like bugs.

• The throttling thresholds on the charts do not reflect surge protection settings. Check the real surge protection thresholds in the admin portal.
• In the interactive and background operation tables, the Throttling(s) column shows zero when throttling is disabled, even if the capacity is overloaded.
• CU % in the top heartbeat line chart can differ from the Total CU in the operation tables by 0.01 to 0.05 percent.
• On the Capacity utilization and throttling chart in logarithmic view, the left and right axes don’t line up.
• The System events table does not list a state that stayed the same over the period.
• The CU (s) column in the matrix by item and operation adds up the item’s past 14 days, including time in a previous workspace if you moved it.
• Exporting data from the Export Data page can sample the data.
• Tenant-level private links work. Workspace-level private links do not work on workspaces where the app is installed.
• Don’t build your own reports on the app’s semantic model. Microsoft supports it only for the reports in the app.

16. Troubleshooting

17. Frequently asked questions

18. Official Microsoft references

Use these when the app or the preview changes.

This guide reflects Microsoft documentation reviewed on 5 November 2026. The redesigned report is in preview, and Microsoft updates the app often. Before you use a chart as incident evidence, confirm the report name, page, time range, SKU, and last refresh time. Incident descriptions and diagrams here are illustrations, not tenant measurements.