Add comprehensive documentation for Azure Resource Graph payload size limit errors in Governance and Workload Optimization reports

[Copilot]

Problem

Users with large Azure environments are encountering payload size limit errors when attempting to load the Governance and Workload Optimization Power BI reports. The error message appears as:

Response payload size is 48439993, and has exceeded the limit of 16777216. Please consider querying less data at a time and make paginated call if needed.

This occurs because both reports use Azure Resource Graph queries with [resultTruncated = false] to retrieve comprehensive resource details. For organizations with millions of resources, the response payload exceeds Azure Resource Graph's 16 MB limit, preventing the reports from loading.

Root Cause

Azure Resource Graph enforces a 16 MB (16,777,216 bytes) response payload limit per query. The Governance and Workload Optimization reports are designed to show detailed resource-level information and are optimized for small to medium-sized environments. When used in large enterprise environments with millions of resources, the unfiltered queries exceed this limit.

This is a by-design limitation of Azure Resource Graph, not a bug in the FinOps toolkit.

Solution

This PR provides comprehensive documentation and practical guidance to help users understand and mitigate the payload size limit error. Since this is a platform limitation, the solution focuses on empowering users with actionable workarounds.

Changes Made

1. Enhanced Error Documentation (help/errors.md)

Expanded the existing "Response payload size exceeded" error section with detailed, step-by-step mitigation strategies:

Option 1: Filter by Subscription

| where subscriptionId in~ ('subscription-id-1', 'subscription-id-2')

Option 2: Filter by Tags

| where tags.Environment in~ ('Production', 'Staging')
| where tags.CostCenter == '12345' and tags.Environment =~ 'Production'

Option 3: Remove Unnecessary Columns

• Guidance on identifying and removing columns that aren't used in report visuals

Option 4: Disable Problematic Queries

• Instructions for disabling specific failing queries while keeping others functional

Each option includes:

• Clear step-by-step instructions for implementing the solution in Power Query Editor
• KQL code examples with proper syntax
• Explanations of when to use each approach
• Links to official Microsoft documentation

2. Updated Report Documentation

Added "Known limitations" sections to both affected reports:

• Governance report (power-bi/governance.md)
• Workload Optimization report (power-bi/workload-optimization.md)

These sections:

• Explain the 16 MB Azure Resource Graph payload limit
• Clarify that reports are designed for small to medium-sized environments
• Provide quick summary of mitigation options
• Link to detailed error reference guide

3. Changelog Entry

Added documentation improvements to the Unreleased section of changelog.md, following the repository's documentation standards.

Impact

• ✅ No code changes - Documentation only, zero risk of introducing bugs
• ✅ No breaking changes - All existing functionality preserved
• ✅ Improved user experience - Clear, actionable self-service guidance
• ✅ Reduced support burden - Users can resolve issues independently
• ✅ Proactive education - Users understand limitations before encountering errors
• ✅ Consistent guidance - Aligned with official Microsoft Azure Resource Graph documentation

References

This documentation is based on and links to official Microsoft documentation:

• Working with large Azure resource data sets
• Troubleshoot errors using Azure Resource Graph
• Azure Resource Graph Power BI connector quickstart
• Guidance for throttled requests

Testing

• [x] Verified all documentation links are valid
• [x] Confirmed markdown formatting follows repository standards
• [x] Validated KQL syntax examples against Azure Resource Graph documentation
• [x] Ensured consistency between Governance and Workload Optimization report documentation
• [x] Tested that solutions are practical and align with Microsoft best practices

Future Enhancements (Out of Scope)

Potential product improvements to consider in future releases:

1. Add subscription/tag filter parameters directly to report templates
2. Implement pagination for large datasets
3. Provide aggregated summary views for enterprise environments
4. Optimize default queries to select only required columns
5. Add environment size detection during report setup

---

Fixes: Provides mitigation guidance for the Governance Report payload size limit error reported in the issue.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Governance Report is not loading says payload size limit is exceeding the limits.</issue_title> <issue_description><!-- ⚠️⚠️⚠️ BEFORE YOU SUBMIT ⚠️⚠️⚠️

1. Confirm there isn't an issue already. If so, vote it up (👍) and add comments.
2. Complete all TODO items below and remove the TODO lines after.
3. Internal: Add applicable labels: Type, Micro PR, Area -->

🐛 Problem

TODO: Governance report is not loading - With payload size limits exceeding the limits. Currently using V0.11 version of Finops hub. MCA customer with billing account admin privileges is trying to pull out data in the governance report, below is the error reported.

👣 Repro steps

TODO: Add repro steps below:

1. Go to Governance.Pbit
2. Click on Load
3. See error

🤔 Expected

TODO: All the ADF pipelines are successful and remaining cost summary, workload optimization reports are loading ok., where-as governance report is not at all loading at this moment.

📷 Screenshots

TODO: Attached is the screenshot.

ℹ️ Additional context

TODO: Governance Reports fails to load in the customer environment due to payload size limits issue.

🙋‍♀️ Ask for the community

We could use your help:

1. Please vote this issue up (👍) to prioritize it.
2. Leave comments to help us solidify the vision. </issue_description>

<agent_instructions>Triage the issue, research using mslearn, provide proposed solutions along with links/citations to authorative sources.</agent_instructions>

Comments on the Issue (you are @copilot in this section)

Fixes microsoft/finops-toolkit#1768

---

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.