Add comprehensive troubleshooting guide for reservation savings calculation issues

[Copilot]

Problem

Users are reporting zero savings for reservations in FinOps toolkit reports, even when they have active reservations in use. This manifests as:

• Rate optimization reports showing 0.00% estimated savings rate (ESR) for reservations
• ContractedCost, EffectiveCost, and ListCost all showing identical values for reservation usage
• Confusion about why price sheet exports don't seem to populate missing cost values

Root Cause

This is a known limitation in Microsoft Cost Management's FOCUS export, not a bug in the FinOps toolkit. According to Microsoft's FOCUS conformance documentation:

ContractedUnitPrice and ContractedCost are 0 for:

• Enterprise Agreement (EA) Marketplace charges
• EA reservation usage when cost allocation is enabled
• All Microsoft Customer Agreement (MCA) reservation usage

The FinOps toolkit already implements the recommended workaround by joining cost data with price sheet data (lines 410-489 in IngestionSetup_v1_2.kql). However, when the price join fails or price data is missing, it falls back to setting ContractedCost = EffectiveCost, resulting in zero calculated savings.

Solution

This PR adds comprehensive documentation to help users diagnose and resolve reservation savings calculation issues:

1. New Troubleshooting Guide

Created a detailed troubleshooting guide at docs-mslearn/toolkit/hubs/troubleshooting-reservation-savings.md that includes:

• Symptoms: Clear description of what users will see when this issue occurs
• Root cause explanation: Why Microsoft Cost Management behaves this way
• Verification steps: How to check if price sheet exports are configured correctly
• Diagnostic queries: KQL queries to identify exactly why the price join is failing
• Resolution steps: Specific actions to take for each scenario (missing exports, wrong scope, timing issues)
• Verification queries: How to confirm the fix is working

2. Enhanced Error Documentation

Updated the MissingContractedCost and MissingListCost error documentation in docs-mslearn/toolkit/help/errors.md to:

• Reference the FOCUS conformance documentation explaining this is expected behavior
• Provide a link to the new troubleshooting guide
• Clarify that this specifically affects MCA reservation usage

3. Updated Savings Calculations Guide

Enhanced docs-mslearn/toolkit/hubs/savings-calculations.md to reference the new troubleshooting guide for users experiencing zero savings scenarios.

4. Navigation and Discoverability

• Added the troubleshooting guide to the table of contents (TOC.yml)
• Updated the changelog to document these documentation improvements

Key User Actions Required

The documentation guides users to verify:

1. Correct export scope: For MCA accounts, price sheet must be exported from billing profile scope, not billing account scope
2. Proper timing: Price sheet must be exported before cost data for each billing period
3. Data availability: Use diagnostic queries to verify prices exist in the Prices_final_v1_2 table
4. Join success: Confirm meter IDs, offer IDs, and billing profile IDs match between cost and price data

Testing

The documentation includes several diagnostic queries that users can run to:

• Verify price data exists for their billing period
• Check if reservation meters have matching prices
• Identify which specific meters are missing prices
• Confirm the fix is working after re-exporting data

Related Issues

• Addresses the issue described in the problem statement
• Related to #1811 (mentioned in issue comments)
• Related to #873 (original price join tracking)

References

All recommendations are based on official Microsoft documentation:

• FOCUS Conformance Summary
• Tutorial: Create and manage Cost Management exports
• Configure scopes for FinOps hubs

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Reservation Cost in Ingestion ADX Databse</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

We have setup the finops toolkit and also using powerbi report setup the cost summary, governance, rate optimization report for our azure tenant. After the creation of rate optimization we noticed that there is no savings from RIs being calculated as we didn't exported the prices yet. We exported the price yet and noticed that the savings calculated is still 0 even though we have signitifcant amount of central reservation being used in the tenant.
We noticed that the ContractedCost and ListCost is 0 in the Focus cost export when central reservation applies to the resource which is fine. But when we use KQL to find the ContractedCost, ListCost and EffectiveCost for the Commitment discount type is Reservation then all these cost are same.

KQL query being used

Costs_final_v1_2
| where BillingPeriodStart between ((now() - 90d) .. now())
| extend Period = extract(@"(\d{4}-\d{2}-\d{2})", 1, tostring(BillingPeriodStart))
| where Period == "2025-08-01"
| where CommitmentDiscountType == "Reservation"
| project EffectiveCost, ContractedCost, ListCost

👣 Repro steps

TODO: Add repro steps below:

1. Go to
2. Click on
3. Scroll down to
4. See error

Ingest Focus Cost export and then ingest Prices export to the msexports in the storage account. After the ADX pipeline runs, then setup the Rate Optimization workbook.
In the ingestion database use the KQL which i provided and see if the price for reservation is same for column contractedcost, effectivecost and listcost or not. As that should help in calculating the discount from savings.

🤔 Expected

TODO: Add a clear and concise description of what you expected to happen.

ContractedCost and Effective cost should be different in the ingestion database in order to calculate savings. Right now its same so it shows savings as 0. 

We have indeed ingested Prices export and reservation export and triggered the ADX pipeline to get it ingested. What should we do in order to calculate the savings from the RIs?
Right now the effective cost is getting populated for contracted cost and list cost for reservation transaction which shows savings as 0. I also looked at the FOCUS cost export manually and for reservation transaction it shows 0 amount for contracted and list cost which is usually the case for reservation transaction.
Using above mentioned KQL you can see what we see in ingestion folder for reservation transactions below in screenshot

📷 Screenshots

TODO: If applicable, add screenshots to help explain your problem. Remove if not applicable.

Snippet from the KQL report from ingestion database showing same cost

Snippet from the Rate Optimization report showing same cost report

ℹ️ Additional context

TODO: Add any other context about the problem here. Remove if not applicable.

Is there an issue in the transformation which is replicating the effective cost value to contracted cost instead of picking up contracted cost from the pricesheet?

🙋‍♀️ 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)

@MS-mikeo @anshu2813 - I believe you are running into the same issue as we have seen on many other deployments (https://github.com//issues/1811). Have you exported the price list and is this an MCA account? @MS-mikeo I have tried it in different order and it does not seem to impact the outcome.

Fixes #1835

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.