From 999629e7ee39e50dc1ea145de435228d3a72f5d6 Mon Sep 17 00:00:00 2001 From: Dmitrii Shilov <6812525+bk201-@users.noreply.github.com> Date: Wed, 11 Nov 2026 17:28:23 +0100 Subject: [PATCH 01/12] fix: align native account advisory evaluations with diagnostic policy Expose typed evaluations and capacity evidence, correct sizing and fan-out decisions, respect backup merge restrictions, and collect shared offers without duplicating recoverable capacity. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- specs/account-overview.md | 169 ++++++-- src/cosmosdb/AzureResourceMetadata.test.ts | 46 +- src/cosmosdb/AzureResourceMetadata.ts | 30 +- .../accountOverview/advisoryText.test.ts | 7 +- .../services/advisories/collect.ts | 233 ++++++---- .../services/advisories/collectParity.test.ts | 255 +++++++---- .../services/advisories/core/helpers.ts | 21 +- .../services/advisories/core/thresholds.ts | 15 +- .../services/advisories/core/types.ts | 177 +++++++- .../derivedAdvisories.parity.test.ts | 44 +- .../advisories/derivedAdvisories.test.ts | 122 +++++- .../detectors/AutoscaleCandidateDetector.ts | 29 +- .../AutoscaleMaxOverProvisionedDetector.ts | 83 +++- .../AutoscaleToManualCandidateDetector.ts | 26 +- .../detectors/CrossPartitionQueryDetector.ts | 85 ++-- .../detectors/ExpensiveConsistencyDetector.ts | 117 ++++- .../detectors/HotPartitionRiskDetector.ts | 64 ++- .../detectors/IdleContainerDetector.ts | 57 ++- .../detectors/IndexingCostRiskDetector.ts | 36 +- .../MultiRegionWriteAntipatternDetector.ts | 170 +++++--- .../detectors/OverProvisioningDetector.ts | 95 ++-- .../PartitionMergeCandidateDetector.ts | 83 +++- .../detectors/ServerlessCandidateDetector.ts | 32 +- .../detectors/ServerlessThrottlingDetector.ts | 24 +- .../detectors/ShardKeyMisalignmentDetector.ts | 81 ++-- .../SharedThroughputStarvationDetector.ts | 48 ++- .../detectors/StorageGrowthRiskDetector.ts | 95 +++- .../detectors/StorageSkewRiskDetector.ts | 30 +- .../UncontrolledIngestionDetector.ts | 33 +- .../detectors/UnderProvisioningDetector.ts | 34 +- .../services/advisories/detectors/fanout.ts | 77 ++++ .../advisories/detectors/storageMath.ts | 20 +- .../services/advisories/fetchers/logs.ts | 7 +- .../advisories/fetchers/metrics.test.ts | 127 +++++- .../services/advisories/fetchers/metrics.ts | 68 ++- .../services/advisories/nativeParity.test.ts | 406 ++++++++++++++++++ .../services/advisories/offerMetrics.test.ts | 256 +++++++++++ .../services/diagnosticPolicy.test.ts | 2 - .../derivedAdvisoriesRouter.test.ts | 59 ++- .../derivedAdvisoriesRouter.ts | 44 +- .../AccountOverview/AccountOverview.test.tsx | 4 +- .../DerivedAdvisories.test.tsx | 42 +- .../AccountOverview/DerivedAdvisories.tsx | 26 +- 43 files changed, 2769 insertions(+), 710 deletions(-) create mode 100644 src/panels/accountOverview/services/advisories/detectors/fanout.ts create mode 100644 src/panels/accountOverview/services/advisories/nativeParity.test.ts create mode 100644 src/panels/accountOverview/services/advisories/offerMetrics.test.ts diff --git a/specs/account-overview.md b/specs/account-overview.md index 1d22790df..3f6144964 100644 --- a/specs/account-overview.md +++ b/specs/account-overview.md @@ -526,24 +526,45 @@ It is not normalized RU divided by the configured max. The Serverless-candidate `TotalRequestUnits` Total collisions per timestamp, divides each bucket by 3,600 seconds, then takes peak/mean over observed hourly buckets. Missing buckets do not become zero samples in either calculation. -| Evidence | Window / grain | Live collector targets | -| ----------------------------------- | ---------------------------------------- | --------------------------------------------------------------------- | -| Manual normalized RU | 30 days / 1 hour | Dedicated manual containers | -| Idle consumed RU, Total | 30 days / 5 minutes | Dedicated manual/autoscale containers | -| Partition p99 + request-rate totals | 7 days / 1 hour | Dedicated containers | -| Partition storage for growth | 30 days / 1 hour | Dedicated containers | -| Partition storage for skew | 7 days / 1 hour | Dedicated containers | -| Index/data storage | Inventory's 7-day component observations | Inventory rows, only if advisory inventory-metric result is available | -| Partition count and DataUsage peaks | 6 hours / 5 minutes | Dedicated containers, explicit database/container queries | -| AutoscaledRU | 30 days / 1 hour | Dedicated autoscale containers | -| Consumed-RU shape | 30 days / 1 hour | Non-Serverless account, no database filter | -| Serverless request-rate totals | 7 days / 1 hour | Serverless containers | -| Log query fan-out evidence | Last 24 hours, raw event aggregation | Dedicated and Serverless containers | -| Log ingestion evidence | Last 24 hours, raw event aggregation | Dedicated containers | -| Log shared-pool evidence | Last 24 hours, raw event aggregation | Shared-throughput database offers | - -Idle/merge queries MUST target known containers, not discover them through wildcard metric series or a larger `top`. -Missing idle peak or missing either merge count/storage excludes that input and records coverage failure. +| Evidence | Window / grain | Live collector targets | +| ----------------------------------- | ---------------------------------------------- | --------------------------------------------------------- | +| Manual normalized RU | 30 days / 1 hour | Dedicated manual and shared manual database offers | +| Idle consumed RU, Total | 30 days / 5 minutes | Dedicated and shared database offers, manual/autoscale | +| Partition p99 + request-rate totals | 7 days / 1 hour | Dedicated and shared database offers | +| Partition storage for growth | 30 days / 1 hour | Dedicated containers | +| Partition storage for skew | 7 days / 1 hour | Dedicated containers | +| Index/data storage | Latest populated samples, 6 hours / 5 minutes | All inventory containers, including shared and Serverless | +| Partition count and DataUsage peaks | 6 hours / 5 minutes | Dedicated containers, explicit database/container queries | +| AutoscaledRU | 30 days / 1 hour | Dedicated and shared database autoscale offers | +| Consumed-RU shape | 30 days / 1 hour | Non-Serverless account, no database filter | +| Serverless request-rate totals | 7 days / 1 hour | Serverless containers | +| Log query fan-out evidence | Last 24 hours, raw event aggregation | Dedicated and Serverless containers | +| Log ingestion evidence | 24 hours, five-minute aggregates or raw events | Dedicated containers | +| Log shared-pool evidence | Same selected request-log source/window | Shared-throughput database offers | + +Per-container idle/merge queries MUST target known containers, not discover them through wildcard metric series or a larger `top`. +Shared-offer throughput utilization/saturation queries select the database offer's empty `CollectionName` dimension, +not the database-wide aggregate that also includes dedicated offers. Shared-offer idle consumption and throttling +query authoritative shared member containers separately, excluding dedicated siblings, and combine aligned buckets +before taking peaks or computing request-rate proportions. Missing membership is not permission to query the whole +database; a failed member read records incomplete coverage rather than contributing zero. +Shared-offer findings use the database scope, never a per-member copy of the offer's recoverable capacity. +DX-003 filters traffic to authoritative shared membership before counting active members or computing proportions. +These deliberately narrower filters are not a literal port of CODA's database-wide metric scope. +The shared-offer `CollectionName eq ''` dimension and dedicated-traffic exclusion still require live verification +on an existing mixed database with populated metric series; controlled SDK fixtures do not establish that fact. +The November 11 read-only check found no shared database offers in the operator's two accessible test accounts, +so no qualifying mixed target was available. No database, offer, workload or billable verification fixture was created. +Duplicate/invalid offer inventory records incomplete coverage and withholds the account materiality denominator. +DX-004 treats successful consumption reads without usable samples as zero/idle. Failed idle reads still exclude +that input and record coverage failure; this exception does not apply to other metric readers. +Unlike CODA's corroborating idle evidence, this path intentionally does not additionally request +`NormalizedRUConsumption`: that observation is not part of the idle predicate, so collecting it would add cost +and a failure dependency without changing the spike-aware consumed-RU decision. +Missing either merge count/storage excludes that input and records coverage failure. Unlike the pinned CODA +acquisition path, absent storage samples are not replaced with zero: unknown storage cannot establish merge capacity. +A successfully observed zero is valid evidence; an empty history records `noData`, while read failures retain +their classified failure reason. Existing production-reader/collector regressions cover these distinctions. Failed checks preserve findings from successful checks and configuration-only inputs. The result exposes metric and log coverage separately. An empty finding list does not prove full coverage. Some empty successful sources abstain via sample gates without marking a failure; coverage flags are not a @@ -573,7 +594,7 @@ internal Derived Advisory policy maintained against CODA. The router uses its de and configuration-only fallback, without reading any VS Code settings. The collector does not accept user Health or partition-threshold objects. The other 28 former advisory settings are unregistered and ignored even when explicitly present in user/workspace JSON. No user files are rewritten, and no CODA import/synchronization is introduced here. -All numeric internal policies and no-override behavior are preserved. The tables below describe internal policy, +No-override behavior is preserved. The tables below describe the adopted internal policy, not user-configurable defaults; changing Health/view settings must not change Derived findings. ### 7.2 Rule predicates and severity @@ -585,27 +606,27 @@ All predicates in one row are AND unless the row explicitly says OR. AO-D identifiers preserve the previous dashboard-document taxonomy; AO-D1 is health and AO-D8 is Azure passthrough, not entries in the derived-detector registry. -| ID / rule | Predicate on collected input, default thresholds | Severity | -| --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | -| AO-D2 `HotPartitionRisk` / DX-006 | Age not known <1 day; >=2 partitions; max p99 >=90%; min p99 <70% | High if rate >=1%; otherwise Medium | -| AO-D4 `SustainedThrottlingInRegion` / DX-005 | Age not known <1 day; >=1,000 requests; rate >=1%; max p99 >=90%; min p99 >=70% | High rate >=20%; Medium >=5%; otherwise Low | -| AO-D5 `OverProvisioning` / DX-001 | Dedicated manual; age not known <7 days; >=24 samples; p99 <30%; peak <90% | M(recoverable RU/s) | -| AO-D6 `AutoscaleCandidate` / DX-012 | Dedicated manual; same age/sample gates as AO-D5; avg >0; peak >=40%; avg <=30%; peak/avg >=5 | Medium | -| AO-D7 `IndexingCostRisk` | Data >0; index >=0; no user exclusions; index/data >0.3 | Low | -| AO-D9 `StorageGrowthRisk` / DX-017 | At least one material partition already >=50 GiB OR projected to 50 GiB within <=180 days; detailed rules below | High <=30 days, Medium <=90, otherwise Low; already at limit is High | -| AO-D10 `ExpensiveConsistency` / DX-016 | >=2 regions; normalized consistency Strong or Bounded Staleness | Strong: Medium; Bounded Staleness: Low | -| AO-D11 `MultiRegionWriteAntipattern` / DX-008 | Multi-write enabled, then first match: Cassandra/Graph/Table API; else <2 write regions; else positively classified non-production | High; Low; Medium respectively; otherwise absent | -| AO-D12 `IdleContainer` / DX-004 | Dedicated manual/autoscale; positive offer; age not known <7 days; observed maximum consumed RU per 5-minute bucket <=50 | M(full manual RU/s or 10% autoscale max) | -| AO-D13 `PartitionMergeCandidate` / DX-009 | Observed rounded actual partition count >=2 and >needed; needed defined below | Medium if actual >=2*needed; otherwise Low | -| AO-D14 `AutoscaleMaxOverProvisioned` / DX-011 | Autoscale configured max >0; age not known <7 days; >=24 samples; peak AutoscaledRU percentage <30% and <90% | M(recoverable floor RU/s) | -| AO-D15 `AutoscaleToManualCandidate` / DX-013 | Autoscale; same age/sample gates; avg >0 and >=66% of configured max; peak/avg <=1.3 | Medium | -| AO-D16 `ServerlessCandidate` / DX-014 | Not Serverless; >=24 hourly samples; peak RU/s in **[10, 5000]**; avg/peak <0.1 | Low | -| AO-D17 `CrossPartitionQuery` / DX-002 | >=50 observed executions; inferred partition count >1; >=10% executions belong to shapes with avg fan-out >=1.5 | High share >=30%; otherwise Medium | -| AO-D18 `ShardKeyMisalignment` / DX-007 | >=50 executions; inferred partitions >=2; fan-out execution share rounded to one decimal >=60% | High rounded share >=80%; otherwise Medium | -| AO-D19 `UncontrolledIngestion` / DX-010 | >=1,000 requests; write RU/total RU >=80%; rate >=10% | High rate >=20%; otherwise Medium | -| AO-D20 `SharedThroughputStarvation` / DX-003 | >=2 collections each with >=100 requests; among those collections pool rate >=5%, total RU >0, largest RU share >=60%, and a different collection has rate >=5% and RU share <=20% | High | -| AO-D21 `ServerlessThrottling` / DX-018 | Serverless container; >=1,000 requests; rate >=1%; no normalized-RU prerequisite | High rate >=20%; Medium >=5%; otherwise Low | -| AO-D3 `StorageSkewRisk` / DX-015 | Age not known <1 day; >=2 valid non-negative partition peaks; busiest >=1 GiB; coolest/busiest <0.7 | High busiest >=40 GiB; Medium >=25 GiB; otherwise Low | +| ID / rule | Predicate on collected input, default thresholds | Severity | +| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | +| AO-D2 `HotPartitionRisk` / DX-006 | Age not known <1 day; >=2 partitions; max p99 >=90%; min p99 <70% | High if rate >=1%; otherwise Medium | +| AO-D4 `SustainedThrottlingInRegion` / DX-005 | Age not known <1 day; >=1,000 requests; rate >=1%; max p99 >=90%; min p99 >=70% | High rate >=20%; Medium >=5%; otherwise Low | +| AO-D5 `OverProvisioning` / DX-001 | Manual offer; age not known <7 days; >=24 samples; p99 <30%; peak <90% | M(recoverable RU/s) | +| AO-D6 `AutoscaleCandidate` / DX-012 | Manual offer; same age/sample gates as AO-D5; avg >0; peak >=40%; avg <=30%; peak/avg >=5 | Medium | +| AO-D7 `IndexingCostRisk` / DX-024 | Finite data >0; finite index >=0; indexing mode not none; index/data >0.3; exclusions are evidence | Medium ratio >1; otherwise Low | +| AO-D9 `StorageGrowthRisk` / DX-017 | At least one material partition already >=50 GiB OR projected to 50 GiB within <=180 days; detailed rules below | High <=30 days, Medium <=90, otherwise Low; already at limit is High | +| AO-D10 `ExpensiveConsistency` / DX-016 | Known integer region count; Strong with >=1 region OR Bounded Staleness with >=2 regions | Strong: Medium; Bounded Staleness: Low | +| AO-D11 `MultiRegionWriteAntipattern` / DX-008 | Multi-write enabled, then first match: Cassandra/Graph/Table API; else <2 write regions; else positively classified non-production | High; Low; Medium respectively; otherwise absent | +| AO-D12 `IdleContainer` / DX-004 | Manual/autoscale offer; finite positive capacity; age not known <7 days; observed maximum consumed RU per 5-minute bucket <=50 | M(full manual RU/s or 10% autoscale max) | +| AO-D13 `PartitionMergeCandidate` / DX-009 | Integer actual partition count >=2 and >needed; finite known non-negative throughput/storage; needed defined below | Medium if actual >=2*needed; otherwise Low | +| AO-D14 `AutoscaleMaxOverProvisioned` / DX-011 | Autoscale configured max >0; age not known <7 days; >=24 samples; peak AutoscaledRU percentage <30% and <90% | M(recoverable floor RU/s) | +| AO-D15 `AutoscaleToManualCandidate` / DX-013 | Autoscale; same age/sample gates; avg >0 and >=66% of configured max; peak/avg <=1.3 | Medium | +| AO-D16 `ServerlessCandidate` / DX-014 | Not Serverless; >=24 hourly samples; peak RU/s in **[10, 5000]**; avg/peak <0.1 | Low | +| AO-D17 `CrossPartitionQuery` / DX-002 | >=50 observed executions; inferred partition count >1; >=10% executions belong to shapes with avg fan-out >=1.5; >=0.1 fan-out queries/s over actual duration | Partition-count/rate matrix below | +| AO-D18 `ShardKeyMisalignment` / DX-007 | >=50 executions; inferred partitions >=2; unrounded fan-out share >=60%; >=0.1 fan-out queries/s over actual duration | Partition-count/rate matrix below | +| AO-D19 `UncontrolledIngestion` / DX-010 | >=1,000 requests; write RU/total RU >=80%; rate >=10% | High rate >=20%; otherwise Medium | +| AO-D20 `SharedThroughputStarvation` / DX-003 | Known shared members; >=2 active members each with >=100 requests; their pool rate >=5%, total RU >0, largest RU share >=60%, and a different member has rate >=5% and RU share <=20% | High | +| AO-D21 `ServerlessThrottling` / DX-018 | Serverless container; >=1,000 requests; rate >=1%; no normalized-RU prerequisite | High rate >=20%; Medium >=5%; otherwise Low | +| AO-D3 `StorageSkewRisk` / DX-015 | Age not known <1 day; >=2 valid non-negative partition peaks; busiest >=1 GiB; coolest/busiest <0.7 | High busiest >=40 GiB; Medium >=25 GiB; otherwise Low | **Capacity materiality M:** with positive known account offer total, High if recoverable/total >=5%, Medium if >=1%, otherwise Low. Without that total, High if recoverable >=5,000 RU/s, @@ -613,15 +634,27 @@ Medium if >=1,000 RU/s, otherwise Low. These are capacity heuristics, not money **Right-sizing formulas:** let P be current offer RU/s, C99=P*p99/100 and Cpeak=P*peak/100. Manual recommended RU is `min(P, max(400, ceil(1.3*C99), ceil(Cpeak)))`; recoverable is `max(0, P-recommended)`. -Autoscale max recommendation is `min(P, max(400, ceil(1.3*Cpeak), ceil(Cpeak)))`; -recoverable floor is `max(0, max(400, 0.1*P) - max(400, 0.1*recommended))`. +Autoscale max recommendation is `min(P, max(1000, ceil(1.3*Cpeak), ceil(Cpeak)))`; +recoverable floor is `max(0, 0.1*P - 0.1*recommended)`, without a manual 400-RU/s floor clamp. Manual-to-autoscale suggested max is `max(1000, ceil(1.3*Cpeak/1000)*1000)`. These outputs are guidance, not an ARM-validated legal target or a change operation. The current over-provisioning rules can emit a finding with zero recoverable capacity, including 400 -> 400 RU/s. +Zero-recovery guidance explains that no modeled reduction is available rather than prescribing an unchanged target. + +**Fan-out severity:** 2-3 physical partitions are Low; 4-6 are Medium at >=1 fan-out queries/s, otherwise Low; + +> =7 are High at >=1 fan-out queries/s, otherwise Medium. All finding/rate gates use unrounded observations. +> Insufficient or invalid observation duration cannot establish a rate. A composite index alone does not remove fan-out. **Merge:** `needed = max(ceil(offer RU/10000), ceil(DataUsage peak/(50*1024^3)), 1)`. The storage input is DataUsage only, not the UI's data-plus-index sum. -The live collector requires both count and storage observations even though the pure evaluator has optional-field fallbacks. +Both the collector and evaluator require known finite count/throughput/storage; unknown storage is never zero. +Structural findings remain visible independently of merge eligibility. Continuous backup at any tier or an enabled +all-versions-and-deletes change feed blocks merge. Account acquisition preserves the optional boolean from the raw +ARM account response, including when the SDK omits this field, without issuing an additional request. The router and +collector forward this state even if backup policy is missing; missing/nonboolean flags remain unknown, not disabled. +Unknown/unsettled migration metadata withholds instructions. Settled Periodic requires the Portal eligibility checker +and current platform/SDK/connector restrictions. Do not recommend disabling PITR or inferring Fabric Mirroring use. **Storage growth:** use the newest valid sample per partition for current bytes, not its peak. Ignore partitions smaller than 1 GiB. Current >=50 GiB wins immediately, even with flat/shrinking history. @@ -631,10 +664,58 @@ Require at least two finite samples at distinct times and slope >=0.1 GiB/day. Projection is `(50*1024^3 - currentBytes)/slope`. Choose the soonest qualifying partition per container; already-at-limit partitions take precedence, with the largest current size breaking that case's tie. The horizon comparison is inclusive. This is not a container-wide storage limit or a growth-based health input. +Horizon and 30/90-day severity comparisons use the fitted slope's arithmetic roundoff, just like the inclusive +minimum-slope gate. Presentation rounding must not decide eligibility or severity. A material partition without +two distinct finite observations produces `insufficient_data`, not `stable`, when no other partition establishes +a finding; already-at-limit and qualifying-growth findings remain available despite another partition's missing history. **Index exclusions:** ignore only exact root strings `/_etag/?` and `/"_etag"/?` when counting exclusions. Nested `_etag`, differently cased, other paths and unknown path entries are not implicitly system exclusions. This is an index-storage proxy, not a measurement of write RU spent maintaining indexes. +Exclusions do not suppress DX-024; large composite/spatial/vector indexes may be justified. +The collector skips DX-024 storage-metric requests for an explicitly disabled indexing mode (`none`, case-insensitive), +without reporting missing metric coverage for that container. Missing or unrecognized modes do not establish disabled +indexing; metric acquisition and missing/failed-evidence reporting remain unchanged for those containers. + +**Conformance:** `externalSpecifications.coda` in `package.json` pins the private source revision. +`npm run test:coda` fetches/verifies an isolated Git-ignored checkout and executes its unmodified `.feature` files +through Cucumber's Gherkin compiler and TypeScript bindings for all 24 rules. Bindings prepare synthetic inputs +and call production evaluations plus the native registry. Metric/log-reader fixtures exercise partition summation, +account RU folding, storage history, latest populated index/data samples, recent throttling and acquisition failures. +Production results expose utilization bands, sizing observations, root causes and non-finding outcomes. +Diagnostic evaluation types constrain root causes and observation shapes per rule; configuration coverage and +configuration-only detectors share the same pure classifications while keeping applicability separate from missing inputs. +Bindings do not reconstruct detector decisions from the absence of a recommendation. Acquisition-error vocabulary +is normalized from actual native structured failures, not fabricated as a clean negative result. +Every selected scenario must evaluate and assert; unknown bindings fail. The private local report inventories all +scenarios, including those outside an explicitly selected subset. Original wording-sensitive guidance assertions +are retained; cross-rule `supersededBy` is additional pipeline metadata, not part of an isolated detector verdict. +Setup fidelity is checked independently of verdict assertions: the DX-008 Serverless exclusion receives otherwise +quantifiable positive manual capacity, and DX-009 migration starts from a known Periodic policy. Missing retention +tiers remain absent rather than literal strings; storage histories, query windows and configured-region normalization +retain the original bindings' inputs. +All 379 scenarios at the manifest pin pass, with zero unbound, skipped or unexecuted scenarios. +DX-004 classifies successful empty consumption reads as idle, without converting acquisition failures to zero. +DX-017 compares fitted growth against the inclusive 0.1 GiB/day floor using a roundoff estimate scaled by sample +magnitudes and regression conditioning, not an arbitrary policy epsilon or rounded fixtures. Growth measurably below +the floor remains stable. Synthetic conformance does not establish live collector acceptance. + +DX-008 regional capacity observations require a complete, positive all-manual offer inventory and known provisioned +account/region count. They report configured per-region RU/s and the global regional footprint, not measured usage, +billable savings or permission to remove regions. Extra-region capacity is only identified for the non-production +finding; legitimate HA has no removable extra-region capacity. Autoscale, serverless and incomplete inventories are +not quantified. MongoDB metadata support in this pure configuration evaluation does not introduce a MongoDB provider. + +`npm run coda:check` independently compares the tracked branch HEAD and pin, reports exact ahead/behind counts including +rewound/divergent/unrelated histories, and exits nonzero for mismatch or unverifiable source access. It never repins. +The package-feed workflow runs it in a separate advisory job without build dependencies or `continue-on-error`. +Private read credentials are withheld from every PR; owner-managed push/manual credentials and optional branch-rule +configuration are required separately. Freshness equality is not a conformance result. + +**Adoption limits:** native collection and computation remain separate; there is no CODA MCP/Python dependency. +Aggregate request-log support, complete per-rule/per-scope evaluation outcomes, other upstream enrichment and approved +public contract distribution remain separate work. Private upstream files are not vendored into tracked source. +These checks do not establish full behavioral parity, Azure collection equivalence or live acceptance. **Environment classification:** AO-D11 uses `classifyEnvironment` in [environmentClassifier.ts](../src/panels/accountOverview/services/environmentClassifier.ts), including its ordered @@ -767,6 +848,8 @@ If inventory refresh removes the focused element, focus fallback applies only on Dismissing a focused advisory moves to the next dismissal control, or previous at the end; removing the group's last finding closes its dialog and focuses the surviving recommendations region. Ordinary dialog closure retains Fluent's trigger-focus restoration. +Advisory group summaries and accessible names describe affected resources, not containers: a scope may identify +a shared database offer or a dedicated container. Findings without a resource scope remain account-wide. The current chart does not establish complete screen-reader/exact-data-table acceptance; see section 10. ## 9. Verification contract diff --git a/src/cosmosdb/AzureResourceMetadata.test.ts b/src/cosmosdb/AzureResourceMetadata.test.ts index a801e2faa..a623b522d 100644 --- a/src/cosmosdb/AzureResourceMetadata.test.ts +++ b/src/cosmosdb/AzureResourceMetadata.test.ts @@ -4,14 +4,19 @@ *--------------------------------------------------------------------------------------------*/ import { type DatabaseAccountGetResults } from '@azure/arm-cosmosdb'; +import { createHttpHeaders } from '@azure/core-rest-pipeline'; +import { type IActionContext } from '@microsoft/vscode-azext-utils'; import { type AzureSubscription } from '@microsoft/vscode-azureresources-api'; import { vi } from 'vitest'; +import { createCosmosDBManagementClient } from '../utils/azureClients'; +import { armTestSubscription, createArmTestClient, createArmTestContext } from './armTestUtils'; import { AzureResourceMetadata } from './AzureResourceMetadata'; import { SERVERLESS_CAPABILITY_NAME } from './cosmosdb-shared-constants'; -// These are only needed so the module under test can be imported; the getters under test never call them. vi.mock('@microsoft/vscode-azext-utils', () => ({ - callWithTelemetryAndErrorHandling: vi.fn(), + callWithTelemetryAndErrorHandling: vi.fn( + async (_event: string, action: (context: IActionContext) => Promise) => action(createArmTestContext()), + ), })); vi.mock('../utils/azureClients', () => ({ createCosmosDBManagementClient: vi.fn(), @@ -35,6 +40,43 @@ class TestableAzureResourceMetadata extends AzureResourceMetadata { } describe('AzureResourceMetadata', () => { + describe('account snapshot', () => { + it.each([ + [true, true], + [false, false], + [undefined, undefined], + [null, undefined], + ['false', undefined], + ])('preserves the unmodeled change-feed flag %j as %j', async (value, expected) => { + const client = createArmTestClient(); + vi.mocked(createCosmosDBManagementClient).mockResolvedValue(client); + const send = vi.spyOn(client.pipeline, 'sendRequest').mockImplementation(async (_http, request) => ({ + request, + status: 200, + headers: createHttpHeaders(), + bodyAsText: JSON.stringify({ + properties: { + documentEndpoint: 'https://account.documents.azure.com', + enableAllVersionsAndDeletesChangeFeed: value, + }, + }), + })); + const result = await AzureResourceMetadata.create({ + id: 'account-id', + name: 'account', + resourceGroup: 'rg', + subscription: armTestSubscription, + azureResourceType: { type: 'microsoft.documentdb/databaseaccounts' }, + raw: {}, + }); + expect(result?.databaseAccount).toMatchObject({ + enableAllVersionsAndDeletesChangeFeed: expected, + documentEndpoint: 'https://account.documents.azure.com', + }); + expect(send).toHaveBeenCalledOnce(); + }); + }); + describe('documentEndpoint', () => { it('returns the document endpoint when present', () => { const metadata = new TestableAzureResourceMetadata({ diff --git a/src/cosmosdb/AzureResourceMetadata.ts b/src/cosmosdb/AzureResourceMetadata.ts index 73cba7def..2d445cd16 100644 --- a/src/cosmosdb/AzureResourceMetadata.ts +++ b/src/cosmosdb/AzureResourceMetadata.ts @@ -37,6 +37,10 @@ type DeepReadonly = T extends (...args: never[]) => unknown ? { readonly [K in keyof T]: DeepReadonly } : T; +type DatabaseAccountSnapshot = DatabaseAccountGetResults & { + enableAllVersionsAndDeletesChangeFeed?: boolean; +}; + export class AzureResourceMetadata { /** * This is only one available way to get AzureResourceMetadata, so we require the following props @@ -70,12 +74,32 @@ export class AzureResourceMetadata { throw new Error(l10n.t('Failed to create CosmosDB management client.')); } - const databaseAccount = await client.databaseAccounts.get(resourceGroup, accountName); + let enableAllVersionsAndDeletesChangeFeed: boolean | undefined; + const databaseAccount = await client.databaseAccounts.get(resourceGroup, accountName, { + onResponse: (response) => { + // The SDK drops this unmodeled property, so preserve only its boolean value from the raw response. + const body: unknown = response.parsedBody; + if (typeof body === 'object' && body !== null && 'properties' in body) { + const properties = body.properties; + if ( + typeof properties === 'object' && + properties !== null && + 'enableAllVersionsAndDeletesChangeFeed' in properties && + typeof properties.enableAllVersionsAndDeletesChangeFeed === 'boolean' + ) { + enableAllVersionsAndDeletesChangeFeed = properties.enableAllVersionsAndDeletesChangeFeed; + } + } + }, + }); // Database account has to have document endpoint nonNullProp(databaseAccount, 'documentEndpoint', `of the database account ${accountId}`); - return new AzureResourceMetadata(subscription, accountId, accountName, resourceGroup, databaseAccount); + return new AzureResourceMetadata(subscription, accountId, accountName, resourceGroup, { + ...databaseAccount, + enableAllVersionsAndDeletesChangeFeed, + }); }); } @@ -84,7 +108,7 @@ export class AzureResourceMetadata { public readonly accountId: string, public readonly accountName: string, public readonly resourceGroup: string, - public readonly databaseAccount: DeepReadonly, + public readonly databaseAccount: DeepReadonly, ) { // The constructor is intentionally simple; all logic is in the static create method } diff --git a/src/panels/accountOverview/advisoryText.test.ts b/src/panels/accountOverview/advisoryText.test.ts index 67bfc28c6..004bcd4f5 100644 --- a/src/panels/accountOverview/advisoryText.test.ts +++ b/src/panels/accountOverview/advisoryText.test.ts @@ -46,7 +46,7 @@ describe('advisory text', () => { expect(parts.filter((part) => part.highlighted)).toEqual([{ text: '400 RU/s', highlighted: true }]); }); - it('marks detector evidence without changing the deferred minimum-capacity verdict', () => { + it('marks minimum-capacity evidence while withholding no-op lowering guidance', () => { const container = 'order-`2026`'; const finding = new OverProvisioningDetector().evaluate( 5, @@ -70,8 +70,9 @@ describe('advisory text', () => { '0 RU/s', '~400 RU/s', ]); - expect(rationale.map((part) => part.text).join('')).toContain(`Container "${container}" stayed at 5%`); - expect(finding?.suggestedAction).toContain('from `400 RU/s` toward `~400 RU/s`'); + expect(rationale.map((part) => part.text).join('')).toContain(`Offer "${container}" stayed at 5%`); + expect(finding?.suggestedAction).toContain('No throughput reduction is available'); + expect(finding?.actionEligibility).toBe('blocked'); expect(finding?.thresholdReference).toBe('Threshold: p99 RU < `30%` and peak < `90%`'); }); }); diff --git a/src/panels/accountOverview/services/advisories/collect.ts b/src/panels/accountOverview/services/advisories/collect.ts index 241efb3f1..fbefec8ac 100644 --- a/src/panels/accountOverview/services/advisories/collect.ts +++ b/src/panels/accountOverview/services/advisories/collect.ts @@ -11,7 +11,6 @@ import { type InventoryThroughputOffer, type ThroughputMode, } from '../inventory'; -import { DEFAULT_HEALTH_THRESHOLDS, getInventoryMetrics } from '../inventoryMetrics'; import { getPartitionHealth, getPartitionStorageSeries, @@ -21,6 +20,7 @@ import { import { getContainerCreatedAt, getKnownResourceAgeDays, getSystemCreatedAt } from '../resourceAge'; import { getRuTrends, getThrottleRate } from '../ruTrends'; import { classifyUnavailable, containerKey } from '../shared'; +import { offerScope } from './core/helpers'; import { DIAGNOSTIC_POLICY } from './core/thresholds'; import { type AccountConfigInput, @@ -53,6 +53,7 @@ import { getAccountConsumedRuShape, getAutoscaleUtilization, getContainerIdlePeak, + getContainerIndexingUsage, getContainerMergeStoragePeak, getContainerPartitionCount, } from './fetchers/metrics'; @@ -167,20 +168,12 @@ function isDedicatedContainerOffer(row: InventoryContainerRow): boolean { return row.offerLevel === 'container' && row.throughputRU !== undefined && row.throughputRU > 0; } -function isDedicatedManualOffer(row: InventoryContainerRow): boolean { - return isDedicatedContainerOffer(row) && row.offerThroughputMode === 'manual'; -} - -function isDedicatedAutoscaleOffer(row: InventoryContainerRow): boolean { - return isDedicatedContainerOffer(row) && row.offerThroughputMode === 'autoscale'; -} - function isServerlessContainer(row: InventoryContainerRow): boolean { return row.throughputMode === 'serverless'; } -function scopeOf(row: Pick): string { - return containerKey(row.databaseId, row.containerId); +function scopeOf(row: { databaseId: string; containerId?: string }): string { + return offerScope(row); } function rowAgeDays(row: InventoryContainerRow, accountCreatedAt: string | undefined, now: number): number | undefined { @@ -227,6 +220,7 @@ export async function collectDerivedAdvisories( } = params; const now = Date.now(); + const effectiveAccountConfig = accountConfig && { ...accountConfig, isServerless }; const metricFailures: MetricSourceStatus['failures'] = []; const accountCreatedAtPromise = capture(getAccountCreatedAt(cosmosClient, resourceGroup, accountName)); @@ -245,7 +239,7 @@ export async function collectDerivedAdvisories( const accountCreation = await accountCreatedAtPromise; const accountCreatedAt = accountCreation.value; const dedicatedTargets = rows.filter(isDedicatedContainerOffer); - if (accountCreation.reason && dedicatedTargets.length > 0) { + if (accountCreation.reason && offers.length > 0) { for (const rule of AGE_GATED_RULES) { addMetricFailure(metricFailures, rule, accountCreation.reason); } @@ -265,16 +259,47 @@ export async function collectDerivedAdvisories( } }, ); - const manualTargets = dedicatedTargets.filter(isDedicatedManualOffer); - const autoscaleTargets = dedicatedTargets.filter(isDedicatedAutoscaleOffer); + const uniqueOffers = new Map(); + const invalidOfferScopes = new Set(); + for (const offer of offers) { + const scope = scopeOf(offer); + if ( + !Number.isFinite(offer.throughputRU) || + offer.throughputRU <= 0 || + uniqueOffers.has(scope) || + invalidOfferScopes.has(scope) + ) { + uniqueOffers.delete(scope); + invalidOfferScopes.add(scope); + for (const rule of AGE_GATED_RULES) { + addMetricFailure(metricFailures, rule, 'noData', scope); + } + continue; + } + uniqueOffers.set(scope, offer); + } + const offerTargets = [...uniqueOffers.values()]; + const manualTargets = offerTargets.filter((offer) => offer.offerThroughputMode === 'manual'); + const autoscaleTargets = offerTargets.filter((offer) => offer.offerThroughputMode === 'autoscale'); const serverlessTargets = rows.filter(isServerlessContainer); const logTargets = rows.filter((row) => isDedicatedContainerOffer(row) || isServerlessContainer(row)); const rowsByScope = new Map(rows.map((row) => [scopeOf(row), row])); - const scopeProvisionedRuTotal = - inventory.value?.throughputInventoryComplete === true - ? offers.reduce((sum, offer) => (sum ?? 0) + offer.throughputRU, undefined) + const sharedContainerIds = (offer: InventoryThroughputOffer): string[] | undefined => + offer.offerLevel === 'database' + ? rows + .filter((row) => row.databaseId === offer.databaseId && row.offerLevel === 'database') + .map((row) => row.containerId) : undefined; - + const offerAgeDays = (offer: InventoryThroughputOffer): number | undefined => + getKnownResourceAgeDays( + rowsByScope.get(scopeOf(offer))?.resourceCreatedAt ?? offer.resourceCreatedAt, + accountCreatedAt, + now, + ); + const scopeProvisionedRuTotal = + inventory.value?.throughputInventoryComplete !== true || invalidOfferScopes.size > 0 + ? undefined + : offerTargets.reduce((sum, offer) => sum + offer.throughputRU, 0); const manualObservation = DIAGNOSTIC_POLICY.overProvisioning.observation; const saturationObservation = DIAGNOSTIC_POLICY.partitionSaturation.observation; const storageObservation = DIAGNOSTIC_POLICY.storageGrowth.observation; @@ -290,6 +315,7 @@ export async function collectDerivedAdvisories( row.databaseId, row.containerId, manualObservation, + sharedContainerIds(row), ); return { row, result }; }) @@ -313,15 +339,24 @@ export async function collectDerivedAdvisories( ruPercents, peakPercent: result.peakPercent, provisionedRu: row.throughputRU, - resourceAgeDays: rowAgeDays(row, accountCreatedAt, now), + resourceAgeDays: offerAgeDays(row), }, ]; }); const idleContainers: IdleContainerInput[] = ( - await mapInBatches(dedicatedTargets, async (row) => ({ + await mapInBatches(offerTargets, async (row) => ({ row, - result: await capture(getContainerIdlePeak(monitorClient, accountId, row.databaseId, row.containerId, now)), + result: await capture( + getContainerIdlePeak( + monitorClient, + accountId, + row.databaseId, + row.containerId, + now, + sharedContainerIds(row), + ), + ), })) ).flatMap(({ row, result }) => { if (result.value === undefined) { @@ -335,42 +370,46 @@ export async function collectDerivedAdvisories( peakRuPerBucket: result.value, throughputMode: row.throughputMode, provisionedRu: row.throughputRU, - resourceAgeDays: rowAgeDays(row, accountCreatedAt, now), + resourceAgeDays: offerAgeDays(row), }, ]; }); - const inventoryMetrics = - rows.length === 0 - ? undefined - : await getInventoryMetrics( - monitorClient, - accountId, - manualObservation.timeRange, - DEFAULT_HEALTH_THRESHOLDS, - manualObservation, - isServerless, - ); - if (inventoryMetrics && !inventoryMetrics.available) { - addMetricFailure(metricFailures, 'IndexingCostRisk', inventoryMetrics.reason ?? 'noData'); - } - const indexing: IndexingUsageInput[] = - inventoryMetrics?.available === true - ? rows.map((row) => { - const metrics = inventoryMetrics.metrics[scopeOf(row)]; - return { - databaseId: row.databaseId, - containerId: row.containerId, - indexUsageBytes: - metrics?.storage.index.status === 'available' ? metrics.storage.index.bytes : undefined, - dataUsageBytes: - metrics?.storage.data.status === 'available' ? metrics.storage.data.bytes : undefined, - userExcludedPathCount: row.userExcludedPathCount, - }; - }) - : []; + const indexing: IndexingUsageInput[] = ( + await mapInBatches( + rows.filter((row) => row.indexingMode.toLowerCase() !== 'none'), + async (row) => ({ + row, + result: await capture( + getContainerIndexingUsage(monitorClient, accountId, row.databaseId, row.containerId, now), + ), + }), + ) + ).flatMap(({ row, result }) => { + if ( + !result.value || + result.value.indexUsageBytes === undefined || + !Number.isFinite(result.value.indexUsageBytes) || + result.value.indexUsageBytes < 0 || + result.value.dataUsageBytes === undefined || + !Number.isFinite(result.value.dataUsageBytes) || + result.value.dataUsageBytes <= 0 + ) { + addMetricFailure(metricFailures, 'IndexingCostRisk', result.reason ?? 'noData', scopeOf(row)); + return []; + } + return [ + { + databaseId: row.databaseId, + containerId: row.containerId, + ...result.value, + userExcludedPathCount: row.userExcludedPathCount, + indexingMode: row.indexingMode, + }, + ]; + }); - const partitionSignals = await mapInBatches(dedicatedTargets, async (row) => { + const partitionSignals = await mapInBatches(offerTargets, async (row) => { const [partition, throttle, growth, skew] = await Promise.all([ capture( getPartitionHealth( @@ -398,28 +437,33 @@ export async function collectDerivedAdvisories( row.databaseId, row.containerId, saturationObservation, + sharedContainerIds(row), ), ), - capture( - getPartitionStorageSeries( - monitorClient, - accountId, - storageObservation.timeRange, - row.databaseId, - row.containerId, - storageObservation, - ), - ), - capture( - getPartitionStorageSeries( - monitorClient, - accountId, - storageSkewObservation.timeRange, - row.databaseId, - row.containerId, - storageSkewObservation, - ), - ), + row.containerId === undefined + ? undefined + : capture( + getPartitionStorageSeries( + monitorClient, + accountId, + storageObservation.timeRange, + row.databaseId, + row.containerId, + storageObservation, + ), + ), + row.containerId === undefined + ? undefined + : capture( + getPartitionStorageSeries( + monitorClient, + accountId, + storageSkewObservation.timeRange, + row.databaseId, + row.containerId, + storageSkewObservation, + ), + ), ]); return { row, partition, throttle, growth, skew }; }); @@ -429,7 +473,7 @@ export async function collectDerivedAdvisories( const storageSkew: PartitionStorageResult[] = []; for (const { row, partition, throttle, growth, skew } of partitionSignals) { const scope = scopeOf(row); - const ageDays = rowAgeDays(row, accountCreatedAt, now); + const ageDays = offerAgeDays(row); if (partition.reason) { addMetricFailure(metricFailures, 'SustainedThrottlingInRegion', partition.reason, scope); @@ -456,6 +500,9 @@ export async function collectDerivedAdvisories( }); } + if (row.containerId === undefined || !growth || !skew) { + continue; + } if (growth.reason) { addMetricFailure(metricFailures, 'StorageGrowthRisk', growth.reason, scope); } else if (!growth.value?.available) { @@ -501,6 +548,7 @@ export async function collectDerivedAdvisories( actualPartitions: count.value, provisionedRu: row.throughputRU, dataUsageBytes: storage.value, + backupPolicy: accountConfig?.backupPolicy, }, ]; }); @@ -509,7 +557,7 @@ export async function collectDerivedAdvisories( await mapInBatches(autoscaleTargets, async (row) => ({ row, result: await capture( - getAutoscaleUtilization(monitorClient, accountId, row.databaseId, row.containerId, row.throughputRU!), + getAutoscaleUtilization(monitorClient, accountId, row.databaseId, row.containerId, row.throughputRU), ), })) ).flatMap(({ row, result }) => { @@ -519,7 +567,9 @@ export async function collectDerivedAdvisories( addMetricFailure(metricFailures, 'AutoscaleToManualCandidate', result.reason, scope); return []; } - if (!result.value) { + if (!result.value || result.value.sampleCount < DIAGNOSTIC_POLICY.autoscaleUtilization.minSamples) { + addMetricFailure(metricFailures, 'AutoscaleMaxOverProvisioned', 'noData', scope); + addMetricFailure(metricFailures, 'AutoscaleToManualCandidate', 'noData', scope); return []; } return [ @@ -530,7 +580,7 @@ export async function collectDerivedAdvisories( avgPercent: result.value.avgPercent, sampleCount: result.value.sampleCount, configuredMaxRu: row.throughputRU, - resourceAgeDays: rowAgeDays(row, accountCreatedAt, now), + resourceAgeDays: offerAgeDays(row), }, ]; }); @@ -581,9 +631,10 @@ export async function collectDerivedAdvisories( logsClient, accountId, logTargets, - offers, + offerTargets, params.onLogsDiagnostic, dedicatedTargets, + rows.filter((row) => row.offerLevel === 'database'), ); const advisories = computeDerivedAdvisories( @@ -608,12 +659,9 @@ export async function collectDerivedAdvisories( weeklyPeakPercent: undefined, hasManualThroughput: manualTargets.length > 0, manualProvisionedRuTotal: - inventory.value?.throughputInventoryComplete === true - ? manualTargets.reduce( - (sum, row) => (sum ?? 0) + (row.throughputRU ?? 0), - undefined, - ) - : undefined, + scopeProvisionedRuTotal === undefined + ? undefined + : manualTargets.reduce((sum, row) => (sum ?? 0) + row.throughputRU, undefined), partitions, storage: storage.map((result) => ({ databaseId: result.databaseId, @@ -633,7 +681,14 @@ export async function collectDerivedAdvisories( autoscaleUtilizations, serverless, scopeProvisionedRuTotal, - accountConfig, + manualRegionalCapacityRu: + scopeProvisionedRuTotal !== undefined && + manualTargets.length > 0 && + manualTargets.length === offerTargets.length && + !isServerless + ? scopeProvisionedRuTotal + : undefined, + accountConfig: effectiveAccountConfig, crossPartition: logs.crossPartition, ingestion: logs.ingestion, sharedThroughput: logs.sharedThroughput, @@ -666,6 +721,7 @@ export async function collectTier2Logs( }[], onDiagnostic?: LogsDiagnosticReporter, ingestionTargets: readonly { databaseId: string; containerId: string }[] = scanTargets, + sharedMembers: readonly { databaseId: string; containerId: string }[] = [], ): Promise { const empty = { crossPartition: [], ingestion: [], sharedThroughput: [] }; const failures: NonNullable = []; @@ -736,7 +792,14 @@ export async function collectTier2Logs( return { crossPartition: crossPartitionResults.filter((result): result is CrossPartitionInput => result !== undefined), ingestion: ingestionResults.filter((result): result is UncontrolledIngestionInput => result !== undefined), - sharedThroughput: sharedResults.filter((result): result is SharedThroughputInput => result !== undefined), + sharedThroughput: sharedResults + .filter((result): result is SharedThroughputInput => result !== undefined) + .map((result) => ({ + ...result, + sharedContainerIds: sharedMembers + .filter((member) => member.databaseId === result.databaseId) + .map((member) => member.containerId), + })), logSource: coverage(), }; } diff --git a/src/panels/accountOverview/services/advisories/collectParity.test.ts b/src/panels/accountOverview/services/advisories/collectParity.test.ts index 64aaa4e13..db131db00 100644 --- a/src/panels/accountOverview/services/advisories/collectParity.test.ts +++ b/src/panels/accountOverview/services/advisories/collectParity.test.ts @@ -3,7 +3,7 @@ * Licensed under the MIT License. See License.txt in the project root for license information. *--------------------------------------------------------------------------------------------*/ -import { afterEach, describe, expect, it, vi } from 'vitest'; +import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'; import { API } from '../../../../AzureDBExperiences'; import type * as InventoryModule from '../inventory'; import type * as RuTrendsModule from '../ruTrends'; @@ -14,11 +14,6 @@ vi.mock('../inventory', () => ({ getSqlInventoryDetails: vi.fn(), })); -vi.mock('../inventoryMetrics', async () => { - const { OVERVIEW_DEFAULTS } = await import('../healthPolicy'); - return { DEFAULT_HEALTH_THRESHOLDS: OVERVIEW_DEFAULTS.health, getInventoryMetrics: vi.fn() }; -}); - vi.mock('../partitionHealth', async () => { const { OVERVIEW_DEFAULTS } = await import('../healthPolicy'); return { @@ -39,25 +34,30 @@ vi.mock('./engine', () => ({ })); vi.mock('./fetchers/logs', () => ({ + fetchConsistencyReadRu: vi.fn(), fetchCrossPartitionShapes: vi.fn(), fetchSharedThroughputTraffic: vi.fn(), fetchUncontrolledIngestion: vi.fn(), logWindow: vi.fn(() => ({ startTime: new Date(0), endTime: new Date(1) })), probeCdbLogs: vi.fn(), + selectDataPlaneSource: vi.fn(), + requestLogWindow: vi.fn(() => ({ startTime: new Date(0), endTime: new Date(1) })), })); vi.mock('./fetchers/metrics', () => ({ getAccountConsumedRuShape: vi.fn(), + getAccountRequestStatusCounts: vi.fn(), + getThrottledOperationCounts: vi.fn(), getAutoscaleUtilization: vi.fn(), getContainerIdlePeak: vi.fn(), + getContainerIndexingUsage: vi.fn(), getContainerMergeStoragePeak: vi.fn(), getContainerPartitionCount: vi.fn(), })); -import { CosmosDBManagementClient } from '@azure/arm-cosmosdb'; +import { CosmosDBManagementClient, type ThroughputSettingsGetResults } from '@azure/arm-cosmosdb'; import { MonitorClient, type Response as MetricsResponse } from '@azure/arm-monitor'; import { getSqlInventoryDetails } from '../inventory'; -import { getInventoryMetrics } from '../inventoryMetrics'; import { getPartitionHealth, getPartitionStorageSeries } from '../partitionHealth'; import { getRuTrends, getThrottleRate } from '../ruTrends'; import { GB, pagedItems } from '../testFixtures'; @@ -75,10 +75,15 @@ import { getAccountConsumedRuShape, getAutoscaleUtilization, getContainerIdlePeak, + getContainerIndexingUsage, getContainerMergeStoragePeak, getContainerPartitionCount, } from './fetchers/metrics'; +beforeEach(() => { + vi.mocked(probeCdbLogs).mockResolvedValue({ available: false, reason: 'noData' }); +}); + afterEach(() => { vi.resetAllMocks(); }); @@ -117,6 +122,8 @@ function params(overrides: Partial[0 multiRegionWritesEnabled: false, writeRegionCount: 1, api: API.Core, + backupPolicy: { type: 'Periodic' }, + perRegionPerPartitionAutoscaleEnabled: true, }, logsClient: { queryResource: vi.fn() }, ...overrides, @@ -158,15 +165,105 @@ describe('collectDerivedAdvisories parity wiring', () => { }, ); + it.each(['none', 'NoNe', 'NONE'])( + 'skips DX-024 metric acquisition and coverage failures for %s indexing', + async (indexingMode) => { + const inventory = await vi.importActual('../inventory'); + const engine = await vi.importActual('./engine'); + vi.mocked(getSqlInventoryDetails).mockImplementation(inventory.getSqlInventoryDetails); + vi.mocked(computeDerivedAdvisories).mockImplementation(engine.computeDerivedAdvisories); + const cosmosClient = new CosmosDBManagementClient({ getToken: async () => null }, 'sub'); + vi.spyOn(cosmosClient.databaseAccounts, 'get').mockResolvedValue({}); + vi.spyOn(cosmosClient.sqlResources, 'listSqlDatabases').mockImplementation(() => + pagedItems([{ resource: { id: 'db' } }]), + ); + vi.spyOn(cosmosClient.sqlResources, 'listSqlContainers').mockImplementation(() => + pagedItems([{ resource: { id: 'disabled', indexingPolicy: { indexingMode } } }]), + ); + vi.mocked(getThrottleRate).mockResolvedValue({ ratePercent: 0, totalRequests: 0 }); + vi.mocked(getContainerIndexingUsage).mockRejectedValue({ statusCode: 403 }); + + const result = await collectDerivedAdvisories( + params({ cosmosClient, isServerless: true, logsClient: undefined }), + ); + + expect(result.metricSource.failures.filter((failure) => failure.rule === 'IndexingCostRisk')).toEqual([]); + expect(getContainerIndexingUsage).not.toHaveBeenCalled(); + expect(result.advisories.filter((item) => item.rule === 'IndexingCostRisk')).toEqual([]); + expect(vi.mocked(computeDerivedAdvisories).mock.calls[0][0].indexing).toEqual([]); + }, + ); + + it.each<{ indexingMode: string | undefined; outcome: 'positive' | 'empty' | 'denied' }>([ + { indexingMode: 'consistent', outcome: 'positive' }, + { indexingMode: 'lazy', outcome: 'positive' }, + { indexingMode: undefined, outcome: 'positive' }, + { indexingMode: 'unknown', outcome: 'positive' }, + { indexingMode: 'consistent', outcome: 'empty' }, + { indexingMode: 'consistent', outcome: 'denied' }, + ])( + 'preserves DX-024 $outcome results for $indexingMode indexing beside a disabled container', + async ({ indexingMode, outcome }) => { + const inventory = await vi.importActual('../inventory'); + const engine = await vi.importActual('./engine'); + vi.mocked(getSqlInventoryDetails).mockImplementation(inventory.getSqlInventoryDetails); + vi.mocked(computeDerivedAdvisories).mockImplementation(engine.computeDerivedAdvisories); + const cosmosClient = new CosmosDBManagementClient({ getToken: async () => null }, 'sub'); + vi.spyOn(cosmosClient.databaseAccounts, 'get').mockResolvedValue({}); + vi.spyOn(cosmosClient.sqlResources, 'listSqlDatabases').mockImplementation(() => + pagedItems([{ resource: { id: 'db' } }]), + ); + vi.spyOn(cosmosClient.sqlResources, 'listSqlContainers').mockImplementation(() => + pagedItems([ + { resource: { id: 'disabled', indexingPolicy: { indexingMode: 'none' } } }, + { resource: { id: 'eligible', indexingPolicy: { indexingMode } } }, + ]), + ); + vi.mocked(getThrottleRate).mockResolvedValue({ ratePercent: 0, totalRequests: 0 }); + if (outcome === 'denied') { + vi.mocked(getContainerIndexingUsage).mockRejectedValue({ statusCode: 403 }); + } else { + vi.mocked(getContainerIndexingUsage).mockResolvedValue( + outcome === 'positive' ? { indexUsageBytes: 60, dataUsageBytes: 100 } : {}, + ); + } + + const collectionParams = params({ cosmosClient, isServerless: true, logsClient: undefined }); + const result = await collectDerivedAdvisories(collectionParams); + + expect(getContainerIndexingUsage).toHaveBeenCalledExactlyOnceWith( + collectionParams.monitorClient, + collectionParams.accountId, + 'db', + 'eligible', + expect.any(Number), + ); + expect( + result.advisories.filter((item) => item.rule === 'IndexingCostRisk').map((item) => item.scope), + ).toEqual(outcome === 'positive' ? ['db/eligible'] : []); + expect(result.metricSource.failures.filter((failure) => failure.rule === 'IndexingCostRisk')).toEqual( + outcome === 'positive' + ? [] + : [ + { + rule: 'IndexingCostRisk', + scope: 'db/eligible', + reason: outcome === 'denied' ? 'rbac' : 'noData', + }, + ], + ); + }, + ); + it.each([ { paths: [], indexUsageBytes: 50, dataUsageBytes: 100, fires: true }, { paths: ['/_etag/?'], indexUsageBytes: 50, dataUsageBytes: 100, fires: true }, { paths: ['/"_etag"/?'], indexUsageBytes: 50, dataUsageBytes: 100, fires: true }, - { paths: ['/_etag/?', '/payload/*'], indexUsageBytes: 50, dataUsageBytes: 100, fires: false }, - { paths: ['/"_etag"/?', '/payload/*'], indexUsageBytes: 50, dataUsageBytes: 100, fires: false }, - { paths: ['/payload/_etag/?'], indexUsageBytes: 50, dataUsageBytes: 100, fires: false }, - { paths: ['/payload/"_etag"/?'], indexUsageBytes: 50, dataUsageBytes: 100, fires: false }, - { paths: ['/_etag/*'], indexUsageBytes: 50, dataUsageBytes: 100, fires: false }, + { paths: ['/_etag/?', '/payload/*'], indexUsageBytes: 50, dataUsageBytes: 100, fires: true }, + { paths: ['/"_etag"/?', '/payload/*'], indexUsageBytes: 50, dataUsageBytes: 100, fires: true }, + { paths: ['/payload/_etag/?'], indexUsageBytes: 50, dataUsageBytes: 100, fires: true }, + { paths: ['/payload/"_etag"/?'], indexUsageBytes: 50, dataUsageBytes: 100, fires: true }, + { paths: ['/_etag/*'], indexUsageBytes: 50, dataUsageBytes: 100, fires: true }, { paths: ['/_etag/?'], indexUsageBytes: 20, dataUsageBytes: 100, fires: false }, { paths: ['/_etag/?'], indexUsageBytes: 30, dataUsageBytes: 100, fires: false }, { paths: ['/_etag/?'], indexUsageBytes: undefined, dataUsageBytes: 100, fires: false }, @@ -196,47 +293,27 @@ describe('collectDerivedAdvisories parity wiring', () => { pagedItems([{ resource: { id: 'events', indexingPolicy } }]), ); vi.mocked(getThrottleRate).mockResolvedValue({ ratePercent: 0, totalRequests: 0 }); - vi.mocked(getInventoryMetrics).mockResolvedValue({ - available: true, - metrics: { - 'db/events': { - databaseId: 'db', - containerId: 'events', - storage: { - data: - dataUsageBytes === undefined - ? { status: 'unavailable', reason: 'noData' } - : { status: 'available', bytes: dataUsageBytes, timestamp: 0 }, - index: - indexUsageBytes === undefined - ? { status: 'unavailable', reason: 'noData' } - : { status: 'available', bytes: indexUsageBytes, timestamp: 0 }, - }, - throttled: false, - health: 'Healthy', - }, - }, - generatedAt: 0, - }); + vi.mocked(getContainerIndexingUsage).mockResolvedValue({ indexUsageBytes, dataUsageBytes }); const result = await collectDerivedAdvisories( params({ cosmosClient, isServerless: true, logsClient: undefined }), ); expect(result.advisories.filter((item) => item.rule === 'IndexingCostRisk')).toHaveLength(fires ? 1 : 0); - expect(vi.mocked(getInventoryMetrics).mock.calls[0][5]).toBe(true); + expect(getContainerIndexingUsage).toHaveBeenCalledWith( + expect.anything(), + expect.any(String), + 'db', + 'events', + expect.any(Number), + ); expect(getRuTrends).not.toHaveBeenCalled(); expect(getPartitionHealth).not.toHaveBeenCalled(); const collectedInventory = await vi.mocked(getSqlInventoryDetails).mock.results[0].value; expect(collectedInventory.rows[0].excludedPathCount).toBe(paths.length); expect(indexingPolicy).toEqual(originalPolicy); - vi.mocked(getInventoryMetrics).mockResolvedValue({ - available: false, - reason: 'noData', - metrics: {}, - generatedAt: 0, - }); + vi.mocked(getContainerIndexingUsage).mockResolvedValue({}); const unavailable = await collectDerivedAdvisories( params({ cosmosClient, isServerless: true, logsClient: undefined }), ); @@ -244,7 +321,7 @@ describe('collectDerivedAdvisories parity wiring', () => { expect(unavailable.metricSource.failures).toContainEqual({ rule: 'IndexingCostRisk', reason: 'noData', - scope: undefined, + scope: 'db/events', }); }, ); @@ -256,6 +333,9 @@ describe('collectDerivedAdvisories parity wiring', () => { 'missing storage', 'zero storage', 'access denied', + 'full fidelity', + 'full fidelity without backup policy', + 'disabled full fidelity', ] as const)( 'collects idle and merge metrics for all twelve active containers without wildcard truncation: %s', async (scenario) => { @@ -295,11 +375,6 @@ describe('collectDerivedAdvisories parity wiring', () => { timeRange: '7D', generatedAt: 0, }); - vi.mocked(getInventoryMetrics).mockResolvedValue({ - available: false, - metrics: {}, - generatedAt: 0, - }); vi.mocked(getPartitionHealth).mockRejectedValue(new Error('unavailable')); vi.mocked(getPartitionStorageSeries).mockRejectedValue(new Error('unavailable')); vi.mocked(getThrottleRate).mockResolvedValue({ ratePercent: 0, totalRequests: 1000 }); @@ -365,9 +440,21 @@ describe('collectDerivedAdvisories parity wiring', () => { }; }); - const result = await collectDerivedAdvisories(params({ monitorClient, logsClient: undefined })); + const fullFidelityChangeFeedEnabled = + scenario === 'full fidelity' || scenario === 'full fidelity without backup policy' + ? true + : scenario === 'disabled full fidelity' + ? false + : undefined; + const backupPolicy = { + type: scenario === 'full fidelity without backup policy' ? undefined : 'Periodic', + fullFidelityChangeFeedEnabled, + }; + const options = params({ monitorClient, logsClient: undefined }); + options.accountConfig = { ...options.accountConfig, backupPolicy }; + const result = await collectDerivedAdvisories(options); const inputs = vi.mocked(computeDerivedAdvisories).mock.calls[0][0]; - const missingIdle = scenario === 'missing idle' || scenario === 'access denied'; + const missingIdle = scenario === 'access denied'; const missingMerge = scenario === 'missing partition count' || scenario === 'missing storage' || @@ -378,13 +465,25 @@ describe('collectDerivedAdvisories parity wiring', () => { (failure) => failure.rule === 'IdleContainer' || failure.rule === 'PartitionMergeCandidate', ); - expect.soft(result.advisories.filter((item) => item.rule === 'IdleContainer')).toEqual([]); + const idleAdvisories = result.advisories.filter((item) => item.rule === 'IdleContainer'); + const idleFinding = expect.objectContaining({ + scope: 'db0/c0', + evidence: { peakRuPerBucket: 0, provisionedRu: 1000, recoverableRu: 1000 }, + }); + expect.soft(idleAdvisories).toEqual(scenario === 'missing idle' ? [idleFinding] : []); expect.soft(inputs.idleContainers).toHaveLength(idleRows.length); - expect.soft(inputs.idleContainers?.every((item) => item.peakRuPerBucket === 1000)).toBe(true); + for (const row of idleRows) { + expect.soft(inputs.idleContainers).toContainEqual( + expect.objectContaining({ + databaseId: row.databaseId, + containerId: row.containerId, + peakRuPerBucket: scenario === 'missing idle' && row === rows[0] ? 0 : 1000, + }), + ); + } expect.soft(inputs.partitionMerges).toHaveLength(mergeRows.length); - expect - .soft(result.advisories.filter((item) => item.rule === 'PartitionMergeCandidate')) - .toHaveLength(mergeRows.length); + const mergeAdvisories = result.advisories.filter((item) => item.rule === 'PartitionMergeCandidate'); + expect.soft(mergeAdvisories).toHaveLength(mergeRows.length); for (const row of mergeRows) { expect.soft(inputs.partitionMerges).toContainEqual({ databaseId: row.databaseId, @@ -392,7 +491,14 @@ describe('collectDerivedAdvisories parity wiring', () => { actualPartitions: 4, provisionedRu: 1000, dataUsageBytes: scenario === 'zero storage' && row === rows[0] ? 0 : GB, + backupPolicy, }); + expect + .soft( + mergeAdvisories.find((advisory) => advisory.scope === `${row.databaseId}/${row.containerId}`) + ?.actionEligibility, + ) + .toBe(fullFidelityChangeFeedEnabled === true ? 'blocked' : 'requiresValidation'); } expect.soft(list).toHaveBeenCalledTimes(rows.length * 3); expect.soft(peakConcurrency).toBeGreaterThan(1); @@ -456,11 +562,6 @@ describe('collectDerivedAdvisories parity wiring', () => { generatedAt: 0, }); vi.mocked(getContainerIdlePeak).mockResolvedValue(1000); - vi.mocked(getInventoryMetrics).mockResolvedValue({ - available: false, - metrics: {}, - generatedAt: 0, - }); vi.mocked(getPartitionHealth).mockRejectedValue(new Error('unavailable')); vi.mocked(getPartitionStorageSeries).mockRejectedValue(new Error('unavailable')); vi.mocked(getThrottleRate).mockResolvedValue({ ratePercent: 0, totalRequests: 1000 }); @@ -484,7 +585,7 @@ describe('collectDerivedAdvisories parity wiring', () => { expect(sizing.some((item) => item.scope === 'db/c11')).toBe(true); }); - it('uses dedicated offers for container checks, includes serverless throttling, and counts scope RU once per offer', async () => { + it('evaluates dedicated and shared database offers, with capacity counted once per offer', async () => { vi.mocked(getSqlInventoryDetails).mockResolvedValue({ databases: ['db-shared', 'db-manual', 'db-auto', 'db-sls'], throughputInventoryComplete: true, @@ -586,11 +687,7 @@ describe('collectDerivedAdvisories parity wiring', () => { vi.mocked(getContainerIdlePeak).mockImplementation(async (_client, _resource, databaseId) => databaseId === 'db-manual' ? 0 : 20, ); - vi.mocked(getInventoryMetrics).mockResolvedValue({ - available: true, - metrics: {}, - generatedAt: 1, - }); + vi.mocked(getContainerIndexingUsage).mockResolvedValue({ indexUsageBytes: 20, dataUsageBytes: 100 }); vi.mocked(getPartitionHealth).mockResolvedValue({ available: true, mode: 'ru', @@ -634,6 +731,7 @@ describe('collectDerivedAdvisories parity wiring', () => { databaseId, containerId, shapes: [], + evaluationWindowSeconds: 86400, })); vi.mocked(fetchUncontrolledIngestion).mockImplementation(async (_logs, _account, databaseId, containerId) => ({ databaseId, @@ -678,14 +776,16 @@ describe('collectDerivedAdvisories parity wiring', () => { expect.objectContaining({ databaseId: 'db-manual', containerId: 'manual-c', provisionedRu: 1000 }), ]); expect(inputs.idleContainers).toEqual([ + expect.objectContaining({ databaseId: 'db-shared', containerId: undefined, peakRuPerBucket: 20 }), expect.objectContaining({ containerId: 'manual-c', peakRuPerBucket: 0 }), expect.objectContaining({ containerId: 'auto-c', peakRuPerBucket: 20 }), ]); - expect(inputs.partitions.map((item) => item.containerId)).toEqual(['manual-c', 'auto-c']); + expect(inputs.partitions.map((item) => item.containerId)).toEqual([undefined, 'manual-c', 'auto-c']); expect(inputs.partitionMerges?.map((item) => item.containerId)).toEqual(['manual-c', 'auto-c']); - expect(inputs.autoscaleUtilizations?.map((item) => item.containerId)).toEqual(['auto-c']); + expect(inputs.autoscaleUtilizations?.map((item) => item.containerId)).toEqual([undefined, 'auto-c']); expect(inputs.serverlessThrottling?.map((item) => item.containerId)).toEqual(['serverless-c']); expect(inputs.scopeProvisionedRuTotal).toBe(10_000); + expect(inputs.manualRegionalCapacityRu).toBeUndefined(); expect(inputs.sharedThroughput).toEqual([expect.objectContaining({ databaseId: 'db-shared', sharedRu: 4000 })]); expect(vi.mocked(fetchCrossPartitionShapes).mock.calls.map((call) => call[3])).toEqual([ 'manual-c', @@ -735,11 +835,6 @@ describe('collectDerivedAdvisories parity wiring', () => { generatedAt: 1, }); vi.mocked(getContainerIdlePeak).mockRejectedValue(new Error('idle failed')); - vi.mocked(getInventoryMetrics).mockResolvedValue({ - available: true, - metrics: {}, - generatedAt: 1, - }); vi.mocked(getPartitionHealth).mockResolvedValue({ available: true, mode: 'ru', @@ -774,7 +869,12 @@ describe('collectDerivedAdvisories parity wiring', () => { sampleCount: 50, }); vi.mocked(probeCdbLogs).mockResolvedValue({ available: true }); - vi.mocked(fetchCrossPartitionShapes).mockResolvedValue({ databaseId: 'db', containerId: 'c', shapes: [] }); + vi.mocked(fetchCrossPartitionShapes).mockResolvedValue({ + databaseId: 'db', + containerId: 'c', + shapes: [], + evaluationWindowSeconds: 86400, + }); vi.mocked(fetchUncontrolledIngestion).mockResolvedValue(undefined); vi.mocked(fetchSharedThroughputTraffic).mockResolvedValue({ databaseId: 'db', @@ -810,7 +910,12 @@ describe('collectDerivedAdvisories parity wiring', () => { sampleCount: 30, }); vi.mocked(probeCdbLogs).mockResolvedValue({ available: true }); - vi.mocked(fetchCrossPartitionShapes).mockResolvedValue({ databaseId: 'db', containerId: 'c', shapes: [] }); + vi.mocked(fetchCrossPartitionShapes).mockResolvedValue({ + databaseId: 'db', + containerId: 'c', + shapes: [], + evaluationWindowSeconds: 86400, + }); vi.mocked(fetchUncontrolledIngestion).mockResolvedValue(undefined); vi.mocked(fetchSharedThroughputTraffic).mockResolvedValue({ databaseId: 'db', diff --git a/src/panels/accountOverview/services/advisories/core/helpers.ts b/src/panels/accountOverview/services/advisories/core/helpers.ts index 98ab41148..e8a7b9d31 100644 --- a/src/panels/accountOverview/services/advisories/core/helpers.ts +++ b/src/panels/accountOverview/services/advisories/core/helpers.ts @@ -4,10 +4,29 @@ *--------------------------------------------------------------------------------------------*/ import { DIAGNOSTIC_POLICY } from './thresholds'; -import { type DerivedAdvisory, type DerivedAdvisorySeverity } from './types'; +import { + type DerivedAdvisory, + type DerivedAdvisorySeverity, + type UtilizationBand, +} from './types'; + +export function utilizationBand(value: number, moderateUpperPercent: number): UtilizationBand { + return value < DIAGNOSTIC_POLICY.overProvisioning.idleBandPercent + ? 'idle' + : value < DIAGNOSTIC_POLICY.overProvisioning.lowBandPercent + ? 'low' + : value < moderateUpperPercent + ? 'moderate' + : 'ok'; +} const ADVISORY_SEVERITY_ORDER: Record = { High: 0, Medium: 1, Low: 2 }; +/** Shared throughput belongs to the database offer; it must never be recovered once per member. */ +export function offerScope(input: { databaseId: string; containerId?: string }): string { + return input.containerId === undefined ? input.databaseId : `${input.databaseId}/${input.containerId}`; +} + /** Sorts advisories by severity (High first), then rule, then scope. Pure. */ export function compareAdvisories(a: DerivedAdvisory, b: DerivedAdvisory): number { return ( diff --git a/src/panels/accountOverview/services/advisories/core/thresholds.ts b/src/panels/accountOverview/services/advisories/core/thresholds.ts index f02ff3d48..eef0efd2b 100644 --- a/src/panels/accountOverview/services/advisories/core/thresholds.ts +++ b/src/panels/accountOverview/services/advisories/core/thresholds.ts @@ -39,6 +39,8 @@ export const DIAGNOSTIC_POLICY = { }, // DX-001 and DX-011 share the right-sizing band, peak guard and headroom policy. overProvisioning: { + idleBandPercent: 1, + lowBandPercent: 10, minResourceAgeDays: 7, minSamples: 24, bandPercent: 30, @@ -128,6 +130,8 @@ export const DIAGNOSTIC_POLICY = { }, indexing: { usageRatio: 0.3, + mediumRatio: 1, + observation: { windowMs: 6 * HOUR, interval: 'PT5M', bucketMs: 5 * MINUTE } satisfies RangeConfig, }, partitionMerge: { mediumExcessRatio: 2, @@ -140,13 +144,15 @@ export const DIAGNOSTIC_POLICY = { crossPartition: { minQueries: 50, fanoutThreshold: 1.5, - highPercent: 30, mediumPercent: 10, + minQueriesPerSecond: 0.1, + highQueriesPerSecond: 1, + mediumPartitions: 4, + highPartitions: 7, }, shardKey: { structuralPercent: 60, minPartitions: 2, - highPercent: 80, }, ingestion: { writeRuPercentFloor: 80, @@ -164,7 +170,8 @@ export const DIAGNOSTIC_POLICY = { victimSharePercent: 20, }, expensiveConsistency: { - minRegions: 2, + minStrongRegions: 1, + minBoundedStalenessRegions: 2, }, multiRegionWrite: { minWriteRegions: 2, @@ -193,10 +200,8 @@ export const DEFAULT_ADVISORY_THRESHOLDS: DerivedAdvisoryThresholds = { // uncontrolled_ingestion.py, shared_throughput.py). crossPartitionMinQueries: DIAGNOSTIC_POLICY.crossPartition.minQueries, crossPartitionFanoutThreshold: DIAGNOSTIC_POLICY.crossPartition.fanoutThreshold, - crossPartitionHighPct: DIAGNOSTIC_POLICY.crossPartition.highPercent, crossPartitionMedPct: DIAGNOSTIC_POLICY.crossPartition.mediumPercent, shardKeyStructuralPct: DIAGNOSTIC_POLICY.shardKey.structuralPercent, - shardKeyHighPct: DIAGNOSTIC_POLICY.shardKey.highPercent, ingestionWriteRuPctFloor: DIAGNOSTIC_POLICY.ingestion.writeRuPercentFloor, ingestionThrottleRatePct: DIAGNOSTIC_POLICY.ingestion.throttleRatePercent, ingestionHighPct: DIAGNOSTIC_POLICY.ingestion.highPercent, diff --git a/src/panels/accountOverview/services/advisories/core/types.ts b/src/panels/accountOverview/services/advisories/core/types.ts index 737a3f722..06f154320 100644 --- a/src/panels/accountOverview/services/advisories/core/types.ts +++ b/src/panels/accountOverview/services/advisories/core/types.ts @@ -13,7 +13,7 @@ import { type LogsFailureKind, type LogsOperation } from '../fetchers/logsDiagno // // Unlike Azure Alerts + Advisor recommendations, these advisories are derived on // the extension host from telemetry the dashboard has already fetched (RU trends, -// inventory metrics, partition health). No new ARM endpoints. The portal does not +// inventory metrics, partition health and account request metrics), plus optional diagnostic logs. The portal does not // derive these on its Overview blade. Thresholds follow the internal CODA-governed policy, not VS Code settings. // Every rule function is pure so it can be unit-tested against synthetic inputs; collectDerivedAdvisories does // the fetching and calls computeDerivedAdvisories. @@ -42,6 +42,109 @@ export type DerivedAdvisoryRule = export type DerivedAdvisorySeverity = 'High' | 'Medium' | 'Low'; +export type UtilizationBand = 'idle' | 'low' | 'moderate' | 'ok' | 'insufficient_data'; + +/** Production sizing observations remain inspectable even when a finding is withheld. */ +export interface ProvisioningEvaluation { + band: UtilizationBand; + recommendedRu?: number; + recoverableRu?: number; + advisory?: DerivedAdvisory; +} + +type EvaluationOutcome = { rootCause: RootCause } & ([ + Observations, +] extends [never] + ? { observations?: never } + : { observations: Observations }); + +interface AdvisoryEvaluationResults { + AutoscaleCandidate: EvaluationOutcome<'insufficient_data' | 'spiky_manual' | 'well_matched'>; + AutoscaleToManualCandidate: EvaluationOutcome<'insufficient_data' | 'well_matched' | 'steady_autoscale'>; + CrossPartitionQuery: EvaluationOutcome< + | 'insufficient_data' + | 'single_partition_container' + | 'mostly_single_partition' + | 'occasional_fanout' + | 'cross_partition' + >; + ExpensiveConsistency: EvaluationOutcome< + 'unknown' | 'default_or_relaxed' | 'single_region' | 'strong_single_region' | 'premium_multi_region' + >; + HotPartitionRisk: EvaluationOutcome< + 'insufficient_data' | 'single_partition' | 'not_saturated' | 'uniform_saturation' | 'hot_partition' + >; + IdleContainer: + | EvaluationOutcome<'insufficient_data' | 'active'> + | EvaluationOutcome<'idle', { recoverableRu: number }>; + IndexingCostRisk: + | EvaluationOutcome<'indexing_disabled' | 'insufficient_data'> + | EvaluationOutcome< + 'normal_ratio' | 'high_index_ratio', + { indexDataRatio: number; userExcludedPathCount: number } + >; + MultiRegionWriteAntipattern: { + rootCause: + | 'not_multi_region_writes' + | `${'cassandra' | 'gremlin' | 'table' | 'mongo'}_multi_region_writes` + | 'single_region_multi_region_writes_tripwire' + | 'legitimate_ha' + | 'nonprod_multi_region_writes'; + observations?: + | { regionalCapacityQuantified: false } + | { + regionalCapacityQuantified: true; + configuredPerRegionRu: number; + globalRegionalFootprintRu: number; + removableExtraRegionRu: number | null; + }; + }; + PartitionMergeCandidate: + | EvaluationOutcome<'insufficient_data' | 'single_partition' | 'right_sized'> + | EvaluationOutcome< + 'over_partitioned', + { + mergeEligibility: + | 'blocked_pitr' + | 'blocked_full_fidelity' + | 'requires_platform_validation' + | 'unknown'; + } + >; + ServerlessCandidate: EvaluationOutcome< + | 'already_serverless' + | 'insufficient_data' + | 'idle_or_empty' + | 'too_high' + | 'steady_load' + | 'serverless_candidate' + >; + ServerlessThrottling: + | EvaluationOutcome<'insufficient_data' | 'not_throttling'> + | EvaluationOutcome<'serverless_throttling', { throttleRatePercent: number }>; + ShardKeyMisalignment: EvaluationOutcome<'insufficient_data' | 'not_misaligned' | 'shard_key_misaligned'>; + SharedThroughputStarvation: + | EvaluationOutcome<'insufficient_data' | 'single_collection' | 'not_throttling' | 'no_disparity'> + | EvaluationOutcome<'starvation', { monopolizer: string; victim: string }>; + StorageGrowthRisk: + | EvaluationOutcome<'insufficient_data' | 'too_small' | 'stable'> + | EvaluationOutcome<'at_or_over_limit' | 'rapid_growth', { daysToLimit: number }>; + StorageSkewRisk: EvaluationOutcome< + 'insufficient_data' | 'single_partition' | 'uniform_storage' | 'too_small' | 'storage_skew' + >; + SustainedThrottlingInRegion: EvaluationOutcome< + 'insufficient_data' | 'not_throttling' | 'skew_suspected' | 'global_under_provisioning' + >; + UncontrolledIngestion: EvaluationOutcome<'insufficient_data' | 'not_uncontrolled' | 'uncontrolled_ingestion'>; +} + +export type AdvisoryEvaluation = + AdvisoryEvaluationResults[Rule] & { + advisory?: DerivedAdvisory; + /** A diagnostic classification can have severity without emitting this rule's finding. */ + severity?: DerivedAdvisorySeverity; + }; + export interface DerivedAdvisory { /** Stable id (rule + optional scope) so the webview can dismiss it for the session. */ id: string; @@ -58,6 +161,10 @@ export interface DerivedAdvisory { scope?: string; /** Retained for diagnostic provenance, but hidden from the default actionable list. */ supersededBy?: string; + /** Machine-readable observed/modelled values, separate from localized presentation. Not telemetry. */ + evidence?: Record; + /** Structural findings can remain visible while a proposed action is blocked or unverified. */ + actionEligibility?: 'requiresValidation' | 'blocked' | 'unknown'; } /** @@ -75,7 +182,7 @@ export interface LogsSourceStatus { failures?: { operation: LogsOperation; kind: LogsFailureKind; reason: UnavailableReason }[]; } -/** Failed metric checks stay distinguishable from successful checks with no finding. */ +/** Missing metric/configuration evidence stays distinguishable from successful checks with no finding. */ export interface MetricSourceStatus { available: boolean; failures: { rule: DerivedAdvisoryRule; scope?: string; reason: UnavailableReason }[]; @@ -175,14 +282,10 @@ export interface DerivedAdvisoryThresholds { crossPartitionMinQueries: number; /** DX-002: a query shape whose average fan-out (distinct partitions per logical query) is at or above this counts as cross-partition. */ crossPartitionFanoutThreshold: number; - /** DX-002: share (%) of executions fanning out at or above which CrossPartitionQuery is High (else Medium down to the med floor). */ - crossPartitionHighPct: number; /** DX-002: share (%) of executions fanning out below which CrossPartitionQuery does not fire. */ crossPartitionMedPct: number; /** DX-007: share (%) of executions fanning out at or above which the partition *key* is structurally misaligned (re-key), superseding DX-002. */ shardKeyStructuralPct: number; - /** DX-007: cross-partition share (%) at or above which ShardKeyMisalignment is High (else Medium). */ - shardKeyHighPct: number; /** DX-010: write-op RU share (%) at or above which the workload is write-dominant. */ ingestionWriteRuPctFloor: number; /** DX-010: 429 rate (%) at or above which the container is throttling (paired with write-dominance to fire). */ @@ -211,7 +314,8 @@ export interface DerivedAdvisoryThresholds { export interface PartitionSaturationInput { resourceAgeDays?: number; databaseId: string; - containerId: string; + /** Absent for a shared database offer. */ + containerId?: string; /** Busiest physical partition's p99 utilization (% of provisioned). */ maxP99: number; /** Coolest physical partition's p99 utilization (% of provisioned). */ @@ -258,6 +362,7 @@ export interface IndexingUsageInput { dataUsageBytes?: number; /** Number of excluded paths other than the default root `_etag` exclusion. */ userExcludedPathCount: number; + indexingMode?: string; } /** Already-known ARM account configuration the config-only advisories (DX-016 / DX-008) read. */ @@ -277,16 +382,28 @@ export interface AccountConfigInput { /** Number of write regions the account has. */ writeRegionCount: number; /** Canonical API; undefined means unknown. */ - api: API | undefined; + api: API | 'MongoDB' | undefined; + backupPolicy?: BackupEligibilityInput; + /** Unknown must not be interpreted as provisioned capacity or as a disabled feature. */ + isServerless?: boolean; + perRegionPerPartitionAutoscaleEnabled?: boolean; +} + +export interface BackupEligibilityInput { + type?: string; + continuousTier?: string; + migrationState?: { status?: string; targetType?: string }; + fullFidelityChangeFeedEnabled?: boolean; } /** Already-fetched idle signal for one container over the 30-day window (DX-004). */ export interface IdleContainerInput { resourceAgeDays?: number; databaseId: string; - containerId: string; - /** Peak RU consumed in any single bucket (max of `TotalRequestUnits`, Total). 0 for an all-zero/empty series. */ - peakRuPerBucket: number; + /** Absent for a shared database offer; recovery belongs to the offer, not each member. */ + containerId?: string; + /** Peak RU consumed in any bucket; successful empty reads become zero, unavailable reads remain undefined. */ + peakRuPerBucket?: number; /** Throughput billing mode; only manual (dedicated/shared) and autoscale offers are recoverable. */ throughputMode: ThroughputMode; /** The container's configured provisioned RU/s (autoscale max for autoscale). */ @@ -303,13 +420,15 @@ export interface PartitionMergeInput { provisionedRu?: number; /** Peak data storage in bytes over the same six-hour window as the partition count. */ dataUsageBytes?: number; + backupPolicy?: BackupEligibilityInput; } /** Already-fetched autoscale duty-cycle signal for one container (DX-011 / DX-013). */ export interface AutoscaleUtilizationInput { resourceAgeDays?: number; databaseId: string; - containerId: string; + /** Absent for a shared database offer. */ + containerId?: string; /** Peak of the `AutoscaledRU`-as-%-of-configured-max series over the window (0..100). */ peakPercent: number; /** Average of the same series (0..100), for the duty-cycle read. */ @@ -332,10 +451,10 @@ export interface ServerlessCandidateInput { isServerless: boolean; } -/** One dedicated manual offer's observed utilization; never an account-level mixture of throughput modes. */ +/** One manual offer's observed utilization; dedicated container or shared database, never a mode mixture. */ export interface ManualThroughputInput { databaseId: string; - containerId: string; + containerId?: string; ruPercents: readonly number[]; peakPercent?: number; provisionedRu: number; @@ -370,6 +489,22 @@ export interface QueryShapeInput { avgFanout: number; /** Widest fan-out observed for this shape, the container's estimated physical-partition count. */ maxFanout: number; + /** Mean logical-query RU only when every execution/activity matched valid raw request charges. Not savings. */ + avgRu?: number; +} + +/** Auditable request-log source and half-open absolute observation window. Not telemetry. */ +export interface RequestLogEvidence { + sourceTable: 'CDBDataPlaneRequests' | 'CDBDataPlaneRequests5M'; + sourceResolution: 'perRequest' | 'PT5M'; + observationStart: string; + observationEnd: string; +} + +export interface ConsistencyReadRuInput extends RequestLogEvidence { + status: 'observed' | 'noObservations'; + readRequests: number; + readRu: number; } /** Per-container cross-partition / shard-key input (DX-002 / DX-007). */ @@ -377,19 +512,21 @@ export interface CrossPartitionInput { databaseId: string; containerId: string; shapes: readonly QueryShapeInput[]; + /** Actual duration of the request-log observation; rates must not assume a fixed day. */ + evaluationWindowSeconds: number; + observationStart?: string; + observationEnd?: string; } export interface CrossPartitionThresholds { minQueries: number; fanoutThreshold: number; - highPct: number; medPct: number; } export interface ShardKeyThresholds { structuralPct: number; minPartitions: number; - highPct: number; } /** Per-container write-dominance + throttling input (CODA DX-010). RU/request totals over the window. */ @@ -408,6 +545,7 @@ export interface UncontrolledIngestionInput { burstFactor: number; /** Dominant write-path client `UserAgent`, surfaced as context when present. */ dominantUserAgent?: string; + requestLogEvidence?: RequestLogEvidence; } export interface UncontrolledIngestionThresholds { @@ -431,6 +569,9 @@ export interface SharedThroughputInput { /** Provisioned RU/s shared across the database's collections, surfaced as context. */ sharedRu: number; collections: readonly CollectionTrafficInput[]; + /** Authoritative shared-offer membership. Unknown membership is insufficient evidence. */ + sharedContainerIds?: readonly string[]; + requestLogEvidence?: RequestLogEvidence; } export interface SharedThroughputThresholds { @@ -471,8 +612,12 @@ export interface DerivedAdvisoryInputs { serverless?: ServerlessCandidateInput; /** Total provisioned RU/s across the account, the materiality denominator for the idle/autoscale-max rules. */ scopeProvisionedRuTotal?: number; + /** Complete positive all-manual offer inventory only; autoscale/unknown inventory cannot quantify regions. */ + manualRegionalCapacityRu?: number; /** Account-level ARM configuration for the config-only advisories (DX-016 / DX-008); absent when unavailable. */ accountConfig?: AccountConfigInput; + /** Optional observed read charge; never gates the configuration-only consistency finding. */ + consistencyReadRu?: ConsistencyReadRuInput; /** Per-container query fan-out shapes (Log Analytics) for the cross-partition + shard-key rules (DX-002 / DX-007). */ crossPartition?: readonly CrossPartitionInput[]; /** Per-container write-dominance + throttling (Log Analytics) for the uncontrolled-ingestion rule (DX-010). */ diff --git a/src/panels/accountOverview/services/advisories/derivedAdvisories.parity.test.ts b/src/panels/accountOverview/services/advisories/derivedAdvisories.parity.test.ts index 166fbf9bc..19cfe34ec 100644 --- a/src/panels/accountOverview/services/advisories/derivedAdvisories.parity.test.ts +++ b/src/panels/accountOverview/services/advisories/derivedAdvisories.parity.test.ts @@ -6,13 +6,9 @@ /** * CODA parity tests (P10.6 Part B). * - * Each `describe` below mirrors, scenario-for-scenario, a CODA detector's own offline unit test so that our ported - * TypeScript detectors reproduce CODA's classification methodology (positive **and** negative cases). The CODA source - * fixture is cited on each block; the scenarios are the same input shapes and expected verdicts, re-expressed against - * our `evaluate*` surface. This is a methodology-parity harness — it deliberately overlaps the behavioural coverage in - * `derivedAdvisories.test.ts`, but organised by CODA fixture so a reviewer can check parity rule-by-rule. - * - * CODA reference repo: azure-data-database-platform/coda — tests/test_*.py. + * Native methodology regressions, including the adopted 0.17.15 corrections. + * Historical fixture references below explain provenance; this is not an executable imported contract or a + * complete parity certificate. Newly authored boundary coverage lives in nativeParity.test.ts. */ import { describe, expect, it } from 'vitest'; @@ -690,10 +686,10 @@ describe('CODA parity — DX-016 ExpensiveConsistency (test_consistency.py)', () expect(v?.severity).toBe('Low'); }); - it('Strong on a single region is not flagged (test_strong_single_region_not_flagged)', () => { + it('Strong on a known single region is Medium', () => { expect( evaluateExpensiveConsistency(accountConfig({ consistencyLevel: 'Strong', regionCount: 1 })), - ).toBeUndefined(); + ).toMatchObject({ severity: 'Medium' }); }); it('an enum-style level is normalised (test_enum_style_value_normalized)', () => { @@ -858,7 +854,6 @@ describe('CODA parity — DX-008 MultiRegionWriteAntipattern (test_multi_region_ const CP_THRESHOLDS = { minQueries: DEFAULT_ADVISORY_THRESHOLDS.crossPartitionMinQueries, fanoutThreshold: DEFAULT_ADVISORY_THRESHOLDS.crossPartitionFanoutThreshold, - highPct: DEFAULT_ADVISORY_THRESHOLDS.crossPartitionHighPct, medPct: DEFAULT_ADVISORY_THRESHOLDS.crossPartitionMedPct, }; @@ -867,11 +862,11 @@ function shape(text: string, executions: number, avgFanout: number, maxFanout: n } function cpInput(shapes: QueryShapeInput[]): CrossPartitionInput { - return { databaseId: 'db', containerId: 'c', shapes }; + return { databaseId: 'db', containerId: 'c', shapes, evaluationWindowSeconds: 1000 }; } describe('DX-002 cross-partition query fan-out parity', () => { - it('flags High when the dominant share of executions fans out', () => { + it('flags Low for a two-partition workload above the fan-out rate floor', () => { const v = evaluateCrossPartitionQuery( cpInput([ shape('SELECT * FROM c WHERE c.email=@e', 800, 2.0, 2), @@ -880,12 +875,12 @@ describe('DX-002 cross-partition query fan-out parity', () => { CP_THRESHOLDS, ); expect(v?.rule).toBe('CrossPartitionQuery'); - expect(v?.severity).toBe('High'); // 80% cross + expect(v?.severity).toBe('Low'); expect(v?.scope).toBe('db/c'); expect(v?.rationale).toContain('email'); }); - it('flags Medium at a moderate cross-partition share', () => { + it('flags Low at a moderate cross-partition share on two partitions', () => { const v = evaluateCrossPartitionQuery( cpInput([ shape('SELECT * FROM c WHERE c.email=@e', 150, 2.0, 2), @@ -893,7 +888,7 @@ describe('DX-002 cross-partition query fan-out parity', () => { ]), CP_THRESHOLDS, ); - expect(v?.severity).toBe('Medium'); // 15% cross + expect(v?.severity).toBe('Low'); }); it('does not flag a mostly single-partition workload', () => { @@ -926,7 +921,6 @@ describe('DX-002 cross-partition query fan-out parity', () => { const SHARD_THRESHOLDS = { structuralPct: DEFAULT_ADVISORY_THRESHOLDS.shardKeyStructuralPct, minPartitions: 2, - highPct: DEFAULT_ADVISORY_THRESHOLDS.shardKeyHighPct, }; const CP_FANOUT = DEFAULT_ADVISORY_THRESHOLDS.crossPartitionFanoutThreshold; @@ -938,16 +932,16 @@ function shardRows(crossExec: number, singleExec: number): CrossPartitionInput { } describe('DX-007 shard-key misalignment parity', () => { - it('flags High when the dominant share fans out (≥ 80%)', () => { + it('flags Low when the dominant share fans out over only two partitions', () => { const v = evaluateShardKeyMisalignment(shardRows(850, 150), SHARD_THRESHOLDS, CP_FANOUT); expect(v?.rule).toBe('ShardKeyMisalignment'); - expect(v?.severity).toBe('High'); + expect(v?.severity).toBe('Low'); expect(v?.suggestedAction.toLowerCase()).toContain('re-key'); }); - it('flags Medium at a moderate-dominant share ([60,80))', () => { + it('flags Low at a structural share on two partitions', () => { const v = evaluateShardKeyMisalignment(shardRows(650, 350), SHARD_THRESHOLDS, CP_FANOUT); - expect(v?.severity).toBe('Medium'); + expect(v?.severity).toBe('Low'); }); it('does not flag a per-query-only problem (< structural share)', () => { @@ -973,10 +967,9 @@ describe('DX-007 shard-key misalignment parity', () => { expect(v).toBeUndefined(); // container only spans 2 partitions }); - it('inherits DX-002s minimum-query sufficiency gate and one-decimal share rounding', () => { + it('inherits the minimum-query gate without rounding a below-threshold share into a finding', () => { expect(evaluateShardKeyMisalignment(shardRows(30, 19), SHARD_THRESHOLDS, CP_FANOUT)).toBeUndefined(); - const rounded = evaluateShardKeyMisalignment(shardRows(5995, 4005), SHARD_THRESHOLDS, CP_FANOUT); - expect(rounded?.severity).toBe('Medium'); + expect(evaluateShardKeyMisalignment(shardRows(5995, 4005), SHARD_THRESHOLDS, CP_FANOUT)).toBeUndefined(); }); }); @@ -1110,6 +1103,7 @@ describe('DX-003 shared-throughput starvation parity', () => { { databaseId: 'shareddb', sharedRu: 1000, + sharedContainerIds: ['hot', 'cold'], collections: [coll('hot', 10000, 500, 900000), coll('cold', 1000, 300, 50000)], }, SHARED_THRESHOLDS, @@ -1126,6 +1120,7 @@ describe('DX-003 shared-throughput starvation parity', () => { { databaseId: 'shareddb', sharedRu: 1000, + sharedContainerIds: ['a', 'b'], collections: [coll('a', 10000, 50, 600000), coll('b', 8000, 40, 400000)], }, SHARED_THRESHOLDS, @@ -1138,6 +1133,7 @@ describe('DX-003 shared-throughput starvation parity', () => { { databaseId: 'shareddb', sharedRu: 1000, + sharedContainerIds: ['a', 'b'], collections: [coll('a', 10000, 800, 520000), coll('b', 10000, 700, 480000)], }, SHARED_THRESHOLDS, @@ -1150,6 +1146,7 @@ describe('DX-003 shared-throughput starvation parity', () => { { databaseId: 'shareddb', sharedRu: 1000, + sharedContainerIds: ['solo', 'idle'], collections: [coll('solo', 10000, 900, 900000), coll('idle', 5, 0, 10)], }, SHARED_THRESHOLDS, @@ -1162,6 +1159,7 @@ describe('DX-003 shared-throughput starvation parity', () => { { databaseId: 'shareddb', sharedRu: 1000, + sharedContainerIds: ['hot', 'cold'], collections: [coll('hot', 10000, 900, 950000), coll('cold', 1000, 5, 50000)], }, SHARED_THRESHOLDS, diff --git a/src/panels/accountOverview/services/advisories/derivedAdvisories.test.ts b/src/panels/accountOverview/services/advisories/derivedAdvisories.test.ts index befd7f96b..ce60abb59 100644 --- a/src/panels/accountOverview/services/advisories/derivedAdvisories.test.ts +++ b/src/panels/accountOverview/services/advisories/derivedAdvisories.test.ts @@ -334,7 +334,7 @@ describe('evaluateAutoscaleCandidate', () => { it('includes the CODA-style recommended autoscale max when provisioned RU is known', () => { const advisory = evaluateAutoscaleCandidate(64, 8, dutyCycle, true, 4_000, 'db/orders', 'orders'); - expect(advisory?.suggestedAction).toContain((4_000).toLocaleString()); + expect(advisory?.suggestedAction).toContain('max ≈ 4000 RU/s'); }); }); @@ -355,7 +355,7 @@ describe('evaluateIndexingCostRisk', () => { expect(advisory?.rationale).toContain('50%'); }); - it('does not fire when user paths are excluded', () => { + it('retains high-ratio findings when user paths are already excluded', () => { expect( evaluateIndexingCostRisk( { @@ -367,7 +367,7 @@ describe('evaluateIndexingCostRisk', () => { }, 0.3, ), - ).toBeUndefined(); + ).toMatchObject({ severity: 'Low', evidence: { userExcludedPathCount: 2 } }); }); it('does not fire below the ratio, or with missing/zero data usage', () => { @@ -493,6 +493,112 @@ describe('evaluateStorageGrowthRisk', () => { expect(evaluateStorageGrowthRisk(container([storageSeries('0', [45, 45, 45, 45])]), 180)).toBeUndefined(); }); + it.each([ + { rate: 0.1, fires: true }, + { rate: 0.1 - 1e-10, fires: false }, + { rate: 0.1 + 1e-10, fires: true }, + ])('preserves the inclusive growth floor at $rate GiB/day', ({ rate, fires }) => { + const growthFinding = expect.objectContaining({ rule: 'StorageGrowthRisk', severity: 'High' }); + for (const origin of [0, Date.UTC(2026, 0, 1)]) { + for (const days of [Array.from({ length: 10 }, (_, index) => index), [0, 1.25, 3, 7, 9]]) { + const partition = { + partitionId: '0', + samples: days.map((day) => ({ + timestamp: origin + day * DAY, + bytes: (49.9 - (9 - day) * rate) * GIB, + })), + }; + const advisory = evaluateStorageGrowthRisk(container([partition]), 180); + expect(advisory).toEqual(fires ? growthFinding : undefined); + } + } + }); + + it.each([ + { current: 32, severity: 'Low', lowerSeverity: undefined }, + { current: 41, severity: 'Medium', lowerSeverity: 'Low' }, + { current: 47, severity: 'High', lowerSeverity: 'Medium' }, + ])('preserves inclusive horizon/severity boundaries at $current GiB', ({ current, severity, lowerSeverity }) => { + for (const origin of [0, Date.UTC(2026, 0, 1)]) { + for (const offset of [-1e-6, 0, 1e-6]) { + const partition = { + partitionId: '0', + samples: Array.from({ length: 24 }, (_, i) => ({ + timestamp: origin + i * (DAY / 24), + bytes: (current + offset - ((23 - i) / 24) * 0.1) * GIB, + })), + }; + expect(evaluateStorageGrowthRisk(container([partition]), 180)?.severity).toBe( + offset < 0 ? lowerSeverity : severity, + ); + } + } + }); + + it('uses the same inclusive comparison for a custom horizon', () => { + const samples = Array.from({ length: 24 }, (_, i) => ({ + timestamp: Date.UTC(2026, 0, 1) + i * (DAY / 24), + bytes: (45.5 - ((23 - i) / 24) * 0.1) * GIB, + })); + const input = container([{ partitionId: '0', samples }]); + expect(evaluateStorageGrowthRisk(input, 45)?.severity).toBe('Medium'); + expect(evaluateStorageGrowthRisk(input, 45 - 1e-6)).toBeUndefined(); + }); + + it.each([ + { samples: [] }, + { samples: [{ timestamp: 0, bytes: 40 * GIB }] }, + { + samples: [ + { timestamp: 0, bytes: 40 * GIB }, + { timestamp: 0, bytes: 41 * GIB }, + ], + }, + { + samples: [ + { timestamp: NaN, bytes: 40 * GIB }, + { timestamp: DAY, bytes: NaN }, + ], + }, + ])('reports missing material history instead of a stable trend: %j', ({ samples }) => { + const detector = new StorageGrowthRiskDetector(); + const result = detector.evaluateResult(container([{ partitionId: '0', samples }]), 180); + expect(result).toEqual({ rootCause: 'insufficient_data' }); + }); + + it('does not call the whole container stable while a material partition has no trend', () => { + const result = new StorageGrowthRiskDetector().evaluateResult( + container([ + storageSeries('known', [40, 40]), + { partitionId: 'unknown', samples: [{ timestamp: 0, bytes: 45 * GIB }] }, + ]), + 180, + ); + expect(result).toEqual({ rootCause: 'insufficient_data' }); + }); + + it('retains stable and too-small results when their required evidence is available', () => { + const detector = new StorageGrowthRiskDetector(); + expect(detector.evaluateResult(container([storageSeries('flat', [40, 40])]), 180).rootCause).toBe('stable'); + expect(detector.evaluateResult(container([storageSeries('shrinking', [41, 40])]), 180).rootCause).toBe( + 'stable', + ); + expect(detector.evaluateResult(container([storageSeries('tiny', [0.5])]), 180).rootCause).toBe('too_small'); + }); + + it('preserves real findings even if another partition has insufficient history', () => { + const detector = new StorageGrowthRiskDetector(); + const unknown = { partitionId: 'unknown', samples: [{ timestamp: 0, bytes: 40 * GIB }] }; + expect(detector.evaluateResult(container([unknown, storageSeries('full', [50])]), 180)).toMatchObject({ + rootCause: 'at_or_over_limit', + advisory: { severity: 'High' }, + }); + expect(detector.evaluateResult(container([unknown, storageSeries('growing', [48, 49])]), 180)).toMatchObject({ + rootCause: 'rapid_growth', + advisory: { severity: 'High' }, + }); + }); + it('reports the soonest-to-fill partition across the container', () => { const advisory = evaluateStorageGrowthRisk( container([storageSeries('slow', [10, 11, 12, 13]), storageSeries('fast', [43, 45, 47, 49])]), @@ -675,8 +781,10 @@ describe('evaluateExpensiveConsistency', () => { expect(advisory?.severity).toBe('Low'); }); - it('does not fire on a single region (no cross-region cost)', () => { - expect(evaluateExpensiveConsistency(config({ consistencyLevel: 'Strong', regionCount: 1 }))).toBeUndefined(); + it('fires Medium for Strong local quorum reads in a known single region', () => { + expect(evaluateExpensiveConsistency(config({ consistencyLevel: 'Strong', regionCount: 1 }))).toMatchObject({ + severity: 'Medium', + }); }); it('does not fire on the Session default', () => { @@ -1063,6 +1171,7 @@ describe('computeDerivedAdvisories Tier-2 wiring', () => { { databaseId: 'db', containerId: 'orders', + evaluationWindowSeconds: 1000, shapes: [ { text: 'SELECT * FROM c WHERE c.email=@e', executions: 850, avgFanout: 2, maxFanout: 2 }, { text: 'SELECT * FROM c WHERE c.pk=@p', executions: 150, avgFanout: 1, maxFanout: 1 }, @@ -1087,6 +1196,7 @@ describe('computeDerivedAdvisories Tier-2 wiring', () => { { databaseId: 'db', containerId: 'orders', + evaluationWindowSeconds: 1000, shapes: [ { text: 'SELECT * FROM c WHERE c.email=@e', executions: 150, avgFanout: 2, maxFanout: 2 }, { text: 'SELECT * FROM c WHERE c.pk=@p', executions: 850, avgFanout: 1, maxFanout: 1 }, @@ -1097,7 +1207,7 @@ describe('computeDerivedAdvisories Tier-2 wiring', () => { DEFAULT_ADVISORY_THRESHOLDS, ).filter((a) => a.scope === 'db/orders'); expect(rules).toHaveLength(1); - expect(rules[0]).toMatchObject({ rule: 'CrossPartitionQuery', severity: 'Medium' }); + expect(rules[0]).toMatchObject({ rule: 'CrossPartitionQuery', severity: 'Low' }); }); it('marks manual right-sizing as superseded when the same container is idle or better suited for autoscale', () => { diff --git a/src/panels/accountOverview/services/advisories/detectors/AutoscaleCandidateDetector.ts b/src/panels/accountOverview/services/advisories/detectors/AutoscaleCandidateDetector.ts index cfcda9750..8fcec9237 100644 --- a/src/panels/accountOverview/services/advisories/detectors/AutoscaleCandidateDetector.ts +++ b/src/panels/accountOverview/services/advisories/detectors/AutoscaleCandidateDetector.ts @@ -5,11 +5,15 @@ import * as l10n from '@vscode/l10n'; import { escapeAdvisoryText } from '../../../advisoryText'; -import { containerKey } from '../../shared'; import { Detector, type DetectorContext } from '../core/Detector'; -import { clampRationale, finiteNumbers, hasMinimumKnownResourceAge, mean } from '../core/helpers'; +import { clampRationale, finiteNumbers, hasMinimumKnownResourceAge, mean, offerScope } from '../core/helpers'; import { DIAGNOSTIC_POLICY } from '../core/thresholds'; -import { type AutoscaleThresholds, type DerivedAdvisory, type ManualThroughputInput } from '../core/types'; +import { + type AdvisoryEvaluation, + type AutoscaleThresholds, + type DerivedAdvisory, + type ManualThroughputInput, +} from '../core/types'; const AUTOSCALE_MIN_MAX_RU = 1_000; const AUTOSCALE_STEP_RU = 1_000; @@ -79,9 +83,9 @@ function evaluateAutoscaleCandidate( ), suggestedAction: containerId && recommendedMax !== undefined - ? l10n.t('Enable autoscale on "{container}" and start with a maximum near `{recommended} RU/s`.', { + ? l10n.t('Convert to autoscale on "{container}" and start with `max ≈ {recommended} RU/s`.', { container: escapeAdvisoryText(containerId), - recommended: recommendedMax.toLocaleString(), + recommended: recommendedMax, }) + ' ' + l10n.t('This ceiling still covers the observed peak with headroom.') @@ -93,6 +97,7 @@ function evaluateAutoscaleCandidate( avg: thresholds.avgPercent, ratio: thresholds.peakToAvgRatio, }), + evidence: { recommendedMaxRu: recommendedMax ?? null }, scope, }; } @@ -100,30 +105,32 @@ function evaluateAutoscaleCandidate( function evaluateManualThroughput( input: ManualThroughputInput, thresholds: AutoscaleThresholds, -): DerivedAdvisory | undefined { +): AdvisoryEvaluation<'AutoscaleCandidate'> { const samples = finiteNumbers(input.ruPercents); if ( samples.length < DIAGNOSTIC_POLICY.overProvisioning.minSamples || !hasMinimumKnownResourceAge(input.resourceAgeDays, DIAGNOSTIC_POLICY.overProvisioning.minResourceAgeDays) ) { - return undefined; + return { rootCause: 'insufficient_data' }; } - return evaluateAutoscaleCandidate( + const advisory = evaluateAutoscaleCandidate( input.peakPercent ?? (samples.length > 0 ? Math.max(...samples) : undefined), mean(samples), thresholds, true, input.provisionedRu, - containerKey(input.databaseId, input.containerId), - input.containerId, + offerScope(input), + input.containerId ?? input.databaseId, l10n.t('30 days'), ); + return { rootCause: advisory ? 'spiky_manual' : 'well_matched', advisory }; } export class AutoscaleCandidateDetector extends Detector { readonly rule = 'AutoscaleCandidate' as const; readonly supersedes = ['OverProvisioning'] as const; evaluate = evaluateAutoscaleCandidate; + evaluateResult = evaluateManualThroughput; run(ctx: DetectorContext): DerivedAdvisory[] { const { inputs, thresholds } = ctx; const dutyCycle = { @@ -133,7 +140,7 @@ export class AutoscaleCandidateDetector extends Detector { }; if (inputs.manualThroughput !== undefined) { return inputs.manualThroughput - .map((input) => evaluateManualThroughput(input, dutyCycle)) + .map((input) => this.evaluateResult(input, dutyCycle).advisory) .filter((advisory): advisory is DerivedAdvisory => advisory !== undefined); } const advisory = this.evaluate( diff --git a/src/panels/accountOverview/services/advisories/detectors/AutoscaleMaxOverProvisionedDetector.ts b/src/panels/accountOverview/services/advisories/detectors/AutoscaleMaxOverProvisionedDetector.ts index c41ae7240..5cb2e4f36 100644 --- a/src/panels/accountOverview/services/advisories/detectors/AutoscaleMaxOverProvisionedDetector.ts +++ b/src/panels/accountOverview/services/advisories/detectors/AutoscaleMaxOverProvisionedDetector.ts @@ -5,16 +5,21 @@ import * as l10n from '@vscode/l10n'; import { escapeAdvisoryText } from '../../../advisoryText'; -import { containerKey } from '../../shared'; import { Detector, type DetectorContext } from '../core/Detector'; -import { capacityMaterialitySeverity, clampRationale, hasMinimumKnownResourceAge } from '../core/helpers'; +import { + capacityMaterialitySeverity, + clampRationale, + hasMinimumKnownResourceAge, + offerScope, + utilizationBand, +} from '../core/helpers'; import { DIAGNOSTIC_POLICY } from '../core/thresholds'; -import { type AutoscaleUtilizationInput, type DerivedAdvisory } from '../core/types'; +import { type AutoscaleUtilizationInput, type DerivedAdvisory, type ProvisioningEvaluation } from '../core/types'; -// Platform minimum RU/s floor a right-size recommendation never drops below — a container's minimum manual -// throughput is 400 RU/s: +// Analytical minimum autoscale maximum, distinct from the 400 RU/s manual minimum. +// Resource-specific minima and service increments still require validation: // https://learn.microsoft.com/azure/cosmos-db/set-throughput -const OVERPROVISIONING_MIN_RU = 400; +const AUTOSCALE_MIN_MAX_RU = 1_000; // DX-004/011: autoscale bills between 10% and 100% of the configured max (`0.1*Tmax ≤ T ≤ Tmax`), so an idle // or over-sized autoscale container only recovers its idle floor, never the full max: @@ -34,47 +39,50 @@ function evaluateAutoscaleMaxOverProvisioned( input: AutoscaleUtilizationInput, bandPercent: number, scopeProvisionedRu?: number, -): DerivedAdvisory | undefined { +): ProvisioningEvaluation { if ( + !Number.isFinite(input.sampleCount) || input.sampleCount < DIAGNOSTIC_POLICY.autoscaleUtilization.minSamples || input.configuredMaxRu === undefined || + !Number.isFinite(input.configuredMaxRu) || input.configuredMaxRu <= 0 || + !Number.isFinite(input.peakPercent) || + input.peakPercent < 0 || !hasMinimumKnownResourceAge(input.resourceAgeDays, DIAGNOSTIC_POLICY.autoscaleUtilization.minResourceAgeDays) ) { - return undefined; + return { band: 'insufficient_data' }; } const peak = input.peakPercent; // Peak at/above the saturation guard, or at/above the moderate band, means the max is genuinely needed. if (peak >= DIAGNOSTIC_POLICY.overProvisioning.peakGuardPercent || peak >= bandPercent) { - return undefined; + return { band: 'ok', recommendedRu: input.configuredMaxRu, recoverableRu: 0 }; } const max = input.configuredMaxRu; const peakConsumed = (peak / 100) * max; const recommended = Math.min( max, Math.max( - OVERPROVISIONING_MIN_RU, + AUTOSCALE_MIN_MAX_RU, Math.ceil(peakConsumed * DIAGNOSTIC_POLICY.overProvisioning.headroomMultiplier), Math.ceil(peakConsumed), ), ); - const floor = (ru: number): number => Math.max(OVERPROVISIONING_MIN_RU, AUTOSCALE_IDLE_FRACTION * ru); - const wastedExact = Math.max(0, floor(max) - floor(recommended)); + const wastedExact = Math.max(0, AUTOSCALE_IDLE_FRACTION * max - AUTOSCALE_IDLE_FRACTION * recommended); const wastedRu = Math.round(wastedExact); const severity = capacityMaterialitySeverity(wastedExact, scopeProvisionedRu); - const scope = containerKey(input.databaseId, input.containerId); + const scope = offerScope(input); const peakPct = Math.round(peak); const recommend = Math.round(recommended); - return { + const advisory: DerivedAdvisory = { id: `AutoscaleMaxOverProvisioned:${scope}`, rule: 'AutoscaleMaxOverProvisioned', severity, title: l10n.t('Autoscale max may be set too high'), rationale: clampRationale( l10n.t( - 'Autoscale on "{container}" never provisioned more than `{peak}%` of its `{max} RU/s` max over the window, below the `{band}%` band.', + 'Autoscale offer "{container}" never provisioned more than `{peak}%` of its `{max} RU/s` max over the window, below the `{band}%` band.', { - container: escapeAdvisoryText(input.containerId), + container: escapeAdvisoryText(input.containerId ?? input.databaseId), peak: peakPct, max: Math.round(max), band: Math.round(bandPercent), @@ -86,23 +94,52 @@ function evaluateAutoscaleMaxOverProvisioned( { wasted: wastedRu }, ), ), + evidence: { + configuredMaxRu: max, + recommendedMaxRu: recommended, + recoverableIdleFloorRu: wastedExact, + peakPercent: peak, + }, + actionEligibility: wastedExact > 0 ? 'requiresValidation' : 'blocked', suggestedAction: - l10n.t('Lower the autoscale max on "{container}" toward `~{recommended} RU/s`.', { - container: escapeAdvisoryText(input.containerId), - recommended: recommend, - }) + - ' ' + - l10n.t('The idle floor will track real demand while the ceiling still covers the observed peak.'), + wastedExact > 0 + ? l10n.t( + 'Review lowering the autoscale max on "{container}" toward the analytical target `~{recommended} RU/s`.', + { + container: escapeAdvisoryText(input.containerId ?? input.databaseId), + recommended: recommend, + }, + ) + + ' ' + + l10n.t( + 'Validate service increments, resource-specific minimum throughput, storage and future demand before changing the maximum.', + ) + : l10n.t( + 'No maximum reduction is available under this model. Review workload placement; do not lower below the service minimum.', + ), thresholdReference: l10n.t('Threshold: peak AutoscaledRU < `{band}%` of the configured max', { band: Math.round(bandPercent), }), scope, }; + return { + band: utilizationBand(peak, bandPercent), + recommendedRu: recommended, + recoverableRu: wastedExact, + advisory, + }; } export class AutoscaleMaxOverProvisionedDetector extends Detector { readonly rule = 'AutoscaleMaxOverProvisioned' as const; - evaluate = evaluateAutoscaleMaxOverProvisioned; + evaluateResult = evaluateAutoscaleMaxOverProvisioned; + evaluate = ( + input: AutoscaleUtilizationInput, + bandPercent: number, + scopeProvisionedRu?: number, + ): DerivedAdvisory | undefined => { + return this.evaluateResult(input, bandPercent, scopeProvisionedRu).advisory; + }; run(ctx: DetectorContext): DerivedAdvisory[] { const out: DerivedAdvisory[] = []; for (const util of ctx.inputs.autoscaleUtilizations ?? []) { diff --git a/src/panels/accountOverview/services/advisories/detectors/AutoscaleToManualCandidateDetector.ts b/src/panels/accountOverview/services/advisories/detectors/AutoscaleToManualCandidateDetector.ts index bc7d3657b..24c7c3f48 100644 --- a/src/panels/accountOverview/services/advisories/detectors/AutoscaleToManualCandidateDetector.ts +++ b/src/panels/accountOverview/services/advisories/detectors/AutoscaleToManualCandidateDetector.ts @@ -5,11 +5,10 @@ import * as l10n from '@vscode/l10n'; import { escapeAdvisoryText } from '../../../advisoryText'; -import { containerKey } from '../../shared'; import { Detector, type DetectorContext } from '../core/Detector'; -import { clampRationale, hasMinimumKnownResourceAge } from '../core/helpers'; +import { clampRationale, hasMinimumKnownResourceAge, offerScope } from '../core/helpers'; import { DIAGNOSTIC_POLICY } from '../core/thresholds'; -import { type AutoscaleUtilizationInput, type DerivedAdvisory } from '../core/types'; +import { type AdvisoryEvaluation, type AutoscaleUtilizationInput, type DerivedAdvisory } from '../core/types'; /** * AutoscaleToManualCandidate (CODA DX-013): an *autoscale* container whose load is **steady-high** — average @@ -22,31 +21,31 @@ function evaluateAutoscaleToManualCandidate( input: AutoscaleUtilizationInput, avgFloorPercent: number, peakToAvgCeiling: number, -): DerivedAdvisory | undefined { +): AdvisoryEvaluation<'AutoscaleToManualCandidate'> { if ( input.sampleCount < DIAGNOSTIC_POLICY.autoscaleUtilization.minSamples || input.avgPercent <= 0 || !hasMinimumKnownResourceAge(input.resourceAgeDays, DIAGNOSTIC_POLICY.autoscaleUtilization.minResourceAgeDays) ) { - return undefined; + return { rootCause: 'insufficient_data' }; } const peakToAvg = input.peakPercent / input.avgPercent; if (input.avgPercent < avgFloorPercent || peakToAvg > peakToAvgCeiling) { - return undefined; + return { rootCause: 'well_matched' }; } - const scope = containerKey(input.databaseId, input.containerId); + const scope = offerScope(input); const avg = Math.round(input.avgPercent); const peak = Math.round(input.peakPercent); const ratio = Math.round(peakToAvg * 10) / 10; - return { + const advisory: DerivedAdvisory = { id: `AutoscaleToManualCandidate:${scope}`, rule: 'AutoscaleToManualCandidate', severity: 'Medium', - title: l10n.t('Autoscale container looks steady: manual may be cheaper'), + title: l10n.t('Autoscale offer looks steady: manual may be cheaper'), rationale: clampRationale( l10n.t( 'Autoscale on "{container}" averaged `{avg}%` of its max with a peak of `{peak}%`, a `{ratio}×` peak-to-average.', - { container: escapeAdvisoryText(input.containerId), avg, peak, ratio }, + { container: escapeAdvisoryText(input.containerId ?? input.databaseId), avg, peak, ratio }, ) + ' ' + l10n.t('The load is steady and high with little spikiness.') + @@ -57,7 +56,7 @@ function evaluateAutoscaleToManualCandidate( ), suggestedAction: l10n.t( 'Consider converting "{container}" to manual throughput at a fixed RU/s near the sustained level to drop the autoscale premium.', - { container: escapeAdvisoryText(input.containerId) }, + { container: escapeAdvisoryText(input.containerId ?? input.databaseId) }, ), thresholdReference: l10n.t('Threshold: average ≥ `{avg}%` of max and peak/average ≤ `{ratio}×`', { avg: Math.round(avgFloorPercent), @@ -65,11 +64,14 @@ function evaluateAutoscaleToManualCandidate( }), scope, }; + return { rootCause: 'steady_autoscale', advisory }; } export class AutoscaleToManualCandidateDetector extends Detector { readonly rule = 'AutoscaleToManualCandidate' as const; - evaluate = evaluateAutoscaleToManualCandidate; + evaluateResult = evaluateAutoscaleToManualCandidate; + evaluate = (...args: Parameters) => + evaluateAutoscaleToManualCandidate(...args).advisory; run(ctx: DetectorContext): DerivedAdvisory[] { const out: DerivedAdvisory[] = []; for (const util of ctx.inputs.autoscaleUtilizations ?? []) { diff --git a/src/panels/accountOverview/services/advisories/detectors/CrossPartitionQueryDetector.ts b/src/panels/accountOverview/services/advisories/detectors/CrossPartitionQueryDetector.ts index 061f27489..df7976de2 100644 --- a/src/panels/accountOverview/services/advisories/detectors/CrossPartitionQueryDetector.ts +++ b/src/panels/accountOverview/services/advisories/detectors/CrossPartitionQueryDetector.ts @@ -8,34 +8,14 @@ import { escapeAdvisoryText } from '../../../advisoryText'; import { containerKey } from '../../shared'; import { Detector, type DetectorContext } from '../core/Detector'; import { clampRationale } from '../core/helpers'; +import { DIAGNOSTIC_POLICY } from '../core/thresholds'; import { + type AdvisoryEvaluation, type CrossPartitionInput, type CrossPartitionThresholds, type DerivedAdvisory, - type DerivedAdvisorySeverity, - type QueryShapeInput, } from '../core/types'; - -/** Folds the per-shape fan-out into total executions, cross-partition share, and the worst (most frequent) shape. Pure. */ -interface CrossPartitionStats { - totalQueries: number; - containerPartitions: number; - crossPartitionPct: number; - worst: QueryShapeInput | undefined; -} - -function crossPartitionStats(shapes: readonly QueryShapeInput[], fanoutThreshold: number): CrossPartitionStats { - const totalQueries = shapes.reduce((sum, s) => sum + s.executions, 0); - const containerPartitions = shapes.reduce((max, s) => Math.max(max, s.maxFanout), 0); - const crossShapes = shapes.filter((s) => s.avgFanout >= fanoutThreshold); - const crossExec = crossShapes.reduce((sum, s) => sum + s.executions, 0); - const crossPartitionPct = totalQueries > 0 ? (100 * crossExec) / totalQueries : 0; - const worst = crossShapes.reduce( - (best, s) => (best === undefined || s.executions > best.executions ? s : best), - undefined, - ); - return { totalQueries, containerPartitions, crossPartitionPct, worst }; -} +import { fanoutRuDescription, fanoutRuEvidence, fanoutSeverity, fanoutStats } from './fanout'; /** Collapses whitespace and truncates an anonymized query shape for display. Pure. */ function shortQueryShape(text: string): string { @@ -47,28 +27,36 @@ function shortQueryShape(text: string): string { * CrossPartitionQuery (CODA DX-002): query shapes that do not filter on the container's partition key fan out * across every physical partition, multiplying RU and latency. Fires when the container has ≥ 2 physical * partitions, there is enough query traffic (`minQueries`), and the share of executions whose shape fans out - * (average ≥ `fanoutThreshold` partitions) is at or above `medPct` — High at/above `highPct`, else Medium. The + * (average ≥ `fanoutThreshold` partitions) is at or above `medPct`, with at least 0.1 fan-out queries/s. + * Severity uses physical-partition count and the unrounded fan-out rate. The * surfaced text is the service-anonymized shape, so remediation is structural (add the partition key to the * filter). Container-scoped. Pure. */ function evaluateCrossPartitionQuery( input: CrossPartitionInput, thresholds: CrossPartitionThresholds, -): DerivedAdvisory | undefined { - const { totalQueries, containerPartitions, crossPartitionPct, worst } = crossPartitionStats( - input.shapes, - thresholds.fanoutThreshold, - ); - if (totalQueries < thresholds.minQueries || containerPartitions <= 1) { - return undefined; +): AdvisoryEvaluation<'CrossPartitionQuery'> { + const stats = fanoutStats(input, thresholds.fanoutThreshold); + if (!stats) { + return { rootCause: 'insufficient_data' }; + } + const { totalQueries, containerPartitions, crossPartitionPct, crossQueriesPerSecond, worst } = stats; + if (totalQueries < thresholds.minQueries) { + return { rootCause: 'insufficient_data' }; + } + if (containerPartitions <= 1) { + return { rootCause: 'single_partition_container' }; } if (crossPartitionPct < thresholds.medPct || worst === undefined) { - return undefined; + return { rootCause: 'mostly_single_partition' }; } - const severity: DerivedAdvisorySeverity = crossPartitionPct >= thresholds.highPct ? 'High' : 'Medium'; + if (crossQueriesPerSecond < DIAGNOSTIC_POLICY.crossPartition.minQueriesPerSecond) { + return { rootCause: 'occasional_fanout' }; + } + const severity = fanoutSeverity(containerPartitions, crossQueriesPerSecond); const pct = Math.round(crossPartitionPct); const shape = shortQueryShape(worst.text); - return { + const advisory: DerivedAdvisory = { id: `CrossPartitionQuery/${containerKey(input.databaseId, input.containerId)}`, rule: 'CrossPartitionQuery', severity, @@ -87,24 +75,38 @@ function evaluateCrossPartitionQuery( ), suggestedAction: l10n.t( - "Add the container's partition key to the query filter (or a composite index) so it targets a single logical partition.", + "Include the container's partition key in the query filter where the access pattern permits. A composite index alone does not eliminate fan-out.", ) + ' ' + l10n.t( 'For access patterns that inherently filter on a different key, serve them from a global secondary index or a change-feed-synced copy.', ) + ' ' + - l10n.t('Cross-partition fan-out multiplies RU and latency and does not scale as the container grows.'), - thresholdReference: l10n.t('Threshold: ≥ `{pct}%` of executions fan out (avg ≥ `{fanout} partitions/query`)', { - pct: thresholds.medPct, - fanout: thresholds.fanoutThreshold, - }), + l10n.t('Cross-partition fan-out multiplies RU and latency and does not scale as the container grows.') + + fanoutRuDescription(worst), + evidence: { + totalQueries, + containerPartitions, + crossPartitionPct, + crossQueriesPerSecond, + ...fanoutRuEvidence(input, worst), + }, + thresholdReference: l10n.t( + 'Threshold: ≥ `{pct}%` fan-out share, avg ≥ `{fanout} partitions/query`, and ≥ `0.1 fan-out queries/s`', + { + pct: thresholds.medPct, + fanout: thresholds.fanoutThreshold, + }, + ), }; + return { rootCause: 'cross_partition', advisory }; } export class CrossPartitionQueryDetector extends Detector { readonly rule = 'CrossPartitionQuery' as const; - evaluate = evaluateCrossPartitionQuery; + evaluateResult = evaluateCrossPartitionQuery; + evaluate = (...args: Parameters) => + evaluateCrossPartitionQuery(...args).advisory; run(ctx: DetectorContext): DerivedAdvisory[] { const t = ctx.thresholds; const out: DerivedAdvisory[] = []; @@ -112,7 +114,6 @@ export class CrossPartitionQueryDetector extends Detector { const a = this.evaluate(input, { minQueries: t.crossPartitionMinQueries, fanoutThreshold: t.crossPartitionFanoutThreshold, - highPct: t.crossPartitionHighPct, medPct: t.crossPartitionMedPct, }); if (a) { diff --git a/src/panels/accountOverview/services/advisories/detectors/ExpensiveConsistencyDetector.ts b/src/panels/accountOverview/services/advisories/detectors/ExpensiveConsistencyDetector.ts index 947bc6b5f..b9be459f2 100644 --- a/src/panels/accountOverview/services/advisories/detectors/ExpensiveConsistencyDetector.ts +++ b/src/panels/accountOverview/services/advisories/detectors/ExpensiveConsistencyDetector.ts @@ -7,13 +7,18 @@ import * as l10n from '@vscode/l10n'; import { Detector, type DetectorContext } from '../core/Detector'; import { clampRationale } from '../core/helpers'; import { DIAGNOSTIC_POLICY } from '../core/thresholds'; -import { type AccountConfigInput, type DerivedAdvisory } from '../core/types'; +import { + type AccountConfigInput, + type AdvisoryEvaluation, + type ConsistencyReadRuInput, + type DerivedAdvisory, +} from '../core/types'; -// ─── Account-scoped configuration advisories (ARM config only) ───────────────────── +// ─── Account-scoped configuration advisories ────────────────────────────────────── // -// DX-016 and DX-008 read only the account's ARM configuration — no workload, no metrics — and surface -// qualitative antipatterns (they explain the consequence and ask the customer to confirm intent; they assert -// no RU/s or dollar figure). Both are account-scoped, so at most one of each fires per account. +// DX-016 and DX-008 trigger from ARM configuration. DX-016 can include optional observed read charge. +// DX-008 can also report configured regional capacity from a complete manual-offer inventory, +// never a savings estimate. Both are account-scoped, so at most one of each fires per account. /** Consistency levels stronger than the Session default, normalised to lowercase (no separators). */ const PREMIUM_CONSISTENCY_LEVELS: ReadonlySet = new Set(['strong', 'boundedstaleness']); @@ -25,54 +30,122 @@ function normalizeConsistency(level: string | undefined): string { /** * ExpensiveConsistency (CODA DX-016): the account runs a premium consistency level (Strong or Bounded Staleness) - * across two or more regions. Across multiple regions these levels make writes wait on additional regions, raising - * write latency and tightening availability; the default Session consistency suits most workloads. On a single - * region the cross-region cost does not apply, so it never fires there. Strong is Medium, Bounded Staleness is Low. + * Strong also applies to a known single region because of local quorum read cost. + * Multi-region guidance separately considers cross-region write latency. Strong is Medium, Bounded Staleness is Low. * Pure. */ -function evaluateExpensiveConsistency(config: AccountConfigInput): DerivedAdvisory | undefined { +function evaluateExpensiveConsistency( + config: AccountConfigInput, + readCharge?: ConsistencyReadRuInput, +): AdvisoryEvaluation<'ExpensiveConsistency'> { const level = normalizeConsistency(config.consistencyLevel); + if (!level) { + return { rootCause: 'unknown' }; + } + if (!PREMIUM_CONSISTENCY_LEVELS.has(level)) { + return { rootCause: 'default_or_relaxed' }; + } + if (!Number.isInteger(config.regionCount) || config.regionCount < 1) { + return { rootCause: 'unknown' }; + } if ( - !PREMIUM_CONSISTENCY_LEVELS.has(level) || - config.regionCount < DIAGNOSTIC_POLICY.expensiveConsistency.minRegions + config.regionCount < + (level === 'strong' + ? DIAGNOSTIC_POLICY.expensiveConsistency.minStrongRegions + : DIAGNOSTIC_POLICY.expensiveConsistency.minBoundedStalenessRegions) ) { - return undefined; + return { rootCause: 'single_region' }; } const isStrong = level === 'strong'; const displayLevel = config.consistencyLevel ?? (isStrong ? 'Strong' : 'Bounded Staleness'); - return { + const observed = + readCharge?.status === 'observed' && + Number.isSafeInteger(readCharge.readRequests) && + readCharge.readRequests > 0 && + Number.isFinite(readCharge.readRu) && + readCharge.readRu >= 0 + ? readCharge + : undefined; + const advisory: DerivedAdvisory = { id: 'ExpensiveConsistency', rule: 'ExpensiveConsistency', severity: isStrong ? 'Medium' : 'Low', - title: l10n.t('Premium consistency across regions'), + title: l10n.t('Review stronger consistency requirements'), rationale: clampRationale( l10n.t('This account uses {level} consistency across `{regions} regions`.', { level: displayLevel, regions: config.regionCount, }) + ' ' + - l10n.t('Across multiple regions this level raises write latency and tightens availability.') + + l10n.t('Quorum reads can cost more RU than Session or Eventual consistency.') + ' ' + - l10n.t( - 'Strong makes writes wait on additional regions. The default Session consistency is sufficient for most workloads.', - ), + (config.regionCount > 1 + ? l10n.t( + 'Across multiple regions, review the additional write-latency and availability trade-offs.', + ) + : l10n.t('In one region this is a local read-cost review, not a cross-region latency finding.')), ), suggestedAction: l10n.t('Confirm the application genuinely needs this consistency level.') + ' ' + - l10n.t("If not, relax it to Session (or Bounded Staleness) after validating the application's tolerance."), - thresholdReference: l10n.t('Threshold: Strong or Bounded Staleness across ≥ `2 regions`'), + l10n.t( + 'Consider Session only after validating application correctness and request-level overrides; Session is not equivalent to global Strong consistency.', + ) + + ' ' + + l10n.t( + 'The account has one default consistency level. For load-balanced applications, pass the Cosmos response SessionToken through the web tier to the end-user client in a cookie or equivalent client context.', + ) + + ' ' + + l10n.t( + 'On a later web request, pass the token into the Cosmos request options of whichever SDK instance handles that request. There is no direct SDK-to-SDK synchronization; tokens remain opaque, partition-bound and are not equivalent to Strong consistency.', + ) + + (observed + ? ' ' + + l10n.t( + 'Request logs observed `{ru} read RU` across `{requests} requests`. Half (`{bound} RU`) is only a theoretical upper bound on avoidable read charge: logs do not reveal per-request consistency overrides. This is not measured or monetary savings.', + { + ru: observed.readRu.toFixed(2), + requests: observed.readRequests, + bound: (observed.readRu / 2).toFixed(2), + }, + ) + : ''), + evidence: { + consistencyLevel: level, + regionCount: config.regionCount, + readRuStatus: observed + ? 'observed' + : readCharge?.status === 'noObservations' + ? 'noObservations' + : 'unavailable', + ...(observed + ? { + sourceTable: observed.sourceTable, + sourceResolution: observed.sourceResolution, + observationStart: observed.observationStart, + observationEnd: observed.observationEnd, + observedReadRequests: observed.readRequests, + observedReadRu: observed.readRu, + upperBoundAvoidableReadRu: observed.readRu / 2, + } + : {}), + }, + actionEligibility: 'requiresValidation', + thresholdReference: l10n.t('Threshold: Strong in ≥ `1 region`, or Bounded Staleness in ≥ `2 regions`'), }; + return { rootCause: config.regionCount === 1 ? 'strong_single_region' : 'premium_multi_region', advisory }; } export class ExpensiveConsistencyDetector extends Detector { readonly rule = 'ExpensiveConsistency' as const; - evaluate = evaluateExpensiveConsistency; + evaluateResult = evaluateExpensiveConsistency; + evaluate = (...args: Parameters) => + evaluateExpensiveConsistency(...args).advisory; run(ctx: DetectorContext): DerivedAdvisory[] { if (!ctx.inputs.accountConfig) { return []; } - const advisory = this.evaluate(ctx.inputs.accountConfig); + const advisory = this.evaluate(ctx.inputs.accountConfig, ctx.inputs.consistencyReadRu); return advisory ? [advisory] : []; } } diff --git a/src/panels/accountOverview/services/advisories/detectors/HotPartitionRiskDetector.ts b/src/panels/accountOverview/services/advisories/detectors/HotPartitionRiskDetector.ts index b2f22c650..6000e461b 100644 --- a/src/panels/accountOverview/services/advisories/detectors/HotPartitionRiskDetector.ts +++ b/src/panels/accountOverview/services/advisories/detectors/HotPartitionRiskDetector.ts @@ -5,11 +5,15 @@ import * as l10n from '@vscode/l10n'; import { escapeAdvisoryText } from '../../../advisoryText'; -import { containerKey } from '../../shared'; import { Detector, type DetectorContext } from '../core/Detector'; -import { clampRationale, hasMinimumKnownResourceAge } from '../core/helpers'; +import { clampRationale, hasMinimumKnownResourceAge, offerScope } from '../core/helpers'; import { DIAGNOSTIC_POLICY } from '../core/thresholds'; -import { type DerivedAdvisory, type DerivedAdvisorySeverity, type PartitionSaturationInput } from '../core/types'; +import { + type AdvisoryEvaluation, + type DerivedAdvisory, + type DerivedAdvisorySeverity, + type PartitionSaturationInput, +} from '../core/types'; /** * HotPartitionRisk (DX-006): the busiest physical partition is **saturated** (p99 at or above the saturation @@ -24,16 +28,26 @@ function evaluateHotPartitionRisk( saturationPercent: number, headroomPercent: number, throttleThresholdPercent: number, -): DerivedAdvisory | undefined { +): AdvisoryEvaluation<'HotPartitionRisk'> { if ( !hasMinimumKnownResourceAge(input.resourceAgeDays, DIAGNOSTIC_POLICY.partitionSaturation.minResourceAgeDays) || - input.partitionCount < DIAGNOSTIC_POLICY.partitionSaturation.minHotPartitions || - input.maxP99 < saturationPercent || - input.minP99 >= headroomPercent + input.partitionCount === 0 || + !Number.isFinite(input.maxP99) || + !Number.isFinite(input.minP99) ) { - return undefined; + return { rootCause: 'insufficient_data' }; } - const scope = containerKey(input.databaseId, input.containerId); + if (input.partitionCount < DIAGNOSTIC_POLICY.partitionSaturation.minHotPartitions) { + return { rootCause: 'single_partition' }; + } + if (input.maxP99 < saturationPercent) { + return { rootCause: 'not_saturated' }; + } + if (input.minP99 >= headroomPercent) { + return { rootCause: 'uniform_saturation' }; + } + const scope = offerScope(input); + const name = input.containerId ?? input.databaseId; const busiest = Math.round(input.maxP99); const coolest = Math.round(input.minP99); const saturation = Math.round(saturationPercent); @@ -47,16 +61,16 @@ function evaluateHotPartitionRisk( 'It is not throttling yet, but the pinned partition cannot borrow spare capacity from the other partitions as load grows.', ); - return { + const advisory: DerivedAdvisory = { id: `HotPartitionRisk:${scope}`, rule: 'HotPartitionRisk', severity, - title: l10n.t('Hot physical partition in {container}', { container: input.containerId }), + title: l10n.t('Hot physical partition in {container}', { container: name }), rationale: clampRationale( l10n.t( 'In "{container}", the busiest of `{count} physical partitions` ran at `{busiest}%` p99 utilization.', { - container: escapeAdvisoryText(input.containerId), + container: escapeAdvisoryText(name), count: input.partitionCount, busiest, }, @@ -72,26 +86,32 @@ function evaluateHotPartitionRisk( impact, ), suggestedAction: - l10n.t( - 'Redesign the partition key for higher cardinality so traffic spreads across partitions. Re-keying an existing container is migration-class.', - ) + - ' ' + - l10n.t( - 'Per-partition or per-region autoscale can soften the cost of feeding the hot partition while you redesign.', - ) + - ' ' + - l10n.t('It does not remove the throttling on a single hot key.'), + input.containerId === undefined + ? l10n.t( + 'Review the shared database offer and member workloads for partition skew. Identify the affected containers before changing a partition key or isolating throughput.', + ) + : l10n.t( + 'Redesign the partition key for higher cardinality so traffic spreads across partitions. Re-keying an existing container is migration-class.', + ) + + ' ' + + l10n.t( + 'Per-partition or per-region autoscale can soften the cost of feeding the hot partition while you redesign.', + ) + + ' ' + + l10n.t('It does not remove the throttling on a single hot key.'), thresholdReference: l10n.t('Threshold: busiest partition p99 ≥ `{saturation}%` while another < `{headroom}%`', { saturation, headroom, }), scope, }; + return { rootCause: 'hot_partition', advisory }; } export class HotPartitionRiskDetector extends Detector { readonly rule = 'HotPartitionRisk' as const; - evaluate = evaluateHotPartitionRisk; + evaluateResult = evaluateHotPartitionRisk; + evaluate = (...args: Parameters) => evaluateHotPartitionRisk(...args).advisory; run(ctx: DetectorContext): DerivedAdvisory[] { const t = ctx.thresholds; const out: DerivedAdvisory[] = []; diff --git a/src/panels/accountOverview/services/advisories/detectors/IdleContainerDetector.ts b/src/panels/accountOverview/services/advisories/detectors/IdleContainerDetector.ts index b002d154f..095985d40 100644 --- a/src/panels/accountOverview/services/advisories/detectors/IdleContainerDetector.ts +++ b/src/panels/accountOverview/services/advisories/detectors/IdleContainerDetector.ts @@ -6,11 +6,10 @@ import * as l10n from '@vscode/l10n'; import { escapeAdvisoryText } from '../../../advisoryText'; import { type ThroughputMode } from '../../inventory'; -import { containerKey } from '../../shared'; import { Detector, type DetectorContext } from '../core/Detector'; -import { capacityMaterialitySeverity, clampRationale, hasMinimumKnownResourceAge } from '../core/helpers'; +import { capacityMaterialitySeverity, clampRationale, hasMinimumKnownResourceAge, offerScope } from '../core/helpers'; import { DIAGNOSTIC_POLICY } from '../core/thresholds'; -import { type DerivedAdvisory, type IdleContainerInput } from '../core/types'; +import { type AdvisoryEvaluation, type DerivedAdvisory, type IdleContainerInput } from '../core/types'; // DX-004/011: autoscale bills between 10% and 100% of the configured max (`0.1*Tmax ≤ T ≤ Tmax`), so an idle // or over-sized autoscale container only recovers its idle floor, never the full max: @@ -25,8 +24,8 @@ const MANUAL_THROUGHPUT_MODES: ReadonlySet = new Set { const isAutoscale = input.throughputMode === 'autoscale'; const isManual = MANUAL_THROUGHPUT_MODES.has(input.throughputMode); // Only manual/autoscale containers have a provisioned offer to recover; serverless has none. if ( (!isAutoscale && !isManual) || input.provisionedRu === undefined || + !Number.isFinite(input.provisionedRu) || input.provisionedRu <= 0 || + input.peakRuPerBucket === undefined || + !Number.isFinite(input.peakRuPerBucket) || + input.peakRuPerBucket < 0 || !hasMinimumKnownResourceAge(input.resourceAgeDays, DIAGNOSTIC_POLICY.idle.minResourceAgeDays) ) { - return undefined; + return { rootCause: 'insufficient_data' }; } // Consumed real RU in some bucket ⇒ active, not idle — DX-001 right-sizes it instead. if (input.peakRuPerBucket > maxIdlePeakRu) { - return undefined; + return { rootCause: 'active' }; } const recoverableRu = isAutoscale ? AUTOSCALE_IDLE_FRACTION * input.provisionedRu : input.provisionedRu; const severity = capacityMaterialitySeverity(recoverableRu, scopeProvisionedRu); - const scope = containerKey(input.databaseId, input.containerId); + const scope = offerScope(input); const peak = Math.round(input.peakRuPerBucket); const recoverable = Math.round(recoverableRu); const provisioned = Math.round(input.provisionedRu); const rationale = isAutoscale - ? l10n.t('Container "{container}" consumed at most `{peak} RU` in any single bucket over the last `30 days`.', { - container: escapeAdvisoryText(input.containerId), + ? l10n.t('Offer "{container}" consumed at most `{peak} RU` in any single bucket over the last `30 days`.', { + container: escapeAdvisoryText(input.containerId ?? input.databaseId), peak, }) + ' ' + @@ -70,8 +73,8 @@ function evaluateIdleContainer( 'Decommissioning it recovers the autoscale idle floor (`~{recoverable} RU/s` of its `{provisioned} RU/s` max).', { recoverable, provisioned }, ) - : l10n.t('Container "{container}" consumed at most `{peak} RU` in any single bucket over the last `30 days`.', { - container: escapeAdvisoryText(input.containerId), + : l10n.t('Offer "{container}" consumed at most `{peak} RU` in any single bucket over the last `30 days`.', { + container: escapeAdvisoryText(input.containerId ?? input.databaseId), peak, }) + ' ' + @@ -80,30 +83,44 @@ function evaluateIdleContainer( }) + ' ' + l10n.t('Its full `{recoverable} RU/s` provisioned capacity is recoverable.', { recoverable }); - return { + const advisory: DerivedAdvisory = { id: `IdleContainer:${scope}`, rule: 'IdleContainer', severity, - title: l10n.t('Container looks idle'), + title: l10n.t('Provisioned offer looks idle'), + evidence: { provisionedRu: input.provisionedRu, recoverableRu, peakRuPerBucket: input.peakRuPerBucket }, rationale: clampRationale(rationale), - suggestedAction: l10n.t( - 'Review "{container}" for decommission, a TTL policy, or archival; confirm it is genuinely unused before removing it.', - { container: escapeAdvisoryText(input.containerId) }, - ), + suggestedAction: + input.containerId === undefined + ? l10n.t( + 'Review the shared database offer and all its member workloads before decommissioning or changing capacity. An idle member alone does not make the shared offer recoverable.', + ) + : l10n.t( + 'Review "{container}" for decommission, a TTL policy, or archival; confirm it is genuinely unused before removing it.', + { container: escapeAdvisoryText(input.containerId ?? input.databaseId) }, + ), thresholdReference: l10n.t('Threshold: peak ≤ `{threshold} RU` per bucket over `30 days`', { threshold: Math.round(maxIdlePeakRu), }), scope, }; + return { rootCause: 'idle', advisory, observations: { recoverableRu } }; } export class IdleContainerDetector extends Detector { readonly rule = 'IdleContainer' as const; readonly supersedes = ['OverProvisioning', 'AutoscaleMaxOverProvisioned'] as const; - evaluate = evaluateIdleContainer; + appliesTo(mode: ThroughputMode): boolean { + return mode === 'autoscale' || MANUAL_THROUGHPUT_MODES.has(mode); + } + evaluateResult = evaluateIdleContainer; + evaluate = (...args: Parameters) => evaluateIdleContainer(...args).advisory; run(ctx: DetectorContext): DerivedAdvisory[] { const out: DerivedAdvisory[] = []; for (const idle of ctx.inputs.idleContainers ?? []) { + if (!this.appliesTo(idle.throughputMode)) { + continue; + } const a = this.evaluate(idle, ctx.thresholds.idlePeakRuPerBucket, ctx.inputs.scopeProvisionedRuTotal); if (a) { out.push(a); diff --git a/src/panels/accountOverview/services/advisories/detectors/IndexingCostRiskDetector.ts b/src/panels/accountOverview/services/advisories/detectors/IndexingCostRiskDetector.ts index da54cf42a..05251b8ce 100644 --- a/src/panels/accountOverview/services/advisories/detectors/IndexingCostRiskDetector.ts +++ b/src/panels/accountOverview/services/advisories/detectors/IndexingCostRiskDetector.ts @@ -8,52 +8,64 @@ import { escapeAdvisoryText } from '../../../advisoryText'; import { containerKey } from '../../shared'; import { Detector, type DetectorContext } from '../core/Detector'; import { clampRationale } from '../core/helpers'; -import { type DerivedAdvisory, type IndexingUsageInput } from '../core/types'; +import { DIAGNOSTIC_POLICY } from '../core/thresholds'; +import { type AdvisoryEvaluation, type DerivedAdvisory, type IndexingUsageInput } from '../core/types'; /** - * IndexingCostRisk (best-effort): index storage is a large fraction of data - * storage AND the container has no user exclusions. Pure. + * IndexingCostRisk (DX-024): index storage is a large fraction of data storage. + * Exclusions are evidence, not a suppression gate or proof of unused indexes. Pure. */ -function evaluateIndexingCostRisk(input: IndexingUsageInput, ratioThreshold: number): DerivedAdvisory | undefined { +function evaluateIndexingCostRisk( + input: IndexingUsageInput, + ratioThreshold: number, +): AdvisoryEvaluation<'IndexingCostRisk'> { const { indexUsageBytes, dataUsageBytes, userExcludedPathCount } = input; + if (input.indexingMode?.toLowerCase() === 'none') { + return { rootCause: 'indexing_disabled' }; + } if ( - userExcludedPathCount > 0 || dataUsageBytes === undefined || + !Number.isFinite(dataUsageBytes) || dataUsageBytes <= 0 || indexUsageBytes === undefined || + !Number.isFinite(indexUsageBytes) || indexUsageBytes < 0 ) { - return undefined; + return { rootCause: 'insufficient_data' }; } const ratio = indexUsageBytes / dataUsageBytes; if (ratio <= ratioThreshold) { - return undefined; + return { rootCause: 'normal_ratio', observations: { indexDataRatio: ratio, userExcludedPathCount } }; } const scope = containerKey(input.databaseId, input.containerId); const percent = Math.round(ratio * 100); const threshold = Math.round(ratioThreshold * 100); - return { + const advisory: DerivedAdvisory = { id: `IndexingCostRisk:${scope}`, rule: 'IndexingCostRisk', - severity: 'Low', + severity: ratio > DIAGNOSTIC_POLICY.indexing.mediumRatio ? 'Medium' : 'Low', title: l10n.t('High indexing overhead in {container}', { container: input.containerId }), rationale: clampRationale( l10n.t( - 'Index storage in "{container}" is `{percent}%` of its data size, above the `{threshold}%` threshold, and the container has no user exclusions in its indexing policy. Indexing every property inflates storage and the RU cost of every write.', + 'Index storage in "{container}" is `{percent}%` of its data size, above the `{threshold}%` threshold. This is a storage-footprint warning, not proof of unused indexes or measured write-RU savings.', { container: escapeAdvisoryText(input.containerId), percent, threshold }, ), ), suggestedAction: l10n.t( - 'Exclude paths that are never used in filters from the indexing policy to cut write RU charges and index storage.', + 'Review actual filter and sort requirements before changing indexes. Composite, spatial and vector indexes can legitimately be large; do not exclude paths solely because this ratio is high.', ), + evidence: { indexUsageBytes, dataUsageBytes, indexDataRatio: ratio, userExcludedPathCount }, + actionEligibility: 'requiresValidation', thresholdReference: l10n.t('Threshold: index/data storage > `{threshold}%`', { threshold }), scope, }; + return { rootCause: 'high_index_ratio', advisory, observations: { indexDataRatio: ratio, userExcludedPathCount } }; } export class IndexingCostRiskDetector extends Detector { readonly rule = 'IndexingCostRisk' as const; - evaluate = evaluateIndexingCostRisk; + evaluateResult = evaluateIndexingCostRisk; + evaluate = (...args: Parameters) => evaluateIndexingCostRisk(...args).advisory; run(ctx: DetectorContext): DerivedAdvisory[] { const out: DerivedAdvisory[] = []; for (const indexing of ctx.inputs.indexing) { diff --git a/src/panels/accountOverview/services/advisories/detectors/MultiRegionWriteAntipatternDetector.ts b/src/panels/accountOverview/services/advisories/detectors/MultiRegionWriteAntipatternDetector.ts index ce0fc2eca..0134a552e 100644 --- a/src/panels/accountOverview/services/advisories/detectors/MultiRegionWriteAntipatternDetector.ts +++ b/src/panels/accountOverview/services/advisories/detectors/MultiRegionWriteAntipatternDetector.ts @@ -9,10 +9,18 @@ import { classifyEnvironment } from '../../environmentClassifier'; import { Detector, type DetectorContext } from '../core/Detector'; import { clampRationale } from '../core/helpers'; import { DIAGNOSTIC_POLICY } from '../core/thresholds'; -import { type AccountConfigInput, type DerivedAdvisory } from '../core/types'; +import { type AccountConfigInput, type AdvisoryEvaluation, type DerivedAdvisory } from '../core/types'; /** Cosmos DB APIs whose drivers cannot use multi-region-write failover, so the flag is always a misconfiguration. */ -const NON_MULTI_WRITE_APIS: ReadonlySet = new Set([API.Cassandra, API.Graph, API.Table]); +const NON_MULTI_WRITE_APIS = new Map< + NonNullable, + 'cassandra' | 'gremlin' | 'table' | 'mongo' +>([ + [API.Cassandra, 'cassandra'], + [API.Graph, 'gremlin'], + [API.Table, 'table'], + ['MongoDB', 'mongo'], +]); /** * MultiRegionWriteAntipattern (CODA DX-008): multi-region writes are enabled where the RTO=0 write-failover @@ -22,37 +30,43 @@ const NON_MULTI_WRITE_APIS: ReadonlySet = new Set([API.Cassandra, API.Graph * need RTO=0 write failover. Two-or-more write regions in production is legitimate active-active HA and never * fires. Pure. */ -function evaluateMultiRegionWrites(config: AccountConfigInput): DerivedAdvisory | undefined { +function evaluateMultiRegionWrites(config: AccountConfigInput): AdvisoryEvaluation<'MultiRegionWriteAntipattern'> { if (!config.multiRegionWritesEnabled) { - return undefined; + return { rootCause: 'not_multi_region_writes' }; } const base = { id: 'MultiRegionWriteAntipattern', rule: 'MultiRegionWriteAntipattern' as const }; - const disableAction = l10n.t('Disable multi-region writes unless the write-failover benefit genuinely applies.'); + const disableAction = l10n.t( + 'Review multi-region-write compatibility and availability requirements before changing the flag. Disabling multi-write while keeping all regions does not remove their provisioned capacity.', + ); // Wrong-API: the failover benefit is impossible regardless of environment — highest confidence. - if (config.api !== undefined && NON_MULTI_WRITE_APIS.has(config.api)) { - const apiLabel = getExperienceFromApi(config.api).shortName; + const apiCode = config.api === undefined ? undefined : NON_MULTI_WRITE_APIS.get(config.api); + if (config.api !== undefined && apiCode !== undefined) { + const apiLabel = config.api === 'MongoDB' ? 'MongoDB' : getExperienceFromApi(config.api).shortName; return { - ...base, - severity: 'High', - title: l10n.t('Multi-region writes on a {api} account', { api: apiLabel }), - rationale: clampRationale( - l10n.t('Multi-region writes are enabled on a {api} API account.', { api: apiLabel }) + - ' ' + - l10n.t( - "The {api} drivers cannot use Cosmos DB's multi-region-write failover, so the RTO=0 HA benefit never materialises.", - { - api: apiLabel, - }, - ) + - ' ' + - l10n.t( - 'The account still carries the write-conflict surface (and `2×` write cost across any second write region).', - ), - ), - suggestedAction: disableAction, - thresholdReference: l10n.t('Threshold: multi-region writes enabled on a non-SQL API account'), + rootCause: `${apiCode}_multi_region_writes`, + advisory: { + ...base, + severity: 'High', + title: l10n.t('Multi-region writes on a {api} account', { api: apiLabel }), + rationale: clampRationale( + l10n.t('Multi-region writes are enabled on a {api} API account.', { api: apiLabel }) + + ' ' + + l10n.t( + "The {api} drivers cannot use Cosmos DB's multi-region-write failover, so the RTO=0 HA benefit never materialises.", + { + api: apiLabel, + }, + ) + + ' ' + + l10n.t( + 'Review the write-conflict and pricing implications against the current API and region configuration.', + ), + ), + suggestedAction: disableAction, + thresholdReference: l10n.t('Threshold: multi-region writes enabled on a non-SQL API account'), + }, }; } @@ -60,55 +74,97 @@ function evaluateMultiRegionWrites(config: AccountConfigInput): DerivedAdvisory // failover needs a second region), and write cost doubles the moment a second write region is added. if (config.writeRegionCount < DIAGNOSTIC_POLICY.multiRegionWrite.minWriteRegions) { return { + rootCause: 'single_region_multi_region_writes_tripwire', + advisory: { + ...base, + severity: 'Low', + title: l10n.t('Multi-region writes with a single write region'), + rationale: clampRationale( + l10n.t('Multi-region writes are enabled but the account has a single write region.') + + ' ' + + l10n.t('The feature delivers no benefit today (RTO=0 write failover needs a second region).') + + ' ' + + l10n.t( + 'Adding write regions can increase cost and conflict complexity; no savings are quantified here.', + ), + ), + suggestedAction: l10n.t( + 'Disable multi-region writes to remove the tripwire unless a second write region is imminent and justified.', + ), + thresholdReference: l10n.t('Threshold: multi-region writes enabled with a single write region'), + }, + }; + } + + // Two or more write regions: legitimate active-active HA in production; only flagged in non-production. + const env = classifyEnvironment(config.accountName, config.tags, config.subscriptionName); + if (!env.isNonProd) { + return { rootCause: 'legitimate_ha' }; + } + return { + rootCause: 'nonprod_multi_region_writes', + advisory: { ...base, - severity: 'Low', - title: l10n.t('Multi-region writes with a single write region'), + severity: 'Medium', + title: l10n.t('Multi-region writes on a non-production account'), rationale: clampRationale( - l10n.t('Multi-region writes are enabled but the account has a single write region.') + + l10n.t( + 'Multi-region writes are enabled across `{regions} write regions` on a non-production account, which does not need RTO=0 write failover.', + { regions: config.writeRegionCount }, + ) + ' ' + - l10n.t('The feature delivers no benefit today (RTO=0 write failover needs a second region).') + - ' ' + - l10n.t('Write cost doubles the moment a second write region is added.'), + l10n.t( + 'Confirm this inferred environment and its availability requirements with the account owner.', + ), ), suggestedAction: l10n.t( - 'Disable multi-region writes to remove the tripwire unless a second write region is imminent and justified.', + 'Review disabling multi-region writes if active-active availability is unnecessary. Separately assess whether extra regions can be removed; toggling multi-write alone does not recover regional capacity.', ), - thresholdReference: l10n.t('Threshold: multi-region writes enabled with a single write region'), - }; - } + thresholdReference: l10n.t( + 'Threshold: multi-region writes across ≥ `2 write regions` on a non-prod account', + ), + }, + }; +} - // Two or more write regions: legitimate active-active HA in production; only flagged in non-production. - const env = classifyEnvironment(config.accountName, config.tags, config.subscriptionName); - if (!env.isNonProd) { - return undefined; +function evaluateRegionalCapacity( + config: AccountConfigInput, + manualRu?: number, +): AdvisoryEvaluation<'MultiRegionWriteAntipattern'> { + const result = evaluateMultiRegionWrites(config); + if ( + config.isServerless !== false || + manualRu === undefined || + !Number.isFinite(manualRu) || + manualRu <= 0 || + !Number.isInteger(config.regionCount) || + config.regionCount < 1 + ) { + return { ...result, observations: { regionalCapacityQuantified: false } }; } + const observations = { + regionalCapacityQuantified: true as const, + configuredPerRegionRu: manualRu, + globalRegionalFootprintRu: manualRu * config.regionCount, + removableExtraRegionRu: + result.rootCause === 'nonprod_multi_region_writes' ? manualRu * (config.regionCount - 1) : null, + }; return { - ...base, - severity: 'Medium', - title: l10n.t('Multi-region writes on a non-production account'), - rationale: clampRationale( - l10n.t( - 'Multi-region writes are enabled across `{regions} write regions` on a non-production account, which does not need RTO=0 write failover.', - { regions: config.writeRegionCount }, - ) + - ' ' + - l10n.t('This doubles write cost and adds write-conflict surface for no benefit.'), - ), - suggestedAction: l10n.t( - 'Disable multi-region writes (and consider dropping the second write region) on dev/test/stage accounts.', - ), - thresholdReference: l10n.t('Threshold: multi-region writes across ≥ `2 write regions` on a non-prod account'), + ...result, + observations, + advisory: result.advisory ? { ...result.advisory, evidence: observations } : undefined, }; } export class MultiRegionWriteAntipatternDetector extends Detector { readonly rule = 'MultiRegionWriteAntipattern' as const; - evaluate = evaluateMultiRegionWrites; + evaluateResult = evaluateRegionalCapacity; + evaluate = (...args: Parameters) => evaluateRegionalCapacity(...args).advisory; run(ctx: DetectorContext): DerivedAdvisory[] { if (!ctx.inputs.accountConfig) { return []; } - const advisory = this.evaluate(ctx.inputs.accountConfig); + const advisory = this.evaluate(ctx.inputs.accountConfig, ctx.inputs.manualRegionalCapacityRu); return advisory ? [advisory] : []; } } diff --git a/src/panels/accountOverview/services/advisories/detectors/OverProvisioningDetector.ts b/src/panels/accountOverview/services/advisories/detectors/OverProvisioningDetector.ts index c5f8c4c40..39adda50a 100644 --- a/src/panels/accountOverview/services/advisories/detectors/OverProvisioningDetector.ts +++ b/src/panels/accountOverview/services/advisories/detectors/OverProvisioningDetector.ts @@ -12,9 +12,11 @@ import { clampRationale, finiteNumbers, hasMinimumKnownResourceAge, + offerScope, + utilizationBand, } from '../core/helpers'; import { DIAGNOSTIC_POLICY } from '../core/thresholds'; -import { type DerivedAdvisory, type ManualThroughputInput } from '../core/types'; +import { type DerivedAdvisory, type ManualThroughputInput, type ProvisioningEvaluation } from '../core/types'; // Platform minimum RU/s floor a right-size recommendation never drops below — a container's minimum manual // throughput is 400 RU/s: @@ -74,13 +76,15 @@ function evaluateOverProvisioning( : 'Medium'; const materiality = wastedRu !== undefined && recommendedRu !== undefined - ? l10n.t( - ' That leaves roughly `{wasted} RU/s` recoverable by lowering the offer toward `~{recommended} RU/s`.', - { - wasted: wastedRu.toLocaleString(), - recommended: recommendedRu.toLocaleString(), - }, - ) + ? wastedExact === 0 + ? l10n.t( + ' The modeled recoverable capacity is `{wasted} RU/s`; the target remains `~{recommended} RU/s`, so no reduction is available.', + { wasted: wastedRu.toLocaleString(), recommended: recommendedRu.toLocaleString() }, + ) + : l10n.t( + ' That leaves roughly `{wasted} RU/s` recoverable by lowering the offer toward `~{recommended} RU/s`.', + { wasted: wastedRu.toLocaleString(), recommended: recommendedRu.toLocaleString() }, + ) : ''; return { @@ -93,7 +97,7 @@ function evaluateOverProvisioning( rationale: clampRationale( (containerId ? l10n.t( - 'Container "{container}" stayed at `{p99}%` 99th-percentile normalized RU over the last `{window}`.', + 'Offer "{container}" stayed at `{p99}%` 99th-percentile normalized RU over the last `{window}`.', { container: escapeAdvisoryText(containerId), p99, window: observationLabel }, ) + ' ' + @@ -107,19 +111,31 @@ function evaluateOverProvisioning( ) + materiality, ), + evidence: { + p99Percent, + peakPercent: peakPercent ?? null, + provisionedRu: provisionedRu ?? null, + recommendedRu: recommendedRu ?? null, + recoverableRu: wastedExact ?? null, + }, + actionEligibility: wastedExact === 0 ? 'blocked' : 'requiresValidation', suggestedAction: - containerId && recommendedRu !== undefined && provisionedRu !== undefined + wastedExact === 0 ? l10n.t( - 'Lower "{container}" from `{provisioned} RU/s` toward `~{recommended} RU/s`, or switch it to autoscale if demand is bursty.', - { - container: escapeAdvisoryText(containerId), - provisioned: Math.round(provisionedRu).toLocaleString(), - recommended: recommendedRu.toLocaleString(), - }, + 'No throughput reduction is available under this model. Validate the service minimum and workload needs; do not apply an unchanged target.', ) - : l10n.t( - 'Lower provisioned RU/s to match observed demand, or switch to autoscale so capacity tracks usage automatically.', - ), + : containerId && recommendedRu !== undefined && provisionedRu !== undefined + ? l10n.t( + 'Lower "{container}" from `{provisioned} RU/s` toward `~{recommended} RU/s`, or switch it to autoscale if demand is bursty.', + { + container: escapeAdvisoryText(containerId), + provisioned: Math.round(provisionedRu).toLocaleString(), + recommended: recommendedRu.toLocaleString(), + }, + ) + : l10n.t( + 'Lower provisioned RU/s to match observed demand, or switch to autoscale so capacity tracks usage automatically.', + ), thresholdReference: l10n.t('Threshold: p99 RU < `{threshold}%` and peak < `90%`', { threshold }), scope, }; @@ -129,40 +145,55 @@ function evaluateManualThroughput( input: ManualThroughputInput, thresholdPercent: number, scopeProvisionedRuTotal?: number, -): DerivedAdvisory | undefined { +): ProvisioningEvaluation { const samples = finiteNumbers(input.ruPercents); if ( samples.length < DIAGNOSTIC_POLICY.overProvisioning.minSamples || !hasMinimumKnownResourceAge(input.resourceAgeDays, DIAGNOSTIC_POLICY.overProvisioning.minResourceAgeDays) ) { - return undefined; + return { band: 'insufficient_data' }; + } + const p99 = percentile(samples, DIAGNOSTIC_POLICY.overProvisioning.percentile); + if (p99 === undefined) { + return { band: 'insufficient_data' }; } - return evaluateOverProvisioning( - percentile(samples, DIAGNOSTIC_POLICY.overProvisioning.percentile), - input.peakPercent ?? (samples.length > 0 ? Math.max(...samples) : undefined), + const peak = input.peakPercent ?? Math.max(...samples); + const advisory = evaluateOverProvisioning( + p99, + peak, thresholdPercent, true, input.provisionedRu, scopeProvisionedRuTotal, - `${input.databaseId}/${input.containerId}`, - input.containerId, + offerScope(input), + input.containerId ?? input.databaseId, l10n.t('30 days'), ); + const recommendedRu = advisory?.evidence?.recommendedRu; + return { + band: + peak >= DIAGNOSTIC_POLICY.overProvisioning.peakGuardPercent ? 'ok' : utilizationBand(p99, thresholdPercent), + recommendedRu: typeof recommendedRu === 'number' ? recommendedRu : input.provisionedRu, + recoverableRu: typeof advisory?.evidence?.recoverableRu === 'number' ? advisory.evidence.recoverableRu : 0, + advisory, + }; } export class OverProvisioningDetector extends Detector { readonly rule = 'OverProvisioning' as const; evaluate = evaluateOverProvisioning; + evaluateResult = evaluateManualThroughput; run(ctx: DetectorContext): DerivedAdvisory[] { const { inputs, thresholds } = ctx; if (inputs.manualThroughput !== undefined) { return inputs.manualThroughput - .map((input) => - evaluateManualThroughput( - input, - thresholds.overProvisioningBandPercent, - inputs.scopeProvisionedRuTotal, - ), + .map( + (input) => + this.evaluateResult( + input, + thresholds.overProvisioningBandPercent, + inputs.scopeProvisionedRuTotal, + ).advisory, ) .filter((advisory): advisory is DerivedAdvisory => advisory !== undefined); } diff --git a/src/panels/accountOverview/services/advisories/detectors/PartitionMergeCandidateDetector.ts b/src/panels/accountOverview/services/advisories/detectors/PartitionMergeCandidateDetector.ts index bc39af4e8..5bb7b5dfb 100644 --- a/src/panels/accountOverview/services/advisories/detectors/PartitionMergeCandidateDetector.ts +++ b/src/panels/accountOverview/services/advisories/detectors/PartitionMergeCandidateDetector.ts @@ -9,7 +9,12 @@ import { containerKey } from '../../shared'; import { Detector, type DetectorContext } from '../core/Detector'; import { clampRationale } from '../core/helpers'; import { DIAGNOSTIC_POLICY } from '../core/thresholds'; -import { type DerivedAdvisory, type DerivedAdvisorySeverity, type PartitionMergeInput } from '../core/types'; +import { + type AdvisoryEvaluation, + type DerivedAdvisory, + type DerivedAdvisorySeverity, + type PartitionMergeInput, +} from '../core/types'; import { GIB } from './storageMath'; // DX-009: each physical partition serves up to 10,000 RU/s and stores up to 50 GiB. Both are Azure platform @@ -34,24 +39,52 @@ function neededPartitions(provisionedRu: number, storageBytes: number): number { * Severity is Medium when actual ≥ 2× needed (the slice is very thin), else Low. Merge is a platform operation. * Pure. */ -function evaluatePartitionMergeCandidate(input: PartitionMergeInput): DerivedAdvisory | undefined { +function evaluatePartitionMergeCandidate(input: PartitionMergeInput): AdvisoryEvaluation<'PartitionMergeCandidate'> { const actual = input.actualPartitions; // 0 ⇒ no partition reading (insufficient data); 1 ⇒ single partition can never be merged. - if (actual <= 1) { - return undefined; + if ( + !Number.isInteger(actual) || + actual < 1 || + input.provisionedRu === undefined || + !Number.isFinite(input.provisionedRu) || + input.provisionedRu < 0 || + input.dataUsageBytes === undefined || + !Number.isFinite(input.dataUsageBytes) || + input.dataUsageBytes < 0 + ) { + return { rootCause: 'insufficient_data' }; } - const provisionedRu = input.provisionedRu ?? 0; - const storageBytes = input.dataUsageBytes ?? 0; + if (actual === 1) { + return { rootCause: 'single_partition' }; + } + const provisionedRu = input.provisionedRu; + const storageBytes = input.dataUsageBytes; const needed = neededPartitions(provisionedRu, storageBytes); if (actual <= needed) { - return undefined; + return { rootCause: 'right_sized' }; } const severity: DerivedAdvisorySeverity = actual >= DIAGNOSTIC_POLICY.partitionMerge.mediumExcessRatio * needed ? 'Medium' : 'Low'; const scope = containerKey(input.databaseId, input.containerId); const ruSlice = provisionedRu > 0 ? Math.round(provisionedRu / actual) : 0; const gib = Math.round((storageBytes / GIB) * 10) / 10; - return { + const policy = input.backupPolicy; + const backupType = policy?.type?.toLowerCase(); + const blocked = backupType === 'continuous' || policy?.fullFidelityChangeFeedEnabled === true; + const migration = policy?.migrationState; + const settledPeriodic = + backupType === 'periodic' && + (migration === undefined || + (migration.status?.toLowerCase() === 'completed' && migration.targetType?.toLowerCase() === 'periodic')); + const eligibility = + backupType === 'continuous' + ? 'blocked_pitr' + : policy?.fullFidelityChangeFeedEnabled === true + ? 'blocked_full_fidelity' + : settledPeriodic + ? 'requires_platform_validation' + : 'unknown'; + const advisory: DerivedAdvisory = { id: `PartitionMergeCandidate:${scope}`, rule: 'PartitionMergeCandidate', severity, @@ -77,19 +110,45 @@ function evaluatePartitionMergeCandidate(input: PartitionMergeInput): DerivedAdv 'This usually follows scaling RU/s down (or deleting data) after a high-throughput or large period.', ), ), - suggestedAction: l10n.t( - 'Merge the physical partitions (Azure Portal or CLI) to consolidate the RU/s back onto fewer partitions.', - ), + evidence: { + actualPartitions: actual, + neededPartitions: needed, + provisionedRu, + dataUsageBytes: storageBytes, + backupType: backupType ?? 'unknown', + mergeEligibility: eligibility, + }, + actionEligibility: blocked ? 'blocked' : settledPeriodic ? 'requiresValidation' : 'unknown', + suggestedAction: blocked + ? l10n.t( + 'Partition merge is blocked by continuous backup or conflicting all-versions-and-deletes metadata. Continuous backup cannot be reverted to periodic backup. Do not disable protection to enable a merge.', + ) + + (policy?.fullFidelityChangeFeedEnabled === true + ? ' ' + + l10n.t( + 'All-versions-and-deletes change feed requires continuous backup; enablement does not establish active consumer usage. Resolve inconsistent or missing backup metadata without weakening protection.', + ) + : '') + : settledPeriodic + ? l10n.t( + 'Use the Azure Portal merge eligibility checker and verify current platform, SDK and connector restrictions. Periodic backup alone does not establish eligibility. Only after those checks should a merge be considered.', + ) + : l10n.t( + 'Merge eligibility is unknown because backup policy is missing or migration metadata is present and unsettled. Verify the account state; merge instructions are withheld.', + ), thresholdReference: l10n.t( 'Threshold: physical partitions > max(ceil(RU/`10,000`), ceil(storage/`50 GiB`), `1`)', ), scope, }; + return { rootCause: 'over_partitioned', advisory, observations: { mergeEligibility: eligibility } }; } export class PartitionMergeCandidateDetector extends Detector { readonly rule = 'PartitionMergeCandidate' as const; - evaluate = evaluatePartitionMergeCandidate; + evaluateResult = evaluatePartitionMergeCandidate; + evaluate = (...args: Parameters) => + evaluatePartitionMergeCandidate(...args).advisory; run(ctx: DetectorContext): DerivedAdvisory[] { const out: DerivedAdvisory[] = []; for (const merge of ctx.inputs.partitionMerges ?? []) { diff --git a/src/panels/accountOverview/services/advisories/detectors/ServerlessCandidateDetector.ts b/src/panels/accountOverview/services/advisories/detectors/ServerlessCandidateDetector.ts index 1020d3c56..3e1d6f3b1 100644 --- a/src/panels/accountOverview/services/advisories/detectors/ServerlessCandidateDetector.ts +++ b/src/panels/accountOverview/services/advisories/detectors/ServerlessCandidateDetector.ts @@ -7,7 +7,12 @@ import * as l10n from '@vscode/l10n'; import { Detector, type DetectorContext } from '../core/Detector'; import { clampRationale } from '../core/helpers'; import { DIAGNOSTIC_POLICY } from '../core/thresholds'; -import { type DerivedAdvisory, type ServerlessCandidateInput, type ServerlessCandidateThresholds } from '../core/types'; +import { + type AdvisoryEvaluation, + type DerivedAdvisory, + type ServerlessCandidateInput, + type ServerlessCandidateThresholds, +} from '../core/types'; /** * ServerlessCandidate (CODA DX-014): the account's total consumed throughput is **low and sporadic** — a small @@ -20,21 +25,27 @@ import { type DerivedAdvisory, type ServerlessCandidateInput, type ServerlessCan function evaluateServerlessCandidate( input: ServerlessCandidateInput, thresholds: ServerlessCandidateThresholds, -): DerivedAdvisory | undefined { - if (input.isServerless || input.sampleCount < DIAGNOSTIC_POLICY.serverless.minSamples) { - return undefined; +): AdvisoryEvaluation<'ServerlessCandidate'> { + if (input.isServerless) { + return { rootCause: 'already_serverless' }; } - if (input.peakRuPerSec < thresholds.peakFloorRuPerSec || input.peakRuPerSec > thresholds.peakCeilingRuPerSec) { - return undefined; + if (input.sampleCount < DIAGNOSTIC_POLICY.serverless.minSamples) { + return { rootCause: 'insufficient_data' }; + } + if (input.peakRuPerSec < thresholds.peakFloorRuPerSec) { + return { rootCause: 'idle_or_empty' }; + } + if (input.peakRuPerSec > thresholds.peakCeilingRuPerSec) { + return { rootCause: 'too_high' }; } const ratio = input.peakRuPerSec > 0 ? input.avgRuPerSec / input.peakRuPerSec : 0; if (ratio >= thresholds.sporadicRatio) { - return undefined; + return { rootCause: 'steady_load' }; } const peak = Math.round(input.peakRuPerSec); const avg = Math.round(input.avgRuPerSec); const ratioPct = Math.round(ratio * 100); - return { + const advisory: DerivedAdvisory = { id: 'ServerlessCandidate', rule: 'ServerlessCandidate', severity: 'Low', @@ -59,11 +70,14 @@ function evaluateServerlessCandidate( ratio: thresholds.sporadicRatio, }), }; + return { rootCause: 'serverless_candidate', advisory }; } export class ServerlessCandidateDetector extends Detector { readonly rule = 'ServerlessCandidate' as const; - evaluate = evaluateServerlessCandidate; + evaluateResult = evaluateServerlessCandidate; + evaluate = (...args: Parameters) => + evaluateServerlessCandidate(...args).advisory; run(ctx: DetectorContext): DerivedAdvisory[] { const { inputs, thresholds } = ctx; if (!inputs.serverless) { diff --git a/src/panels/accountOverview/services/advisories/detectors/ServerlessThrottlingDetector.ts b/src/panels/accountOverview/services/advisories/detectors/ServerlessThrottlingDetector.ts index 959ae25c3..57c9d3ed7 100644 --- a/src/panels/accountOverview/services/advisories/detectors/ServerlessThrottlingDetector.ts +++ b/src/panels/accountOverview/services/advisories/detectors/ServerlessThrottlingDetector.ts @@ -9,16 +9,21 @@ import { containerKey } from '../../shared'; import { Detector, type DetectorContext } from '../core/Detector'; import { clampRationale } from '../core/helpers'; import { DIAGNOSTIC_POLICY } from '../core/thresholds'; -import { type DerivedAdvisory, type DerivedAdvisorySeverity, type ServerlessThrottlingInput } from '../core/types'; +import { + type AdvisoryEvaluation, + type DerivedAdvisory, + type DerivedAdvisorySeverity, + type ServerlessThrottlingInput, +} from '../core/types'; const SERVERLESS_RU_PER_PARTITION = 5_000; -function evaluateServerlessThrottling(input: ServerlessThrottlingInput): DerivedAdvisory | undefined { +function evaluateServerlessThrottling(input: ServerlessThrottlingInput): AdvisoryEvaluation<'ServerlessThrottling'> { if (input.totalRequests < DIAGNOSTIC_POLICY.serverlessThrottling.minRequests) { - return undefined; + return { rootCause: 'insufficient_data' }; } if (input.throttleRatePercent < DIAGNOSTIC_POLICY.serverlessThrottling.throttleRatePercent) { - return undefined; + return { rootCause: 'not_throttling' }; } const scope = containerKey(input.databaseId, input.containerId); const severity: DerivedAdvisorySeverity = @@ -28,7 +33,7 @@ function evaluateServerlessThrottling(input: ServerlessThrottlingInput): Derived ? 'Medium' : 'Low'; const rate = Math.round(input.throttleRatePercent * 10) / 10; - return { + const advisory: DerivedAdvisory = { id: `ServerlessThrottling:${scope}`, rule: 'ServerlessThrottling', severity, @@ -59,11 +64,18 @@ function evaluateServerlessThrottling(input: ServerlessThrottlingInput): Derived }), scope, }; + return { + rootCause: 'serverless_throttling', + advisory, + observations: { throttleRatePercent: input.throttleRatePercent }, + }; } export class ServerlessThrottlingDetector extends Detector { readonly rule = 'ServerlessThrottling' as const; - evaluate = evaluateServerlessThrottling; + evaluateResult = evaluateServerlessThrottling; + evaluate = (...args: Parameters) => + evaluateServerlessThrottling(...args).advisory; run(ctx: DetectorContext): DerivedAdvisory[] { const out: DerivedAdvisory[] = []; for (const input of ctx.inputs.serverlessThrottling ?? []) { diff --git a/src/panels/accountOverview/services/advisories/detectors/ShardKeyMisalignmentDetector.ts b/src/panels/accountOverview/services/advisories/detectors/ShardKeyMisalignmentDetector.ts index 372eb0fd3..3d4c7e6a6 100644 --- a/src/panels/accountOverview/services/advisories/detectors/ShardKeyMisalignmentDetector.ts +++ b/src/panels/accountOverview/services/advisories/detectors/ShardKeyMisalignmentDetector.ts @@ -9,62 +9,44 @@ import { Detector, type DetectorContext } from '../core/Detector'; import { clampRationale } from '../core/helpers'; import { DIAGNOSTIC_POLICY } from '../core/thresholds'; import { + type AdvisoryEvaluation, type CrossPartitionInput, type DerivedAdvisory, - type DerivedAdvisorySeverity, - type QueryShapeInput, type ShardKeyThresholds, } from '../core/types'; - -/** Folds the per-shape fan-out into total executions, cross-partition share, and the worst (most frequent) shape. Pure. */ -interface CrossPartitionStats { - totalQueries: number; - containerPartitions: number; - crossPartitionPct: number; - worst: QueryShapeInput | undefined; -} - -function crossPartitionStats(shapes: readonly QueryShapeInput[], fanoutThreshold: number): CrossPartitionStats { - const totalQueries = shapes.reduce((sum, s) => sum + s.executions, 0); - const containerPartitions = shapes.reduce((max, s) => Math.max(max, s.maxFanout), 0); - const crossShapes = shapes.filter((s) => s.avgFanout >= fanoutThreshold); - const crossExec = crossShapes.reduce((sum, s) => sum + s.executions, 0); - const crossPartitionPct = totalQueries > 0 ? (100 * crossExec) / totalQueries : 0; - const worst = crossShapes.reduce( - (best, s) => (best === undefined || s.executions > best.executions ? s : best), - undefined, - ); - return { totalQueries, containerPartitions, crossPartitionPct, worst }; -} +import { fanoutRuDescription, fanoutRuEvidence, fanoutSeverity, fanoutStats } from './fanout'; /** * ShardKeyMisalignment (CODA DX-007): the structural escalation of DX-002. When the *dominant* share of query * executions fans out (≥ `structuralPct`) across ≥ `minPartitions` physical partitions, the problem is the * partition key itself (the data model), not individual queries — the fix is to re-key the container * (migration-class). Reuses DX-002's fan-out signal. When this fires it **supersedes** DX-002 on the same - * container (the caller drops the DX-002 advisory). Container-scoped. Pure. + * container (the engine retains DX-002 as superseded evidence). Container-scoped. Pure. */ function evaluateShardKeyMisalignment( input: CrossPartitionInput, thresholds: ShardKeyThresholds, crossPartitionFanoutThreshold: number, minQueries: number = DIAGNOSTIC_POLICY.crossPartition.minQueries, -): DerivedAdvisory | undefined { - const { totalQueries, containerPartitions, crossPartitionPct } = crossPartitionStats( - input.shapes, - crossPartitionFanoutThreshold, - ); - const roundedCrossPartitionPct = Math.round(crossPartitionPct * 10) / 10; +): AdvisoryEvaluation<'ShardKeyMisalignment'> { + const stats = fanoutStats(input, crossPartitionFanoutThreshold); + if (!stats) { + return { rootCause: 'insufficient_data' }; + } + const { totalQueries, containerPartitions, crossPartitionPct, crossQueriesPerSecond, worst } = stats; + if (totalQueries < minQueries) { + return { rootCause: 'insufficient_data' }; + } if ( - totalQueries < minQueries || - roundedCrossPartitionPct < thresholds.structuralPct || + crossPartitionPct < thresholds.structuralPct || + crossQueriesPerSecond < DIAGNOSTIC_POLICY.crossPartition.minQueriesPerSecond || containerPartitions < thresholds.minPartitions ) { - return undefined; + return { rootCause: 'not_misaligned' }; } - const severity: DerivedAdvisorySeverity = roundedCrossPartitionPct >= thresholds.highPct ? 'High' : 'Medium'; - const pct = Math.round(roundedCrossPartitionPct); - return { + const severity = fanoutSeverity(containerPartitions, crossQueriesPerSecond); + const pct = Math.round(crossPartitionPct); + const advisory: DerivedAdvisory = { id: `ShardKeyMisalignment/${containerKey(input.databaseId, input.containerId)}`, rule: 'ShardKeyMisalignment', severity, @@ -92,18 +74,32 @@ function evaluateShardKeyMisalignment( ' ' + l10n.t( 'Per-query fixes cannot resolve a fundamentally mismatched key, and the cost grows as the container adds partitions.', - ), - thresholdReference: l10n.t('Threshold: ≥ `{pct}%` of executions fan out across ≥ `{partitions} partitions`', { - pct: thresholds.structuralPct, - partitions: thresholds.minPartitions, - }), + ) + + fanoutRuDescription(worst), + evidence: { + totalQueries, + containerPartitions, + crossPartitionPct, + crossQueriesPerSecond, + ...fanoutRuEvidence(input, worst), + }, + thresholdReference: l10n.t( + 'Threshold: ≥ `{pct}%` fan-out share across ≥ `{partitions} partitions`, and ≥ `0.1 fan-out queries/s`', + { + pct: thresholds.structuralPct, + partitions: thresholds.minPartitions, + }, + ), }; + return { rootCause: 'shard_key_misaligned', advisory }; } export class ShardKeyMisalignmentDetector extends Detector { readonly rule = 'ShardKeyMisalignment' as const; readonly supersedes = ['CrossPartitionQuery'] as const; - evaluate = evaluateShardKeyMisalignment; + evaluateResult = evaluateShardKeyMisalignment; + evaluate = (...args: Parameters) => + evaluateShardKeyMisalignment(...args).advisory; run(ctx: DetectorContext): DerivedAdvisory[] { const t = ctx.thresholds; const out: DerivedAdvisory[] = []; @@ -113,7 +109,6 @@ export class ShardKeyMisalignmentDetector extends Detector { { structuralPct: t.shardKeyStructuralPct, minPartitions: DIAGNOSTIC_POLICY.shardKey.minPartitions, - highPct: t.shardKeyHighPct, }, t.crossPartitionFanoutThreshold, t.crossPartitionMinQueries, diff --git a/src/panels/accountOverview/services/advisories/detectors/SharedThroughputStarvationDetector.ts b/src/panels/accountOverview/services/advisories/detectors/SharedThroughputStarvationDetector.ts index ab9c6dac8..f1f33210e 100644 --- a/src/panels/accountOverview/services/advisories/detectors/SharedThroughputStarvationDetector.ts +++ b/src/panels/accountOverview/services/advisories/detectors/SharedThroughputStarvationDetector.ts @@ -9,6 +9,7 @@ import { Detector, type DetectorContext } from '../core/Detector'; import { clampRationale } from '../core/helpers'; import { DIAGNOSTIC_POLICY } from '../core/thresholds'; import { + type AdvisoryEvaluation, type CollectionTrafficInput, type DerivedAdvisory, type SharedThroughputInput, @@ -26,17 +27,40 @@ import { function evaluateSharedThroughputStarvation( input: SharedThroughputInput, thresholds: SharedThroughputThresholds, -): DerivedAdvisory | undefined { - const active = input.collections.filter((c) => c.requests >= thresholds.minRequests); +): AdvisoryEvaluation<'SharedThroughputStarvation'> { + if (!input.sharedContainerIds) { + return { rootCause: 'insufficient_data' }; + } + const members = new Set(input.sharedContainerIds); + const traffic = input.collections.filter((c) => members.has(c.containerId)); + if ( + new Set(traffic.map((c) => c.containerId)).size !== traffic.length || + traffic.some( + (c) => + !Number.isFinite(c.requests) || + c.requests < 0 || + !Number.isFinite(c.throttledRequests) || + c.throttledRequests < 0 || + c.throttledRequests > c.requests || + !Number.isFinite(c.ruConsumed) || + c.ruConsumed < 0, + ) + ) { + return { rootCause: 'insufficient_data' }; + } + const active = traffic.filter((c) => c.requests >= thresholds.minRequests); if (active.length < DIAGNOSTIC_POLICY.sharedThroughput.minActiveCollections) { - return undefined; + return { rootCause: active.length === 0 ? 'insufficient_data' : 'single_collection' }; } const ruTotal = active.reduce((sum, c) => sum + c.ruConsumed, 0); const reqTotal = active.reduce((sum, c) => sum + c.requests, 0); const thrTotal = active.reduce((sum, c) => sum + c.throttledRequests, 0); const poolRate = reqTotal > 0 ? (100 * thrTotal) / reqTotal : 0; - if (poolRate < thresholds.poolThrottlePct || ruTotal <= 0) { - return undefined; + if (ruTotal <= 0) { + return { rootCause: 'insufficient_data' }; + } + if (poolRate < thresholds.poolThrottlePct) { + return { rootCause: 'not_throttling' }; } const share = (c: CollectionTrafficInput): number => (100 * c.ruConsumed) / ruTotal; const throttleRate = (c: CollectionTrafficInput): number => @@ -50,10 +74,10 @@ function evaluateSharedThroughputStarvation( share(c) <= thresholds.victimSharePct, ); if (monoShare < thresholds.dominancePct || victims.length === 0) { - return undefined; + return { rootCause: 'no_disparity' }; } const victim = victims.reduce((worst, c) => (throttleRate(c) > throttleRate(worst) ? c : worst), victims[0]); - return { + const advisory: DerivedAdvisory = { id: `SharedThroughputStarvation/${input.databaseId}`, rule: 'SharedThroughputStarvation', severity: 'High', @@ -97,12 +121,20 @@ function evaluateSharedThroughputStarvation( share: thresholds.victimSharePct, }, ), + evidence: { ...input.requestLogEvidence }, + }; + return { + rootCause: 'starvation', + advisory, + observations: { monopolizer: monopolizer.containerId, victim: victim.containerId }, }; } export class SharedThroughputStarvationDetector extends Detector { readonly rule = 'SharedThroughputStarvation' as const; - evaluate = evaluateSharedThroughputStarvation; + evaluateResult = evaluateSharedThroughputStarvation; + evaluate = (...args: Parameters) => + evaluateSharedThroughputStarvation(...args).advisory; run(ctx: DetectorContext): DerivedAdvisory[] { const t = ctx.thresholds; const out: DerivedAdvisory[] = []; diff --git a/src/panels/accountOverview/services/advisories/detectors/StorageGrowthRiskDetector.ts b/src/panels/accountOverview/services/advisories/detectors/StorageGrowthRiskDetector.ts index 2f2416c65..11d7c60ce 100644 --- a/src/panels/accountOverview/services/advisories/detectors/StorageGrowthRiskDetector.ts +++ b/src/panels/accountOverview/services/advisories/detectors/StorageGrowthRiskDetector.ts @@ -8,9 +8,15 @@ import { escapeAdvisoryText } from '../../../advisoryText'; import { containerKey } from '../../shared'; import { Detector, type DetectorContext } from '../core/Detector'; import { clampRationale } from '../core/helpers'; -import { type ContainerStorageInput, type DerivedAdvisory, type DerivedAdvisorySeverity } from '../core/types'; +import { + type AdvisoryEvaluation, + type ContainerStorageInput, + type DerivedAdvisory, + type DerivedAdvisorySeverity, +} from '../core/types'; import { daysToStorageLimit, + fitStorageGrowth, GIB, latestBytes, PARTITION_STORAGE_LIMIT_BYTES, @@ -18,7 +24,6 @@ import { STORAGE_GROWTH_MEDIUM_DAYS, STORAGE_GROWTH_MIN_MATERIAL_BYTES, STORAGE_GROWTH_MIN_SLOPE_BYTES_PER_DAY, - storageGrowthSlopeBytesPerDay, } from './storageMath'; /** @@ -30,43 +35,87 @@ import { * growing steadily does. Immaterial (< 1 GiB) and flat/noisy (< 0.1 GiB/day) * partitions are ignored. Severity grades by horizon. Pure. */ -function evaluateStorageGrowthRisk(input: ContainerStorageInput, horizonDays: number): DerivedAdvisory | undefined { +function evaluateStorageGrowthRisk( + input: ContainerStorageInput, + horizonDays: number, +): AdvisoryEvaluation<'StorageGrowthRisk'> { if (horizonDays <= 0) { - return undefined; + return { rootCause: 'stable' }; } - let soonest: { days: number; currentBytes: number; slopeBytesPerDay: number; atOrOverLimit: boolean } | undefined; + let soonest: + | { + days: number; + currentBytes: number; + slopeBytesPerDay: number; + roundoffBytesPerDay: number; + atOrOverLimit: boolean; + } + | undefined; + let largestObserved = 0; + let missingHistory = false; for (const partition of input.partitions) { const currentBytes = latestBytes(partition); - if (currentBytes === undefined || currentBytes < STORAGE_GROWTH_MIN_MATERIAL_BYTES) { + if (currentBytes !== undefined) { + largestObserved = Math.max(largestObserved, currentBytes); + } + if (currentBytes === undefined) { + missingHistory = true; + continue; + } + if (currentBytes < STORAGE_GROWTH_MIN_MATERIAL_BYTES) { continue; } if (currentBytes >= PARTITION_STORAGE_LIMIT_BYTES) { - const atLimit = { days: 0, currentBytes, slopeBytesPerDay: 0, atOrOverLimit: true }; + const atLimit = { days: 0, currentBytes, slopeBytesPerDay: 0, roundoffBytesPerDay: 0, atOrOverLimit: true }; if (soonest === undefined || !soonest.atOrOverLimit || currentBytes > soonest.currentBytes) { soonest = atLimit; } continue; } - const slopeBytesPerDay = storageGrowthSlopeBytesPerDay(partition.samples); - if (slopeBytesPerDay === undefined || slopeBytesPerDay < STORAGE_GROWTH_MIN_SLOPE_BYTES_PER_DAY) { + const trend = fitStorageGrowth(partition.samples); + if (trend === undefined) { + missingHistory = true; continue; } + if (trend.slopeBytesPerDay + trend.roundoffBytesPerDay < STORAGE_GROWTH_MIN_SLOPE_BYTES_PER_DAY) { + continue; + } + const { slopeBytesPerDay } = trend; const days = daysToStorageLimit(currentBytes, slopeBytesPerDay, PARTITION_STORAGE_LIMIT_BYTES); if (days === undefined) { continue; } if (soonest === undefined || (!soonest.atOrOverLimit && days < soonest.days)) { - soonest = { days, currentBytes, slopeBytesPerDay, atOrOverLimit: false }; + soonest = { + days, + currentBytes, + slopeBytesPerDay, + roundoffBytesPerDay: trend.roundoffBytesPerDay, + atOrOverLimit: false, + }; } } - if (soonest === undefined || soonest.days > horizonDays) { - return undefined; + // Compare in bytes/day so the same regression roundoff protects every inclusive boundary. + const reachesWithinDays = (days: number): boolean => + soonest !== undefined && + (soonest.atOrOverLimit || + soonest.slopeBytesPerDay + soonest.roundoffBytesPerDay >= + (PARTITION_STORAGE_LIMIT_BYTES - soonest.currentBytes) / days); + if (soonest === undefined || !reachesWithinDays(horizonDays)) { + return { + rootCause: + missingHistory || largestObserved <= 0 + ? 'insufficient_data' + : largestObserved < STORAGE_GROWTH_MIN_MATERIAL_BYTES + ? 'too_small' + : 'stable', + }; } if (soonest.atOrOverLimit) { const scope = containerKey(input.databaseId, input.containerId); const currentGiB = Math.round((soonest.currentBytes / GIB) * 10) / 10; - return { + const advisory: DerivedAdvisory = { id: `StorageGrowthRisk:${scope}`, rule: 'StorageGrowthRisk', severity: 'High', @@ -92,20 +141,20 @@ function evaluateStorageGrowthRisk(input: ContainerStorageInput, horizonDays: nu thresholdReference: l10n.t('Threshold: current partition size ≥ `50 GiB`'), scope, }; + return { rootCause: 'at_or_over_limit', advisory, observations: { daysToLimit: 0 } }; } - const severity: DerivedAdvisorySeverity = - soonest.days <= STORAGE_GROWTH_HIGH_DAYS - ? 'High' - : soonest.days <= STORAGE_GROWTH_MEDIUM_DAYS - ? 'Medium' - : 'Low'; + const severity: DerivedAdvisorySeverity = reachesWithinDays(STORAGE_GROWTH_HIGH_DAYS) + ? 'High' + : reachesWithinDays(STORAGE_GROWTH_MEDIUM_DAYS) + ? 'Medium' + : 'Low'; const scope = containerKey(input.databaseId, input.containerId); const days = Math.max(0, Math.round(soonest.days)); const currentGiB = Math.round((soonest.currentBytes / GIB) * 10) / 10; const perDayGiB = Math.round((soonest.slopeBytesPerDay / GIB) * 100) / 100; const horizon = Math.round(horizonDays); - return { + const advisory: DerivedAdvisory = { id: `StorageGrowthRisk:${scope}`, rule: 'StorageGrowthRisk', severity, @@ -129,16 +178,18 @@ function evaluateStorageGrowthRisk(input: ContainerStorageInput, horizonDays: nu l10n.t('Confirm the partition key spreads new data across partitions, and archive or delete cold data.') + ' ' + l10n.t('Ensure large logical keys stay well under the `20 GiB` per-key cap so partitions split cleanly.'), - thresholdReference: l10n.t('Threshold: projected < `{horizon} days` to the `50 GiB` partition ceiling', { + thresholdReference: l10n.t('Threshold: projected ≤ `{horizon} days` to the `50 GiB` partition ceiling', { horizon, }), scope, }; + return { rootCause: 'rapid_growth', advisory, observations: { daysToLimit: soonest.days } }; } export class StorageGrowthRiskDetector extends Detector { readonly rule = 'StorageGrowthRisk' as const; - evaluate = evaluateStorageGrowthRisk; + evaluateResult = evaluateStorageGrowthRisk; + evaluate = (...args: Parameters) => evaluateStorageGrowthRisk(...args).advisory; run(ctx: DetectorContext): DerivedAdvisory[] { const out: DerivedAdvisory[] = []; for (const storage of ctx.inputs.storage) { diff --git a/src/panels/accountOverview/services/advisories/detectors/StorageSkewRiskDetector.ts b/src/panels/accountOverview/services/advisories/detectors/StorageSkewRiskDetector.ts index e99cb8f6b..99c5328d4 100644 --- a/src/panels/accountOverview/services/advisories/detectors/StorageSkewRiskDetector.ts +++ b/src/panels/accountOverview/services/advisories/detectors/StorageSkewRiskDetector.ts @@ -9,7 +9,12 @@ import { containerKey } from '../../shared'; import { Detector, type DetectorContext } from '../core/Detector'; import { clampRationale, hasMinimumKnownResourceAge } from '../core/helpers'; import { DIAGNOSTIC_POLICY } from '../core/thresholds'; -import { type ContainerStorageInput, type DerivedAdvisory, type DerivedAdvisorySeverity } from '../core/types'; +import { + type AdvisoryEvaluation, + type ContainerStorageInput, + type DerivedAdvisory, + type DerivedAdvisorySeverity, +} from '../core/types'; import { balanceRatio, GIB, @@ -29,12 +34,15 @@ import { * ceiling (≥ 80% → High, ≥ 50% → Medium). Balanced-but-large partitions are * healthy: they simply split as they grow. Pure. */ -function evaluateStorageSkewRisk(input: ContainerStorageInput, balanceThreshold: number): DerivedAdvisory | undefined { +function evaluateStorageSkewRisk( + input: ContainerStorageInput, + balanceThreshold: number, +): AdvisoryEvaluation<'StorageSkewRisk'> { if ( balanceThreshold <= 0 || !hasMinimumKnownResourceAge(input.resourceAgeDays, DIAGNOSTIC_POLICY.storageSkew.minResourceAgeDays) ) { - return undefined; + return { rootCause: 'insufficient_data' }; } const sizes = input.partitions .map((partition) => { @@ -45,12 +53,18 @@ function evaluateStorageSkewRisk(input: ContainerStorageInput, balanceThreshold: }) .filter((bytes): bytes is number => bytes !== undefined); const ratio = balanceRatio(sizes); + if (sizes.length === 0) { + return { rootCause: 'insufficient_data' }; + } + if (sizes.length === 1) { + return { rootCause: 'single_partition' }; + } if (ratio === undefined || ratio >= balanceThreshold) { - return undefined; + return { rootCause: 'uniform_storage' }; } const busiestBytes = Math.max(...sizes); if (busiestBytes < STORAGE_SKEW_MIN_BUSIEST_BYTES) { - return undefined; + return { rootCause: 'too_small' }; } const severity: DerivedAdvisorySeverity = @@ -60,7 +74,7 @@ function evaluateStorageSkewRisk(input: ContainerStorageInput, balanceThreshold: const balance = Math.round(ratio * 100) / 100; const threshold = Math.round(balanceThreshold * 100) / 100; const ceilingPercent = Math.round((busiestBytes / PARTITION_STORAGE_LIMIT_BYTES) * 100); - return { + const advisory: DerivedAdvisory = { id: `StorageSkewRisk:${scope}`, rule: 'StorageSkewRisk', severity, @@ -93,11 +107,13 @@ function evaluateStorageSkewRisk(input: ContainerStorageInput, balanceThreshold: }), scope, }; + return { rootCause: 'storage_skew', advisory }; } export class StorageSkewRiskDetector extends Detector { readonly rule = 'StorageSkewRisk' as const; - evaluate = evaluateStorageSkewRisk; + evaluateResult = evaluateStorageSkewRisk; + evaluate = (...args: Parameters) => evaluateStorageSkewRisk(...args).advisory; run(ctx: DetectorContext): DerivedAdvisory[] { const out: DerivedAdvisory[] = []; for (const storage of ctx.inputs.storageSkew ?? ctx.inputs.storage) { diff --git a/src/panels/accountOverview/services/advisories/detectors/UncontrolledIngestionDetector.ts b/src/panels/accountOverview/services/advisories/detectors/UncontrolledIngestionDetector.ts index 95580e915..160a5e3da 100644 --- a/src/panels/accountOverview/services/advisories/detectors/UncontrolledIngestionDetector.ts +++ b/src/panels/accountOverview/services/advisories/detectors/UncontrolledIngestionDetector.ts @@ -9,6 +9,7 @@ import { containerKey } from '../../shared'; import { Detector, type DetectorContext } from '../core/Detector'; import { clampRationale } from '../core/helpers'; import { + type AdvisoryEvaluation, type DerivedAdvisory, type DerivedAdvisorySeverity, type UncontrolledIngestionInput, @@ -22,16 +23,16 @@ import { * The fix is application-side rate control, complementary to DX-005's "add RU/s". Container-scoped. Pure. */ function evaluateUncontrolledIngestion( - input: UncontrolledIngestionInput, + input: UncontrolledIngestionInput | undefined, thresholds: UncontrolledIngestionThresholds, -): DerivedAdvisory | undefined { - if (input.totalRequests < thresholds.minRequests) { - return undefined; +): AdvisoryEvaluation<'UncontrolledIngestion'> { + if (!input || input.totalRequests < thresholds.minRequests) { + return { rootCause: 'insufficient_data' }; } const writeRuPct = input.totalRu > 0 ? (100 * input.writeRu) / input.totalRu : 0; const throttleRate = input.totalRequests > 0 ? (100 * input.throttledRequests) / input.totalRequests : 0; if (writeRuPct < thresholds.writeRuPctFloor || throttleRate < thresholds.throttleRatePct) { - return undefined; + return { rootCause: 'not_uncontrolled' }; } const severity: DerivedAdvisorySeverity = throttleRate >= thresholds.highPct ? 'High' : 'Medium'; const writePct = Math.round(writeRuPct); @@ -39,7 +40,7 @@ function evaluateUncontrolledIngestion( const client = input.dominantUserAgent ? l10n.t(' Dominant client: {client}.', { client: escapeAdvisoryText(input.dominantUserAgent) }) : ''; - return { + const advisory: DerivedAdvisory = { id: `UncontrolledIngestion/${containerKey(input.databaseId, input.containerId)}`, rule: 'UncontrolledIngestion', severity, @@ -55,8 +56,11 @@ function evaluateUncontrolledIngestion( ) + ' ' + l10n.t( - 'Combined with a peak-to-average write burst of `~{burst}×`, this is the signature of uncontrolled ingestion.', - { burst: input.burstFactor.toFixed(1) }, + 'The peak-to-average write burst is `~{burst}×` over `{interval}` buckets; burstiness is supporting evidence, not a trigger.', + { + burst: input.burstFactor.toFixed(1), + interval: input.requestLogEvidence?.sourceResolution === 'PT5M' ? '5m' : '1m', + }, ) + client, ), @@ -78,12 +82,23 @@ function evaluateUncontrolledIngestion( writePct: thresholds.writeRuPctFloor, throttlePct: thresholds.throttleRatePct, }), + evidence: { + writeRu: input.writeRu, + totalRu: input.totalRu, + totalRequests: input.totalRequests, + throttledRequests: input.throttledRequests, + burstFactor: input.burstFactor, + ...input.requestLogEvidence, + }, }; + return { rootCause: 'uncontrolled_ingestion', advisory }; } export class UncontrolledIngestionDetector extends Detector { readonly rule = 'UncontrolledIngestion' as const; - evaluate = evaluateUncontrolledIngestion; + evaluateResult = evaluateUncontrolledIngestion; + evaluate = (...args: Parameters) => + evaluateUncontrolledIngestion(...args).advisory; run(ctx: DetectorContext): DerivedAdvisory[] { const t = ctx.thresholds; const out: DerivedAdvisory[] = []; diff --git a/src/panels/accountOverview/services/advisories/detectors/UnderProvisioningDetector.ts b/src/panels/accountOverview/services/advisories/detectors/UnderProvisioningDetector.ts index deec94ed2..5a76be835 100644 --- a/src/panels/accountOverview/services/advisories/detectors/UnderProvisioningDetector.ts +++ b/src/panels/accountOverview/services/advisories/detectors/UnderProvisioningDetector.ts @@ -5,11 +5,15 @@ import * as l10n from '@vscode/l10n'; import { escapeAdvisoryText } from '../../../advisoryText'; -import { containerKey } from '../../shared'; import { Detector, type DetectorContext } from '../core/Detector'; -import { clampRationale, hasMinimumKnownResourceAge } from '../core/helpers'; +import { clampRationale, hasMinimumKnownResourceAge, offerScope } from '../core/helpers'; import { DIAGNOSTIC_POLICY } from '../core/thresholds'; -import { type DerivedAdvisory, type DerivedAdvisorySeverity, type PartitionSaturationInput } from '../core/types'; +import { + type AdvisoryEvaluation, + type DerivedAdvisory, + type DerivedAdvisorySeverity, + type PartitionSaturationInput, +} from '../core/types'; /** * SustainedThrottlingInRegion / genuine under-provisioning (DX-005): a container is sustaining 429 throttling @@ -24,20 +28,24 @@ function evaluateUnderProvisioning( saturationPercent: number, headroomPercent: number, throttleThresholdPercent: number, -): DerivedAdvisory | undefined { +): AdvisoryEvaluation<'SustainedThrottlingInRegion'> { if ( input.totalRequests < DIAGNOSTIC_POLICY.underProvisioning.minRequests || !hasMinimumKnownResourceAge(input.resourceAgeDays, DIAGNOSTIC_POLICY.partitionSaturation.minResourceAgeDays) ) { - return undefined; + return { rootCause: 'insufficient_data' }; } const throttling = input.throttleRatePercent >= throttleThresholdPercent; const atCapacity = input.maxP99 >= saturationPercent; const uniform = input.minP99 >= headroomPercent; - if (!throttling || !atCapacity || !uniform) { - return undefined; + if (!throttling || !atCapacity) { + return { rootCause: 'not_throttling' }; } - const scope = containerKey(input.databaseId, input.containerId); + if (!uniform) { + return { rootCause: 'skew_suspected', severity: 'Medium' }; + } + const scope = offerScope(input); + const name = input.containerId ?? input.databaseId; const rate = Math.round(input.throttleRatePercent * 10) / 10; const busiest = Math.round(input.maxP99); const coolest = Math.round(input.minP99); @@ -67,14 +75,14 @@ function evaluateUnderProvisioning( ) : l10n.t('Raise provisioned throughput, or convert to autoscale if the demand is bursty.'); - return { + const advisory: DerivedAdvisory = { id: `SustainedThrottlingInRegion:${scope}`, rule: 'SustainedThrottlingInRegion', severity, - title: l10n.t('Sustained throttling in {container}', { container: input.containerId }), + title: l10n.t('Sustained throttling in {container}', { container: name }), rationale: clampRationale( l10n.t('In "{container}", `{rate}%` of requests were throttled (HTTP 429).', { - container: escapeAdvisoryText(input.containerId), + container: escapeAdvisoryText(name), rate, }) + ' ' + @@ -103,11 +111,13 @@ function evaluateUnderProvisioning( ), scope, }; + return { rootCause: 'global_under_provisioning', advisory }; } export class UnderProvisioningDetector extends Detector { readonly rule = 'SustainedThrottlingInRegion' as const; - evaluate = evaluateUnderProvisioning; + evaluateResult = evaluateUnderProvisioning; + evaluate = (...args: Parameters) => evaluateUnderProvisioning(...args).advisory; run(ctx: DetectorContext): DerivedAdvisory[] { const t = ctx.thresholds; const out: DerivedAdvisory[] = []; diff --git a/src/panels/accountOverview/services/advisories/detectors/fanout.ts b/src/panels/accountOverview/services/advisories/detectors/fanout.ts new file mode 100644 index 000000000..76e8a408e --- /dev/null +++ b/src/panels/accountOverview/services/advisories/detectors/fanout.ts @@ -0,0 +1,77 @@ +/*--------------------------------------------------------------------------------------------- + * Copyright (c) Microsoft Corporation. All rights reserved. + * Licensed under the MIT License. See License.txt in the project root for license information. + *--------------------------------------------------------------------------------------------*/ + +import * as l10n from '@vscode/l10n'; +import { DIAGNOSTIC_POLICY } from '../core/thresholds'; +import { type CrossPartitionInput, type DerivedAdvisorySeverity, type QueryShapeInput } from '../core/types'; + +export function fanoutStats(input: CrossPartitionInput, fanoutThreshold: number) { + if ( + !Number.isFinite(input.evaluationWindowSeconds) || + input.evaluationWindowSeconds <= 0 || + input.shapes.some( + (shape) => + !Number.isFinite(shape.executions) || + shape.executions < 0 || + !Number.isFinite(shape.avgFanout) || + shape.avgFanout < 0 || + !Number.isFinite(shape.maxFanout) || + shape.maxFanout < 0, + ) + ) { + return undefined; + } + const totalQueries = input.shapes.reduce((sum, shape) => sum + shape.executions, 0); + const containerPartitions = input.shapes.reduce((max, shape) => Math.max(max, shape.maxFanout), 0); + const crossShapes = input.shapes.filter((shape) => shape.avgFanout >= fanoutThreshold); + const crossQueries = crossShapes.reduce((sum, shape) => sum + shape.executions, 0); + const worst = crossShapes.reduce( + (best, shape) => (!best || shape.executions > best.executions ? shape : best), + undefined, + ); + return { + totalQueries, + containerPartitions, + crossPartitionPct: totalQueries > 0 ? (100 * crossQueries) / totalQueries : 0, + crossQueriesPerSecond: crossQueries / input.evaluationWindowSeconds, + worst, + }; +} + +export function fanoutSeverity(partitions: number, queriesPerSecond: number): DerivedAdvisorySeverity { + const policy = DIAGNOSTIC_POLICY.crossPartition; + if (partitions >= policy.highPartitions) { + return queriesPerSecond >= policy.highQueriesPerSecond ? 'High' : 'Medium'; + } + + return partitions >= policy.mediumPartitions && queriesPerSecond >= policy.highQueriesPerSecond ? 'Medium' : 'Low'; +} + +export function fanoutRuEvidence( + input: CrossPartitionInput, + shape: QueryShapeInput | undefined, +): Record { + return shape?.avgRu !== undefined && Number.isFinite(shape.avgRu) && shape.avgRu >= 0 + ? { + queryRuStatus: 'observed', + worstShapeAvgRu: shape.avgRu, + worstShapeRuExecutions: shape.executions, + queryRuSource: 'CDBDataPlaneRequests', + ...(input.observationStart && input.observationEnd + ? { observationStart: input.observationStart, observationEnd: input.observationEnd } + : {}), + } + : { queryRuStatus: 'unavailable' }; +} + +export function fanoutRuDescription(shape: QueryShapeInput | undefined): string { + return shape?.avgRu !== undefined && Number.isFinite(shape.avgRu) && shape.avgRu >= 0 + ? ' ' + + l10n.t( + 'The most frequent fan-out shape averaged `{ru} RU` per logical execution with complete request-log matches. Observed charge is supporting evidence, not estimated savings.', + { ru: shape.avgRu.toFixed(2) }, + ) + : ''; +} diff --git a/src/panels/accountOverview/services/advisories/detectors/storageMath.ts b/src/panels/accountOverview/services/advisories/detectors/storageMath.ts index 16798fbb2..fea8cbbd6 100644 --- a/src/panels/accountOverview/services/advisories/detectors/storageMath.ts +++ b/src/panels/accountOverview/services/advisories/detectors/storageMath.ts @@ -53,25 +53,41 @@ export function latestBytes(series: StoragePartitionSeries): number | undefined * delta — is robust to a single noisy endpoint. Pure. */ export function storageGrowthSlopeBytesPerDay(samples: readonly PartitionStorageSample[]): number | undefined { + return fitStorageGrowth(samples)?.slopeBytesPerDay; +} + +/** Fits the trend with an arithmetic roundoff estimate, so inclusive thresholds survive cancellation. */ +export function fitStorageGrowth( + samples: readonly PartitionStorageSample[], +): { slopeBytesPerDay: number; roundoffBytesPerDay: number } | undefined { const clean = samples.filter((s) => Number.isFinite(s.timestamp) && Number.isFinite(s.bytes)); if (clean.length < DIAGNOSTIC_POLICY.storageGrowth.minSamples) { return undefined; } - const xsDays = clean.map((s) => s.timestamp / MS_PER_DAY); + const xsDays = clean.map((s) => (s.timestamp - clean[0].timestamp) / MS_PER_DAY); const ys = clean.map((s) => s.bytes); const meanX = mean(xsDays); const meanY = mean(ys); let numerator = 0; let denominator = 0; + let weightedMagnitude = 0; for (let i = 0; i < clean.length; i++) { const dx = xsDays[i] - meanX; numerator += dx * (ys[i] - meanY); denominator += dx * dx; + weightedMagnitude += Math.abs(dx) * (Math.abs(ys[i]) + Math.abs(meanY)); } if (denominator === 0) { return undefined; } - return numerator / denominator; + // Scale summation roundoff by the original byte magnitudes, not the much smaller centered differences. + // This is numerical precision, not a tolerance on the growth policy or on measurement noise. + const accumulatedEpsilon = clean.length * Number.EPSILON; + const relativeRoundoff = accumulatedEpsilon / (1 - accumulatedEpsilon); + return { + slopeBytesPerDay: numerator / denominator, + roundoffBytesPerDay: (relativeRoundoff * weightedMagnitude) / denominator, + }; } /** diff --git a/src/panels/accountOverview/services/advisories/fetchers/logs.ts b/src/panels/accountOverview/services/advisories/fetchers/logs.ts index 77ac49381..9df1233e0 100644 --- a/src/panels/accountOverview/services/advisories/fetchers/logs.ts +++ b/src/panels/accountOverview/services/advisories/fetchers/logs.ts @@ -239,7 +239,12 @@ export async function fetchCrossPartitionShapes( avgFanout: num(r.avgFanout), maxFanout: Math.round(num(r.maxFanout)), })); - return { databaseId, containerId, shapes }; + return { + databaseId, + containerId, + shapes, + evaluationWindowSeconds: (timespan.endTime.getTime() - timespan.startTime.getTime()) / 1000, + }; } /** diff --git a/src/panels/accountOverview/services/advisories/fetchers/metrics.test.ts b/src/panels/accountOverview/services/advisories/fetchers/metrics.test.ts index 22568d599..e7d3e332e 100644 --- a/src/panels/accountOverview/services/advisories/fetchers/metrics.test.ts +++ b/src/panels/accountOverview/services/advisories/fetchers/metrics.test.ts @@ -5,16 +5,22 @@ import { describe, expect, it, vi } from 'vitest'; import { mockClient, type Series } from '../../testFixtures'; -import { getContainerIdlePeak, getContainerMergeStoragePeak, getContainerPartitionCount } from './metrics'; +import { + getAutoscaleUtilization, + getContainerIdlePeak, + getContainerIndexingUsage, + getContainerMergeStoragePeak, + getContainerPartitionCount, +} from './metrics'; const timestamp = '2026-01-01T00:00:00.000Z'; const readers = [ - { metric: 'TotalRequestUnits', read: getContainerIdlePeak, regionalPeak: 60 }, - { metric: 'PhysicalPartitionCount', read: getContainerPartitionCount, regionalPeak: 8 }, - { metric: 'DataUsage', read: getContainerMergeStoragePeak, regionalPeak: 8 }, + { metric: 'TotalRequestUnits', read: getContainerIdlePeak, regionalPeak: 60, emptyPeak: 0 }, + { metric: 'PhysicalPartitionCount', read: getContainerPartitionCount, regionalPeak: 8, emptyPeak: undefined }, + { metric: 'DataUsage', read: getContainerMergeStoragePeak, regionalPeak: 8, emptyPeak: undefined }, ]; -describe.each(readers)('$metric container evidence', ({ metric, read, regionalPeak }) => { +describe.each(readers)('$metric container evidence', ({ metric, read, regionalPeak, emptyPeak }) => { it.each([ { label: 'missing metric', value: [] }, { label: 'missing series', value: [{ timeseries: [] }] }, @@ -35,9 +41,116 @@ describe.each(readers)('$metric container evidence', ({ metric, read, regionalPe }, ], }, - ])('keeps $label unknown instead of returning zero', async ({ value }) => { + ])('applies the metric-specific empty policy to $label', async ({ value }) => { const client = mockClient({ [metric]: { value } }); - expect(await read(client, 'resource', 'db', 'container')).toBeUndefined(); + expect(await read(client, 'resource', 'db', 'container')).toBe(emptyPeak); + }); + + it('propagates request failures instead of treating them as empty telemetry', async () => { + const client = mockClient({}); + const error = new Error('Metric request failed'); + vi.spyOn(client.metrics, 'list').mockRejectedValueOnce(error); + await expect(read(client, 'resource', 'db', 'container')).rejects.toBe(error); + }); + + describe('diagnostic offer scope and indexing window', () => { + it('selects independently latest populated storage samples over six hours', async () => { + const client = mockClient({ + IndexUsage: { + value: [ + { + timeseries: [ + { + data: [ + { timeStamp: timestamp, maximum: 30 }, + { timeStamp: '2026-01-01T00:05:00.000Z', maximum: 40 }, + { timeStamp: '2026-01-01T00:10:00.000Z', maximum: null }, + ], + }, + ], + }, + ], + }, + DataUsage: { + value: [ + { + timeseries: [ + { + data: [ + { timeStamp: timestamp, maximum: 100 }, + { timeStamp: '2026-01-01T00:10:00.000Z', maximum: 200 }, + ], + }, + ], + }, + ], + }, + }); + const now = Date.parse('2026-01-01T00:15:00.000Z'); + const list = vi.spyOn(client.metrics, 'list'); + expect(await getContainerIndexingUsage(client, 'resource', 'db', 'container', now)).toEqual({ + indexUsageBytes: 40, + dataUsageBytes: 200, + }); + expect(list).toHaveBeenCalledWith( + 'resource', + expect.objectContaining({ + interval: 'PT5M', + timespan: '2025-12-31T18:15:00.000Z/2026-01-01T00:15:00.000Z', + filter: "CollectionName eq 'container' and DatabaseName eq 'db'", + }), + ); + }); + + it('retains missing index telemetry rather than turning it into zero', async () => { + const client = mockClient({ + IndexUsage: { value: [] }, + DataUsage: { value: [{ timeseries: [{ data: [{ timeStamp: timestamp, maximum: 100 }] }] }] }, + }); + expect(await getContainerIndexingUsage(client, 'resource', 'db', 'container')).toEqual({ + indexUsageBytes: undefined, + dataUsageBytes: 100, + }); + }); + + it('queries the empty collection dimension for a shared autoscale offer', async () => { + const client = mockClient({ + AutoscaledRU: { + value: [ + { + timeseries: [ + { data: [{ timeStamp: timestamp, maximum: 200 }] }, + { data: [{ timeStamp: timestamp, maximum: 200 }] }, + ], + }, + ], + }, + }); + const list = vi.spyOn(client.metrics, 'list'); + expect(await getAutoscaleUtilization(client, 'resource', 'db', undefined, 4000)).toEqual({ + peakPercent: 10, + avgPercent: 10, + sampleCount: 1, + }); + expect(list).toHaveBeenCalledWith( + 'resource', + expect.objectContaining({ + filter: "CollectionName eq '' and DatabaseName eq 'db' and PhysicalPartitionId eq '*'", + }), + ); + }); + + it('reads shared idle consumption from authoritative member containers', async () => { + const client = mockClient({ + TotalRequestUnits: { value: [{ timeseries: [{ data: [{ timeStamp: timestamp, total: 0 }] }] }] }, + }); + const list = vi.spyOn(client.metrics, 'list'); + expect(await getContainerIdlePeak(client, 'resource', 'db', undefined, undefined, ['member'])).toBe(0); + expect(list).toHaveBeenCalledExactlyOnceWith( + 'resource', + expect.objectContaining({ filter: "CollectionName eq 'member' and DatabaseName eq 'db'" }), + ); + }); }); it('preserves an observed zero and scopes both escaped identifiers without wildcard dimensions', async () => { diff --git a/src/panels/accountOverview/services/advisories/fetchers/metrics.ts b/src/panels/accountOverview/services/advisories/fetchers/metrics.ts index 3592b36be..0349517dd 100644 --- a/src/panels/accountOverview/services/advisories/fetchers/metrics.ts +++ b/src/panels/accountOverview/services/advisories/fetchers/metrics.ts @@ -7,9 +7,10 @@ import { type MonitorClient } from '@azure/arm-monitor'; import { querySeries } from '../../ruTrends'; import { containerFilter, - escapeODataLiteral, parseMonitorTimestamp, pickPointValue, + requestMetricFilter, + throughputOfferFilter, type MetricAggregation, type RangeConfig, } from '../../shared'; @@ -22,7 +23,7 @@ import { DIAGNOSTIC_POLICY } from '../core/thresholds'; // already fetch. Idle reads 30 days in five-minute buckets so periodic workloads are not mistaken for idle; // autoscale/serverless use hourly buckets, while partition-merge reads the most recent six hours. // All series are read as `Total`/`Maximum` and folded to per-container (or account-total) shapes the pure -// evaluators consume. Callers report failed or missing evidence as incomplete coverage, never assumed zero usage. +// evaluators consume. Failed reads remain incomplete coverage; only DX-004 treats successful empty consumption as idle. /** Builds the `start/end` ISO-8601 timespan for a diagnostic observation ending now. */ function advisoryTimespan(observation: RangeConfig, now = Date.now()): string { @@ -88,18 +89,19 @@ export async function getAccountConsumedRuShape( } /** - * Reads one known container without wildcard dimensions, so Azure Monitor's series limit cannot omit other - * containers. Only observed numeric samples count as evidence; an empty response remains unknown, not zero. + * Reads known containers without wildcard dimensions, so Azure Monitor's series limit cannot omit other + * containers. Shared member buckets are combined before taking the peak. An empty response remains unknown here. */ async function getContainerMetricPeak( client: MonitorClient, resourceUri: string, databaseId: string, - containerId: string, + containerId: string | undefined, metricName: string, aggregation: MetricAggregation, observation: RangeConfig, now: number, + sharedContainerIds?: readonly string[], ): Promise { const buckets = await querySeries( client, @@ -108,23 +110,28 @@ async function getContainerMetricPeak( aggregation, advisoryTimespan(observation, now), observation.interval, - containerFilter(databaseId, containerId), + requestMetricFilter(databaseId, containerId, sharedContainerIds), ); return buckets.size > 0 ? Math.max(...buckets.values()) : undefined; } /** - * Reads a container's peak `TotalRequestUnits` per bucket for the spike-aware idle gate (DX-004). - * Regional series are summed per bucket before taking the peak. + * Reads an offer's peak `TotalRequestUnits` per bucket for the spike-aware idle gate (DX-004). + * Shared membership must be explicit. Member and regional series are summed per bucket before taking the peak. + * Successful reads without usable samples count as idle; request and embedded metric errors still reject. */ export async function getContainerIdlePeak( client: MonitorClient, resourceUri: string, databaseId: string, - containerId: string, + containerId: string | undefined, now = Date.now(), -): Promise { - return getContainerMetricPeak( + sharedContainerIds?: readonly string[], +): Promise { + if (containerId === undefined && sharedContainerIds === undefined) { + throw new Error('Shared-offer idle metrics require authoritative container membership.'); + } + const peak = await getContainerMetricPeak( client, resourceUri, databaseId, @@ -133,7 +140,9 @@ export async function getContainerIdlePeak( 'Total', DIAGNOSTIC_POLICY.idle.observation, now, + sharedContainerIds, ); + return peak ?? 0; } /** @@ -193,8 +202,8 @@ export interface AutoscaleUtilizationSummary { } /** - * Reads one autoscale container's `AutoscaledRU` (`Maximum`) over the 30-day window, split by - * `PhysicalPartitionId`, sums the per-partition provisioned value at each timestamp (the container's provisioned + * Reads one autoscale offer's `AutoscaledRU` (`Maximum`) over the 30-day window, split by + * `PhysicalPartitionId`, sums the per-partition provisioned value at each timestamp (the offer's provisioned * value is the sum across partitions), and normalises by the configured max to a 0..100 "how much of the max was * provisioned" series. Returns its peak/average duty cycle for DX-011 (peak band) and DX-013 (steady-high read). */ @@ -202,13 +211,13 @@ export async function getAutoscaleUtilization( client: MonitorClient, resourceUri: string, databaseId: string, - containerId: string, + containerId: string | undefined, configuredMaxRu: number, ): Promise { - if (!(configuredMaxRu > 0)) { - return { peakPercent: 0, avgPercent: 0, sampleCount: 0 }; + if (!Number.isFinite(configuredMaxRu) || configuredMaxRu <= 0) { + throw new Error('Autoscale utilization requires a finite positive configured maximum.'); } - const filter = `DatabaseName eq '${escapeODataLiteral(databaseId)}' and CollectionName eq '${escapeODataLiteral(containerId)}' and PhysicalPartitionId eq '*'`; + const filter = `${throughputOfferFilter(databaseId, containerId)} and PhysicalPartitionId eq '*'`; const observation = DIAGNOSTIC_POLICY.autoscaleUtilization.observation; const response = await client.metrics.list(resourceUri, { metricnames: 'AutoscaledRU', @@ -248,3 +257,28 @@ export async function getAutoscaleUtilization( const peakPercent = Math.max(...percents); return { peakPercent, avgPercent, sampleCount: percents.length }; } + +/** Independently latest populated index/data samples, without summing replicas or imputing missing sizes. */ +export async function getContainerIndexingUsage( + client: MonitorClient, + resourceUri: string, + databaseId: string, + containerId: string, + now = Date.now(), +): Promise<{ indexUsageBytes?: number; dataUsageBytes?: number }> { + const observation = DIAGNOSTIC_POLICY.indexing.observation; + const read = async (metricName: string): Promise => { + const buckets = await querySeries( + client, + resourceUri, + metricName, + 'Maximum', + advisoryTimespan(observation, now), + observation.interval, + containerFilter(databaseId, containerId), + ); + return buckets.size > 0 ? buckets.get(Math.max(...buckets.keys())) : undefined; + }; + const [indexUsageBytes, dataUsageBytes] = await Promise.all([read('IndexUsage'), read('DataUsage')]); + return { indexUsageBytes, dataUsageBytes }; +} diff --git a/src/panels/accountOverview/services/advisories/nativeParity.test.ts b/src/panels/accountOverview/services/advisories/nativeParity.test.ts new file mode 100644 index 000000000..9a1f30ff6 --- /dev/null +++ b/src/panels/accountOverview/services/advisories/nativeParity.test.ts @@ -0,0 +1,406 @@ +/*--------------------------------------------------------------------------------------------- + * Copyright (c) Microsoft Corporation. All rights reserved. + * Licensed under the MIT License. See License.txt in the project root for license information. + *--------------------------------------------------------------------------------------------*/ + +import { describe, expect, expectTypeOf, it } from 'vitest'; +import { API } from '../../../../AzureDBExperiences'; +import { DEFAULT_ADVISORY_THRESHOLDS } from './core/thresholds'; +import { + type AdvisoryEvaluation, + type ConsistencyReadRuInput, + type CrossPartitionInput, + type DerivedAdvisoryInputs, +} from './core/types'; +import { AutoscaleMaxOverProvisionedDetector } from './detectors/AutoscaleMaxOverProvisionedDetector'; +import { CrossPartitionQueryDetector } from './detectors/CrossPartitionQueryDetector'; +import { ExpensiveConsistencyDetector } from './detectors/ExpensiveConsistencyDetector'; +import { IndexingCostRiskDetector } from './detectors/IndexingCostRiskDetector'; +import { PartitionMergeCandidateDetector } from './detectors/PartitionMergeCandidateDetector'; +import { ShardKeyMisalignmentDetector } from './detectors/ShardKeyMisalignmentDetector'; +import { SharedThroughputStarvationDetector } from './detectors/SharedThroughputStarvationDetector'; +import { computeDerivedAdvisories } from './engine'; + +const base: DerivedAdvisoryInputs = { + weeklyRuPercents: [], + hasManualThroughput: false, + partitions: [], + storage: [], + indexing: [], +}; + +describe('diagnostic result types', () => { + it('constrains each detector to its own root causes and observations', () => { + expectTypeOf(new IndexingCostRiskDetector().evaluateResult).returns.toEqualTypeOf< + AdvisoryEvaluation<'IndexingCostRisk'> + >(); + expectTypeOf['rootCause']>().toEqualTypeOf< + 'insufficient_data' | 'active' | 'idle' + >(); + expectTypeOf< + Extract, { rootCause: 'idle' }>['observations'] + >().toEqualTypeOf<{ recoverableRu: number }>(); + expectTypeOf< + Extract, { rootCause: 'insufficient_data' | 'active' }>['observations'] + >().toEqualTypeOf(); + expectTypeOf< + Extract< + AdvisoryEvaluation<'StorageGrowthRisk'>, + { rootCause: 'rapid_growth' | 'at_or_over_limit' } + >['observations'] + >().toEqualTypeOf<{ daysToLimit: number }>(); + }); +}); + +function fanout(crossQueries: number, totalQueries: number, partitions: number, seconds = 3600): CrossPartitionInput { + return { + databaseId: 'db', + containerId: 'items', + evaluationWindowSeconds: seconds, + shapes: [ + { text: 'SELECT * FROM c', executions: crossQueries, avgFanout: partitions, maxFanout: partitions }, + { + text: 'SELECT * FROM c WHERE c.pk = @pk', + executions: totalQueries - crossQueries, + avgFanout: 1, + maxFanout: 1, + }, + ], + }; +} + +describe('optional RU evidence is not detection policy or money', () => { + it.each([undefined, 0, 0.01, 500, NaN, Infinity, -1])( + 'preserves fan-out and supersession decisions with average RU %s', + (avgRu) => { + const input = fanout(3600, 4000, 7); + const enriched = { + ...input, + observationStart: '2026-11-11T08:00:00Z', + observationEnd: '2026-11-11T09:00:00Z', + shapes: input.shapes.map((shape) => ({ ...shape, avgRu })), + }; + const before = computeDerivedAdvisories({ ...base, crossPartition: [input] }, DEFAULT_ADVISORY_THRESHOLDS); + const after = computeDerivedAdvisories( + { ...base, crossPartition: [enriched] }, + DEFAULT_ADVISORY_THRESHOLDS, + ); + const decisions = (items: typeof before) => + items.map(({ id, severity, supersededBy }) => ({ id, severity, supersededBy })); + expect(decisions(after)).toEqual(decisions(before)); + expect(after).toHaveLength(2); + const valid = avgRu !== undefined && Number.isFinite(avgRu) && avgRu >= 0; + for (const finding of after) { + expect(finding.evidence?.queryRuStatus).toBe(valid ? 'observed' : 'unavailable'); + expect(finding.evidence?.worstShapeAvgRu).toBe(valid ? avgRu : undefined); + expect(finding.evidence?.observationStart).toBe(valid ? enriched.observationStart : undefined); + expect(finding.suggestedAction.includes('not estimated savings')).toBe(valid); + } + }, + ); + + const readCharge: ConsistencyReadRuInput = { + status: 'observed', + readRequests: 10, + readRu: 400, + sourceTable: 'CDBDataPlaneRequests5M', + sourceResolution: 'PT5M', + observationStart: '2026-11-10T09:15:00Z', + observationEnd: '2026-11-11T09:15:00Z', + }; + + it.each([ + undefined, + readCharge, + { ...readCharge, readRu: 0 }, + { ...readCharge, status: 'noObservations' as const, readRequests: 0, readRu: 0 }, + { ...readCharge, readRu: NaN }, + { ...readCharge, readRequests: 0.5 }, + ])('preserves the configuration verdict for read-charge evidence %j', (observed) => { + const detector = new ExpensiveConsistencyDetector(); + const config = { + accountName: 'prod', + consistencyLevel: 'Strong', + regionCount: 2, + multiRegionWritesEnabled: false, + writeRegionCount: 1, + api: API.Core, + }; + const finding = detector.evaluate(config, observed); + expect(finding).toMatchObject({ + rule: 'ExpensiveConsistency', + severity: 'Medium', + actionEligibility: 'requiresValidation', + }); + const valid = + observed?.status === 'observed' && observed.readRequests === 10 && Number.isFinite(observed.readRu); + expect(finding?.evidence?.observedReadRu).toBe(valid ? observed.readRu : undefined); + expect(finding?.evidence?.upperBoundAvoidableReadRu).toBe(valid ? observed.readRu / 2 : undefined); + expect(finding?.suggestedAction.includes('not measured or monetary savings')).toBe(valid); + expect(finding?.evidence?.sourceTable).toBe(valid ? 'CDBDataPlaneRequests5M' : undefined); + expect(detector.evaluate({ ...config, consistencyLevel: 'Session' }, observed)).toBeUndefined(); + }); +}); + +describe('native autoscale model', () => { + const detector = new AutoscaleMaxOverProvisionedDetector(); + it.each([ + [400, 10, 400, 0], + [1000, 10, 1000, 0], + [4000, 10, 1000, 300], + [4000, 19.25, 1001, 299.9], + [10000, 10, 1300, 870], + ])('models maximum %s at peak %s without the manual floor clamp', (max, peak, target, recovery) => { + const result = detector.evaluate( + { + databaseId: 'db', + sampleCount: 24, + configuredMaxRu: max, + peakPercent: peak, + avgPercent: peak, + }, + 30, + 30000, + ); + expect(result?.scope).toBe('db'); + expect(result?.evidence?.recommendedMaxRu).toBe(target); + expect(result?.evidence?.recoverableIdleFloorRu).toBeCloseTo(recovery); + expect(result?.actionEligibility).toBe(recovery > 0 ? 'requiresValidation' : 'blocked'); + expect(result?.suggestedAction).toMatch(recovery === 0 ? /No maximum reduction/ : /Review lowering/); + }); + + it.each([NaN, Infinity, -1, 0])('rejects an invalid maximum %s', (max) => { + expect( + detector.evaluate( + { databaseId: 'db', peakPercent: 10, avgPercent: 10, sampleCount: 24, configuredMaxRu: max }, + 30, + ), + ).toBeUndefined(); + }); + + it.each([29.99, 30, 30.01, 90])('uses the unrounded peak-band boundary %s', (peak) => { + const result = detector.evaluate( + { databaseId: 'db', peakPercent: peak, avgPercent: peak, sampleCount: 24, configuredMaxRu: 10000 }, + 30, + ); + expect(Boolean(result)).toBe(peak < 30); + }); + + it.each([ + [4000, 'High'], + [30000, 'Medium'], + [100000, 'Low'], + ] as const)('uses the unchanged offer-capacity denominator %s', (scope, severity) => { + expect( + detector.evaluate( + { databaseId: 'db', peakPercent: 10, avgPercent: 10, sampleCount: 24, configuredMaxRu: 4000 }, + 30, + scope, + )?.severity, + ).toBe(severity); + }); +}); + +describe('fan-out decisions at the observation interface', () => { + it.each([59.95, 59.99, 60, 60.01])('does not round share %s before classification', (pct) => { + const result = new ShardKeyMisalignmentDetector().evaluate( + fanout(Math.round(pct * 100), 10000, 7), + { structuralPct: 60, minPartitions: 2 }, + 1.5, + ); + const expectedShare = expect.closeTo(pct); + expect(Boolean(result)).toBe(pct >= 60); + expect(result?.evidence?.crossPartitionPct).toEqual(pct >= 60 ? expectedShare : undefined); + }); + + it.each([ + [359, undefined], + [360, 'Medium'], + [361, 'Medium'], + [3599, 'Medium'], + [3600, 'High'], + [3601, 'High'], + ] as const)('classifies %s fan-out queries per hour before rate rounding', (queries, severity) => { + const result = new ShardKeyMisalignmentDetector().evaluate( + fanout(queries, queries, 7), + { structuralPct: 60, minPartitions: 2 }, + 1.5, + ); + expect(result?.severity).toBe(severity); + }); + + it.each([ + [2, 0.1, 'Low'], + [3, 1, 'Low'], + [4, 0.1, 'Low'], + [6, 1, 'Medium'], + [7, 0.1, 'Medium'], + [7, 1, 'High'], + ] as const)('grades %s partitions at %s queries/s as %s', (partitions, rate, severity) => { + const result = new CrossPartitionQueryDetector().evaluate(fanout(rate * 3600, rate * 3600, partitions), { + minQueries: 50, + fanoutThreshold: 1.5, + medPct: 10, + }); + expect(result?.severity).toBe(severity); + }); + + it('uses the supplied duration rather than a fixed daily denominator', () => { + const detector = new CrossPartitionQueryDetector(); + const thresholds = { minQueries: 50, fanoutThreshold: 1.5, medPct: 10 }; + expect(detector.evaluate(fanout(360, 360, 7, 3600), thresholds)?.severity).toBe('Medium'); + expect(detector.evaluate(fanout(360, 360, 7, 7200), thresholds)).toBeUndefined(); + expect(detector.evaluate(fanout(360, 360, 7, NaN), thresholds)).toBeUndefined(); + }); +}); + +describe('merge structure versus action eligibility', () => { + const detector = new PartitionMergeCandidateDetector(); + const input = { + databaseId: 'db', + containerId: 'items', + actualPartitions: 4, + provisionedRu: 10000, + dataUsageBytes: 0, + }; + + it.each([undefined, NaN, Infinity, -1])('requires finite known throughput and storage (%s)', (value) => { + expect(detector.evaluate({ ...input, provisionedRu: value })).toBeUndefined(); + expect(detector.evaluate({ ...input, dataUsageBytes: value })).toBeUndefined(); + }); + + it('does not mistake 180 GiB for zero storage', () => { + expect(detector.evaluate({ ...input, dataUsageBytes: 180 * 1024 ** 3 })).toBeUndefined(); + expect(detector.evaluate(input)?.severity).toBe('Medium'); + }); + + it.each([ + [{ type: 'Continuous' }, 'blocked'], + [{ type: 'Periodic' }, 'requiresValidation'], + [{ type: 'Periodic', migrationState: { status: 'Completed', targetType: 'Periodic' } }, 'requiresValidation'], + [undefined, 'unknown'], + [{ type: 'Periodic', migrationState: { status: 'InProgress', targetType: 'Continuous' } }, 'unknown'], + [{ type: 'Periodic', fullFidelityChangeFeedEnabled: true }, 'blocked'], + ] as const)('retains the finding while gating backup state %j', (backupPolicy, eligibility) => { + const result = detector.evaluate({ ...input, backupPolicy }); + expect(result?.severity).toBe('Medium'); + expect(result?.actionEligibility).toBe(eligibility); + expect(result?.suggestedAction).not.toMatch(/Merge the physical partitions/); + }); +}); + +describe('configuration and indexing adoption', () => { + it('suppresses explicitly disabled indexing and rejects non-finite storage sizes', () => { + const detector = new IndexingCostRiskDetector(); + const input = { + databaseId: 'db', + containerId: 'items', + indexUsageBytes: 200, + dataUsageBytes: 100, + userExcludedPathCount: 0, + }; + expect(detector.evaluate({ ...input, indexingMode: 'none' }, 0.3)).toBeUndefined(); + expect(detector.evaluate({ ...input, dataUsageBytes: NaN }, 0.3)).toBeUndefined(); + expect(detector.evaluate({ ...input, indexUsageBytes: Infinity }, 0.3)).toBeUndefined(); + }); + + it.each([ + ['Strong', 1, 'Medium'], + ['Strong', 2, 'Medium'], + ['BoundedStaleness', 1, undefined], + ['BoundedStaleness', 2, 'Low'], + ['Strong', 0, undefined], + ['Strong', NaN, undefined], + ['Session', 2, undefined], + ] as const)( + 'evaluates %s in %s regions without conflating local and regional costs', + (consistencyLevel, regionCount, severity) => { + const result = new ExpensiveConsistencyDetector().evaluate({ + accountName: 'acct', + regionCount, + consistencyLevel, + multiRegionWritesEnabled: false, + writeRegionCount: 1, + api: API.Core, + }); + const tokenGuidance = expect.stringContaining('SessionToken'); + const correctnessGuidance = expect.stringContaining('not equivalent'); + expect(result?.severity).toBe(severity); + expect(result?.suggestedAction).toEqual(severity ? tokenGuidance : undefined); + expect(result?.suggestedAction).toEqual(severity ? correctnessGuidance : undefined); + }, + ); + + it.each([ + [0.3, undefined], + [0.31, 'Low'], + [1, 'Low'], + [1.01, 'Medium'], + ] as const)('uses ratio %s with user exclusions as evidence, not a veto', (ratio, severity) => { + const result = new IndexingCostRiskDetector().evaluate( + { + databaseId: 'db', + containerId: 'items', + indexUsageBytes: ratio * 100, + dataUsageBytes: 100, + userExcludedPathCount: 2, + }, + 0.3, + ); + expect(result?.severity).toBe(severity); + expect(result?.evidence?.userExcludedPathCount).toBe(severity ? 2 : undefined); + }); +}); + +describe('shared offer ownership', () => { + it('filters dedicated siblings before shared-pool totals and dominance decisions', () => { + const detector = new SharedThroughputStarvationDetector(); + const thresholds = { + minRequests: 100, + poolThrottlePct: 5, + dominancePct: 60, + victimThrottlePct: 5, + victimSharePct: 20, + }; + const input = { + databaseId: 'db', + sharedRu: 4000, + sharedContainerIds: ['a', 'b'], + collections: [ + { containerId: 'a', requests: 1000, throttledRequests: 50, ruConsumed: 80 }, + { containerId: 'b', requests: 1000, throttledRequests: 50, ruConsumed: 20 }, + { containerId: 'dedicated', requests: 100000, throttledRequests: 0, ruConsumed: 10000 }, + ], + }; + expect(detector.evaluate(input, thresholds)?.severity).toBe('High'); + expect(detector.evaluate({ ...input, sharedContainerIds: ['b'] }, thresholds)).toBeUndefined(); + expect(detector.evaluate({ ...input, sharedContainerIds: undefined }, thresholds)).toBeUndefined(); + }); + + it('keeps database-scoped recovery and supersession separate from a dedicated sibling', () => { + const results = computeDerivedAdvisories( + { + ...base, + scopeProvisionedRuTotal: 5000, + manualThroughput: [ + { databaseId: 'db', provisionedRu: 4000, ruPercents: Array(24).fill(10) }, + { + databaseId: 'db', + containerId: 'dedicated', + provisionedRu: 1000, + ruPercents: Array(24).fill(10), + }, + ], + idleContainers: [ + { databaseId: 'db', throughputMode: 'shared', provisionedRu: 4000, peakRuPerBucket: 0 }, + ], + }, + DEFAULT_ADVISORY_THRESHOLDS, + ); + expect( + results.find((result) => result.rule === 'OverProvisioning' && result.scope === 'db')?.supersededBy, + ).toBe('IdleContainer'); + expect(results.find((result) => result.scope === 'db/dedicated')?.supersededBy).toBeUndefined(); + expect(results.filter((result) => result.rule === 'IdleContainer')).toHaveLength(1); + }); +}); diff --git a/src/panels/accountOverview/services/advisories/offerMetrics.test.ts b/src/panels/accountOverview/services/advisories/offerMetrics.test.ts new file mode 100644 index 000000000..fb718b033 --- /dev/null +++ b/src/panels/accountOverview/services/advisories/offerMetrics.test.ts @@ -0,0 +1,256 @@ +/*--------------------------------------------------------------------------------------------- + * Copyright (c) Microsoft Corporation. All rights reserved. + * Licensed under the MIT License. See License.txt in the project root for license information. + *--------------------------------------------------------------------------------------------*/ + +import { CosmosDBManagementClient } from '@azure/arm-cosmosdb'; +import { + MonitorClient, + type MetricValue, + type Response as MetricsResponse, + type TimeSeriesElement, +} from '@azure/arm-monitor'; +import { afterEach, describe, expect, it, vi } from 'vitest'; +import { API } from '../../../../AzureDBExperiences'; +import { dims, GB, pagedItems, pdims } from '../testFixtures'; +import { collectDerivedAdvisories } from './collect'; +import { DEFAULT_ADVISORY_THRESHOLDS } from './core/thresholds'; +import { getContainerIdlePeak } from './fetchers/metrics'; + +afterEach(() => { + vi.restoreAllMocks(); +}); + +function fixture(mode: 'manual' | 'autoscale', activeShared = false, deniedMetric?: string) { + const credential = { + getToken: async () => { + throw new Error('Network access is forbidden in offer metric tests.'); + }, + }; + const cosmosClient = new CosmosDBManagementClient(credential, 'fixture'); + const monitorClient = new MonitorClient(credential, 'fixture'); + const createdAt = new Date('2020-01-01T00:00:00.000Z'); + const notFound = Object.assign(new Error('No dedicated offer'), { statusCode: 404 }); + vi.spyOn(cosmosClient.databaseAccounts, 'get').mockResolvedValue({ systemData: { createdAt } }); + vi.spyOn(cosmosClient.sqlResources, 'listSqlDatabases').mockImplementation(() => + pagedItems([{ resource: { id: 'mixed-db' }, systemData: { createdAt } }]), + ); + vi.spyOn(cosmosClient.sqlResources, 'listSqlContainers').mockImplementation(() => + pagedItems( + ['shared-a', 'shared-b', 'dedicated'].map((id) => ({ + resource: { id, indexingPolicy: { indexingMode: 'none' } }, + systemData: { createdAt }, + })), + ), + ); + vi.spyOn(cosmosClient.sqlResources, 'getSqlDatabaseThroughput').mockResolvedValue({ + resource: mode === 'manual' ? { throughput: 4000 } : { autoscaleSettings: { maxThroughput: 4000 } }, + }); + vi.spyOn(cosmosClient.sqlResources, 'getSqlContainerThroughput').mockImplementation( + async (_rg, _account, _database, container) => { + if (container !== 'dedicated') { + throw notFound; + } + return { + resource: mode === 'manual' ? { throughput: 10000 } : { autoscaleSettings: { maxThroughput: 10000 } }, + }; + }, + ); + + const points = (field: 'maximum' | 'total' | 'count', value: number): MetricValue[] => + Array.from({ length: 24 }, (_, index) => ({ + timeStamp: new Date(Date.UTC(2026, 0, 1, index)), + [field]: value, + })); + const response = (metric: string, timeseries: TimeSeriesElement[]): MetricsResponse => ({ + timespan: '', + value: [ + { id: 'fixture', type: 'Microsoft.Insights/metrics', name: { value: metric }, unit: 'Count', timeseries }, + ], + }); + const list = vi.spyOn(monitorClient.metrics, 'list').mockImplementation(async (_resource, options) => { + const metric = options?.metricnames ?? ''; + const collection = options?.filter?.match(/CollectionName eq '((?:''|[^'])*)'/)?.[1]?.replaceAll("''", "'"); + if (metric === deniedMetric && collection === 'shared-b') { + throw Object.assign(new Error('Metric access denied'), { statusCode: 403 }); + } + if (metric === 'NormalizedRUConsumption' || metric === 'AutoscaledRU') { + // Shared throughput has offer-level telemetry, not per-member utilization series. + if (collection === 'shared-a' || collection === 'shared-b') { + return response(metric, []); + } + const sharedValues = metric === 'AutoscaledRU' ? [200, 200] : [15, 10]; + const dedicatedValues = metric === 'AutoscaledRU' ? [5000, 5000] : [100, 100]; + const values = + collection === '' + ? sharedValues + : collection === 'dedicated' + ? dedicatedValues + : [...sharedValues, ...dedicatedValues]; + return response( + metric, + values.map((value, index) => ({ + metadatavalues: pdims('mixed-db', collection ?? '', 'PhysicalPartitionId', `${index}`), + data: points('maximum', value), + })), + ); + } + if (metric === 'TotalRequestUnits') { + const shared = activeShared ? 30 : 0; + const total = collection === undefined ? 10000 + shared * 2 : collection === 'dedicated' ? 10000 : shared; + return response(metric, [{ data: points('total', total) }]); + } + if (metric === 'TotalRequests') { + const counts = collection === undefined ? [2080, 920] : collection === 'dedicated' ? [100, 900] : [990, 10]; + return response( + metric, + counts.map((count, index) => ({ + metadatavalues: options?.filter?.includes('OperationType') + ? [{ name: { value: 'OperationType' }, value: index === 0 ? 'Read' : 'Create' }] + : dims('mixed-db', collection ?? '', index === 0 ? '200' : '429'), + data: points('count', count), + })), + ); + } + return response(metric, [ + { + metadatavalues: pdims('mixed-db', collection ?? '', 'PhysicalPartitionId', '0'), + data: points('maximum', metric === 'PhysicalPartitionCount' ? 1 : 10 * GB), + }, + ]); + }); + + const collect = () => + collectDerivedAdvisories({ + monitorClient, + cosmosClient, + accountId: 'fixture-account', + resourceGroup: 'rg', + accountName: 'acct-prod', + isServerless: false, + advisoryThresholds: DEFAULT_ADVISORY_THRESHOLDS, + accountConfig: { + accountName: 'acct-prod', + regionCount: 1, + writeRegionCount: 1, + multiRegionWritesEnabled: false, + api: API.Core, + backupPolicy: { type: 'Periodic' }, + perRegionPerPartitionAutoscaleEnabled: true, + }, + }); + return { monitorClient, list, collect }; +} + +describe('mixed shared and dedicated offer metric acquisition', () => { + it.each(['manual', 'autoscale'] as const)( + 'does not let busy dedicated traffic hide an idle %s shared offer', + async (mode) => { + const { collect, list } = fixture(mode); + const result = await collect(); + expect(result.advisories.filter((advisory) => advisory.rule === 'IdleContainer')).toEqual([ + expect.objectContaining({ scope: 'mixed-db' }), + ]); + const idleFilters = list.mock.calls + .filter( + ([, options]) => + options?.metricnames === 'TotalRequestUnits' && options.filter?.includes('DatabaseName'), + ) + .map(([, options]) => options?.filter); + expect(idleFilters).toHaveLength(3); + expect(idleFilters).toEqual( + expect.arrayContaining([ + "CollectionName eq 'dedicated' and DatabaseName eq 'mixed-db'", + "CollectionName eq 'shared-a' and DatabaseName eq 'mixed-db'", + "CollectionName eq 'shared-b' and DatabaseName eq 'mixed-db'", + ]), + ); + expect(result.metricSource).toEqual({ available: true, failures: [] }); + }, + ); + + it.each(['manual', 'autoscale'] as const)( + 'isolates %s utilization and partition/request signals from dedicated siblings', + async (mode) => { + const { collect } = fixture(mode, true); + const result = await collect(); + const sharedRules = result.advisories + .filter((advisory) => advisory.scope === 'mixed-db') + .map((advisory) => advisory.rule); + expect(sharedRules).toContain(mode === 'manual' ? 'OverProvisioning' : 'AutoscaleMaxOverProvisioned'); + expect(sharedRules).not.toContain('IdleContainer'); + expect(sharedRules).not.toContain('SustainedThrottlingInRegion'); + expect(sharedRules).not.toContain('HotPartitionRisk'); + expect(result.advisories).toContainEqual( + expect.objectContaining({ + rule: 'SustainedThrottlingInRegion', + scope: 'mixed-db/dedicated', + }), + ); + }, + ); + + it.each(['TotalRequestUnits', 'TotalRequests'])( + 'reports a member failure in %s without a false clean/idle result', + async (metric) => { + const { collect } = fixture('manual', false, metric); + const result = await collect(); + expect(result.metricSource.failures).toContainEqual({ + rule: metric === 'TotalRequestUnits' ? 'IdleContainer' : 'SustainedThrottlingInRegion', + scope: 'mixed-db', + reason: 'rbac', + }); + expect(result.advisories).toContainEqual( + expect.objectContaining({ + rule: 'SustainedThrottlingInRegion', + scope: 'mixed-db/dedicated', + }), + ); + expect(result.advisories.filter((advisory) => advisory.rule === 'IdleContainer')).toHaveLength( + metric === 'TotalRequestUnits' ? 0 : 1, + ); + }, + ); + + it('sums aligned member buckets before taking the idle peak', async () => { + const { monitorClient, list } = fixture('manual'); + list.mockImplementation(async (_resource, options) => ({ + timespan: '', + value: [ + { + id: 'fixture', + type: 'Microsoft.Insights/metrics', + name: { value: 'TotalRequestUnits' }, + unit: 'Count', + timeseries: [ + { + data: [0, 1].map((index) => ({ + timeStamp: new Date(Date.UTC(2026, 0, 1, index)), + total: + options?.filter?.includes("CollectionName eq 'shared-a'") === (index === 0) + ? 40 + : 0, + })), + }, + ], + }, + ], + })); + expect( + await getContainerIdlePeak(monitorClient, 'fixture', 'mixed-db', undefined, undefined, [ + 'shared-a', + 'shared-b', + 'shared-a', + ]), + ).toBe(40); + }); + + it('requires membership and does not discover containers through a database-wide idle query', async () => { + const { monitorClient, list } = fixture('manual'); + await expect(getContainerIdlePeak(monitorClient, 'fixture', 'mixed-db', undefined)).rejects.toThrow( + 'authoritative container membership', + ); + expect(await getContainerIdlePeak(monitorClient, 'fixture', 'mixed-db', undefined, undefined, [])).toBe(0); + expect(list).not.toHaveBeenCalled(); + }); +}); diff --git a/src/panels/accountOverview/services/diagnosticPolicy.test.ts b/src/panels/accountOverview/services/diagnosticPolicy.test.ts index 26b119e30..2e523e8dd 100644 --- a/src/panels/accountOverview/services/diagnosticPolicy.test.ts +++ b/src/panels/accountOverview/services/diagnosticPolicy.test.ts @@ -45,10 +45,8 @@ describe('diagnostic policy compatibility', () => { serverlessPeakCeilingRuPerSec: 5000, crossPartitionMinQueries: 50, crossPartitionFanoutThreshold: 1.5, - crossPartitionHighPct: 30, crossPartitionMedPct: 10, shardKeyStructuralPct: 60, - shardKeyHighPct: 80, ingestionWriteRuPctFloor: 80, ingestionThrottleRatePct: 10, ingestionHighPct: 20, diff --git a/src/panels/trpc/routers/accountOverview/derivedAdvisoriesRouter.test.ts b/src/panels/trpc/routers/accountOverview/derivedAdvisoriesRouter.test.ts index 4409c3846..ae5f020f2 100644 --- a/src/panels/trpc/routers/accountOverview/derivedAdvisoriesRouter.test.ts +++ b/src/panels/trpc/routers/accountOverview/derivedAdvisoriesRouter.test.ts @@ -10,6 +10,7 @@ import { API } from '../../../../AzureDBExperiences'; import { collectDerivedAdvisories } from '../../../accountOverview/services/advisories'; import type * as advisories from '../../../accountOverview/services/advisories'; import { DEFAULT_ADVISORY_THRESHOLDS } from '../../../accountOverview/services/advisories/core/thresholds'; +import { PartitionMergeCandidateDetector } from '../../../accountOverview/services/advisories/detectors/PartitionMergeCandidateDetector'; import { mockClient } from '../../../accountOverview/services/testFixtures'; import { getDerivedAdvisoriesForAccount } from './derivedAdvisoriesRouter'; @@ -27,12 +28,18 @@ function metadata(account: DatabaseAccountGetResults = {}) { accountId: '/subscriptions/sub/resourceGroups/rg/providers/Microsoft.DocumentDB/databaseAccounts/account', accountName: 'account', resourceGroup: 'rg', - subscription: { name: 'Production' }, + subscription: { + name: 'Production', + subscriptionId: 'sub', + environment: { resourceManagerEndpointUrl: 'https://management.azure.com' }, + }, isServerless: false, databaseAccount: { kind: 'GlobalDocumentDB', locations: [{ locationName: 'westus' }, { locationName: 'eastus' }], consistencyPolicy: { defaultConsistencyLevel: 'Strong' }, + backupPolicy: { type: 'Periodic' }, + enablePerRegionPerPartitionAutoscale: true, ...account, }, getMonitorClient: vi.fn().mockResolvedValue(mockClient({})), @@ -46,6 +53,56 @@ function metadata(account: DatabaseAccountGetResults = {}) { beforeEach(() => vi.clearAllMocks()); describe('account advisory acquisition', () => { + it.each([ + [true, { type: 'Periodic' }, 'blocked'], + [false, { type: 'Periodic' }, 'requiresValidation'], + [undefined, { type: 'Periodic' }, 'requiresValidation'], + [true, undefined, 'blocked'], + [false, undefined, 'unknown'], + [undefined, undefined, 'unknown'], + ] as const)( + 'preserves change-feed state %s with backup %j through merge eligibility %s', + async (enabled, backupPolicy, eligibility) => { + vi.mocked(collectDerivedAdvisories).mockResolvedValueOnce({ + advisories: [], + logSource: { available: true }, + metricSource: { available: true, failures: [] }, + }); + const account = { backupPolicy, enableAllVersionsAndDeletesChangeFeed: enabled }; + await getDerivedAdvisoriesForAccount(metadata(account)); + const params = vi.mocked(collectDerivedAdvisories).mock.calls[0][0]; + expect(params.accountConfig?.backupPolicy?.fullFidelityChangeFeedEnabled).toBe(enabled); + const merge = new PartitionMergeCandidateDetector().evaluate({ + databaseId: 'db', + containerId: 'items', + actualPartitions: 4, + provisionedRu: 1000, + dataUsageBytes: 0, + backupPolicy: params.accountConfig?.backupPolicy, + }); + expect(merge?.actionEligibility).toBe(eligibility); + expect(params.accountConfig?.backupPolicy?.type).toBe(backupPolicy?.type); + }, + ); + + it('passes existing ARM backup and migration metadata without acquiring another identity', async () => { + const backupPolicy = { type: 'Periodic', migrationState: { status: 'InProgress', targetType: 'Continuous' } }; + const input = metadata({ backupPolicy }); + vi.mocked(collectDerivedAdvisories).mockResolvedValueOnce({ + advisories: [], + logSource: { available: false, reason: 'noData' }, + metricSource: { available: true, failures: [] }, + }); + await getDerivedAdvisoriesForAccount(input); + expect(collectDerivedAdvisories).toHaveBeenCalledWith( + expect.objectContaining({ + accountConfig: expect.objectContaining({ backupPolicy }), + }), + ); + expect(input.getClient).toHaveBeenCalledOnce(); + expect(input.getMonitorClient).toHaveBeenCalledOnce(); + }); + it.each(['unsupported', 'noData', 'rbac'] as const)( 'separates metric and log coverage in the %s configuration-only fallback', async (reason) => { diff --git a/src/panels/trpc/routers/accountOverview/derivedAdvisoriesRouter.ts b/src/panels/trpc/routers/accountOverview/derivedAdvisoriesRouter.ts index 75498c630..ca296226b 100644 --- a/src/panels/trpc/routers/accountOverview/derivedAdvisoriesRouter.ts +++ b/src/panels/trpc/routers/accountOverview/derivedAdvisoriesRouter.ts @@ -35,12 +35,19 @@ type AdvisoryAccountMetadata = Pick< | 'getMonitorClient' | 'getClient' | 'getLogsQueryClient' -> & { subscription: { readonly name: string } }; +> & { + subscription: { + readonly name: string; + readonly subscriptionId: string; + readonly environment: { readonly resourceManagerEndpointUrl: string }; + }; +}; export async function getDerivedAdvisoriesForAccount( metadata: AdvisoryAccountMetadata, ): Promise { const account = metadata.databaseAccount as DatabaseAccountGetResults; + const fullFidelityChangeFeedEnabled = metadata.databaseAccount.enableAllVersionsAndDeletesChangeFeed; const api = tryGetExperience(account)?.api; const accountConfig: AccountConfigInput = { accountName: metadata.accountName, @@ -51,6 +58,21 @@ export async function getDerivedAdvisoriesForAccount( multiRegionWritesEnabled: account.enableMultipleWriteLocations ?? false, writeRegionCount: account.writeLocations?.length ?? 0, api, + isServerless: metadata.isServerless, + perRegionPerPartitionAutoscaleEnabled: account.enablePerRegionPerPartitionAutoscale, + backupPolicy: + account.backupPolicy || fullFidelityChangeFeedEnabled !== undefined + ? { + type: account.backupPolicy?.type, + migrationState: account.backupPolicy?.migrationState, + continuousTier: + account.backupPolicy?.type === 'Continuous' && + 'continuousModeProperties' in account.backupPolicy + ? account.backupPolicy.continuousModeProperties?.tier + : undefined, + fullFidelityChangeFeedEnabled, + } + : undefined, }; const advisoryThresholds = DEFAULT_ADVISORY_THRESHOLDS; const configOnly = (reason: UnavailableReason): DerivedAdvisoriesResult => ({ @@ -69,15 +91,17 @@ export async function getDerivedAdvisoriesForAccount( ), metricSource: { available: false, - failures: DETECTORS.filter( - ({ rule }) => - rule !== 'ExpensiveConsistency' && - rule !== 'MultiRegionWriteAntipattern' && - rule !== 'CrossPartitionQuery' && - rule !== 'ShardKeyMisalignment' && - rule !== 'UncontrolledIngestion' && - rule !== 'SharedThroughputStarvation', - ).map(({ rule }) => ({ rule, reason })), + failures: [ + ...DETECTORS.filter( + ({ rule }) => + rule !== 'ExpensiveConsistency' && + rule !== 'MultiRegionWriteAntipattern' && + rule !== 'CrossPartitionQuery' && + rule !== 'ShardKeyMisalignment' && + rule !== 'UncontrolledIngestion' && + rule !== 'SharedThroughputStarvation', + ).map(({ rule }) => ({ rule, reason })), + ], }, logSource: { available: false, reason }, generatedAt: Date.now(), diff --git a/src/webviews/cosmosdb/AccountOverview/AccountOverview.test.tsx b/src/webviews/cosmosdb/AccountOverview/AccountOverview.test.tsx index 6b7ca9bbb..45f44836d 100644 --- a/src/webviews/cosmosdb/AccountOverview/AccountOverview.test.tsx +++ b/src/webviews/cosmosdb/AccountOverview/AccountOverview.test.tsx @@ -3205,7 +3205,7 @@ describe('tabbed Account Overview', () => { ], }); render(, { wrapper: Wrapper }); - const card = await screen.findByRole('button', { name: /^Idle containers/ }); + const card = await screen.findByRole('button', { name: /^Idle provisioned offers/ }); await user.click(card); const close = screen.getByRole('button', { name: 'Close' }); close.focus(); @@ -3251,7 +3251,7 @@ describe('tabbed Account Overview', () => { ], }); render(, { wrapper: Wrapper }); - await user.click(await screen.findByRole('button', { name: /^Idle containers/ })); + await user.click(await screen.findByRole('button', { name: /^Idle provisioned offers/ })); expect(screen.getByRole('dialog')).toBeVisible(); const calls = dataQueryCounts(); navigate(target, 1); diff --git a/src/webviews/cosmosdb/AccountOverview/DerivedAdvisories.test.tsx b/src/webviews/cosmosdb/AccountOverview/DerivedAdvisories.test.tsx index 19657de72..6bef717ec 100644 --- a/src/webviews/cosmosdb/AccountOverview/DerivedAdvisories.test.tsx +++ b/src/webviews/cosmosdb/AccountOverview/DerivedAdvisories.test.tsx @@ -144,6 +144,7 @@ describe('log coverage guidance', () => { }); describe('metric coverage and actionable findings', () => { + it('announces incomplete metric checks without claiming a clean result or blaming Log Analytics', () => { showCoverage( { available: true }, @@ -168,7 +169,7 @@ describe('metric coverage and actionable findings', () => { 'Configuration checks and successful analyses still contribute recommendations.', ), ).toBeInTheDocument(); - expect(screen.getAllByText(/Idle containers: Access denied/)).toHaveLength(1); + expect(screen.getAllByText(/Idle provisioned offers: Access denied/)).toHaveLength(1); expect(screen.getByText('No advisories from the checks that completed.')).toBeInTheDocument(); expect(screen.queryByText('No advisories from your telemetry right now.')).not.toBeInTheDocument(); expect(screen.queryByRole('button', { name: /Learn/ })).not.toBeInTheDocument(); @@ -187,6 +188,23 @@ describe('metric coverage and actionable findings', () => { thresholdReference: 'Peak consumption at most 50 RU.', } as const; + it.each([ + { scopes: ['shared-db'], label: '1 resource affected' }, + { scopes: ['db/items'], label: '1 resource affected' }, + { scopes: ['shared-db', 'db/items'], label: 'Some resources affected' }, + { scopes: ['shared-db', 'shared-db'], label: '1 resource affected' }, + { scopes: [undefined], label: 'Account-wide' }, + ])('uses resource-aware visible and accessible summaries for $scopes', ({ scopes, label }) => { + showCoverage(undefined, { + advisories: scopes.map((scope, index) => ({ ...common, id: `idle-${index}`, scope })), + }); + const trigger = screen.getByRole('button', { name: /^Idle provisioned offers/ }); + expect(trigger).toHaveTextContent('Idle provisioned offers'); + expect(within(trigger).getByText(label)).toBeVisible(); + expect(trigger).toHaveAccessibleName(`Idle provisioned offers. ${label}. Show affected resources.`); + expect(trigger).not.toHaveTextContent(/containers? affected/); + }); + function showDismissibleGroup() { function Harness() { const [dismissedIds, setDismissedIds] = useState>(new Set()); @@ -223,7 +241,7 @@ describe('metric coverage and actionable findings', () => { ])('keeps focus inside the dialog after dismissing db/%s', async (removed, next, key) => { const user = userEvent.setup(); showDismissibleGroup(); - const trigger = screen.getByRole('button', { name: /^Idle containers/ }); + const trigger = screen.getByRole('button', { name: /^Idle provisioned offers/ }); await user.click(trigger); screen.getByRole('button', { name: `Dismiss advisory for db/${removed}` }).focus(); await user.keyboard(key); @@ -239,14 +257,14 @@ describe('metric coverage and actionable findings', () => { it('closes the emptied group and focuses the surviving section after the last dismissal', async () => { const user = userEvent.setup(); showDismissibleGroup(); - await user.click(screen.getByRole('button', { name: /^Idle containers/ })); + await user.click(screen.getByRole('button', { name: /^Idle provisioned offers/ })); screen.getByRole('button', { name: 'Dismiss advisory for db/a' }).focus(); for (const key of ['a', 'b', 'c']) { expect(screen.getByRole('button', { name: `Dismiss advisory for db/${key}` })).toHaveFocus(); await user.keyboard('{Enter}'); } expect(screen.queryByRole('dialog')).not.toBeInTheDocument(); - expect(screen.queryByRole('button', { name: /^Idle containers/ })).not.toBeInTheDocument(); + expect(screen.queryByRole('button', { name: /^Idle provisioned offers/ })).not.toBeInTheDocument(); expect(screen.getByLabelText('Recommendations')).toHaveFocus(); expect(screen.getByText('No advisories from your telemetry right now.')).toBeVisible(); }); @@ -254,7 +272,7 @@ describe('metric coverage and actionable findings', () => { it('does not move focus when a dismissal removes an unfocused button', async () => { const user = userEvent.setup(); showDismissibleGroup(); - await user.click(screen.getByRole('button', { name: /^Idle containers/ })); + await user.click(screen.getByRole('button', { name: /^Idle provisioned offers/ })); const close = screen.getByRole('button', { name: 'Close' }); close.focus(); fireEvent.click(screen.getByRole('button', { name: 'Dismiss advisory for db/a' })); @@ -270,9 +288,9 @@ describe('metric coverage and actionable findings', () => { { ...common, id: 'idle-b', scope: 'db/b' }, ], }); - await user.click(screen.getByRole('button', { name: /^Idle containers/ })); + await user.click(screen.getByRole('button', { name: /^Idle provisioned offers/ })); const dialog = within(screen.getByRole('dialog')); - const list = dialog.getByRole('list', { name: 'Idle containers' }); + const list = dialog.getByRole('list', { name: 'Idle provisioned offers' }); const items = within(list).getAllByRole('listitem'); expect(items).toHaveLength(2); expect(items[0]).toHaveTextContent(/^db\/a$/); @@ -303,14 +321,14 @@ describe('metric coverage and actionable findings', () => { { ...common, id: 'idle-b', scope: 'db/b', rationale: 'Peak: 20 RU.' }, ], }); - const trigger = screen.getByRole('button', { name: /^Idle containers/ }); + const trigger = screen.getByRole('button', { name: /^Idle provisioned offers/ }); expect(trigger).toHaveClass(cardClassNames.root); const badge = within(trigger).getByText('Low'); expect(badge).toHaveClass(badgeClassNames.root); expect(badge).not.toHaveAttribute('tabindex'); expect(badge).not.toHaveAttribute('aria-hidden'); - expect(trigger).toHaveTextContent('Idle containers'); - expect(trigger).toHaveAccessibleName(/^Idle containers/); + expect(trigger).toHaveTextContent('Idle provisioned offers'); + expect(trigger).toHaveAccessibleName(/^Idle provisioned offers/); const descriptions = trigger .getAttribute('aria-describedby') ?.split(' ') @@ -327,7 +345,7 @@ describe('metric coverage and actionable findings', () => { expect(screen.queryAllByRole('dialog')).toHaveLength(openWith === 'Enter' ? 1 : 0); await user.keyboard(`[/${openWith}]`); const dialog = within(screen.getByRole('dialog')); - const list = dialog.getByRole('list', { name: 'Idle containers' }); + const list = dialog.getByRole('list', { name: 'Idle provisioned offers' }); const summary = within(list).getByRole('button', { name: 'db/a' }); expect(summary).toHaveClass(accordionHeaderClassNames.button); expect(summary).toHaveTextContent('db/a'); @@ -403,7 +421,7 @@ describe('metric coverage and actionable findings', () => { }, ], }); - await user.click(screen.getByRole('button', { name: /^Idle containers/ })); + await user.click(screen.getByRole('button', { name: /^Idle provisioned offers/ })); const dialog = within(screen.getByRole('dialog')); expect(dialog.getByText('400 RU/s').tagName).toBe('SPAN'); expect(dialog.getByText('50 RU').tagName).toBe('SPAN'); diff --git a/src/webviews/cosmosdb/AccountOverview/DerivedAdvisories.tsx b/src/webviews/cosmosdb/AccountOverview/DerivedAdvisories.tsx index f700a45f0..d09050d20 100644 --- a/src/webviews/cosmosdb/AccountOverview/DerivedAdvisories.tsx +++ b/src/webviews/cosmosdb/AccountOverview/DerivedAdvisories.tsx @@ -283,7 +283,7 @@ function ruleMeta(rule: DerivedAdvisoryRule): { name: string; description: strin return { name: l10n.t('Indexing cost risk'), description: l10n.t( - 'Index storage is large relative to data, suggesting the indexing policy covers more than the workload actually queries.', + 'Index storage is large relative to data. Review query requirements; this ratio alone does not prove indexes are unused.', ), }; case 'ExpensiveConsistency': @@ -297,14 +297,14 @@ function ruleMeta(rule: DerivedAdvisoryRule): { name: string; description: strin return { name: l10n.t('Multi-region write antipattern'), description: l10n.t( - 'Multi-region writes are enabled without a conflict-resolution setup that fits the workload, risking write conflicts.', + 'Review whether multi-region writes fit the API, write-region configuration and environment requirements.', ), }; case 'IdleContainer': return { - name: l10n.t('Idle containers'), + name: l10n.t('Idle provisioned offers'), description: l10n.t( - 'Containers are provisioned but serve almost no traffic. Their entire reservation is round-the-clock waste.', + 'Provisioned containers or shared database offers serve almost no traffic. Review recoverable manual capacity or the autoscale idle floor.', ), }; case 'PartitionMergeCandidate': @@ -318,7 +318,7 @@ function ruleMeta(rule: DerivedAdvisoryRule): { name: string; description: strin return { name: l10n.t('Autoscale max set too high'), description: l10n.t( - 'Autoscale containers rarely approach their configured maximum, so the max can be lowered to cap cost safely.', + 'Autoscale offers rarely approach their configured maximum. Review analytical targets and service minima before changing capacity.', ), }; case 'AutoscaleToManualCandidate': @@ -384,13 +384,13 @@ interface AdvisoryGroup { /** The most severe advisory in the group drives the card's badge and sort order. */ severity: DerivedAdvisorySeverity; advisories: DerivedAdvisory[]; - /** Distinct container scopes that fired this rule; empty for account-wide rules. */ + /** Distinct resource scopes that fired this rule; empty for account-wide rules. */ scopeCount: number; } /** - * Collapses the flat advisory list into one entry per detector. At scale a per-container list can run to tens of - * thousands of rows; grouping keeps the card to at most one row per detector and defers the container list to + * Collapses the flat advisory list into one entry per detector. At scale a per-resource list can run to tens of + * thousands of rows; grouping keeps the card to at most one row per detector and defers the resource list to * an on-demand dialog, so the DOM never holds every finding at once. */ function groupAdvisories(advisories: readonly DerivedAdvisory[]): AdvisoryGroup[] { @@ -474,17 +474,17 @@ function logCoverageNotice(reason: UnavailableReason | undefined): { } } -/** Card summary line: how many containers a scoped detector hit, or that the finding is account-wide. */ +/** Card summary line: whether a scoped detector hit one or multiple resources, or the finding is account-wide. */ function groupCountLabel(group: AdvisoryGroup): string { if (group.scopeCount === 0) { return l10n.t('Account-wide'); } - return group.scopeCount === 1 ? l10n.t('1 container affected') : l10n.t('Some containers affected'); + return group.scopeCount === 1 ? l10n.t('1 resource affected') : l10n.t('Some resources affected'); } /** - * One summary card per detector. Shows the detector's name, description, headline severity, and how many containers - * matched — but not the containers themselves. Activating it opens the drill-in dialog with the full per-container + * One summary card per detector. Shows the detector's name, description, headline severity, and affected-resource + * summary — but not the resources themselves. Activating it opens the drill-in dialog with the full per-resource * list, so the section stays at one row per detector no matter how many findings the account has. */ const AdvisoryGroupCard = ({ @@ -526,7 +526,7 @@ const AdvisoryGroupCard = ({ event.currentTarget.click(); } }} - aria-label={l10n.t('{name}. {count}. Show affected containers.', { name: group.name, count })} + aria-label={l10n.t('{name}. {count}. Show affected resources.', { name: group.name, count })} aria-describedby={`${id}-severity ${id}-description`} aria-haspopup="dialog" {...restoreFocusTargetAttributes} From 3225dbde9a82a075b8a4585f6473f3c2fcde52dc Mon Sep 17 00:00:00 2001 From: Dmitrii Shilov <6812525+bk201-@users.noreply.github.com> Date: Wed, 11 Nov 2026 17:39:40 +0100 Subject: [PATCH 02/12] chore: finalize native advisory localization and formatting Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- l10n/bundle.l10n.json | 80 +++++++++++-------- .../services/advisories/collectParity.test.ts | 2 +- .../services/advisories/core/helpers.ts | 6 +- .../DerivedAdvisories.test.tsx | 1 - 4 files changed, 49 insertions(+), 40 deletions(-) diff --git a/l10n/bundle.l10n.json b/l10n/bundle.l10n.json index db4e2ba67..dc20f1d41 100644 --- a/l10n/bundle.l10n.json +++ b/l10n/bundle.l10n.json @@ -4,6 +4,7 @@ " folder inside .cosmosdb-migration.": " folder inside .cosmosdb-migration.", " That leaves roughly `{wasted} RU/s` recoverable by lowering the offer toward `~{recommended} RU/s`.": " That leaves roughly `{wasted} RU/s` recoverable by lowering the offer toward `~{recommended} RU/s`.", " The busiest observed sample still stayed below the `90%` peak guard, so this looks steadily oversized rather than bursty.": " The busiest observed sample still stayed below the `90%` peak guard, so this looks steadily oversized rather than bursty.", + " The modeled recoverable capacity is `{wasted} RU/s`; the target remains `~{recommended} RU/s`, so no reduction is available.": " The modeled recoverable capacity is `{wasted} RU/s`; the target remains `~{recommended} RU/s`, so no reduction is available.", ".NET SDK {0} or newer is required to install Cosmos DB Shell. Install the .NET SDK, download it manually, or configure an existing Cosmos DB Shell path in settings.": ".NET SDK {0} or newer is required to install Cosmos DB Shell. Install the .NET SDK, download it manually, or configure an existing Cosmos DB Shell path in settings.", "\"{0}\" is not implemented on \"{1}\".": "\"{0}\" is not implemented on \"{1}\".", "\"{container}\" throttled `{rate}%` of requests over the last `7 days`. Serverless has no throughput knob.": "\"{container}\" throttled `{rate}%` of requests over the last `7 days`. Serverless has no throughput knob.", @@ -66,7 +67,7 @@ "{label}: {share} share": "{label}: {share} share", "{label}: {value} p99 utilization": "{label}: {value} p99 utilization", "{mode} · {excluded} excluded · {composite} composite": "{mode} · {excluded} excluded · {composite} composite", - "{name}. {count}. Show affected containers.": "{name}. {count}. Show affected containers.", + "{name}. {count}. Show affected resources.": "{name}. {count}. Show affected resources.", "{phase} / {input}: {reason}": "{phase} / {input}: {reason}", "{phase} diagnostics": "{phase} diagnostics", "{phase}: action completed successfully.": "{phase}: action completed successfully.", @@ -112,6 +113,7 @@ "1 container affected": "1 container affected", "1 matching scenario": "1 matching scenario", "1 more step": "1 more step", + "1 resource affected": "1 resource affected", "1d": "1d", "1h": "1h", "20 GB limit": "20 GB limit", @@ -178,7 +180,7 @@ "Account:": "Account:", "Accounts, preferences, settings": "Accounts, preferences, settings", "Accounts, transactions, payments": "Accounts, transactions, payments", - "Across multiple regions this level raises write latency and tightens availability.": "Across multiple regions this level raises write latency and tightens availability.", + "Across multiple regions, review the additional write-latency and availability trade-offs.": "Across multiple regions, review the additional write-latency and availability trade-offs.", "Actions": "Actions", "Active": "Active", "Active alerts could not be checked. Previously known problems are retained.": "Active alerts could not be checked. Previously known problems are retained.", @@ -200,7 +202,7 @@ "Add property…": "Add property…", "Add read query": "Add read query", "Add the business/unique key identifiers and the attributes you filter queries by. Press Enter to add.": "Add the business/unique key identifiers and the attributes you filter queries by. Press Enter to add.", - "Add the container's partition key to the query filter (or a composite index) so it targets a single logical partition.": "Add the container's partition key to the query filter (or a composite index) so it targets a single logical partition.", + "Adding write regions can increase cost and conflict complexity; no savings are quantified here.": "Adding write regions can increase cost and conflict complexity; no savings are quantified here.", "Additional Assessment Instructions": "Additional Assessment Instructions", "Additional assessment instructions help": "Additional assessment instructions help", "Additional Discovery Instructions": "Additional Discovery Instructions", @@ -235,6 +237,7 @@ "All pending orders (admin dashboard)": "All pending orders (admin dashboard)", "All saved schemas have been deleted.": "All saved schemas have been deleted.", "All throughput modes": "All throughput modes", + "All-versions-and-deletes change feed requires continuous backup; enablement does not establish active consumer usage. Resolve inconsistent or missing backup metadata without weakening protection.": "All-versions-and-deletes change feed requires continuous backup; enablement does not establish active consumer usage. Resolve inconsistent or missing backup metadata without weakening protection.", "Allow Copilot to sample your container schema to generate an accurate query?": "Allow Copilot to sample your container schema to generate an accurate query?", "Alternative": "Alternative", "Always upload": "Always upload", @@ -279,13 +282,13 @@ "Autoscale bills a `10%` idle floor of the max even at zero load, so an over-high max wastes `~{wasted} RU/s` of that floor.": "Autoscale bills a `10%` idle floor of the max even at zero load, so an over-high max wastes `~{wasted} RU/s` of that floor.", "Autoscale candidates": "Autoscale candidates", "Autoscale carries a per-RU premium over manual, and a workload that stays high does not benefit from scaling.": "Autoscale carries a per-RU premium over manual, and a workload that stays high does not benefit from scaling.", - "Autoscale container looks steady: manual may be cheaper": "Autoscale container looks steady: manual may be cheaper", - "Autoscale containers rarely approach their configured maximum, so the max can be lowered to cap cost safely.": "Autoscale containers rarely approach their configured maximum, so the max can be lowered to cap cost safely.", "Autoscale containers running at a steady load would usually be cheaper on fixed manual throughput.": "Autoscale containers running at a steady load would usually be cheaper on fixed manual throughput.", "Autoscale max may be set too high": "Autoscale max may be set too high", "Autoscale max set too high": "Autoscale max set too high", + "Autoscale offer \"{container}\" never provisioned more than `{peak}%` of its `{max} RU/s` max over the window, below the `{band}%` band.": "Autoscale offer \"{container}\" never provisioned more than `{peak}%` of its `{max} RU/s` max over the window, below the `{band}%` band.", + "Autoscale offer looks steady: manual may be cheaper": "Autoscale offer looks steady: manual may be cheaper", + "Autoscale offers rarely approach their configured maximum. Review analytical targets and service minima before changing capacity.": "Autoscale offers rarely approach their configured maximum. Review analytical targets and service minima before changing capacity.", "Autoscale on \"{container}\" averaged `{avg}%` of its max with a peak of `{peak}%`, a `{ratio}×` peak-to-average.": "Autoscale on \"{container}\" averaged `{avg}%` of its max with a peak of `{peak}%`, a `{ratio}×` peak-to-average.", - "Autoscale on \"{container}\" never provisioned more than `{peak}%` of its `{max} RU/s` max over the window, below the `{band}%` band.": "Autoscale on \"{container}\" never provisioned more than `{peak}%` of its `{max} RU/s` max over the window, below the `{band}%` band.", "Autoscale to manual candidates": "Autoscale to manual candidates", "Availability": "Availability", "Availability across a date range": "Availability across a date range", @@ -388,7 +391,6 @@ "Column context menu for {0}": "Column context menu for {0}", "Column resize options.": "Column resize options.", "Column Width (px)": "Column Width (px)", - "Combined with a peak-to-average write burst of `~{burst}×`, this is the signature of uncontrolled ingestion.": "Combined with a peak-to-average write burst of `~{burst}×`, this is the signature of uncontrolled ingestion.", "Compatibility adjustments": "Compatibility adjustments", "Compatibility adjustments ({count})": "Compatibility adjustments ({count})", "Compatibility: {count} empty optional fields are interpreted as omitted. Viewing this project does not change the saved checkpoint.": "Compatibility: {count} empty optional fields are interpreted as omitted. Viewing this project does not change the saved checkpoint.", @@ -403,6 +405,7 @@ "Confirm that the agent has already stopped in Chat. This only clears local run tracking; it does not cancel Chat.": "Confirm that the agent has already stopped in Chat. This only clears local run tracking; it does not cancel Chat.", "Confirm the application genuinely needs this consistency level.": "Confirm the application genuinely needs this consistency level.", "Confirm the partition key spreads new data across partitions, and archive or delete cold data.": "Confirm the partition key spreads new data across partitions, and archive or delete cold data.", + "Confirm this inferred environment and its availability requirements with the account owner.": "Confirm this inferred environment and its availability requirements with the account owner.", "Connect to {0}": "Connect to {0}", "Connect to a container first": "Connect to a container first", "Connect to a container to generate a schema": "Connect to a container to generate a schema", @@ -417,18 +420,16 @@ "Connection timed out. Please verify the connection string and that the host is reachable.": "Connection timed out. Please verify the connection string and that the host is reachable.", "Connection verified successfully.": "Connection verified successfully.", "Consider converting \"{container}\" to manual throughput at a fixed RU/s near the sustained level to drop the autoscale premium.": "Consider converting \"{container}\" to manual throughput at a fixed RU/s near the sustained level to drop the autoscale premium.", + "Consider Session only after validating application correctness and request-level overrides; Session is not equivalent to global Strong consistency.": "Consider Session only after validating application correctness and request-level overrides; Session is not equivalent to global Strong consistency.", "Consistency": "Consistency", "Container": "Container", "Container \"{container}\" already exists with a different partition key. Choose another database or change the model. Existing containers are not modified.": "Container \"{container}\" already exists with a different partition key. Choose another database or change the model. Existing containers are not modified.", - "Container \"{container}\" consumed at most `{peak} RU` in any single bucket over the last `30 days`.": "Container \"{container}\" consumed at most `{peak} RU` in any single bucket over the last `30 days`.", "Container \"{container}\" has `{actual} physical partitions` but its `{ru} RU/s` and `{gib} GiB` only need `{needed}`.": "Container \"{container}\" has `{actual} physical partitions` but its `{ru} RU/s` and `{gib} GiB` only need `{needed}`.", - "Container \"{container}\" stayed at `{p99}%` 99th-percentile normalized RU over the last `{window}`.": "Container \"{container}\" stayed at `{p99}%` 99th-percentile normalized RU over the last `{window}`.", "Container {0} not found": "Container {0} not found", "Container {container} in database {database}": "Container {container} in database {database}", "Container {n}": "Container {n}", "Container inventory": "Container inventory", "Container inventory pages": "Container inventory pages", - "Container looks idle": "Container looks idle", "Container may be over-partitioned": "Container may be over-partitioned", "Container name": "Container name", "Container name cannot be longer than 255 characters": "Container name cannot be longer than 255 characters", @@ -440,7 +441,6 @@ "Container throttling": "Container throttling", "Container:": "Container:", "Containers": "Containers", - "Containers are provisioned but serve almost no traffic. Their entire reservation is round-the-clock waste.": "Containers are provisioned but serve almost no traffic. Their entire reservation is round-the-clock waste.", "Containers have more physical partitions than their RU/s and storage need, adding avoidable per-partition overhead.": "Containers have more physical partitions than their RU/s and storage need, adding avoidable per-partition overhead.", "Containers in a shared-throughput database compete for one RU pool and starve each other under load.": "Containers in a shared-throughput database compete for one RU pool and starve each other under load.", "Containers matching the current filters: {count}": "Containers matching the current filters: {count}", @@ -448,6 +448,7 @@ "Content Management": "Content Management", "Continue": "Continue", "Continuing will clear completion of the following steps and discard the existing recommendation. Your entered model data will be kept. Do you want to continue?": "Continuing will clear completion of the following steps and discard the existing recommendation. Your entered model data will be kept. Do you want to continue?", + "Convert to autoscale on \"{container}\" and start with `max ≈ {recommended} RU/s`.": "Convert to autoscale on \"{container}\" and start with `max ≈ {recommended} RU/s`.", "Coolest partition p99:": "Coolest partition p99:", "Copied input must remain inside its selected folder.": "Copied input must remain inside its selected folder.", "Copilot chooses the model; reasoning capability may vary": "Copilot chooses the model; reasoning capability may vary", @@ -611,9 +612,7 @@ "Design containers, partition keys, and relationships visually.": "Design containers, partition keys, and relationships visually.", "Determined by the selected resource group": "Determined by the selected resource group", "Direct": "Direct", - "Disable multi-region writes (and consider dropping the second write region) on dev/test/stage accounts.": "Disable multi-region writes (and consider dropping the second write region) on dev/test/stage accounts.", "Disable multi-region writes to remove the tripwire unless a second write region is imminent and justified.": "Disable multi-region writes to remove the tripwire unless a second write region is imminent and justified.", - "Disable multi-region writes unless the write-failover benefit genuinely applies.": "Disable multi-region writes unless the write-failover benefit genuinely applies.", "Disabled": "Disabled", "Discard Changes and Refresh": "Discard Changes and Refresh", "Discovery input must be relative to the migration folder and remain inside the workspace.": "Discovery input must be relative to the migration folder and remain inside the workspace.", @@ -668,7 +667,6 @@ "Either resource ID or connection string is required": "Either resource ID or connection string is required", "Element with id of {rootId} not found.": "Element with id of {rootId} not found.", "Empty or a JSON array, e.g. [1, {\"key\": \"value\"}]": "Empty or a JSON array, e.g. [1, {\"key\": \"value\"}]", - "Enable autoscale on \"{container}\" and start with a maximum near `{recommended} RU/s`.": "Enable autoscale on \"{container}\" and start with a maximum near `{recommended} RU/s`.", "Enable autoscale on the bursty containers so provisioned RU/s follows demand between the configured floor and ceiling.": "Enable autoscale on the bursty containers so provisioned RU/s follows demand between the configured floor and ceiling.", "Enabled": "Enabled", "Enabling diagnostic settings does not grant query access.": "Enabling diagnostic settings does not grant query access.", @@ -721,7 +719,6 @@ "Exclude file {0}": "Exclude file {0}", "Exclude migration configuration from version control": "Exclude migration configuration from version control", "Exclude migration configuration help": "Exclude migration configuration help", - "Exclude paths that are never used in filters from the indexing policy to cut write RU charges and index storage.": "Exclude paths that are never used in filters from the indexing policy to cut write RU charges and index storage.", "Execute query": "Execute query", "Execution timed out": "Execution timed out", "Execution timed out.": "Execution timed out.", @@ -938,8 +935,7 @@ "Id contains illegal chars (/, \\, ?, #).": "Id contains illegal chars (/, \\, ?, #).", "Id ends with a space.": "Id ends with a space.", "Id must be a string.": "Id must be a string.", - "Idle containers": "Idle containers", - "If not, relax it to Session (or Bounded Staleness) after validating the application's tolerance.": "If not, relax it to Session (or Bounded Staleness) after validating the application's tolerance.", + "Idle provisioned offers": "Idle provisioned offers", "If you enter both, the query defines the access pattern and the description adds context. If they disagree, for example on which property is filtered, Copilot asks you to fix the read instead of guessing.": "If you enter both, the query defines the access pattern and the description adds context. If they disagree, for example on which property is filtered, Copilot asks you to fix the read instead of guessing.", "Ignoring the following files that do not match the \"*.json\" file name pattern:": "Ignoring the following files that do not match the \"*.json\" file name pattern:", "Immutability": "Immutability", @@ -956,10 +952,12 @@ "In \"{container}\", `{rate}%` of requests were throttled (HTTP 429).": "In \"{container}\", `{rate}%` of requests were throttled (HTTP 429).", "In \"{container}\", the busiest of `{count} physical partitions` ran at `{busiest}%` p99 utilization.": "In \"{container}\", the busiest of `{count} physical partitions` ran at `{busiest}%` p99 utilization.", "In Chat": "In Chat", + "In one region this is a local read-cost review, not a cross-region latency finding.": "In one region this is a local read-cost review, not a cross-region latency finding.", "In progress": "In progress", "Include domains without detected application code access patterns (e.g. tables only referenced via stored procedures, ETL, or external systems)": "Include domains without detected application code access patterns (e.g. tables only referenced via stored procedures, ETL, or external systems)", "Include file": "Include file", "Include file {0}": "Include file {0}", + "Include the container's partition key in the query filter where the access pattern permits. A composite index alone does not eliminate fan-out.": "Include the container's partition key in the query filter where the access pattern permits. A composite index alone does not eliminate fan-out.", "Incomplete query result": "Incomplete query result", "Incomplete workload analysis": "Incomplete workload analysis", "Index hit document count": "Index hit document count", @@ -968,8 +966,8 @@ "Index Metrics": "Index Metrics", "Index metrics table": "Index metrics table", "Index Spec": "Index Spec", - "Index storage in \"{container}\" is `{percent}%` of its data size, above the `{threshold}%` threshold, and the container has no user exclusions in its indexing policy. Indexing every property inflates storage and the RU cost of every write.": "Index storage in \"{container}\" is `{percent}%` of its data size, above the `{threshold}%` threshold, and the container has no user exclusions in its indexing policy. Indexing every property inflates storage and the RU cost of every write.", - "Index storage is large relative to data, suggesting the indexing policy covers more than the workload actually queries.": "Index storage is large relative to data, suggesting the indexing policy covers more than the workload actually queries.", + "Index storage in \"{container}\" is `{percent}%` of its data size, above the `{threshold}%` threshold. This is a storage-footprint warning, not proof of unused indexes or measured write-RU savings.": "Index storage in \"{container}\" is `{percent}%` of its data size, above the `{threshold}%` threshold. This is a storage-footprint warning, not proof of unused indexes or measured write-RU savings.", + "Index storage is large relative to data. Review query requirements; this ratio alone does not prove indexes are unused.": "Index storage is large relative to data. Review query requirements; this ratio alone does not prove indexes are unused.", "Indexes": "Indexes", "Indexing": "Indexing", "Indexing cost risk": "Indexing cost risk", @@ -1103,7 +1101,6 @@ "Lower \"{container}\" from `{provisioned} RU/s` toward `~{recommended} RU/s`, or switch it to autoscale if demand is bursty.": "Lower \"{container}\" from `{provisioned} RU/s` toward `~{recommended} RU/s`, or switch it to autoscale if demand is bursty.", "Lower is better.": "Lower is better.", "Lower provisioned RU/s to match observed demand, or switch to autoscale so capacity tracks usage automatically.": "Lower provisioned RU/s to match observed demand, or switch to autoscale so capacity tracks usage automatically.", - "Lower the autoscale max on \"{container}\" toward `~{recommended} RU/s`.": "Lower the autoscale max on \"{container}\" toward `~{recommended} RU/s`.", "Manually set column width": "Manually set column width", "Master key was not entered. Connection will be interrupted.": "Master key was not entered. Connection will be interrupted.", "Matching existing containers are left unchanged.": "Matching existing containers are left unchanged.", @@ -1111,7 +1108,7 @@ "Maximum items per array": "Maximum items per array", "Medium": "Medium", "Medium impact": "Medium impact", - "Merge the physical partitions (Azure Portal or CLI) to consolidate the RU/s back onto fewer partitions.": "Merge the physical partitions (Azure Portal or CLI) to consolidate the RU/s back onto fewer partitions.", + "Merge eligibility is unknown because backup policy is missing or migration metadata is present and unsettled. Verify the account state; merge instructions are withheld.": "Merge eligibility is unknown because backup policy is missing or migration metadata is present and unsettled. Verify the account state; merge instructions are withheld.", "Metadata requests": "Metadata requests", "Metric": "Metric", "Metric data unavailable or incomplete": "Metric data unavailable or incomplete", @@ -1141,7 +1138,6 @@ "Multi-region writes are enabled across `{regions} write regions` on a non-production account, which does not need RTO=0 write failover.": "Multi-region writes are enabled across `{regions} write regions` on a non-production account, which does not need RTO=0 write failover.", "Multi-region writes are enabled but the account has a single write region.": "Multi-region writes are enabled but the account has a single write region.", "Multi-region writes are enabled on a {api} API account.": "Multi-region writes are enabled on a {api} API account.", - "Multi-region writes are enabled without a conflict-resolution setup that fits the workload, risking write conflicts.": "Multi-region writes are enabled without a conflict-resolution setup that fits the workload, risking write conflicts.", "Multi-region writes on a {api} account": "Multi-region writes on a {api} account", "Multi-region writes on a non-production account": "Multi-region writes on a non-production account", "Multi-region writes with a single write region": "Multi-region writes with a single write region", @@ -1189,6 +1185,7 @@ "No index metrics available": "No index metrics available", "No language models available. Please ensure you have access to Copilot.": "No language models available. Please ensure you have access to Copilot.", "No matching resources found.": "No matching resources found.", + "No maximum reduction is available under this model. Review workload placement; do not lower below the service minimum.": "No maximum reduction is available under this model. Review workload placement; do not lower below the service minimum.", "No open Query Editor is connected to database \"{0}\" / container \"{1}\".": "No open Query Editor is connected to database \"{0}\" / container \"{1}\".", "No open Query Editor is connected to database \"{0}\" / container \"{1}\". Call cosmosdb_listOpenConnections to see the available editors.": "No open Query Editor is connected to database \"{0}\" / container \"{1}\". Call cosmosdb_listOpenConnections to see the available editors.", "No permission": "No permission", @@ -1212,6 +1209,7 @@ "No subscriptions found": "No subscriptions found", "No sustained account-wide 429 rate above {percent}% for {duration} in the last {window}.": "No sustained account-wide 429 rate above {percent}% for {duration} in the last {window}.", "No telemetry available for this selection yet.": "No telemetry available for this selection yet.", + "No throughput reduction is available under this model. Validate the service minimum and workload needs; do not apply an unchanged target.": "No throughput reduction is available under this model. Validate the service minimum and workload needs; do not apply an unchanged target.", "No total throughput limit": "No total throughput limit", "None of these fit": "None of these fit", "Normalized RU": "Normalized RU", @@ -1233,7 +1231,10 @@ "Number of output documents": "Number of output documents", "Number of round trips": "Number of round trips", "Object is too large to be shown": "Object is too large to be shown", + "Offer \"{container}\" consumed at most `{peak} RU` in any single bucket over the last `30 days`.": "Offer \"{container}\" consumed at most `{peak} RU` in any single bucket over the last `30 days`.", + "Offer \"{container}\" stayed at `{p99}%` 99th-percentile normalized RU over the last `{window}`.": "Offer \"{container}\" stayed at `{p99}%` 99th-percentile normalized RU over the last `{window}`.", "Older family; not recommended for complex migration": "Older family; not recommended for complex migration", + "On a later web request, pass the token into the Cosmos request options of whichever SDK instance handles that request. There is no direct SDK-to-SDK synchronization; tokens remain opaque, partition-bound and are not equivalent to Strong consistency.": "On a later web request, pass the token into the Cosmos request options of whichever SDK instance handles that request. There is no direct SDK-to-SDK synchronization; tokens remain opaque, partition-bound and are not equivalent to Strong consistency.", "On that trajectory it reaches the `50 GiB` physical-partition split ceiling in roughly `{days} days`, within the `{horizon}-day` risk horizon.": "On that trajectory it reaches the `50 GiB` physical-partition split ceiling in roughly `{days} days`, within the `{horizon}-day` risk horizon.", "One physical partition holds far more data than its siblings and will hit the split ceiling long before them.": "One physical partition holds far more data than its siblings and will hit the split ceiling long before them.", "One physical partition is saturated while its siblings sit idle. Traffic is skewed toward a single partition-key range.": "One physical partition is saturated while its siblings sit idle. Traffic is skewed toward a single partition-key range.", @@ -1303,6 +1304,7 @@ "Partition key recommendation": "Partition key recommendation", "Partition limits": "Partition limits", "Partition merge candidates": "Partition merge candidates", + "Partition merge is blocked by continuous backup or conflicting all-versions-and-deletes metadata. Continuous backup cannot be reverted to periodic backup. Do not disable protection to enable a merge.": "Partition merge is blocked by continuous backup or conflicting all-versions-and-deletes metadata. Continuous backup cannot be reverted to periodic backup. Do not disable protection to enable a merge.", "Partition-key candidates": "Partition-key candidates", "Partition-key candidates — estimated distinct values": "Partition-key candidates — estimated distinct values", "Partition-key guidance": "Partition-key guidance", @@ -1362,7 +1364,6 @@ "Prefer to provision manually? A Bicep template has been generated based on your schema.": "Prefer to provision manually? A Bicep template has been generated based on your schema.", "Preferred for migration": "Preferred for migration", "Preflight": "Preflight", - "Premium consistency across regions": "Premium consistency across regions", "Press Alt+Down to open column menu": "Press Alt+Down to open column menu", "Press Run to execute the query in the editor. Use the dropdown to replay a recent query or tune throughput and priority.": "Press Run to execute the query in the editor. Use the dropdown to replay a recent query or tune throughput and priority.", "Preview": "Preview", @@ -1392,6 +1393,8 @@ "Provision New Account": "Provision New Account", "Provision new Azure Cosmos DB Account": "Provision new Azure Cosmos DB Account", "Provisioned (100%)": "Provisioned (100%)", + "Provisioned containers or shared database offers serve almost no traffic. Review recoverable manual capacity or the autoscale idle floor.": "Provisioned containers or shared database offers serve almost no traffic. Review recoverable manual capacity or the autoscale idle floor.", + "Provisioned offer looks idle": "Provisioned offer looks idle", "Provisioned RU/s stays well above observed demand, so you are paying for capacity the workload never uses.": "Provisioned RU/s stays well above observed demand, so you are paying for capacity the workload never uses.", "Provisioned throughput": "Provisioned throughput", "Provisioned throughput is not applicable to serverless accounts.": "Provisioned throughput is not applicable to serverless accounts.", @@ -1423,6 +1426,7 @@ "QueryRuntimeStatistics availability": "QueryRuntimeStatistics availability", "Quick Start": "Quick Start", "Quick Start tips have been reset. Reopen the Query Editor to see them again.": "Quick Start tips have been reset. Reopen the Query Editor to see them again.", + "Quorum reads can cost more RU than Session or Eventual consistency.": "Quorum reads can cost more RU than Session or Eventual consistency.", "RAG & Embeddings": "RAG & Embeddings", "Raise provisioned throughput above `{ru} RU/s`, or convert to autoscale if the demand is bursty.": "Raise provisioned throughput above `{ru} RU/s`, or convert to autoscale if the demand is bursty.", "Raise provisioned throughput, or convert to autoscale if the demand is bursty.": "Raise provisioned throughput, or convert to autoscale if the demand is bursty.", @@ -1501,6 +1505,7 @@ "Reported continuously by the platform, populated even when the account is idle.": "Reported continuously by the platform, populated even when the account is idle.", "Reporting that a recommendation could not be provided…": "Reporting that a recommendation could not be provided…", "Request Charge": "Request Charge", + "Request logs observed `{ru} read RU` across `{requests} requests`. Half (`{bound} RU`) is only a theoretical upper bound on avoidable read charge: logs do not reveal per-request consistency overrides. This is not measured or monetary savings.": "Request logs observed `{ru} read RU` across `{requests} requests`. Half (`{bound} RU`) is only a theoretical upper bound on avoidable read charge: logs do not reveal per-request consistency overrides. This is not measured or monetary savings.", "Request observations unavailable: {reason}.": "Request observations unavailable: {reason}.", "Request units": "Request units", "Requests": "Requests", @@ -1545,12 +1550,21 @@ "Revealing the connection in the Azure Resources tree…": "Revealing the connection in the Azure Resources tree…", "Review": "Review", "Review \"{container}\" for decommission, a TTL policy, or archival; confirm it is genuinely unused before removing it.": "Review \"{container}\" for decommission, a TTL policy, or archival; confirm it is genuinely unused before removing it.", + "Review actual filter and sort requirements before changing indexes. Composite, spatial and vector indexes can legitimately be large; do not exclude paths solely because this ratio is high.": "Review actual filter and sort requirements before changing indexes. Composite, spatial and vector indexes can legitimately be large; do not exclude paths solely because this ratio is high.", "Review and copy or download the code, then run it in your .NET project using Azure management permissions. This export targets Azure, not the emulator.": "Review and copy or download the code, then run it in your .NET project using Azure management permissions. This export targets Azure, not the emulator.", "Review and copy or download the configuration, then initialize, plan, and apply it with Terraform.": "Review and copy or download the configuration, then initialize, plan, and apply it with Terraform.", "Review and copy or download the template, then deploy it with your Bicep tooling.": "Review and copy or download the template, then deploy it with your Bicep tooling.", "Review and Fix": "Review and Fix", + "Review disabling multi-region writes if active-active availability is unnecessary. Separately assess whether extra regions can be removed; toggling multi-write alone does not recover regional capacity.": "Review disabling multi-region writes if active-active availability is unnecessary. Separately assess whether extra regions can be removed; toggling multi-write alone does not recover regional capacity.", + "Review lowering the autoscale max on \"{container}\" toward the analytical target `~{recommended} RU/s`.": "Review lowering the autoscale max on \"{container}\" toward the analytical target `~{recommended} RU/s`.", + "Review multi-region-write compatibility and availability requirements before changing the flag. Disabling multi-write while keeping all regions does not remove their provisioned capacity.": "Review multi-region-write compatibility and availability requirements before changing the flag. Disabling multi-write while keeping all regions does not remove their provisioned capacity.", + "Review stronger consistency requirements": "Review stronger consistency requirements", "Review the partition key for a higher-cardinality choice so data spreads evenly.": "Review the partition key for a higher-cardinality choice so data spreads evenly.", "Review these issues. They will not block a recommendation.": "Review these issues. They will not block a recommendation.", + "Review the shared database offer and all its member workloads before decommissioning or changing capacity. An idle member alone does not make the shared offer recoverable.": "Review the shared database offer and all its member workloads before decommissioning or changing capacity. An idle member alone does not make the shared offer recoverable.", + "Review the shared database offer and member workloads for partition skew. Identify the affected containers before changing a partition key or isolating throughput.": "Review the shared database offer and member workloads for partition skew. Identify the affected containers before changing a partition key or isolating throughput.", + "Review the write-conflict and pricing implications against the current API and region configuration.": "Review the write-conflict and pricing implications against the current API and region configuration.", + "Review whether multi-region writes fit the API, write-region configuration and environment requirements.": "Review whether multi-region writes fit the API, write-region configuration and environment requirements.", "Review your inputs": "Review your inputs", "Role": "Role", "Role for {name}: {role}": "Role for {name}: {role}", @@ -1685,12 +1699,12 @@ "Smooth queued work instead of dumping bursts all at once. Raising RU/s is the complementary lever.": "Smooth queued work instead of dumping bursts all at once. Raising RU/s is the complementary lever.", "Social & Messaging": "Social & Messaging", "Some analyzers could not run, so coverage is partial.": "Some analyzers could not run, so coverage is partial.", - "Some containers affected": "Some containers affected", "Some items could not be displayed": "Some items could not be displayed", "Some log-based checks were denied access.": "Some log-based checks were denied access.", "Some log-based queries failed or returned incomplete results.": "Some log-based queries failed or returned incomplete results.", "Some migration settings could not be saved. Reload the saved project and discard these unsaved changes?": "Some migration settings could not be saved. Reload the saved project and discard these unsaved changes?", "Some required CDB log tables could not be queried.": "Some required CDB log tables could not be queried.", + "Some resources affected": "Some resources affected", "Some resources may already have been created. Retry using the existing database. Matching containers will be left unchanged.": "Some resources may already have been created. Retry using the existing database. Matching containers will be left unchanged.", "Some selected files are outside the workspace. Would you like to copy them to the migration project?": "Some selected files are outside the workspace. Would you like to copy them to the migration project?", "Some workload checks could not run. Missing or failed metric queries are not treated as zero usage.": "Some workload checks could not run. Missing or failed metric queries are not treated as zero usage.", @@ -1722,7 +1736,6 @@ "Stored procedure name cannot contain the characters '\\', '/', '#', '?', '&'": "Stored procedure name cannot contain the characters '\\', '/', '#', '?', '&'", "Stored procedure name is required.": "Stored procedure name is required.", "Stored Procedures": "Stored Procedures", - "Strong makes writes wait on additional regions. The default Session consistency is sufficient for most workloads.": "Strong makes writes wait on additional regions. The default Session consistency is sufficient for most workloads.", "subscription": "subscription", "Subscription": "Subscription", "Subscription ID": "Subscription ID", @@ -1772,7 +1785,7 @@ "The {api} drivers cannot use Cosmos DB's multi-region-write failover, so the RTO=0 HA benefit never materialises.": "The {api} drivers cannot use Cosmos DB's multi-region-write failover, so the RTO=0 HA benefit never materialises.", "The account action could not be completed. Retry or use the Azure Resources view.": "The account action could not be completed. Retry or use the Azure Resources view.", "The account consumption pattern is intermittent enough that serverless may cost less than provisioned throughput.": "The account consumption pattern is intermittent enough that serverless may cost less than provisioned throughput.", - "The account still carries the write-conflict surface (and `2×` write cost across any second write region).": "The account still carries the write-conflict surface (and `2×` write cost across any second write region).", + "The account has one default consistency level. For load-balanced applications, pass the Cosmos response SessionToken through the web tier to the end-user client in a cookie or equivalent client context.": "The account has one default consistency level. For load-balanced applications, pass the Cosmos response SessionToken through the web tier to the end-user client in a cookie or equivalent client context.", "The account-wide active alert check is unavailable. The filtered list is shown below.": "The account-wide active alert check is unavailable. The filtered list is shown below.", "The active alert count is unavailable for the selected window.": "The active alert count is unavailable for the selected window.", "The apply context is no longer available. Read the Query Editor context again, then retry applying the query.": "The apply context is no longer available. Read the Query Editor context again, then retry applying the query.", @@ -1808,7 +1821,6 @@ "The generated query was written to the Query Editor.": "The generated query was written to the Query Editor.", "The generated schema for {0} is {1} MB even after simplification (limit: {2} MB). Saving it anyway — consider narrowing the data shape if AI suggestions feel imprecise.": "The generated schema for {0} is {1} MB even after simplification (limit: {2} MB). Saving it anyway — consider narrowing the data shape if AI suggestions feel imprecise.", "The generated schema was larger than {0} MB. It has been automatically simplified before saving for {1}.": "The generated schema was larger than {0} MB. It has been automatically simplified before saving for {1}.", - "The idle floor will track real demand while the ceiling still covers the observed peak.": "The idle floor will track real demand while the ceiling still covers the observed peak.", "The insertion failed with status code {0}": "The insertion failed with status code {0}", "The insertion of document {number} failed with error: {error}": "The insertion of document {number} failed with error: {error}", "The issue text was copied to the clipboard. Please paste it into this window.": "The issue text was copied to the clipboard. Please paste it into this window.", @@ -1823,6 +1835,7 @@ "The migration project is located in '{path}', which isn't part of the current workspace.": "The migration project is located in '{path}', which isn't part of the current workspace.", "The minimum specified character length should not exceed the maximum specified character length.": "The minimum specified character length should not exceed the maximum specified character length.", "The model has changed. Get a new recommendation before deploying.": "The model has changed. Get a new recommendation before deploying.", + "The most frequent fan-out shape averaged `{ru} RU` per logical execution with complete request-log matches. Observed charge is supporting evidence, not estimated savings.": "The most frequent fan-out shape averaged `{ru} RU` per logical execution with complete request-log matches. Observed charge is supporting evidence, not estimated savings.", "The most frequent offender averages `{fanout} partitions` per run. Anonymized shape: {shape}": "The most frequent offender averages `{fanout} partitions` per run. Anonymized shape: {shape}", "The name can only contain alphanumeric characters or the symbols ._-()": "The name can only contain alphanumeric characters or the symbols ._-()", "The name can only contain lowercase letters and numbers.": "The name can only contain lowercase letters and numbers.", @@ -1831,6 +1844,7 @@ "The name of your application or service. Examples: OrderService, InventoryAPI, CustomerPortal": "The name of your application or service. Examples: OrderService, InventoryAPI, CustomerPortal", "The partition key change could not be discarded because the item in the new partition has changed. Both items still exist. Resolve the duplicate items before retrying.": "The partition key change could not be discarded because the item in the new partition has changed. Both items still exist. Resolve the duplicate items before retrying.", "The partition key is structurally misaligned with the workload (the data model, not a single bad query).": "The partition key is structurally misaligned with the workload (the data model, not a single bad query).", + "The peak-to-average write burst is `~{burst}×` over `{interval}` buckets; burstiness is supporting evidence, not a trigger.": "The peak-to-average write burst is `~{burst}×` over `{interval}` buckets; burstiness is supporting evidence, not a trigger.", "The phase could not be accepted. Review the diagnostics below.": "The phase could not be accepted. Review the diagnostics below.", "The previous recommendation request was interrupted. Request a recommendation again.": "The previous recommendation request was interrupted. Request a recommendation again.", "The previously saved schema for this container will be replaced.": "The previously saved schema for this container will be replaced.", @@ -1892,7 +1906,6 @@ "This Cosmos DB account has been deleted.": "This Cosmos DB account has been deleted.", "This count covers all Fired alerts retained in Azure Resource Graph, regardless of the filters below. Older active alerts may be outside the selected list period.": "This count covers all Fired alerts retained in Azure Resource Graph, regardless of the filters below. Older active alerts may be outside the selected list period.", "This database already exists. Select Existing database to use it.": "This database already exists. Select Existing database to use it.", - "This doubles write cost and adds write-conflict surface for no benefit.": "This doubles write cost and adds write-conflict surface for no benefit.", "This extension does not support Azure Cosmos DB for": "This extension does not support Azure Cosmos DB for", "This functionality requires installing the Azure Account extension.": "This functionality requires installing the Azure Account extension.", "This functionality requires updating the Azure Account extension to at least version \"{0}\".": "This functionality requires updating the Azure Account extension to at least version \"{0}\".", @@ -1917,8 +1930,8 @@ "This will close all Data Modeler tabs and permanently delete all locally saved Data Modeler data for every account. Deployed databases and containers will not be deleted. This action cannot be undone.": "This will close all Data Modeler tabs and permanently delete all locally saved Data Modeler data for every account. Deployed databases and containers will not be deleted. This action cannot be undone.", "This will delete all {0} saved container schemas. This action cannot be undone.": "This will delete all {0} saved container schemas. This action cannot be undone.", "This workspace is not under version control. It is strongly recommended to initialize a Git repository before starting the migration.": "This workspace is not under version control. It is strongly recommended to initialize a Git repository before starting the migration.", - "Threshold: ≥ `{pct}%` of executions fan out (avg ≥ `{fanout} partitions/query`)": "Threshold: ≥ `{pct}%` of executions fan out (avg ≥ `{fanout} partitions/query`)", - "Threshold: ≥ `{pct}%` of executions fan out across ≥ `{partitions} partitions`": "Threshold: ≥ `{pct}%` of executions fan out across ≥ `{partitions} partitions`", + "Threshold: ≥ `{pct}%` fan-out share across ≥ `{partitions} partitions`, and ≥ `0.1 fan-out queries/s`": "Threshold: ≥ `{pct}%` fan-out share across ≥ `{partitions} partitions`, and ≥ `0.1 fan-out queries/s`", + "Threshold: ≥ `{pct}%` fan-out share, avg ≥ `{fanout} partitions/query`, and ≥ `0.1 fan-out queries/s`": "Threshold: ≥ `{pct}%` fan-out share, avg ≥ `{fanout} partitions/query`, and ≥ `0.1 fan-out queries/s`", "Threshold: 429 rate ≥ `{rate}%` over at least `{requests} requests`": "Threshold: 429 rate ≥ `{rate}%` over at least `{requests} requests`", "Threshold: 429 rate ≥ `{rate}%`, busiest partition p99 ≥ `{saturation}%`, coolest partition p99 ≥ `{headroom}%`": "Threshold: 429 rate ≥ `{rate}%`, busiest partition p99 ≥ `{saturation}%`, coolest partition p99 ≥ `{headroom}%`", "Threshold: average ≥ `{avg}%` of max and peak/average ≤ `{ratio}×`": "Threshold: average ≥ `{avg}%` of max and peak/average ≤ `{ratio}×`", @@ -1936,8 +1949,8 @@ "Threshold: peak in `({floor}, {ceiling}] RU/s` and average/peak < `{ratio}`": "Threshold: peak in `({floor}, {ceiling}] RU/s` and average/peak < `{ratio}`", "Threshold: physical partitions > max(ceil(RU/`10,000`), ceil(storage/`50 GiB`), `1`)": "Threshold: physical partitions > max(ceil(RU/`10,000`), ceil(storage/`50 GiB`), `1`)", "Threshold: pool 429 ≥ `{pool}%`, one collection ≥ `{dominance}%` of RU, a sibling throttling ≥ `{victim}%` at ≤ `{share}%` share": "Threshold: pool 429 ≥ `{pool}%`, one collection ≥ `{dominance}%` of RU, a sibling throttling ≥ `{victim}%` at ≤ `{share}%` share", - "Threshold: projected < `{horizon} days` to the `50 GiB` partition ceiling": "Threshold: projected < `{horizon} days` to the `50 GiB` partition ceiling", - "Threshold: Strong or Bounded Staleness across ≥ `2 regions`": "Threshold: Strong or Bounded Staleness across ≥ `2 regions`", + "Threshold: projected ≤ `{horizon} days` to the `50 GiB` partition ceiling": "Threshold: projected ≤ `{horizon} days` to the `50 GiB` partition ceiling", + "Threshold: Strong in ≥ `1 region`, or Bounded Staleness in ≥ `2 regions`": "Threshold: Strong in ≥ `1 region`, or Bounded Staleness in ≥ `2 regions`", "Threshold: write-RU ≥ `{writePct}%` and 429 rate ≥ `{throttlePct}%`": "Threshold: write-RU ≥ `{writePct}%` and 429 rate ≥ `{throttlePct}%`", "Throttled: {count}": "Throttled: {count}", "Throttling": "Throttling", @@ -2040,6 +2053,7 @@ "URI": "URI", "Use \"Select Files…\" or \"Select Folder…\" to add them, or copy them manually into the ": "Use \"Select Files…\" or \"Select Folder…\" to add them, or copy them manually into the ", "Use the AI menu to generate a query from a description or to explain the current query.": "Use the AI menu to generate a query from a description or to explain the current query.", + "Use the Azure Portal merge eligibility checker and verify current platform, SDK and connector restrictions. Periodic backup alone does not establish eligibility. Only after those checks should a merge be considered.": "Use the Azure Portal merge eligibility checker and verify current platform, SDK and connector restrictions. Periodic backup alone does not establish eligibility. Only after those checks should a merge be considered.", "Use the button to select or create a resource group": "Use the button to select or create a resource group", "Use the SDK throughput-control feature (or the Spark connector) or throughput buckets to cap the batch path.": "Use the SDK throughput-control feature (or the Spark connector) or throughput buckets to cap the batch path.", "User defined function execution time": "User defined function execution time", @@ -2048,6 +2062,7 @@ "Uses container request observations, not normalized RU. Passed means no sustained 429 threshold breach was detected.": "Uses container request observations, not normalized RU. Passed means no sustained 429 threshold breach was detected.", "Uses normalized RU peaks over the selected chart period and sustained container 429 responses.": "Uses normalized RU peaks over the selected chart period and sustained container 429 responses.", "Using resource group \"{0}\".": "Using resource group \"{0}\".", + "Validate service increments, resource-specific minimum throughput, storage and future demand before changing the maximum.": "Validate service increments, resource-specific minimum throughput, storage and future demand before changing the maximum.", "Validation could not establish prerequisite status. Review the reported errors before choosing a repair.": "Validation could not establish prerequisite status. Review the reported errors before choosing a repair.", "Validation failed": "Validation failed", "Validation unavailable": "Validation unavailable", @@ -2099,7 +2114,6 @@ "Workspace": "Workspace", "Workspace not found for id {0}": "Workspace not found for id {0}", "Write and storage pressure": "Write and storage pressure", - "Write cost doubles the moment a second write region is added.": "Write cost doubles the moment a second write region is added.", "Write distribution": "Write distribution", "Write locations": "Write locations", "Write-dominant bursts drive throttling, indicating ingestion is not paced against provisioned throughput.": "Write-dominant bursts drive throttling, indicating ingestion is not paced against provisioned throughput.", diff --git a/src/panels/accountOverview/services/advisories/collectParity.test.ts b/src/panels/accountOverview/services/advisories/collectParity.test.ts index db131db00..08deccb36 100644 --- a/src/panels/accountOverview/services/advisories/collectParity.test.ts +++ b/src/panels/accountOverview/services/advisories/collectParity.test.ts @@ -55,7 +55,7 @@ vi.mock('./fetchers/metrics', () => ({ getContainerPartitionCount: vi.fn(), })); -import { CosmosDBManagementClient, type ThroughputSettingsGetResults } from '@azure/arm-cosmosdb'; +import { CosmosDBManagementClient } from '@azure/arm-cosmosdb'; import { MonitorClient, type Response as MetricsResponse } from '@azure/arm-monitor'; import { getSqlInventoryDetails } from '../inventory'; import { getPartitionHealth, getPartitionStorageSeries } from '../partitionHealth'; diff --git a/src/panels/accountOverview/services/advisories/core/helpers.ts b/src/panels/accountOverview/services/advisories/core/helpers.ts index e8a7b9d31..e3826ada2 100644 --- a/src/panels/accountOverview/services/advisories/core/helpers.ts +++ b/src/panels/accountOverview/services/advisories/core/helpers.ts @@ -4,11 +4,7 @@ *--------------------------------------------------------------------------------------------*/ import { DIAGNOSTIC_POLICY } from './thresholds'; -import { - type DerivedAdvisory, - type DerivedAdvisorySeverity, - type UtilizationBand, -} from './types'; +import { type DerivedAdvisory, type DerivedAdvisorySeverity, type UtilizationBand } from './types'; export function utilizationBand(value: number, moderateUpperPercent: number): UtilizationBand { return value < DIAGNOSTIC_POLICY.overProvisioning.idleBandPercent diff --git a/src/webviews/cosmosdb/AccountOverview/DerivedAdvisories.test.tsx b/src/webviews/cosmosdb/AccountOverview/DerivedAdvisories.test.tsx index 6bef717ec..5d928efb2 100644 --- a/src/webviews/cosmosdb/AccountOverview/DerivedAdvisories.test.tsx +++ b/src/webviews/cosmosdb/AccountOverview/DerivedAdvisories.test.tsx @@ -144,7 +144,6 @@ describe('log coverage guidance', () => { }); describe('metric coverage and actionable findings', () => { - it('announces incomplete metric checks without claiming a clean result or blaming Log Analytics', () => { showCoverage( { available: true }, From 3f4f76d2ff3d6c60077d1e8462fd4766be964d2b Mon Sep 17 00:00:00 2001 From: Dmitrii Shilov <6812525+bk201-@users.noreply.github.com> Date: Wed, 11 Nov 2026 19:42:22 +0100 Subject: [PATCH 03/12] fix: remove redundant array spread in intermediate advisory router Splitting out configuration failures left filter/map as the only array member in the native-detector and request-log layers, triggering unicorn/no-useless-spread. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../derivedAdvisoriesRouter.ts | 20 +++++++++---------- 1 file changed, 9 insertions(+), 11 deletions(-) diff --git a/src/panels/trpc/routers/accountOverview/derivedAdvisoriesRouter.ts b/src/panels/trpc/routers/accountOverview/derivedAdvisoriesRouter.ts index ca296226b..df8c40b0b 100644 --- a/src/panels/trpc/routers/accountOverview/derivedAdvisoriesRouter.ts +++ b/src/panels/trpc/routers/accountOverview/derivedAdvisoriesRouter.ts @@ -91,17 +91,15 @@ export async function getDerivedAdvisoriesForAccount( ), metricSource: { available: false, - failures: [ - ...DETECTORS.filter( - ({ rule }) => - rule !== 'ExpensiveConsistency' && - rule !== 'MultiRegionWriteAntipattern' && - rule !== 'CrossPartitionQuery' && - rule !== 'ShardKeyMisalignment' && - rule !== 'UncontrolledIngestion' && - rule !== 'SharedThroughputStarvation', - ).map(({ rule }) => ({ rule, reason })), - ], + failures: DETECTORS.filter( + ({ rule }) => + rule !== 'ExpensiveConsistency' && + rule !== 'MultiRegionWriteAntipattern' && + rule !== 'CrossPartitionQuery' && + rule !== 'ShardKeyMisalignment' && + rule !== 'UncontrolledIngestion' && + rule !== 'SharedThroughputStarvation', + ).map(({ rule }) => ({ rule, reason })), }, logSource: { available: false, reason }, generatedAt: Date.now(), From a3c40f183b0981d9e7e342fa8f4fefb391dc0ee4 Mon Sep 17 00:00:00 2001 From: Dmitrii Shilov <6812525+bk201-@users.noreply.github.com> Date: Fri, 13 Nov 2026 11:49:42 +0100 Subject: [PATCH 04/12] fix: classify fan-out using all observed query shapes The top-200 shape cap biased execution rates and shares, suppressing findings or overstating structural misalignment. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- specs/account-overview.md | 4 +- .../services/advisories/fetchers/logs.test.ts | 56 +++++++++++++++++++ .../services/advisories/fetchers/logs.ts | 3 +- 3 files changed, 59 insertions(+), 4 deletions(-) diff --git a/specs/account-overview.md b/specs/account-overview.md index 3f6144964..1cab0fdbf 100644 --- a/specs/account-overview.md +++ b/specs/account-overview.md @@ -732,8 +732,8 @@ An SDK partial-query failure excludes that query's evidence rather than treating Independent probes/queries can still provide successful findings. Query fan-out groups `dcount(PartitionKeyRangeId)` by correlated activity ID and query text, -then aggregates execution count/average/max fan-out per query shape and takes the 200 most frequent shapes. -Execution shares and inferred partition count are therefore based on those returned shapes; +then aggregates execution count/average/max fan-out per query shape without a top-shape cap. +Execution shares, rates and inferred partition count use all returned shapes, not a display-limited subset; “inferred partitions” is maximum observed fan-out, not an ARM partition inventory. The strongest query shape is the qualifying shape with the most executions. Ingestion write RU sums RequestCharge for exact operations Create, Upsert, Replace, Delete, Patch, Batch and Execute. diff --git a/src/panels/accountOverview/services/advisories/fetchers/logs.test.ts b/src/panels/accountOverview/services/advisories/fetchers/logs.test.ts index 8bd74379b..b498f126b 100644 --- a/src/panels/accountOverview/services/advisories/fetchers/logs.test.ts +++ b/src/panels/accountOverview/services/advisories/fetchers/logs.test.ts @@ -11,6 +11,8 @@ import { type LogsTable, } from '@azure/monitor-query-logs'; import { describe, expect, it, vi } from 'vitest'; +import { crossPartitionQueryDetector } from '../detectors/CrossPartitionQueryDetector'; +import { shardKeyMisalignmentDetector } from '../detectors/ShardKeyMisalignmentDetector'; import { classifyLogsError, cleanQueryText, @@ -57,6 +59,60 @@ function executorByQuery(map: { match: string; table: LogsTable }[]): LogsQueryE }; } +describe('complete fan-out observations', () => { + it('classifies all 400 shapes instead of suppressing findings with the 200-shape cap', async () => { + const rows = Array.from({ length: 400 }, (_, index) => [`SELECT p${index}`, 30, 4, 4]); + const queryResource = vi.fn(async (_id, query) => { + const limit = query.match(/\| top (\d+) by executions desc/); + return success( + table( + ['QueryText', 'executions', 'avgFanout', 'maxFanout'], + limit ? rows.slice(0, Number(limit[1])) : rows, + ), + ); + }); + const input = await fetchCrossPartitionShapes({ queryResource }, RESOURCE, 'db', 'items', SPAN); + const crossPartition = crossPartitionQueryDetector.evaluate(input, { + minQueries: 50, + fanoutThreshold: 1.5, + medPct: 10, + }); + const shardKey = shardKeyMisalignmentDetector.evaluate(input, { structuralPct: 60, minPartitions: 2 }, 1.5); + for (const advisory of [crossPartition, shardKey]) { + expect(advisory?.evidence).toMatchObject({ + totalQueries: 12_000, + crossPartitionPct: 100, + crossQueriesPerSecond: 12_000 / 86_400, + }); + } + expect(input.shapes).toHaveLength(400); + expect(queryResource).toHaveBeenCalledOnce(); + }); + + it('includes less frequent single-partition shapes in the fan-out denominator', async () => { + const rows = [ + ...Array.from({ length: 200 }, (_, index) => [`SELECT fanout${index}`, 60, 4, 4]), + ...Array.from({ length: 400 }, (_, index) => [`SELECT single${index}`, 59, 1, 1]), + ]; + const queryResource = vi.fn(async (_id, query) => { + const limit = query.match(/\| top (\d+) by executions desc/); + return success( + table( + ['QueryText', 'executions', 'avgFanout', 'maxFanout'], + limit ? rows.slice(0, Number(limit[1])) : rows, + ), + ); + }); + const input = await fetchCrossPartitionShapes({ queryResource }, RESOURCE, 'db', 'items', SPAN); + expect( + crossPartitionQueryDetector.evaluate(input, { minQueries: 50, fanoutThreshold: 1.5, medPct: 10 })?.evidence, + ).toMatchObject({ totalQueries: 35_600, crossPartitionPct: (100 * 12_000) / 35_600 }); + expect( + shardKeyMisalignmentDetector.evaluate(input, { structuralPct: 60, minPartitions: 2 }, 1.5), + ).toBeUndefined(); + }); +}); + describe('tableToRecords', () => { it('maps each row into a column → cell record', () => { const records = tableToRecords(table(['QueryText', 'executions'], [['SELECT 1', 42]])); diff --git a/src/panels/accountOverview/services/advisories/fetchers/logs.ts b/src/panels/accountOverview/services/advisories/fetchers/logs.ts index 9df1233e0..77df9485d 100644 --- a/src/panels/accountOverview/services/advisories/fetchers/logs.ts +++ b/src/panels/accountOverview/services/advisories/fetchers/logs.ts @@ -220,8 +220,7 @@ export async function fetchCrossPartitionShapes( `| where DatabaseName == '${db}' and CollectionName == '${coll}' ` + '| summarize partitionsHit = dcount(PartitionKeyRangeId) by CorrelatedActivityId, QueryText ' + '| summarize executions = count(), avgFanout = avg(partitionsHit), maxFanout = max(partitionsHit) ' + - 'by QueryText ' + - '| top 200 by executions desc'; + 'by QueryText'; const rows = await executeLogsQuery( executor, resourceId, From 4479099fbf0d176d777dea4bca728e1cc9bf71a3 Mon Sep 17 00:00:00 2001 From: Dmitrii Shilov <6812525+bk201-@users.noreply.github.com> Date: Fri, 13 Nov 2026 13:58:30 +0100 Subject: [PATCH 05/12] docs: defer CODA conformance claims until the tooling layer Keep PR two accurate on its own; restore the pin, commands and scenario evidence with PR six. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- specs/account-overview.md | 23 ----------------------- 1 file changed, 23 deletions(-) diff --git a/specs/account-overview.md b/specs/account-overview.md index 1cab0fdbf..264cbcaa5 100644 --- a/specs/account-overview.md +++ b/specs/account-overview.md @@ -677,29 +677,6 @@ The collector skips DX-024 storage-metric requests for an explicitly disabled in without reporting missing metric coverage for that container. Missing or unrecognized modes do not establish disabled indexing; metric acquisition and missing/failed-evidence reporting remain unchanged for those containers. -**Conformance:** `externalSpecifications.coda` in `package.json` pins the private source revision. -`npm run test:coda` fetches/verifies an isolated Git-ignored checkout and executes its unmodified `.feature` files -through Cucumber's Gherkin compiler and TypeScript bindings for all 24 rules. Bindings prepare synthetic inputs -and call production evaluations plus the native registry. Metric/log-reader fixtures exercise partition summation, -account RU folding, storage history, latest populated index/data samples, recent throttling and acquisition failures. -Production results expose utilization bands, sizing observations, root causes and non-finding outcomes. -Diagnostic evaluation types constrain root causes and observation shapes per rule; configuration coverage and -configuration-only detectors share the same pure classifications while keeping applicability separate from missing inputs. -Bindings do not reconstruct detector decisions from the absence of a recommendation. Acquisition-error vocabulary -is normalized from actual native structured failures, not fabricated as a clean negative result. -Every selected scenario must evaluate and assert; unknown bindings fail. The private local report inventories all -scenarios, including those outside an explicitly selected subset. Original wording-sensitive guidance assertions -are retained; cross-rule `supersededBy` is additional pipeline metadata, not part of an isolated detector verdict. -Setup fidelity is checked independently of verdict assertions: the DX-008 Serverless exclusion receives otherwise -quantifiable positive manual capacity, and DX-009 migration starts from a known Periodic policy. Missing retention -tiers remain absent rather than literal strings; storage histories, query windows and configured-region normalization -retain the original bindings' inputs. -All 379 scenarios at the manifest pin pass, with zero unbound, skipped or unexecuted scenarios. -DX-004 classifies successful empty consumption reads as idle, without converting acquisition failures to zero. -DX-017 compares fitted growth against the inclusive 0.1 GiB/day floor using a roundoff estimate scaled by sample -magnitudes and regression conditioning, not an arbitrary policy epsilon or rounded fixtures. Growth measurably below -the floor remains stable. Synthetic conformance does not establish live collector acceptance. - DX-008 regional capacity observations require a complete, positive all-manual offer inventory and known provisioned account/region count. They report configured per-region RU/s and the global regional footprint, not measured usage, billable savings or permission to remove regions. Extra-region capacity is only identified for the non-production From f4565068844315ae39e734522d1f1dbd6cca6f05 Mon Sep 17 00:00:00 2001 From: Dmitrii Shilov <6812525+bk201-@users.noreply.github.com> Date: Fri, 13 Nov 2026 13:58:39 +0100 Subject: [PATCH 06/12] docs: defer CODA freshness command until its implementation layer Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- specs/account-overview.md | 6 ------ 1 file changed, 6 deletions(-) diff --git a/specs/account-overview.md b/specs/account-overview.md index 264cbcaa5..d4db32a3e 100644 --- a/specs/account-overview.md +++ b/specs/account-overview.md @@ -683,12 +683,6 @@ billable savings or permission to remove regions. Extra-region capacity is only finding; legitimate HA has no removable extra-region capacity. Autoscale, serverless and incomplete inventories are not quantified. MongoDB metadata support in this pure configuration evaluation does not introduce a MongoDB provider. -`npm run coda:check` independently compares the tracked branch HEAD and pin, reports exact ahead/behind counts including -rewound/divergent/unrelated histories, and exits nonzero for mismatch or unverifiable source access. It never repins. -The package-feed workflow runs it in a separate advisory job without build dependencies or `continue-on-error`. -Private read credentials are withheld from every PR; owner-managed push/manual credentials and optional branch-rule -configuration are required separately. Freshness equality is not a conformance result. - **Adoption limits:** native collection and computation remain separate; there is no CODA MCP/Python dependency. Aggregate request-log support, complete per-rule/per-scope evaluation outcomes, other upstream enrichment and approved public contract distribution remain separate work. Private upstream files are not vendored into tracked source. From 0a6722fba8510312d79d319aae786c829e30b1fb Mon Sep 17 00:00:00 2001 From: Dmitrii Shilov <6812525+bk201-@users.noreply.github.com> Date: Fri, 13 Nov 2026 15:02:57 +0100 Subject: [PATCH 07/12] fix: distinguish observed zero storage from missing history The zero-initialized maximum incorrectly treated a valid zero-byte sample as missing evidence. Use the empty partition list and missing-history flag for insufficient_data, preserving too_small for observed zero bytes. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- specs/account-overview.md | 3 ++ .../advisories/derivedAdvisories.test.ts | 29 +++++++++++++++++++ .../detectors/StorageGrowthRiskDetector.ts | 2 +- 3 files changed, 33 insertions(+), 1 deletion(-) diff --git a/specs/account-overview.md b/specs/account-overview.md index d4db32a3e..49d975f80 100644 --- a/specs/account-overview.md +++ b/specs/account-overview.md @@ -668,6 +668,9 @@ Horizon and 30/90-day severity comparisons use the fitted slope's arithmetic rou minimum-slope gate. Presentation rounding must not decide eligibility or severity. A material partition without two distinct finite observations produces `insufficient_data`, not `stable`, when no other partition establishes a finding; already-at-limit and qualifying-growth findings remain available despite another partition's missing history. +A valid latest observation of zero bytes is evidence below the materiality floor and produces `too_small` when +all partitions are observed and immaterial. An empty partition list or a partition without usable history remains +`insufficient_data` when no other partition establishes a finding. **Index exclusions:** ignore only exact root strings `/_etag/?` and `/"_etag"/?` when counting exclusions. Nested `_etag`, differently cased, other paths and unknown path entries are not implicitly system exclusions. diff --git a/src/panels/accountOverview/services/advisories/derivedAdvisories.test.ts b/src/panels/accountOverview/services/advisories/derivedAdvisories.test.ts index ce60abb59..061f3b06f 100644 --- a/src/panels/accountOverview/services/advisories/derivedAdvisories.test.ts +++ b/src/panels/accountOverview/services/advisories/derivedAdvisories.test.ts @@ -577,6 +577,35 @@ describe('evaluateStorageGrowthRisk', () => { expect(result).toEqual({ rootCause: 'insufficient_data' }); }); + it.each([{ gib: [0] }, { gib: [0, 0] }, { gib: [2, 0] }])( + 'classifies an observed zero-byte partition as too small ($gib GiB history)', + ({ gib }) => { + const result = new StorageGrowthRiskDetector().evaluateResult(container([storageSeries('0', gib)]), 180); + expect(result).toEqual({ rootCause: 'too_small' }); + }, + ); + + it('classifies multiple observed zero-byte partitions as too small', () => { + const result = new StorageGrowthRiskDetector().evaluateResult( + container([storageSeries('0', [0]), storageSeries('1', [0])]), + 180, + ); + expect(result).toEqual({ rootCause: 'too_small' }); + }); + + it('reports an empty partition list as insufficient data', () => { + const result = new StorageGrowthRiskDetector().evaluateResult(container([]), 180); + expect(result).toEqual({ rootCause: 'insufficient_data' }); + }); + + it('does not let observed zero bytes hide another partition without history', () => { + const result = new StorageGrowthRiskDetector().evaluateResult( + container([storageSeries('zero', [0]), { partitionId: 'unknown', samples: [] }]), + 180, + ); + expect(result).toEqual({ rootCause: 'insufficient_data' }); + }); + it('retains stable and too-small results when their required evidence is available', () => { const detector = new StorageGrowthRiskDetector(); expect(detector.evaluateResult(container([storageSeries('flat', [40, 40])]), 180).rootCause).toBe('stable'); diff --git a/src/panels/accountOverview/services/advisories/detectors/StorageGrowthRiskDetector.ts b/src/panels/accountOverview/services/advisories/detectors/StorageGrowthRiskDetector.ts index 11d7c60ce..374da80ed 100644 --- a/src/panels/accountOverview/services/advisories/detectors/StorageGrowthRiskDetector.ts +++ b/src/panels/accountOverview/services/advisories/detectors/StorageGrowthRiskDetector.ts @@ -104,7 +104,7 @@ function evaluateStorageGrowthRisk( if (soonest === undefined || !reachesWithinDays(horizonDays)) { return { rootCause: - missingHistory || largestObserved <= 0 + missingHistory || input.partitions.length === 0 ? 'insufficient_data' : largestObserved < STORAGE_GROWTH_MIN_MATERIAL_BYTES ? 'too_small' From f793ae7a6249845a25a39c5efb8c0d690a5dd869 Mon Sep 17 00:00:00 2001 From: Dmitrii Shilov <6812525+bk201-@users.noreply.github.com> Date: Fri, 13 Nov 2026 15:18:29 +0100 Subject: [PATCH 08/12] test: cover manual regional capacity and HA exclusions Exercise a mixed shared/dedicated all-manual inventory through the real advisory engine, excluding autoscale and incomplete inventories. Verify removable non-production capacity separately from legitimate production HA. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../services/advisories/collectParity.test.ts | 101 ++++++++++++++++++ .../advisories/derivedAdvisories.test.ts | 26 +++++ 2 files changed, 127 insertions(+) diff --git a/src/panels/accountOverview/services/advisories/collectParity.test.ts b/src/panels/accountOverview/services/advisories/collectParity.test.ts index 08deccb36..37abc059e 100644 --- a/src/panels/accountOverview/services/advisories/collectParity.test.ts +++ b/src/panels/accountOverview/services/advisories/collectParity.test.ts @@ -165,6 +165,107 @@ describe('collectDerivedAdvisories parity wiring', () => { }, ); + it.each([ + { name: 'all manual', complete: true, sharedAutoscale: false, dedicatedAutoscale: false, capacity: 7000 }, + { + name: 'shared autoscale', + complete: true, + sharedAutoscale: true, + dedicatedAutoscale: false, + capacity: undefined, + }, + { + name: 'dedicated autoscale', + complete: true, + sharedAutoscale: false, + dedicatedAutoscale: true, + capacity: undefined, + }, + { name: 'incomplete', complete: false, sharedAutoscale: false, dedicatedAutoscale: false, capacity: undefined }, + ])( + 'quantifies regional capacity only for complete all-manual offers ($name)', + async ({ complete, sharedAutoscale, dedicatedAutoscale, capacity }) => { + const engine = await vi.importActual('./engine'); + vi.mocked(computeDerivedAdvisories).mockImplementation(engine.computeDerivedAdvisories); + const offers: InventoryModule.InventoryThroughputOffer[] = [ + { + databaseId: 'db', + offerLevel: 'database', + throughputMode: sharedAutoscale ? 'autoscale' : 'shared', + offerThroughputMode: sharedAutoscale ? 'autoscale' : 'manual', + throughputRU: 6000, + }, + { + databaseId: 'db', + containerId: 'dedicated', + offerLevel: 'container', + throughputMode: dedicatedAutoscale ? 'autoscale' : 'dedicated', + offerThroughputMode: dedicatedAutoscale ? 'autoscale' : 'manual', + throughputRU: 1000, + }, + ]; + const rows = offers.flatMap((offer) => + (offer.containerId === undefined + ? ['shared-a', 'shared-b'] + : [offer.containerId] + ).map((containerId) => ({ + ...offer, + containerId, + resourceCreatedAt: '2020-01-01T00:00:00Z', + partitionKeyPaths: [], + indexingMode: 'none', + excludedPathCount: 0, + userExcludedPathCount: 0, + compositeIndexCount: 0, + health: 'Healthy', + })), + ); + vi.mocked(getSqlInventoryDetails).mockResolvedValue({ + databases: ['db'], + rows, + offers, + throughputInventoryComplete: complete, + }); + vi.mocked(getRuTrends).mockResolvedValue({ + available: false, + reason: 'noData', + points: [], + provisionedPercent: 100, + timeRange: '7D', + generatedAt: 0, + }); + + const result = await collectDerivedAdvisories( + params({ + logsClient: undefined, + accountConfig: { + accountName: 'orders-dev', + regionCount: 3, + multiRegionWritesEnabled: true, + writeRegionCount: 3, + api: API.Core, + }, + }), + ); + + const inputs = vi.mocked(computeDerivedAdvisories).mock.calls[0][0]; + expect(inputs.scopeProvisionedRuTotal).toBe(complete ? 7000 : undefined); + expect(inputs.manualRegionalCapacityRu).toBe(capacity); + const finding = result.advisories.find((item) => item.rule === 'MultiRegionWriteAntipattern'); + expect(finding).toMatchObject({ severity: 'Medium' }); + expect(finding?.evidence).toEqual( + capacity === undefined + ? undefined + : { + regionalCapacityQuantified: true, + configuredPerRegionRu: 7000, + globalRegionalFootprintRu: 21000, + removableExtraRegionRu: 14000, + }, + ); + }, + ); + it.each(['none', 'NoNe', 'NONE'])( 'skips DX-024 metric acquisition and coverage failures for %s indexing', async (indexingMode) => { diff --git a/src/panels/accountOverview/services/advisories/derivedAdvisories.test.ts b/src/panels/accountOverview/services/advisories/derivedAdvisories.test.ts index 061f3b06f..9645151b2 100644 --- a/src/panels/accountOverview/services/advisories/derivedAdvisories.test.ts +++ b/src/panels/accountOverview/services/advisories/derivedAdvisories.test.ts @@ -869,6 +869,32 @@ describe('evaluateMultiRegionWrites', () => { const advisory = evaluateMultiRegionWrites(config({ accountName: 'orders-dev', writeRegionCount: 2 })); expect(advisory?.severity).toBe('Medium'); }); + + it.each([ + { accountName: 'orders-dev', rootCause: 'nonprod_multi_region_writes', removableExtraRegionRu: 14000 }, + { accountName: 'orders-prod', rootCause: 'legitimate_ha', removableExtraRegionRu: null }, + ])( + 'quantifies regional footprint without assuming HA regions are removable ($accountName)', + ({ accountName, rootCause, removableExtraRegionRu }) => { + const result = new MultiRegionWriteAntipatternDetector().evaluateResult( + config({ accountName, regionCount: 3, writeRegionCount: 3, isServerless: false }), + 7000, + ); + const observations = { + regionalCapacityQuantified: true, + configuredPerRegionRu: 7000, + globalRegionalFootprintRu: 21000, + removableExtraRegionRu, + }; + expect(result.rootCause).toBe(rootCause); + expect(result.observations).toEqual(observations); + expect(result.advisory).toEqual( + removableExtraRegionRu === null + ? undefined + : expect.objectContaining({ severity: 'Medium', evidence: observations }), + ); + }, + ); }); describe('computeDerivedAdvisories with accountConfig', () => { From 15ee413a107a4d25f268049743e67dda8d61d6e8 Mon Sep 17 00:00:00 2001 From: Dmitrii Shilov <6812525+bk201-@users.noreply.github.com> Date: Fri, 13 Nov 2026 15:21:47 +0100 Subject: [PATCH 09/12] test: keep regional capacity expectations unconditional Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../services/advisories/derivedAdvisories.test.ts | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/src/panels/accountOverview/services/advisories/derivedAdvisories.test.ts b/src/panels/accountOverview/services/advisories/derivedAdvisories.test.ts index 9645151b2..6775a8ac4 100644 --- a/src/panels/accountOverview/services/advisories/derivedAdvisories.test.ts +++ b/src/panels/accountOverview/services/advisories/derivedAdvisories.test.ts @@ -888,11 +888,9 @@ describe('evaluateMultiRegionWrites', () => { }; expect(result.rootCause).toBe(rootCause); expect(result.observations).toEqual(observations); - expect(result.advisory).toEqual( - removableExtraRegionRu === null - ? undefined - : expect.objectContaining({ severity: 'Medium', evidence: observations }), - ); + expect(result).toMatchObject({ + advisory: removableExtraRegionRu === null ? undefined : { severity: 'Medium', evidence: observations }, + }); }, ); }); From eb295f5af74f3f0432591472ed372c9568e4c55c Mon Sep 17 00:00:00 2001 From: Dmitrii Shilov <6812525+bk201-@users.noreply.github.com> Date: Fri, 13 Nov 2026 17:41:24 +0100 Subject: [PATCH 10/12] docs: keep native detector evidence scoped to raw logs Describe only the raw request-log acquisition available in this PR; aggregate selection belongs to the following acquisition layer. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- specs/account-overview.md | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/specs/account-overview.md b/specs/account-overview.md index 49d975f80..321892201 100644 --- a/specs/account-overview.md +++ b/specs/account-overview.md @@ -526,21 +526,21 @@ It is not normalized RU divided by the configured max. The Serverless-candidate `TotalRequestUnits` Total collisions per timestamp, divides each bucket by 3,600 seconds, then takes peak/mean over observed hourly buckets. Missing buckets do not become zero samples in either calculation. -| Evidence | Window / grain | Live collector targets | -| ----------------------------------- | ---------------------------------------------- | --------------------------------------------------------- | -| Manual normalized RU | 30 days / 1 hour | Dedicated manual and shared manual database offers | -| Idle consumed RU, Total | 30 days / 5 minutes | Dedicated and shared database offers, manual/autoscale | -| Partition p99 + request-rate totals | 7 days / 1 hour | Dedicated and shared database offers | -| Partition storage for growth | 30 days / 1 hour | Dedicated containers | -| Partition storage for skew | 7 days / 1 hour | Dedicated containers | -| Index/data storage | Latest populated samples, 6 hours / 5 minutes | All inventory containers, including shared and Serverless | -| Partition count and DataUsage peaks | 6 hours / 5 minutes | Dedicated containers, explicit database/container queries | -| AutoscaledRU | 30 days / 1 hour | Dedicated and shared database autoscale offers | -| Consumed-RU shape | 30 days / 1 hour | Non-Serverless account, no database filter | -| Serverless request-rate totals | 7 days / 1 hour | Serverless containers | -| Log query fan-out evidence | Last 24 hours, raw event aggregation | Dedicated and Serverless containers | -| Log ingestion evidence | 24 hours, five-minute aggregates or raw events | Dedicated containers | -| Log shared-pool evidence | Same selected request-log source/window | Shared-throughput database offers | +| Evidence | Window / grain | Live collector targets | +| ----------------------------------- | --------------------------------------------- | --------------------------------------------------------- | +| Manual normalized RU | 30 days / 1 hour | Dedicated manual and shared manual database offers | +| Idle consumed RU, Total | 30 days / 5 minutes | Dedicated and shared database offers, manual/autoscale | +| Partition p99 + request-rate totals | 7 days / 1 hour | Dedicated and shared database offers | +| Partition storage for growth | 30 days / 1 hour | Dedicated containers | +| Partition storage for skew | 7 days / 1 hour | Dedicated containers | +| Index/data storage | Latest populated samples, 6 hours / 5 minutes | All inventory containers, including shared and Serverless | +| Partition count and DataUsage peaks | 6 hours / 5 minutes | Dedicated containers, explicit database/container queries | +| AutoscaledRU | 30 days / 1 hour | Dedicated and shared database autoscale offers | +| Consumed-RU shape | 30 days / 1 hour | Non-Serverless account, no database filter | +| Serverless request-rate totals | 7 days / 1 hour | Serverless containers | +| Log query fan-out evidence | Last 24 hours, raw event aggregation | Dedicated and Serverless containers | +| Log ingestion evidence | Last 24 hours, raw event aggregation | Dedicated containers | +| Log shared-pool evidence | Last 24 hours, raw event aggregation | Shared-throughput database offers | Per-container idle/merge queries MUST target known containers, not discover them through wildcard metric series or a larger `top`. Shared-offer throughput utilization/saturation queries select the database offer's empty `CollectionName` dimension, From 3c0abb5a9c1575f76ea98ed64708f05f6efd814e Mon Sep 17 00:00:00 2001 From: Dmitrii Shilov <6812525+bk201-@users.noreply.github.com> Date: Thu, 19 Nov 2026 13:37:45 +0100 Subject: [PATCH 11/12] fix: regenerate localization in the native detector layer Remove the obsolete container-count key at the earliest affected PR so each descendant passes l10n:check after rebasing. Regenerated the catalog with npm run l10n. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- l10n/bundle.l10n.json | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/l10n/bundle.l10n.json b/l10n/bundle.l10n.json index dc20f1d41..0669e71a0 100644 --- a/l10n/bundle.l10n.json +++ b/l10n/bundle.l10n.json @@ -110,7 +110,6 @@ "$(plus) Create new user-assigned identity": "$(plus) Create new user-assigned identity", "$(warning) Only storage accounts in the region \"{0}\" are shown.": "$(warning) Only storage accounts in the region \"{0}\" are shown.", "$(warning) Some storage accounts were filtered because of their network configurations.": "$(warning) Some storage accounts were filtered because of their network configurations.", - "1 container affected": "1 container affected", "1 matching scenario": "1 matching scenario", "1 more step": "1 more step", "1 resource affected": "1 resource affected", @@ -1560,10 +1559,10 @@ "Review multi-region-write compatibility and availability requirements before changing the flag. Disabling multi-write while keeping all regions does not remove their provisioned capacity.": "Review multi-region-write compatibility and availability requirements before changing the flag. Disabling multi-write while keeping all regions does not remove their provisioned capacity.", "Review stronger consistency requirements": "Review stronger consistency requirements", "Review the partition key for a higher-cardinality choice so data spreads evenly.": "Review the partition key for a higher-cardinality choice so data spreads evenly.", - "Review these issues. They will not block a recommendation.": "Review these issues. They will not block a recommendation.", "Review the shared database offer and all its member workloads before decommissioning or changing capacity. An idle member alone does not make the shared offer recoverable.": "Review the shared database offer and all its member workloads before decommissioning or changing capacity. An idle member alone does not make the shared offer recoverable.", "Review the shared database offer and member workloads for partition skew. Identify the affected containers before changing a partition key or isolating throughput.": "Review the shared database offer and member workloads for partition skew. Identify the affected containers before changing a partition key or isolating throughput.", "Review the write-conflict and pricing implications against the current API and region configuration.": "Review the write-conflict and pricing implications against the current API and region configuration.", + "Review these issues. They will not block a recommendation.": "Review these issues. They will not block a recommendation.", "Review whether multi-region writes fit the API, write-region configuration and environment requirements.": "Review whether multi-region writes fit the API, write-region configuration and environment requirements.", "Review your inputs": "Review your inputs", "Role": "Role", From 9865be520a539f76b14c368e29ed3afe627cf7e6 Mon Sep 17 00:00:00 2001 From: Dmitrii Shilov <6812525+bk201-@users.noreply.github.com> Date: Thu, 19 Nov 2026 16:44:24 +0100 Subject: [PATCH 12/12] fix: preserve CODA storage-skew classification precedence Classify immaterial observations before balance, matching the pinned source contract. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- specs/account-overview.md | 12 ++++++++--- .../derivedAdvisories.parity.test.ts | 21 +++++++++++++++++++ .../advisories/derivedAdvisories.test.ts | 8 +++---- .../detectors/StorageGrowthRiskDetector.ts | 2 +- .../detectors/StorageSkewRiskDetector.ts | 6 +++--- 5 files changed, 38 insertions(+), 11 deletions(-) diff --git a/specs/account-overview.md b/specs/account-overview.md index 321892201..10eb1b88d 100644 --- a/specs/account-overview.md +++ b/specs/account-overview.md @@ -628,6 +628,11 @@ not entries in the derived-detector registry. | AO-D21 `ServerlessThrottling` / DX-018 | Serverless container; >=1,000 requests; rate >=1%; no normalized-RU prerequisite | High rate >=20%; Medium >=5%; otherwise Low | | AO-D3 `StorageSkewRisk` / DX-015 | Age not known <1 day; >=2 valid non-negative partition peaks; busiest >=1 GiB; coolest/busiest <0.7 | High busiest >=40 GiB; Medium >=25 GiB; otherwise Low | +**Storage-skew classification:** match CODA's observed-data ordering: no usable histories is +`insufficient_data`; one usable history is `single_partition`; multiple histories below the 1 GiB +materiality floor are `too_small` before testing balance. Only material balanced observations are +`uniform_storage`. Missing histories are excluded, not replaced with zero-byte partitions. + **Capacity materiality M:** with positive known account offer total, High if recoverable/total >=5%, Medium if >=1%, otherwise Low. Without that total, High if recoverable >=5,000 RU/s, Medium if >=1,000 RU/s, otherwise Low. These are capacity heuristics, not money saved. @@ -668,9 +673,10 @@ Horizon and 30/90-day severity comparisons use the fitted slope's arithmetic rou minimum-slope gate. Presentation rounding must not decide eligibility or severity. A material partition without two distinct finite observations produces `insufficient_data`, not `stable`, when no other partition establishes a finding; already-at-limit and qualifying-growth findings remain available despite another partition's missing history. -A valid latest observation of zero bytes is evidence below the materiality floor and produces `too_small` when -all partitions are observed and immaterial. An empty partition list or a partition without usable history remains -`insufficient_data` when no other partition establishes a finding. +As in CODA, a largest current observation of zero bytes produces `insufficient_data`, not `too_small`. +Positive observations below the materiality floor remain `too_small` when all histories are usable. +An empty partition list or a partition without usable history remains `insufficient_data` when no other partition +establishes a finding. Observed zero bytes are retained as data, not replaced with a missing-series sentinel. **Index exclusions:** ignore only exact root strings `/_etag/?` and `/"_etag"/?` when counting exclusions. Nested `_etag`, differently cased, other paths and unknown path entries are not implicitly system exclusions. diff --git a/src/panels/accountOverview/services/advisories/derivedAdvisories.parity.test.ts b/src/panels/accountOverview/services/advisories/derivedAdvisories.parity.test.ts index 19cfe34ec..0e921ff7c 100644 --- a/src/panels/accountOverview/services/advisories/derivedAdvisories.parity.test.ts +++ b/src/panels/accountOverview/services/advisories/derivedAdvisories.parity.test.ts @@ -608,6 +608,19 @@ describe('CODA parity — DX-017 StorageGrowthRisk (test_storage_growth.py)', () // ------------------------------------------------------------------------------------------------- describe('CODA parity — DX-015 StorageSkewRisk (test_storage_skew.py)', () => { + it.each([ + { histories: [[], []], rootCause: 'insufficient_data' }, + { histories: [[0.2]], rootCause: 'single_partition' }, + { histories: [[0.2], [0.2]], rootCause: 'too_small' }, + { histories: [[0], [0]], rootCause: 'too_small' }, + { histories: [[30], [30], []], rootCause: 'uniform_storage' }, + { histories: [[30], []], rootCause: 'single_partition' }, + ])('preserves observed-series precedence: $histories -> $rootCause', ({ histories, rootCause }) => { + const input = storageContainer(histories.map((values, index) => storageSeries(String(index), values))); + + expect(new StorageSkewRiskDetector().evaluateResult(input, 0.7).rootCause).toBe(rootCause); + }); + it('imbalanced but small is a Low early warning (test_imbalanced_small_is_low_early_warning)', () => { const v = evaluateStorageSkewRisk(storageContainer([storageSeries('0', [2]), storageSeries('1', [0.2])]), 0.7); expect(v?.rule).toBe('StorageSkewRisk'); @@ -866,6 +879,14 @@ function cpInput(shapes: QueryShapeInput[]): CrossPartitionInput { } describe('DX-002 cross-partition query fan-out parity', () => { + it('preserves the CODA root for a sufficient workload whose widest fan-out is one', () => { + const input = cpInput([shape('SELECT * FROM c WHERE c.pk=@p', 800, 1, 1)]); + + expect(new CrossPartitionQueryDetector().evaluateResult(input, CP_THRESHOLDS)).toEqual({ + rootCause: 'single_partition_container', + }); + }); + it('flags Low for a two-partition workload above the fan-out rate floor', () => { const v = evaluateCrossPartitionQuery( cpInput([ diff --git a/src/panels/accountOverview/services/advisories/derivedAdvisories.test.ts b/src/panels/accountOverview/services/advisories/derivedAdvisories.test.ts index 6775a8ac4..db4d5ba2a 100644 --- a/src/panels/accountOverview/services/advisories/derivedAdvisories.test.ts +++ b/src/panels/accountOverview/services/advisories/derivedAdvisories.test.ts @@ -578,19 +578,19 @@ describe('evaluateStorageGrowthRisk', () => { }); it.each([{ gib: [0] }, { gib: [0, 0] }, { gib: [2, 0] }])( - 'classifies an observed zero-byte partition as too small ($gib GiB history)', + 'preserves CODA insufficient_data for an observed zero-byte partition ($gib GiB history)', ({ gib }) => { const result = new StorageGrowthRiskDetector().evaluateResult(container([storageSeries('0', gib)]), 180); - expect(result).toEqual({ rootCause: 'too_small' }); + expect(result).toEqual({ rootCause: 'insufficient_data' }); }, ); - it('classifies multiple observed zero-byte partitions as too small', () => { + it('preserves CODA insufficient_data for multiple observed zero-byte partitions', () => { const result = new StorageGrowthRiskDetector().evaluateResult( container([storageSeries('0', [0]), storageSeries('1', [0])]), 180, ); - expect(result).toEqual({ rootCause: 'too_small' }); + expect(result).toEqual({ rootCause: 'insufficient_data' }); }); it('reports an empty partition list as insufficient data', () => { diff --git a/src/panels/accountOverview/services/advisories/detectors/StorageGrowthRiskDetector.ts b/src/panels/accountOverview/services/advisories/detectors/StorageGrowthRiskDetector.ts index 374da80ed..11d7c60ce 100644 --- a/src/panels/accountOverview/services/advisories/detectors/StorageGrowthRiskDetector.ts +++ b/src/panels/accountOverview/services/advisories/detectors/StorageGrowthRiskDetector.ts @@ -104,7 +104,7 @@ function evaluateStorageGrowthRisk( if (soonest === undefined || !reachesWithinDays(horizonDays)) { return { rootCause: - missingHistory || input.partitions.length === 0 + missingHistory || largestObserved <= 0 ? 'insufficient_data' : largestObserved < STORAGE_GROWTH_MIN_MATERIAL_BYTES ? 'too_small' diff --git a/src/panels/accountOverview/services/advisories/detectors/StorageSkewRiskDetector.ts b/src/panels/accountOverview/services/advisories/detectors/StorageSkewRiskDetector.ts index 99c5328d4..241268b2a 100644 --- a/src/panels/accountOverview/services/advisories/detectors/StorageSkewRiskDetector.ts +++ b/src/panels/accountOverview/services/advisories/detectors/StorageSkewRiskDetector.ts @@ -59,13 +59,13 @@ function evaluateStorageSkewRisk( if (sizes.length === 1) { return { rootCause: 'single_partition' }; } - if (ratio === undefined || ratio >= balanceThreshold) { - return { rootCause: 'uniform_storage' }; - } const busiestBytes = Math.max(...sizes); if (busiestBytes < STORAGE_SKEW_MIN_BUSIEST_BYTES) { return { rootCause: 'too_small' }; } + if (ratio === undefined || ratio >= balanceThreshold) { + return { rootCause: 'uniform_storage' }; + } const severity: DerivedAdvisorySeverity = busiestBytes >= STORAGE_SKEW_HIGH_BYTES ? 'High' : busiestBytes >= STORAGE_SKEW_MEDIUM_BYTES ? 'Medium' : 'Low';