feat(sre-agent): add FinOps recipe content

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "src/templates/sre-agent/submodules/azcapman"]
+	path = src/templates/sre-agent/submodules/azcapman
+	url = https://github.com/microsoft/azcapman.git

src/queries/catalog/ai-cost-by-application.kql

@@ -0,0 +1,33 @@
+// ============================================================================
+// Query: Azure OpenAI Cost by Application
+// Description:
+//   Breaks down Azure OpenAI costs by application, cost center, team, and environment tags.
+//   Useful for AI workload showback, chargeback, and unit economics analysis.
+// Author: FinOps Toolkit Team
+// Parameters:
+//   startDate: Start date for the reporting period (e.g., startofmonth(ago(30d)))
+//   endDate: End date for the reporting period (e.g., startofmonth(now()))
+// Output:
+//   Each row represents a tagged Azure OpenAI cost grouping with token count and cost metrics.
+// Usage:
+//   Use this query to allocate Azure OpenAI usage and cost to applications, teams, and environments.
+// Last Updated: 2026-05-26
+// ============================================================================
+
+let startDate = startofmonth(ago(30d));
+let endDate = startofmonth(now());
+Costs()
+| where ChargePeriodStart >= startDate and ChargePeriodStart < endDate
+| where x_SkuMeterSubcategory has "OpenAI"
+| extend parsedTags = parse_json(Tags)
+| extend Application = tostring(parsedTags["application"])
+| extend CostCenter = tostring(parsedTags["CostCenter"])
+| extend Environment = tostring(parsedTags["environment"])
+| extend Team = tostring(parsedTags["team"])
+| summarize
+    TokenCount = sum(ConsumedQuantity),
+    EffectiveCost = sum(EffectiveCost),
+    BilledCost = sum(BilledCost)
+    by Application, CostCenter, Team, Environment, ResourceName, x_SkuMeterSubcategory
+| extend CostPer1KTokens = iff(TokenCount == 0, 0.0, EffectiveCost / TokenCount * 1000)
+| order by EffectiveCost desc

src/queries/catalog/ai-daily-trend.kql

@@ -0,0 +1,27 @@
+// ============================================================================
+// Query: Azure OpenAI Daily Cost and Token Trend
+// Description:
+//   Returns daily Azure OpenAI token consumption and effective cost.
+//   Useful for AI workload anomaly detection, forecasting, and trend reporting.
+// Author: FinOps Toolkit Team
+// Parameters:
+//   startDate: Start date for the reporting period (e.g., ago(30d))
+//   endDate: End date for the reporting period (e.g., now())
+// Output:
+//   Each row represents one day with token count, cost, and cost per 1K tokens.
+// Usage:
+//   Use this query to monitor AI workload consumption trends and detect daily cost spikes.
+// Last Updated: 2026-05-26
+// ============================================================================
+
+let startDate = ago(30d);
+let endDate = now();
+Costs()
+| where ChargePeriodStart >= startDate and ChargePeriodStart < endDate
+| where x_SkuMeterSubcategory has "OpenAI"
+| summarize
+    DailyTokens = sum(ConsumedQuantity),
+    DailyCost = sum(EffectiveCost)
+    by bin(ChargePeriodStart, 1d)
+| extend CostPer1KTokens = iff(DailyTokens == 0, 0.0, DailyCost / DailyTokens * 1000)
+| order by ChargePeriodStart asc

src/queries/catalog/ai-model-cost-comparison.kql

@@ -0,0 +1,31 @@
+// ============================================================================
+// Query: Azure OpenAI Model Cost Comparison
+// Description:
+//   Compares token volume, effective cost, list cost, and discount percentage by model.
+//   Useful for AI model cost efficiency analysis and rate optimization.
+// Author: FinOps Toolkit Team
+// Parameters:
+//   startDate: Start date for the reporting period (e.g., startofmonth(ago(30d)))
+//   endDate: End date for the reporting period (e.g., startofmonth(now()))
+// Output:
+//   Each row represents one Azure OpenAI model or SKU description with cost per 1K tokens.
+// Usage:
+//   Use this query to compare model economics and identify where model or commitment changes may reduce AI spend.
+// Last Updated: 2026-05-26
+// ============================================================================
+
+let startDate = startofmonth(ago(30d));
+let endDate = startofmonth(now());
+Costs()
+| where ChargePeriodStart >= startDate and ChargePeriodStart < endDate
+| where x_SkuMeterSubcategory has "OpenAI"
+| extend Model = x_SkuDescription
+| summarize
+    TokenCount = sum(ConsumedQuantity),
+    EffectiveCost = sum(EffectiveCost),
+    ListCost = sum(ListCost)
+    by Model
+| extend CostPer1KTokens = iff(TokenCount == 0, 0.0, EffectiveCost / TokenCount * 1000)
+| extend ListPer1KTokens = iff(TokenCount == 0, 0.0, ListCost / TokenCount * 1000)
+| extend DiscountPercent = iff(ListCost == 0, 0.0, (ListCost - EffectiveCost) / ListCost * 100)
+| order by EffectiveCost desc

src/queries/catalog/ai-token-usage-breakdown.kql

@@ -0,0 +1,35 @@
+// ============================================================================
+// Query: Azure OpenAI Token Usage Breakdown
+// Description:
+//   Breaks Azure OpenAI token consumption down by model version and input/output direction.
+//   Calculates effective unit cost per token and cost per 1K tokens.
+// Author: FinOps Toolkit Team
+// Parameters:
+//   startDate: Start date for the reporting period (e.g., startofmonth(ago(30d)))
+//   endDate: End date for the reporting period (e.g., startofmonth(now()))
+// Output:
+//   Each row represents one model and direction with token count and cost metrics.
+// Usage:
+//   Use this query to analyze AI workload unit economics, token direction mix, and model cost efficiency.
+// Last Updated: 2026-05-26
+// ============================================================================
+
+let startDate = startofmonth(ago(30d));
+let endDate = startofmonth(now());
+Costs()
+| where ChargePeriodStart >= startDate and ChargePeriodStart < endDate
+| where x_SkuMeterSubcategory has "OpenAI"
+| extend Model = x_SkuDescription
+| extend Direction = case(
+    Model contains "Input", "Input",
+    Model contains "Output", "Output",
+    "Other")
+| summarize
+    TokenCount = sum(ConsumedQuantity),
+    EffectiveCost = sum(EffectiveCost),
+    BilledCost = sum(BilledCost),
+    ListCost = sum(ListCost)
+    by Model, Direction, x_SkuDescription
+| extend UnitCostPerToken = iff(TokenCount == 0, 0.0, EffectiveCost / TokenCount)
+| extend CostPer1KTokens = UnitCostPerToken * 1000
+| order by EffectiveCost desc

src/queries/catalog/allocation-accuracy-index.kql

@@ -0,0 +1,35 @@
+// ============================================================================
+// Query: Allocation Accuracy Index
+// Description:
+//   Calculates the percentage of total effective cost that is directly attributed using a
+//   three-signal heuristic: allocation rule, cost center, or ownership-tag evidence.
+// KPI: Allocation Accuracy Index (AAI)
+// Formula: Allocation Accuracy Index (AAI) = (Directly Attributed Costs / Total Infrastructure Costs) × 100
+// Author: FinOps toolkit
+// Parameters:
+//   startDate: datetime; start date for the reporting period (default: startofmonth(ago(30d)))
+//   endDate: datetime; end date for the reporting period (default: startofmonth(now()))
+//   allocationEvidenceTagKeys: dynamic; tag keys treated as ownership evidence (default: dynamic(['cost-center','team','owner','application','product']))
+// Output:
+//   Each row represents one BillingCurrency and returns DirectlyAttributedCost, TotalEffectiveCost,
+//   and AAI for Hub-visible CSP costs in the reporting window.
+// Usage:
+//   Use this query to measure how much effective cost is directly attributable within FinOps Hub.
+// Scope Notes: Hub-only AAI. Does not include on-prem, SaaS, or other infrastructure outside Hub schema.
+// Last Tested: 2026-05-28 against msbwftktreyhub.westus.kusto.windows.net/Hub (1,366,763 cost rows in 2026-04 window). UAT result: PASS — 1 row returned
+// =========================================================================
+let startDate = startofmonth(ago(30d));
+let endDate = startofmonth(now());
+let allocationEvidenceTagKeys = dynamic(['cost-center','team','owner','application','product']);
+Costs()
+| where ChargePeriodStart >= startDate and ChargePeriodStart < endDate
+| where not(ChargeCategory == 'Purchase' and isnotempty(CommitmentDiscountCategory))
+| extend tmp_IsAttributed = isnotempty(x_CostAllocationRuleName)
+                          or isnotempty(x_CostCenter)
+                          or array_length(set_intersect(bag_keys(Tags), allocationEvidenceTagKeys)) > 0
+| summarize
+    DirectlyAttributedCost = todouble(sumif(EffectiveCost, tmp_IsAttributed)),
+    TotalEffectiveCost = todouble(sum(EffectiveCost))
+    by BillingCurrency
+| extend AAI = iff(TotalEffectiveCost == 0, 0.0, DirectlyAttributedCost / TotalEffectiveCost * 100.0)
+| project BillingCurrency, DirectlyAttributedCost, TotalEffectiveCost, AAI

src/queries/catalog/anomaly-detection-rate.kql

@@ -0,0 +1,53 @@
+// ============================================================================
+// Query: Anomaly Detection Rate
+// Description:
+//   Calculates the percentage of effective spend attributable to anomaly-flagged days.
+//   Builds daily cost series per service category and billing currency, then applies time-series anomaly detection.
+// KPI: Anomaly Detection Rate
+// Formula: Total Cost of Anomaly Spikes / Total Spend = Anomaly Cost %
+// Author: FinOps toolkit
+// Parameters:
+//   startDate: datetime; Start date for the reporting period (default: startofmonth(ago(30d)))
+//   endDate: datetime; End date for the reporting period (default: startofmonth(now()))
+//   sensitivity: real; Anomaly detection sensitivity for series_decompose_anomalies() (default: 1.5)
+// Output:
+//   Each row returns a BillingCurrency and ServiceCategory pair (plus an Overall rollup row) with AnomalyCost, TotalCost, and AnomalyRatePercent as double values.
+// Usage:
+//   Use this query to quantify how much effective spend falls on anomaly-flagged days by service category and by billing currency.
+// Scope Notes:
+//   Treats both positive spikes and negative drops as anomalies (AnomalyFlags != 0); the Overall row is per BillingCurrency only.
+//   Missing days are zero-filled via make-series default=0.0, and commitment purchase rows are excluded to avoid amortization double-counting.
+// Last Tested: 2026-05-28 against msbwftktreyhub.westus.kusto.windows.net/Hub (1,366,763 cost rows in 2026-04 window). UAT result: PASS — 13 rows returned (per service category)
+// =========================================================================
+let startDate = startofmonth(ago(30d));
+let endDate = startofmonth(now());
+let sensitivity = 1.5;
+let expanded = materialize(
+    Costs()
+    | where ChargePeriodStart >= startDate and ChargePeriodStart < endDate
+    | where not(ChargeCategory == 'Purchase' and isnotempty(CommitmentDiscountCategory))
+    | summarize DailyCost = sum(todouble(EffectiveCost))
+        by bin(ChargePeriodStart, 1d), ServiceCategory, BillingCurrency
+    | make-series CostSeries = sum(DailyCost) default=0.0
+        on ChargePeriodStart from startDate to endDate step 1d
+        by ServiceCategory, BillingCurrency
+    | extend AnomalyFlags = series_decompose_anomalies(CostSeries, sensitivity)
+    | mv-expand CostSeries to typeof(double), AnomalyFlags to typeof(int)
+);
+let perCategory =
+    expanded
+    | summarize
+        AnomalyCost = todouble(sumif(CostSeries, AnomalyFlags != 0)),
+        TotalCost = todouble(sum(CostSeries))
+        by BillingCurrency, ServiceCategory
+    | extend AnomalyRatePercent = todouble(iff(TotalCost == 0.0, 0.0, AnomalyCost / TotalCost * 100.0));
+let overall =
+    expanded
+    | summarize
+        AnomalyCost = todouble(sumif(CostSeries, AnomalyFlags != 0)),
+        TotalCost = todouble(sum(CostSeries))
+        by BillingCurrency
+    | extend ServiceCategory = 'Overall'
+    | extend AnomalyRatePercent = todouble(iff(TotalCost == 0.0, 0.0, AnomalyCost / TotalCost * 100.0));
+union perCategory, overall
+| project BillingCurrency, ServiceCategory, AnomalyCost, TotalCost, AnomalyRatePercent

src/queries/catalog/anomaly-variance-total.kql

@@ -0,0 +1,65 @@
+// ============================================================================
+// Query: Total Unpredicted Variance of Spend
+// Description:
+//   Calculates the net unpredicted variance between actual effective cost and the anomaly baseline
+//   for anomaly-flagged daily buckets by service category and billing currency.
+// KPI: Total Unpredicted Variance of Spend
+// Formula: Total effective cost associated with all anomaly events detected less the predicted spend of the services related to the identified anomalies.
+// Author: FinOps toolkit
+// Parameters:
+//   startDate: datetime; start of the reporting period (default: startofmonth(ago(12 * 30d)))
+//   endDate: datetime; end of the reporting period (default: now())
+//   anomalyThreshold: real; anomaly detection sensitivity threshold (default: 1.5)
+// Output:
+//   Each row returns BillingCurrency, ServiceCategory, AnomalyEventCount, UnpredictedVarianceSigned,
+//   and UnpredictedVarianceAbs for anomaly-detected daily buckets; "(All Services)" rows provide
+//   per-currency totals across all service categories.
+// Usage:
+//   Use this query to quantify net anomalous overspend or underspend by service category and currency.
+// Scope Notes:
+//   Per-group anomaly detection runs independently per (ServiceCategory, BillingCurrency), and groups
+//   with sparse history are filtered when no anomaly baseline is produced. Each BillingCurrency is
+//   reported separately and must not be summed across currencies without FX conversion. The default
+//   12-month window supports STL seasonality decomposition, and UnpredictedVarianceAbs is defined as
+//   abs(sum(actual - baseline)) rather than sum(abs(actual - baseline)).
+// Last Tested: 2026-05-28 against msbwftktreyhub.westus.kusto.windows.net/Hub (1,366,763 cost rows in 2026-04 window). UAT result: PASS — 13 rows returned (per service category)
+// =========================================================================
+let startDate = startofmonth(ago(12 * 30d));
+let endDate = now();
+let anomalyThreshold = 1.5;
+let anomalyBuckets =
+    Costs()
+    | where ChargePeriodStart >= startDate and ChargePeriodStart < endDate
+    | where not(ChargeCategory == 'Purchase' and isnotempty(CommitmentDiscountCategory))
+    | summarize DailyCost = sum(EffectiveCost) by ServiceCategory, BillingCurrency, bin(ChargePeriodStart, 1d)
+    | make-series CostSeries = sum(DailyCost) default=0.0 on ChargePeriodStart from startDate to endDate step 1d by ServiceCategory, BillingCurrency
+    | extend (ad_flag, ad_score, ad_baseline) = series_decompose_anomalies(CostSeries, anomalyThreshold)
+    | mv-expand ChargePeriodStart to typeof(datetime), CostSeries to typeof(real), ad_flag to typeof(real), ad_score to typeof(real), ad_baseline to typeof(real)
+    | extend ad_flag = toint(ad_flag), CostSeries = toreal(CostSeries), ad_score = toreal(ad_score), ad_baseline = toreal(ad_baseline)
+    | where isnotnull(ad_baseline)
+    | where ad_flag != 0
+    | extend Variance = todouble(CostSeries) - todouble(ad_baseline);
+union
+(
+    anomalyBuckets
+    | summarize
+        AnomalyEventCount = count(),
+        UnpredictedVarianceSigned = todouble(sum(Variance)),
+        UnpredictedVarianceAbs = todouble(abs(sum(Variance)))
+        by BillingCurrency, ServiceCategory
+),
+(
+    anomalyBuckets
+    | summarize
+        AnomalyEventCount = count(),
+        UnpredictedVarianceSigned = todouble(sum(Variance)),
+        UnpredictedVarianceAbs = todouble(abs(sum(Variance)))
+        by BillingCurrency
+    | extend ServiceCategory = "(All Services)"
+)
+| project
+    BillingCurrency,
+    ServiceCategory,
+    AnomalyEventCount,
+    UnpredictedVarianceSigned = todouble(UnpredictedVarianceSigned),
+    UnpredictedVarianceAbs = todouble(UnpredictedVarianceAbs)

src/queries/catalog/commitment-discount-waste.kql

@@ -0,0 +1,88 @@
+// ============================================================================
+// Query: Percentage of Commitment Discount Waste
+// Description:
+//   Computes the percentage of commitment discount waste for each commitment by
+//   comparing unused amortized EffectiveCost to total commitment EffectiveCost.
+//   Includes a grand-total row per BillingCurrency across all commitments in the
+//   reporting window.
+// KPI: Percentage of Commitment Discount Waste
+// Formula: (Cost of Commitment Discount unused / total cost Commitment Discount) x 100
+// Author: FinOps toolkit
+// Parameters:
+//   startDate: datetime = startofmonth(ago(30d))
+//   endDate: datetime = startofmonth(now())
+// Output:
+//   BillingCurrency: string. Billing currency for the commitment or grand-total row.
+//   CommitmentDiscountId: string. Commitment identifier; empty string on the grand-total row.
+//   CommitmentDiscountName: string. Commitment name; '(All Commitments)' on the grand-total row.
+//   CommitmentDiscountType: string. Commitment type; empty string on the grand-total row.
+//   UnusedCost: double. Sum of EffectiveCost for rows where CommitmentDiscountStatus == 'Unused'.
+//   TotalCost: double. Sum of EffectiveCost across all commitment rows after filters.
+//   WastePercent: double. Percentage of TotalCost represented by UnusedCost.
+// Usage:
+//   Use this query to identify underutilized commitment discounts and quantify waste by commitment and billing currency.
+// Scope Notes:
+//   - Double-counting prevention: This query operates on amortized-style rows only
+//     (purchase rows excluded).
+//   - Unused row semantics: CommitmentDiscountStatus == 'Unused' rows represent
+//     wasted amortized commitment cost for the charge period.
+//   - CommitmentDiscountStatus values: Only 'Used' and 'Unused' are expected.
+//   - Currency mixing: Grand-total output is scoped per BillingCurrency; cross-
+//     currency aggregation is out of scope.
+//   - Period window: Default startDate/endDate cover one calendar month; adjust
+//     the let bindings for rolling windows.
+//   - KPI limitation vs canonical definition: This implementation uses
+//     EffectiveCost as the cost basis for commitment-discount waste analytics.
+// Last Tested: 2026-05-28 against msbwftktreyhub.westus.kusto.windows.net/Hub (1,366,763 cost rows in 2026-04 window). UAT result: PASS_SCHEMA_WITH_DATA_GAP — query executed and returned expected columns; the hub has 0 commitment-discount rows in the test window, so value semantics require re-UAT on a commitment-active hub.
+// =========================================================================
+let startDate = startofmonth(ago(30d));
+let endDate = startofmonth(now());
+let filteredCosts =
+    Costs()
+    | where ChargePeriodStart >= startDate and ChargePeriodStart < endDate
+    | where isnotempty(CommitmentDiscountId)
+    | where not(ChargeCategory == 'Purchase' and isnotempty(CommitmentDiscountCategory));
+let commitmentWaste =
+    filteredCosts
+    | summarize
+        UnusedCost = sum(iff(CommitmentDiscountStatus == 'Unused', EffectiveCost, real(0))),
+        TotalCost = sum(EffectiveCost)
+        by BillingCurrency, CommitmentDiscountId, CommitmentDiscountName, CommitmentDiscountType
+    | extend WastePercent = iff(TotalCost == 0.0, 0.0, todouble(UnusedCost) / todouble(TotalCost) * 100.0)
+    | project
+        BillingCurrency,
+        CommitmentDiscountId,
+        CommitmentDiscountName,
+        CommitmentDiscountType,
+        UnusedCost = todouble(UnusedCost),
+        TotalCost = todouble(TotalCost),
+        WastePercent = todouble(WastePercent);
+let grandTotals =
+    filteredCosts
+    | summarize
+        UnusedCost = sum(iff(CommitmentDiscountStatus == 'Unused', EffectiveCost, real(0))),
+        TotalCost = sum(EffectiveCost)
+        by BillingCurrency
+    | extend
+        CommitmentDiscountId = '',
+        CommitmentDiscountName = '(All Commitments)',
+        CommitmentDiscountType = ''
+    | extend WastePercent = iff(TotalCost == 0.0, 0.0, todouble(UnusedCost) / todouble(TotalCost) * 100.0)
+    | project
+        BillingCurrency,
+        CommitmentDiscountId,
+        CommitmentDiscountName,
+        CommitmentDiscountType,
+        UnusedCost = todouble(UnusedCost),
+        TotalCost = todouble(TotalCost),
+        WastePercent = todouble(WastePercent);
+union commitmentWaste, grandTotals
+| order by BillingCurrency asc, WastePercent desc, CommitmentDiscountName asc
+| project
+    BillingCurrency,
+    CommitmentDiscountId,
+    CommitmentDiscountName,
+    CommitmentDiscountType,
+    UnusedCost,
+    TotalCost,
+    WastePercent