Enhance documentation for Azure Optimization Engine - #2267
Enhance documentation for Azure Optimization Engine#2267Hélder Pinto (helderpinto) wants to merge 6 commits into
Conversation
Hélder Pinto (helderpinto)
added
Skill: Documentation
microsoft-github-policy-service
Bot
added
the
Needs: Review 👀
There was a problem hiding this comment.
Pull request overview
This PR improves Microsoft Learn documentation for the Azure Optimization Engine (AOE) in the FinOps Toolkit by adding a dedicated reference page and wiring it into navigation and the changelog. It also includes a functional deployment template change removing a legacy Automation variable.
Changes:
- Added a new AOE “Reference” doc covering runbooks, schedules, variables, and data tables.
- Updated AOE customization guidance and the toolkit changelog/TOC to point to the new reference content.
- Removed the
AzureOptimization_LogAnalyticsWorkspaceKeyAutomation variable from the AOE nested deployment template.
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| src/optimization-engine/azuredeploy-nested.bicep | Removes a legacy Automation variable from the deployment template. |
| docs-mslearn/toolkit/optimization-engine/reference.md | Adds the new AOE reference documentation page. |
| docs-mslearn/toolkit/optimization-engine/customize.md | Links readers to the new reference page for the full variable list. |
| docs-mslearn/toolkit/changelog.md | Announces the new AOE reference page and updates ms.date. |
| docs-mslearn/TOC.yml | Adds the new reference page to the AOE documentation TOC. |
💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Brett Wilson (MSBrett)
left a comment
Brett Wilson (MSBrett)
left a comment
There was a problem hiding this comment.
Two publish-facing defects need correction: the page renders with "Runbooks" as its heading instead of a reference title, and its only in-page link is broken. The remaining comments are non-blocking Microsoft style and navigation improvements.
| #customer intent: As a FinOps user, I want to understand the Azure optimization engine reference tables, runbooks, schedules and variables. | ||
| --- | ||
|
|
||
| # Runbooks |
There was a problem hiding this comment.
This article has no page-level H1, so # Runbooks becomes the rendered page heading—the published page will be titled "Runbooks" even though the TOC entry and title metadata say "Reference".
Adding one heading above this line fixes it and matches the pattern already used in setup-options.md and configure-workspaces.md (page H1 followed by additional H1 sections), so the existing section headings can stay as they are:
# Azure optimization engine referenceOptional: title: Reference (line 2) is very generic for a browser tab and search result. title: Azure optimization engine reference would front-load the searchable keywords; the TOC display name can stay "Reference".
| - Runbooks that access Azure SQL Database use `AzureOptimization_SQLServerHostname`; `AzureOptimization_SQLServerDatabase` defaults to `azureoptimization`. | ||
| - Runbooks that ingest data into Log Analytics use `AzureOptimization_DCEIngestionEndpoint` and the DCR mappings stored in Azure SQL Database. | ||
|
|
||
| See [Variables](#-variables) for more details. |
There was a problem hiding this comment.
The only in-page link on this page doesn't resolve. This anchor is left over from the emoji-heading cleanup—# 🧿 Variables produced #-variables, but the heading is now plain # Variables (line 165), so the anchor is #variables.
See [Variables](#variables) for more details.| @@ -0,0 +1,312 @@ | |||
| --- | |||
| title: Reference | |||
| description: Reference to the optimization engine tables, runbooks, schedules and variables. | |||
There was a problem hiding this comment.
Microsoft style uses the serial comma before the conjunction in a list of three or more items. This applies here and in the #customer intent line (line 11):
description: Reference to the optimization engine tables, runbooks, schedules, and variables.| | `Filters` | User-created recommendation suppressions | Not applicable | Created by the `Suppress-Recommendation` script | `Ingest-SuppressionsToLogAnalytics` and remediation runbooks | Yes | | ||
| | `LogAnalyticsIngestControl` | Storage-to-table mappings, DCR identifiers, and CSV ingestion progress | All CSV export containers | Initialized by deployment and updated by `Setup-LogAnalyticsTablesAndDCRs` | `Ingest-OptimizationCSVExportsToLogAnalytics`, `Ingest-RecommendationsToLogAnalytics`, `Ingest-SuppressionsToLogAnalytics` | No | | ||
| | `Recommendations` | Generated recommendations and resource context | `recommendationsexports` | All `Recommend-*` runbooks; populated by `Ingest-RecommendationsToSQLServer` | Cleanup and `Remediate-*` runbooks | Yes | | ||
| | `SqlServerIngestControl` | Recommendation JSON ingestion progress | `recommendationsexports` | Initialized by deployment | `Ingest-RecommendationsToSQLServer` | No | No newline at end of file |
There was a problem hiding this comment.
Every other Azure Optimization Engine article ends with a ## Related content section. This one stops at the final table with no onward navigation. Consider adding:
## Related content
- [Get started with the Azure Optimization Engine](overview.md)
- [Customize Azure optimization engine](customize.md)
- [Troubleshoot Azure Optimization Engine issues](troubleshooting.md)| ## Adjust thresholds | ||
|
|
||
| For Advisor cost recommendations, the AOE's default configuration produces percentile 99th VM metrics aggregations, but you can adjust them to be less conservative. There are also adjustable metrics thresholds that are used to compute the fit score. The default thresholds values are 30% for CPU (5% for shutdown recommendations), 50% for memory (100% for shutdown) and 750 Mbps for network bandwidth (10 Mbps for shutdown). All the adjustable configurations are available as Azure Automation variables. The information in the next table highlights the most relevant configuration variables. To access them, go to the Automation Account _Shared Resources - Variables_ menu option. | ||
| For Advisor cost recommendations, the AOE's default configuration produces percentile 99th VM metrics aggregations, but you can adjust them to be less conservative. There are also adjustable metrics thresholds that are used to compute the fit score. The default threshold values are 30% for CPU (5% for shutdown recommendations), 50% for memory (100% for shutdown) and 750 Mbps for network bandwidth (10 Mbps for shutdown). All the adjustable configurations are available as Azure Automation variables. The information in the next table highlights the most relevant configuration variables. To access them, go to the Automation Account _Shared Resources - Variables_ menu option. For a complete list of AOE variables, check [the reference](reference.md). |
There was a problem hiding this comment.
"the reference" isn't meaningful out of context—link text should make sense on its own. Since the sentence promises a complete variables list, this should also deep-link to that section rather than the top of the page:
For a complete list of AOE variables, see the [Azure optimization engine reference](reference.md#variables).| ### [Optimization Engine](optimization-engine/overview.md) | ||
|
|
||
| - **Added** | ||
| - Added a comprehensive [Azure Optimization Engine reference](optimization-engine/reference.md) for runbooks, schedules, variables, Log Analytics tables, and SQL Database tables. ([#1271](https://github.com/microsoft/finops-toolkit/issues/1271)) |
There was a problem hiding this comment.
Nit: 125 of 128 citation entries in this file put the issue link before the final period (the #2090 line right below is an example). Moving the period keeps it consistent:
- Added a comprehensive [Azure Optimization Engine reference](optimization-engine/reference.md) for runbooks, schedules, variables, Log Analytics tables, and SQL Database tables ([#1271](https://github.com/microsoft/finops-toolkit/issues/1271)).
microsoft-github-policy-service
Bot
added
Needs: Attention 👋
|
@Hélder Pinto (@helderpinto): you have some new feedback! Please review and resolve all comments and I'll let reviewers know by removing the |
🛠️ Description
This pull request introduces documentation improvements to the FinOps toolkit, primarily by adding a comprehensive reference for the Azure Optimization Engine (AOE) and updating related documentation to reflect this addition. These changes enhance the discoverability and usability of AOE configuration details.
Documentation enhancements:
toolkit/optimization-engine/reference.md) to the AOE section in the table of contents, providing comprehensive documentation for runbooks, schedules, variables, Log Analytics tables, and SQL Database tables.Deployment fixes:
AzureOptimization_LogAnalyticsWorkspaceKeyautomation variable from deployment (leftover of upgrade to DCR-based ingestion) and updated variables documentation accordingly.Changelog update:
ms.datefield inchangelog.mdto reflect the latest documentation update.Fixes #1271
📋 Checklist
🔬 How did you test this change?
📦 Deploy to test?
🙋♀️ Do any of the following that apply?
📑 Did you update
docs/changelog.md?📖 Did you update documentation?