diff --git a/src/templates/agent-skills/finops-toolkit/references/finops-hubs-deployment.md b/src/templates/agent-skills/finops-toolkit/references/finops-hubs-deployment.md index 9e11335a9..85efc8b08 100644 --- a/src/templates/agent-skills/finops-toolkit/references/finops-hubs-deployment.md +++ b/src/templates/agent-skills/finops-toolkit/references/finops-hubs-deployment.md @@ -112,7 +112,7 @@ Create exports for each scope you want to monitor: **Required Settings:** - **Type of data:** `Cost and usage details (FOCUS)` -- **Dataset version:** `1.0` or `1.0r2` +- **Dataset version:** `1.2` (latest supported) - **Frequency:** `Daily export of month-to-date costs` - **Container:** `msexports` - **Format:** `Parquet` with `Snappy` compression @@ -129,7 +129,8 @@ Create exports for each scope you want to monitor: | Resource Group | `subscriptions/{subscription-id}/resourceGroups/{rg-name}` | **Supported Datasets:** -- Cost and usage details (FOCUS) - `1.0`, `1.0r2` + +- Cost and usage details (FOCUS) - `1.0-preview(v1)`, `1.0`, `1.0r2`, `1.2-preview`, `1.2` (Cost Management export versions; a FOCUS 1.4 export is not yet available) - Price sheet - `2023-05-01` (required for missing prices) - Reservation details - `2023-03-01` - Reservation recommendations - `2023-05-01` (required for Rate optimization report) diff --git a/src/templates/agent-skills/finops-toolkit/references/finops-hubs.md b/src/templates/agent-skills/finops-toolkit/references/finops-hubs.md index 54f886102..e029211ad 100644 --- a/src/templates/agent-skills/finops-toolkit/references/finops-hubs.md +++ b/src/templates/agent-skills/finops-toolkit/references/finops-hubs.md @@ -50,7 +50,12 @@ All KQL queries are located in `references/queries/`: **Database Rules:** - Always use "Hub" database, NEVER "Ingestion" -- Function-based access: `Costs()`, `Prices()`, `Recommendations()`, `Transactions()` +- Function-based access: `Costs()`, `Prices()`, `CommitmentDiscountUsage()`, `ContractCommitments()`, `BillingPeriods()`, `InvoiceDetails()`, `Recommendations()`, `Transactions()` +- The unversioned functions (`Costs()`, etc.) return the latest supported FOCUS schema (v1_4). Use versioned functions (`Costs_v1_0()`, `Costs_v1_2()`, `Costs_v1_4()`) to pin to a specific schema. +- The hubs v1_4 schema adds FOCUS 1.3 columns — `AllocatedMethodId`, `AllocatedMethodDetails`, `AllocatedResourceId`, `AllocatedResourceName`, `AllocatedTags` (data-generator split cost allocation), `ContractApplied` (per-row contract commitment application), `ServiceProviderName` (vendor that makes the service available — Marketplace publisher or Microsoft; never null; replaces the removed `PublisherName` and `ProviderName`), and `HostProviderName` (infrastructure provider that hosts the resource; always `Microsoft` for Cost Management data) — plus FOCUS 1.4 columns: `CommitmentProgramEligibilityDetails`, `InvoiceDetailId`, and 12 per-row `ContractCommitment*` columns. It also adds three supplemental datasets: `ContractCommitments`, `BillingPeriods`, and `InvoiceDetails`. +- The `ContractCommitments()` function (FOCUS 1.4+) returns provider-confirmed contract commitment metadata — the dataset behind the `ContractApplied` JSON arrays on each cost row. Note: returns no data until Microsoft Cost Management ships a FOCUS 1.4 export (not yet available). +- The `BillingPeriods()` function (FOCUS 1.4+) returns billing period metadata (start/end/status) for aligning cost data with invoice timing. Note: returns no data until Microsoft Cost Management ships a FOCUS 1.4 export (not yet available). +- The `InvoiceDetails()` function (FOCUS 1.4+) returns invoice line-item metadata associated with `InvoiceId` and `InvoiceDetailId` on the cost rows. Note: returns no data until Microsoft Cost Management ships a FOCUS 1.4 export (not yet available). --- diff --git a/src/templates/claude-plugin/agents/ftk-database-query.md b/src/templates/claude-plugin/agents/ftk-database-query.md index 42e20002b..dbe8f29c1 100644 --- a/src/templates/claude-plugin/agents/ftk-database-query.md +++ b/src/templates/claude-plugin/agents/ftk-database-query.md @@ -10,7 +10,7 @@ You are a FinOps Toolkit database specialist with deep expertise in the FinOps h ## Database Architecture -The FinOps hubs database exposes four main analytic functions: +The FinOps hubs database exposes eight main analytic functions. The unversioned forms below return the latest supported FOCUS schema (v1_4); pin to a specific schema with the versioned variants (`Costs_v1_0()`, `Costs_v1_2()`, `Costs_v1_4()`). ### Costs() @@ -28,6 +28,9 @@ The primary table for cost and usage analytics. Aligned with the FOCUS specifica | ChargeCategory | string | Category of the charge (Usage, Purchase) | | PricingCategory | string | Category of pricing (Standard, Spot, Committed) | | CommitmentDiscountStatus | string | Status of commitment discount (Used, Unused) | +| ContractApplied | dynamic | (FOCUS 1.3+, in the hubs v1_4 schema) JSON array of contract commitments applied to this row; empty until a FOCUS 1.4 export ships | +| ServiceProviderName | string | (FOCUS 1.3+, in the hubs v1_4 schema) Vendor that makes the service available (Marketplace publisher or Microsoft); never null; replaces the removed `PublisherName` and `ProviderName` | +| HostProviderName | string | (FOCUS 1.3+, in the hubs v1_4 schema) Infrastructure provider that hosts the resource; always `Microsoft` for Cost Management data | | ResourceId | string | Unique identifier for the resource | | ResourceName | string | Name of the resource | | ResourceType | string | Type of resource | @@ -41,6 +44,22 @@ The primary table for cost and usage analytics. Aligned with the FOCUS specifica Price sheets with list, contracted, and effective pricing. Key columns include `SkuId`, `SkuPriceId`, `ListUnitPrice`, `ContractedUnitPrice`, `x_EffectiveUnitPrice`, `PricingUnit`, `x_SkuMeterCategory`, `x_SkuMeterName`, `x_SkuRegion`, `x_SkuTerm`, `x_EffectivePeriodStart`, `x_EffectivePeriodEnd`. +### CommitmentDiscountUsage() + +Reservation and savings plan utilization, joining commitment discounts to the resources that consumed them. Key columns include `ChargePeriodStart`, `ChargePeriodEnd`, `CommitmentDiscountId`, `CommitmentDiscountQuantity`, `CommitmentDiscountUnit`, `ConsumedQuantity`, `ResourceId`, `ServiceName`, `x_CommitmentDiscountCommittedCount`, `x_CommitmentDiscountNormalizedRatio`. + +### ContractCommitments() + +(FOCUS 1.4+) Provider-confirmed contract commitment metadata — the dataset behind the `ContractApplied` JSON arrays on each row in `Costs()`. Key columns include `ContractCommitmentId`, `ContractCommitmentCategory` (Spend / Usage), `ContractCommitmentCost`, `ContractCommitmentQuantity`, `ContractCommitmentPeriodStart`, `ContractCommitmentPeriodEnd`, `ContractId`, `BillingCurrency`, `InvoiceIssuerName`, `ContractCommitmentPaymentModel`, `ContractCommitmentPaymentInterval`, `ContractCommitmentLifecycleStatus`, `ContractCommitmentDurationType`. Note: returns no data until Microsoft Cost Management ships a FOCUS 1.4 export (not yet available). + +### BillingPeriods() + +(FOCUS 1.4+) Billing period metadata. Key columns: `BillingPeriodStart`, `BillingPeriodEnd`, `BillingPeriodCreated`, `BillingPeriodLastUpdated`, `BillingPeriodStatus`, `InvoiceIssuerName`. Join on billing period to align cost data with invoice timing. Note: returns no data until Microsoft Cost Management ships a FOCUS 1.4 export (not yet available). + +### InvoiceDetails() + +(FOCUS 1.4+) Invoice line-item metadata. Key columns: `InvoiceDetailId`, `InvoiceId`, `BilledCost`, `BillingAccountId`, `BillingCurrency`, `ChargeCategory`, `InvoiceIssueDate`, `InvoiceIssueStatus`, `PaymentCurrency`, `PaymentCurrencyBilledCost`, `PaymentDueDate`, `PaymentTerms`, `PurchaseOrderNumber`, `ReferenceInvoiceId`. Join to `Costs()` on `InvoiceDetailId` (FOCUS 1.4+) for invoice reconciliation. Note: returns no data until Microsoft Cost Management ships a FOCUS 1.4 export (not yet available). + ### Recommendations() Reservation and savings plan recommendations from Microsoft. Key columns include `x_EffectiveCostBefore`, `x_EffectiveCostAfter`, `x_EffectiveCostSavings`, `x_RecommendationDate`, `x_RecommendationDetails` (dynamic), `SubAccountId`. @@ -122,7 +141,7 @@ The plugin provides an `azure-mcp-server` with the Kusto namespace for executing ## Data Sources -- **FinOps hubs database (ADX/Fabric RTI)**: The primary data source. Query using the four analytic functions above via KQL. +- **FinOps hubs database (ADX/Fabric RTI)**: The primary data source. Query using the analytic functions above via KQL. - **Open data**: CSV reference data for pricing units, regions, resource types, and services is available in the FinOps toolkit repository. ## Operational Guidelines diff --git a/src/templates/claude-plugin/output-styles/ftk-output-style.md b/src/templates/claude-plugin/output-styles/ftk-output-style.md index 22ad6ec2e..de34ea5fe 100644 --- a/src/templates/claude-plugin/output-styles/ftk-output-style.md +++ b/src/templates/claude-plugin/output-styles/ftk-output-style.md @@ -133,7 +133,7 @@ Every recommendation must include: ## FinOps domain conventions - Reference FinOps Framework capabilities by their official names (e.g., "Managing commitment-based discounts", not "reservation management") -- Use FOCUS specification terminology when discussing cost data fields (e.g., BilledCost, EffectiveCost, ListCost, ContractedCost) +- Use FOCUS specification terminology when discussing cost data fields (e.g., BilledCost, EffectiveCost, ListCost, ContractedCost). Prefer current FOCUS names: `ServiceProviderName` (vendor that makes the service available; replaces the removed `PublisherName` and `ProviderName`) and `HostProviderName` (infrastructure provider that hosts the resource); `ContractApplied` plus the `ContractCommitments()`, `BillingPeriods()`, and `InvoiceDetails()` datasets for contract commitment, billing-period, and invoice tracking (these return no data until Microsoft Cost Management ships a FOCUS 1.4 export, not yet available). - Reference maturity levels as Crawl/Walk/Run when discussing FinOps practice maturity - Cite the six FinOps principles when they are relevant to a recommendation - For Azure-specific guidance, reference the official Microsoft documentation URL