From f0056329a65ffdd20ec32959b06e5e25f5373248 Mon Sep 17 00:00:00 2001 From: Erik Darling <2136037+erikdarlingdata@users.noreply.github.com> Date: Fri, 23 Oct 2026 16:04:28 -0400 Subject: [PATCH 1/2] Make the right-sized sentence say what decided the verdict (#6646) --- .../AzureSqlDatabaseMemoryScopeTests.cs | 22 ++++++++++++++-- .../FinOpsUtilizationFiguresTests.cs | 2 +- .../FinOps/FinOpsUtilizationFigures.cs | 2 +- .../AzureSqlDatabaseMemoryScopeTests.cs | 22 ++++++++++++++-- Lite/Controls/FinOpsTab.xaml.cs | 2 +- .../ServerHardwareScope.cs | 25 ++++++++++++++++--- 6 files changed, 64 insertions(+), 11 deletions(-) diff --git a/Darling/Darling.Tests/AzureSqlDatabaseMemoryScopeTests.cs b/Darling/Darling.Tests/AzureSqlDatabaseMemoryScopeTests.cs index 7b74f4c0a7..3dec42f387 100644 --- a/Darling/Darling.Tests/AzureSqlDatabaseMemoryScopeTests.cs +++ b/Darling/Darling.Tests/AzureSqlDatabaseMemoryScopeTests.cs @@ -115,8 +115,8 @@ public void HealthScore_DoesNotDependOnTheEngineEdition(int engineEdition) [Fact] public void RightSizedSentence_OnAzureSqlDatabase_CitesTheBufferPoolShare_OfTheDatabasesMemoryLimit() { - var onAzure = ServerHardwareScope.RightSizedExplanation(40m, 62m, 71.0, azureSqlDatabase: true); - var onBox = ServerHardwareScope.RightSizedExplanation(40m, 62m, 71.0, azureSqlDatabase: false); + var onAzure = ServerHardwareScope.RightSizedExplanation(40m, 62m, 62m, 71.0, azureSqlDatabase: true); + var onBox = ServerHardwareScope.RightSizedExplanation(40m, 62m, 62m, 71.0, azureSqlDatabase: false); Assert.Equal( "CPU is moderately loaded (avg 40.0%, p95 62.0%) and memory is well-utilized (buffer pool uses 71% of the database's memory limit). No action needed.", @@ -127,6 +127,24 @@ public void RightSizedSentence_OnAzureSqlDatabase_CitesTheBufferPoolShare_OfTheD onBox); } + /// #6646: RIGHT_SIZED is also the verdict for an idle average with one sample at 40% or more. The sentence names the test that + /// decided, and says "well-utilized" only for a buffer pool holding at least half of its basis. + [Fact] + public void RightSizedSentence_ForAnIdleAverageWithOneBusySample_NamesThePeak_NotAModerateLoadOrWellUtilizedMemory() + { + var peak = ServerHardwareScope.RightSizedExplanation(0.1m, 0m, 40m, 8.0, azureSqlDatabase: false); + Assert.DoesNotContain("moderately loaded", peak, StringComparison.Ordinal); + Assert.DoesNotContain("well-utilized", peak, StringComparison.Ordinal); + Assert.Equal( + "CPU averaged 0.1% (p95 0.0%), but one sample reached 40%, so this server is not rated over-provisioned and buffer pool uses 8% of physical RAM. No action needed.", + peak); + + var grants = ServerHardwareScope.RightSizedExplanation(5m, 8m, 12m, 60.0, azureSqlDatabase: true); + Assert.DoesNotContain("moderately loaded", grants, StringComparison.Ordinal); + Assert.Contains("memory grants use 50% or more of their target", grants, StringComparison.Ordinal); + Assert.Contains("memory is well-utilized (buffer pool uses 60% of the database's memory limit)", grants, StringComparison.Ordinal); + } + [Fact] public void OverProvisionedSentence_OnAzureSqlDatabase_CitesTheBufferPoolShare_OfTheDatabasesMemoryLimit() { diff --git a/Darling/Darling.Tests/FinOpsUtilizationFiguresTests.cs b/Darling/Darling.Tests/FinOpsUtilizationFiguresTests.cs index ed29756c57..fdb1181c72 100644 --- a/Darling/Darling.Tests/FinOpsUtilizationFiguresTests.cs +++ b/Darling/Darling.Tests/FinOpsUtilizationFiguresTests.cs @@ -135,7 +135,7 @@ public void Explanation_EqualsTheOldSwitch_InTheCurrentCulture(string status, in var azure = ServerHardwareScope.HardwareIsTheHosts(dto.EngineEdition); var old = dto.ProvisioningStatus switch { - "RIGHT_SIZED" => ServerHardwareScope.RightSizedExplanation(dto.AvgCpuPct, dto.P95CpuPct, bpPct, azure), + "RIGHT_SIZED" => ServerHardwareScope.RightSizedExplanation(dto.AvgCpuPct, dto.P95CpuPct, dto.MaxCpuPct, bpPct, azure), "OVER_PROVISIONED" => ServerHardwareScope.OverProvisionedExplanation(dto.AvgCpuPct, dto.MaxCpuPct, bpPct, azure), "UNDER_PROVISIONED" => ProvisioningVerdict.UnderProvisionedReason( dto.P95CpuPct, dto.MaxGrantWaiters, dto.GrantTimeouts, dto.ForcedGrants, dto.MaxWorkersCount, dto.CurrentWorkersCount), diff --git a/Darling/PerformanceMonitor.Darling.Storage/FinOps/FinOpsUtilizationFigures.cs b/Darling/PerformanceMonitor.Darling.Storage/FinOps/FinOpsUtilizationFigures.cs index a25a974a84..7cab8faa4b 100644 --- a/Darling/PerformanceMonitor.Darling.Storage/FinOps/FinOpsUtilizationFigures.cs +++ b/Darling/PerformanceMonitor.Darling.Storage/FinOps/FinOpsUtilizationFigures.cs @@ -84,7 +84,7 @@ public static string Explanation(UtilizationEfficiencyDto d, CultureInfo culture var azureSqlDb = ServerHardwareScope.HardwareIsTheHosts(d.EngineEdition); return d.ProvisioningStatus switch { - "RIGHT_SIZED" => ServerHardwareScope.RightSizedExplanation(d.AvgCpuPct, d.P95CpuPct, bpPct, azureSqlDb), + "RIGHT_SIZED" => ServerHardwareScope.RightSizedExplanation(d.AvgCpuPct, d.P95CpuPct, d.MaxCpuPct, bpPct, azureSqlDb), "OVER_PROVISIONED" => ServerHardwareScope.OverProvisionedExplanation(d.AvgCpuPct, d.MaxCpuPct, bpPct, azureSqlDb), /* The reason comes from the same place as the verdict, so a server flagged for grant pressure or worker saturation is not explained as a memory ratio that no longer decides anything (#2246). */ diff --git a/Lite.Tests/AzureSqlDatabaseMemoryScopeTests.cs b/Lite.Tests/AzureSqlDatabaseMemoryScopeTests.cs index 35947035de..83603ffb6f 100644 --- a/Lite.Tests/AzureSqlDatabaseMemoryScopeTests.cs +++ b/Lite.Tests/AzureSqlDatabaseMemoryScopeTests.cs @@ -141,8 +141,8 @@ UtilizationEfficiencyRow Row(int edition, int physicalMb) => Scored(new Utilizat [Fact] public void RightSizedSentence_OnAzureSqlDatabase_CitesTheBufferPoolShare_OfTheDatabasesMemoryLimit() { - var onAzure = ServerHardwareScope.RightSizedExplanation(40m, 62m, 71.0, azureSqlDatabase: true); - var onBox = ServerHardwareScope.RightSizedExplanation(40m, 62m, 71.0, azureSqlDatabase: false); + var onAzure = ServerHardwareScope.RightSizedExplanation(40m, 62m, 62m, 71.0, azureSqlDatabase: true); + var onBox = ServerHardwareScope.RightSizedExplanation(40m, 62m, 62m, 71.0, azureSqlDatabase: false); Assert.Equal( "CPU is moderately loaded (avg 40.0%, p95 62.0%) and memory is well-utilized (buffer pool uses 71% of the database's memory limit). No action needed.", @@ -153,6 +153,24 @@ public void RightSizedSentence_OnAzureSqlDatabase_CitesTheBufferPoolShare_OfTheD onBox); } + /// #6646: RIGHT_SIZED is also the verdict for an idle average with one sample at 40% or more. The sentence names the test that + /// decided, and says "well-utilized" only for a buffer pool holding at least half of its basis. + [Fact] + public void RightSizedSentence_ForAnIdleAverageWithOneBusySample_NamesThePeak_NotAModerateLoadOrWellUtilizedMemory() + { + var peak = ServerHardwareScope.RightSizedExplanation(0.1m, 0m, 40m, 8.0, azureSqlDatabase: false); + Assert.DoesNotContain("moderately loaded", peak, StringComparison.Ordinal); + Assert.DoesNotContain("well-utilized", peak, StringComparison.Ordinal); + Assert.Equal( + "CPU averaged 0.1% (p95 0.0%), but one sample reached 40%, so this server is not rated over-provisioned and buffer pool uses 8% of physical RAM. No action needed.", + peak); + + var grants = ServerHardwareScope.RightSizedExplanation(5m, 8m, 12m, 60.0, azureSqlDatabase: true); + Assert.DoesNotContain("moderately loaded", grants, StringComparison.Ordinal); + Assert.Contains("memory grants use 50% or more of their target", grants, StringComparison.Ordinal); + Assert.Contains("memory is well-utilized (buffer pool uses 60% of the database's memory limit)", grants, StringComparison.Ordinal); + } + [Fact] public void OverProvisionedSentence_OnAzureSqlDatabase_CitesTheBufferPoolShare_OfTheDatabasesMemoryLimit() { diff --git a/Lite/Controls/FinOpsTab.xaml.cs b/Lite/Controls/FinOpsTab.xaml.cs index 1bc17b27da..d19551f5bf 100644 --- a/Lite/Controls/FinOpsTab.xaml.cs +++ b/Lite/Controls/FinOpsTab.xaml.cs @@ -539,7 +539,7 @@ scheduler count it can see is never shown as the CPU it is given. */ /* Contextual explanation — one sentence describing WHY this classification */ ClassificationExplanation.Text = data.ProvisioningStatus switch { - "RIGHT_SIZED" => ServerHardwareScope.RightSizedExplanation(data.AvgCpuPct, data.P95CpuPct, bpPct, azureSqlDb), + "RIGHT_SIZED" => ServerHardwareScope.RightSizedExplanation(data.AvgCpuPct, data.P95CpuPct, data.MaxCpuPct, bpPct, azureSqlDb), "OVER_PROVISIONED" => ServerHardwareScope.OverProvisionedExplanation(data.AvgCpuPct, data.MaxCpuPct, bpPct, azureSqlDb), /* The reason comes from the same place as the verdict. This branch used to read "P95CpuPct > 85 ? CPU : memory ratio is {x} (threshold: 0.95)", so a server flagged for grant diff --git a/PerformanceMonitor.Common/ServerHardwareScope.cs b/PerformanceMonitor.Common/ServerHardwareScope.cs index 810c66a8c5..f8e1d7ccd5 100644 --- a/PerformanceMonitor.Common/ServerHardwareScope.cs +++ b/PerformanceMonitor.Common/ServerHardwareScope.cs @@ -229,11 +229,28 @@ public static string MemoryTabAvailableLabel(int? engineEdition) => /// /// The FinOps utilization verdict sentence for a server whose provisioning is RIGHT_SIZED. Off an Azure SQL Database it is - /// the long-standing sentence, byte for byte. On one it says the same, with the share named against the database's memory - /// limit instead of physical RAM. + /// the long-standing sentence, byte for byte, when the average CPU is at or above . + /// On one it says the same, with the share named against the database's memory limit instead of physical RAM. + /// #6646: RIGHT_SIZED is also the answer for a server whose average is below that bar, so the CPU clause names the test + /// that decided: one sample at or above is real peak demand, so the server is + /// not rated over-provisioned; otherwise grant or memory pressure held it back. "Well-utilized" is said only when the buffer + /// pool holds at least half of the basis. /// - public static string RightSizedExplanation(decimal avgCpuPct, decimal p95CpuPct, double bufferPoolPct, bool azureSqlDatabase) => - string.Create(CultureInfo.CurrentCulture, $"CPU is moderately loaded (avg {avgCpuPct:N1}%, p95 {p95CpuPct:N1}%) and memory is well-utilized (buffer pool uses {bufferPoolPct:N0}% of {MemoryBasis(azureSqlDatabase)}). No action needed."); + public static string RightSizedExplanation(decimal avgCpuPct, decimal p95CpuPct, decimal maxCpuPct, double bufferPoolPct, bool azureSqlDatabase) + { + var cpu = avgCpuPct >= ProvisioningVerdict.IdleAvgCpuPercent + ? string.Create(CultureInfo.CurrentCulture, $"CPU is moderately loaded (avg {avgCpuPct:N1}%, p95 {p95CpuPct:N1}%)") + : maxCpuPct >= ProvisioningVerdict.IdleMaxCpuPercent + ? string.Create(CultureInfo.CurrentCulture, $"CPU averaged {avgCpuPct:N1}% (p95 {p95CpuPct:N1}%), but one sample reached {maxCpuPct:N0}%, so this server is not rated over-provisioned") + : string.Create(CultureInfo.CurrentCulture, $"CPU is lightly loaded (avg {avgCpuPct:N1}%, p95 {p95CpuPct:N1}%), but its memory grants use {ProvisioningVerdict.IdleGrantUtilizationPercent:N0}% or more of their target, so this server is not rated over-provisioned"); + var memory = bufferPoolPct >= RightSizedWellUtilizedBufferPoolPercent + ? string.Create(CultureInfo.CurrentCulture, $"memory is well-utilized (buffer pool uses {bufferPoolPct:N0}% of {MemoryBasis(azureSqlDatabase)})") + : string.Create(CultureInfo.CurrentCulture, $"buffer pool uses {bufferPoolPct:N0}% of {MemoryBasis(azureSqlDatabase)}"); + return cpu + " and " + memory + ". No action needed."; + } + + /// The share of the memory basis the buffer pool must hold for a RIGHT_SIZED sentence to call memory well-utilized (#6646). + private const double RightSizedWellUtilizedBufferPoolPercent = 50.0; /// /// The FinOps utilization verdict sentence for a server whose provisioning is OVER_PROVISIONED. Same rule as From e59bd56c448976bd9e1c69a8c9d66068cf4ba999 Mon Sep 17 00:00:00 2001 From: Erik Darling <2136037+erikdarlingdata@users.noreply.github.com> Date: Sat, 24 Oct 2026 02:41:47 -0400 Subject: [PATCH 2/2] Fix round-1 review findings on the RIGHT_SIZED sentence (#6646) maxCpuPct is an int; the new clauses switch the noun on the edition; the grant clause prints the measured grant utilization; the 50% buffer pool cut moves to ProvisioningVerdict; tests assert literal sentences and tie the sentence to Evaluate. --- .../AzureSqlDatabaseMemoryScopeTests.cs | 65 +++++++++++++++---- .../FinOpsUtilizationFiguresTests.cs | 58 +++++++++++------ .../FinOps/FinOpsUtilizationFigures.cs | 2 +- .../AzureSqlDatabaseMemoryScopeTests.cs | 65 +++++++++++++++---- Lite/Controls/FinOpsTab.xaml.cs | 2 +- .../ProvisioningVerdict.cs | 4 ++ .../ServerHardwareScope.cs | 24 +++---- 7 files changed, 162 insertions(+), 58 deletions(-) diff --git a/Darling/Darling.Tests/AzureSqlDatabaseMemoryScopeTests.cs b/Darling/Darling.Tests/AzureSqlDatabaseMemoryScopeTests.cs index 3dec42f387..f653637676 100644 --- a/Darling/Darling.Tests/AzureSqlDatabaseMemoryScopeTests.cs +++ b/Darling/Darling.Tests/AzureSqlDatabaseMemoryScopeTests.cs @@ -115,8 +115,8 @@ public void HealthScore_DoesNotDependOnTheEngineEdition(int engineEdition) [Fact] public void RightSizedSentence_OnAzureSqlDatabase_CitesTheBufferPoolShare_OfTheDatabasesMemoryLimit() { - var onAzure = ServerHardwareScope.RightSizedExplanation(40m, 62m, 62m, 71.0, azureSqlDatabase: true); - var onBox = ServerHardwareScope.RightSizedExplanation(40m, 62m, 62m, 71.0, azureSqlDatabase: false); + var onAzure = ServerHardwareScope.RightSizedExplanation(40m, 62m, 62, 0m, 71.0, azureSqlDatabase: true); + var onBox = ServerHardwareScope.RightSizedExplanation(40m, 62m, 62, 0m, 71.0, azureSqlDatabase: false); Assert.Equal( "CPU is moderately loaded (avg 40.0%, p95 62.0%) and memory is well-utilized (buffer pool uses 71% of the database's memory limit). No action needed.", @@ -128,21 +128,62 @@ public void RightSizedSentence_OnAzureSqlDatabase_CitesTheBufferPoolShare_OfTheD } /// #6646: RIGHT_SIZED is also the verdict for an idle average with one sample at 40% or more. The sentence names the test that - /// decided, and says "well-utilized" only for a buffer pool holding at least half of its basis. + /// decided, says "well-utilized" only for a buffer pool holding at least half of its basis, and names the target the way the + /// edition does ("database" on an Azure SQL Database, "server" elsewhere). [Fact] public void RightSizedSentence_ForAnIdleAverageWithOneBusySample_NamesThePeak_NotAModerateLoadOrWellUtilizedMemory() { - var peak = ServerHardwareScope.RightSizedExplanation(0.1m, 0m, 40m, 8.0, azureSqlDatabase: false); - Assert.DoesNotContain("moderately loaded", peak, StringComparison.Ordinal); - Assert.DoesNotContain("well-utilized", peak, StringComparison.Ordinal); Assert.Equal( - "CPU averaged 0.1% (p95 0.0%), but one sample reached 40%, so this server is not rated over-provisioned and buffer pool uses 8% of physical RAM. No action needed.", - peak); + "CPU averaged 0.1% (p95 0.0%), but one sample reached 40%, so this server is not rated over-provisioned and the buffer pool uses 8% of physical RAM. No action needed.", + ServerHardwareScope.RightSizedExplanation(0.1m, 0m, 40, 10m, 8.0, azureSqlDatabase: false)); + Assert.Equal( + "CPU averaged 0.1% (p95 0.0%), but one sample reached 40%, so this database is not rated over-provisioned and the buffer pool uses 8% of the database's memory limit. No action needed.", + ServerHardwareScope.RightSizedExplanation(0.1m, 0m, 40, 10m, 8.0, azureSqlDatabase: true)); + } + + /// #6646: with an idle average and no busy sample, only the measured grant utilization holds the verdict at RIGHT_SIZED, so + /// the sentence prints that measurement next to the bar, not the bar alone. + [Fact] + public void RightSizedSentence_ForAnIdleServerHeldByGrantUse_PrintsTheMeasuredGrantUtilization() + { + Assert.Equal( + "CPU is lightly loaded (avg 5.0%, p95 8.0%), but its memory grants peaked at 62% of their target (threshold: 50%), so this database is not rated over-provisioned and memory is well-utilized (buffer pool uses 60% of the database's memory limit). No action needed.", + ServerHardwareScope.RightSizedExplanation(5m, 8m, 12, 62m, 60.0, azureSqlDatabase: true)); + Assert.Equal( + "CPU is lightly loaded (avg 5.0%, p95 8.0%), but its memory grants peaked at 97% of their target (threshold: 50%), so this server is not rated over-provisioned and the buffer pool uses 35% of physical RAM. No action needed.", + ServerHardwareScope.RightSizedExplanation(5m, 8m, 12, 97m, 35.0, azureSqlDatabase: false)); + } - var grants = ServerHardwareScope.RightSizedExplanation(5m, 8m, 12m, 60.0, azureSqlDatabase: true); - Assert.DoesNotContain("moderately loaded", grants, StringComparison.Ordinal); - Assert.Contains("memory grants use 50% or more of their target", grants, StringComparison.Ordinal); - Assert.Contains("memory is well-utilized (buffer pool uses 60% of the database's memory limit)", grants, StringComparison.Ordinal); + /// #6646: the sentence names the arm that ProvisioningVerdict.Evaluate used for the same inputs. Moving a cut point in + /// Evaluate without the sentence (or the reverse) leaves a RIGHT_SIZED server explained by a cause it does not have. + [Fact] + public void RightSizedSentence_NamesTheArmThatProvisioningVerdictEvaluateUsed() + { + const string Moderate = "moderately loaded"; + const string Peak = "one sample reached"; + const string Grants = "memory grants peaked at"; + + (decimal Avg, int Max, decimal P95, decimal Grant, string Arm)[] cases = + [ + (40m, 62, 62m, 0m, Moderate), + (15m, 5, 8m, 0m, Moderate), + (14.9m, 40, 20m, 0m, Peak), + (0.1m, 84, 30m, 0m, Peak), + (5m, 12, 8m, 50m, Grants), + (14.9m, 39, 8m, 99m, Grants), + ]; + + foreach (var (avg, max, p95, grant, arm) in cases) + { + var verdict = ProvisioningVerdict.Evaluate(avg, max, p95, 0, 0, 0, grant, 512, 100); + Assert.Equal(ProvisioningVerdict.RightSized, verdict); + + var sentence = ServerHardwareScope.RightSizedExplanation(avg, p95, max, grant, 30.0, azureSqlDatabase: false); + foreach (var other in new[] { Moderate, Peak, Grants }) + { + Assert.Equal(other == arm, sentence.Contains(other, StringComparison.Ordinal)); + } + } } [Fact] diff --git a/Darling/Darling.Tests/FinOpsUtilizationFiguresTests.cs b/Darling/Darling.Tests/FinOpsUtilizationFiguresTests.cs index fdb1181c72..eaf9e0c191 100644 --- a/Darling/Darling.Tests/FinOpsUtilizationFiguresTests.cs +++ b/Darling/Darling.Tests/FinOpsUtilizationFiguresTests.cs @@ -120,29 +120,47 @@ public void HealthBand_AgreesWithScoreColor_ForEveryScore() } } + /// The RIGHT_SIZED sentence for each reason a server is RIGHT_SIZED, written out as literals (not a copy of the switch). The + /// default Dto is a 12.5% average with a 40% peak and a buffer pool at exactly half of physical memory. [Theory] - [InlineData("RIGHT_SIZED", 0)] - [InlineData("RIGHT_SIZED", 5)] - [InlineData("OVER_PROVISIONED", 0)] - [InlineData("OVER_PROVISIONED", 5)] - [InlineData("UNDER_PROVISIONED", 0)] - [InlineData("NOT_APPLICABLE", 0)] - [InlineData("", 0)] - public void Explanation_EqualsTheOldSwitch_InTheCurrentCulture(string status, int edition) + [InlineData(0, 40, 12.5, 4000, "CPU averaged 12.5% (p95 35.0%), but one sample reached 40%, so this server is not rated over-provisioned and memory is well-utilized (buffer pool uses 50% of physical RAM). No action needed.")] + [InlineData(5, 40, 12.5, 4000, "CPU averaged 12.5% (p95 35.0%), but one sample reached 40%, so this database is not rated over-provisioned and memory is well-utilized (buffer pool uses 50% of the database's memory limit). No action needed.")] + [InlineData(0, 40, 12.5, 3999, "CPU averaged 12.5% (p95 35.0%), but one sample reached 40%, so this server is not rated over-provisioned and the buffer pool uses 50% of physical RAM. No action needed.")] + [InlineData(0, 70, 30.0, 800, "CPU is moderately loaded (avg 30.0%, p95 35.0%) and the buffer pool uses 10% of physical RAM. No action needed.")] + [InlineData(0, 70, 30.0, 6000, "CPU is moderately loaded (avg 30.0%, p95 35.0%) and memory is well-utilized (buffer pool uses 75% of physical RAM). No action needed.")] + public void Explanation_ForRightSized_NamesTheCauseAndTheMemoryShare(int edition, int max, double avg, int bp, string expected) + { + var dto = Dto("RIGHT_SIZED", edition, avg: (decimal)avg, max: max, bp: bp); + Assert.Equal(expected, FinOpsUtilizationFigures.Explanation(dto, CultureInfo.InvariantCulture)); + } + + /// The idle-average, quiet-peak RIGHT_SIZED server is held there by its measured grant utilization, and the sentence prints it. + [Fact] + public void Explanation_ForRightSized_WithAnIdleQuietServer_PrintsTheMeasuredGrantUtilization() + { + var dto = Dto("RIGHT_SIZED", avg: 5m, max: 12, p95: 8m) with { GrantUtilizationPct = 77m }; + Assert.Equal( + "CPU is lightly loaded (avg 5.0%, p95 8.0%), but its memory grants peaked at 77% of their target (threshold: 50%), so this server is not rated over-provisioned and memory is well-utilized (buffer pool uses 50% of physical RAM). No action needed.", + FinOpsUtilizationFigures.Explanation(dto, CultureInfo.InvariantCulture)); + } + + [Theory] + [InlineData("OVER_PROVISIONED", 0, "CPU is lightly loaded (avg 12.5%, max 40%) and buffer pool uses only 50% of physical RAM. This server may have more resources than it needs.")] + [InlineData("OVER_PROVISIONED", 5, "CPU is lightly loaded (avg 12.5%, max 40%) and buffer pool uses only 50% of the database's memory limit. This database may have more resources than it needs.")] + [InlineData("NOT_APPLICABLE", 0, null)] + [InlineData("", 0, "")] + public void Explanation_ForTheOtherStatuses_IsTheirSentence(string status, int edition, string? expected) { var dto = Dto(status, edition, p95: 90m, waiters: 2); - var bpPct = dto.PhysicalMemoryMb > 0 ? (double)dto.BufferPoolMb / dto.PhysicalMemoryMb * 100.0 : 0; - var azure = ServerHardwareScope.HardwareIsTheHosts(dto.EngineEdition); - var old = dto.ProvisioningStatus switch - { - "RIGHT_SIZED" => ServerHardwareScope.RightSizedExplanation(dto.AvgCpuPct, dto.P95CpuPct, dto.MaxCpuPct, bpPct, azure), - "OVER_PROVISIONED" => ServerHardwareScope.OverProvisionedExplanation(dto.AvgCpuPct, dto.MaxCpuPct, bpPct, azure), - "UNDER_PROVISIONED" => ProvisioningVerdict.UnderProvisionedReason( - dto.P95CpuPct, dto.MaxGrantWaiters, dto.GrantTimeouts, dto.ForcedGrants, dto.MaxWorkersCount, dto.CurrentWorkersCount), - ProvisioningVerdict.NotApplicable => ProvisioningVerdict.NotApplicableExplanation, - _ => "" - }; - Assert.Equal(old, FinOpsUtilizationFigures.Explanation(dto, CultureInfo.CurrentCulture)); + var actual = FinOpsUtilizationFigures.Explanation(dto, CultureInfo.InvariantCulture); + Assert.Equal(expected ?? ProvisioningVerdict.NotApplicableExplanation, actual); + } + + [Fact] + public void Explanation_ForUnderProvisioned_SaysWhyItWasFlagged() + { + var dto = Dto("UNDER_PROVISIONED", p95: 90m); + Assert.Contains("90", FinOpsUtilizationFigures.Explanation(dto, CultureInfo.InvariantCulture)); } /// #6139: six samples is no verdict, and the sentence says how many the window holds and how many it needs. diff --git a/Darling/PerformanceMonitor.Darling.Storage/FinOps/FinOpsUtilizationFigures.cs b/Darling/PerformanceMonitor.Darling.Storage/FinOps/FinOpsUtilizationFigures.cs index 7cab8faa4b..9f7ee73dbe 100644 --- a/Darling/PerformanceMonitor.Darling.Storage/FinOps/FinOpsUtilizationFigures.cs +++ b/Darling/PerformanceMonitor.Darling.Storage/FinOps/FinOpsUtilizationFigures.cs @@ -84,7 +84,7 @@ public static string Explanation(UtilizationEfficiencyDto d, CultureInfo culture var azureSqlDb = ServerHardwareScope.HardwareIsTheHosts(d.EngineEdition); return d.ProvisioningStatus switch { - "RIGHT_SIZED" => ServerHardwareScope.RightSizedExplanation(d.AvgCpuPct, d.P95CpuPct, d.MaxCpuPct, bpPct, azureSqlDb), + "RIGHT_SIZED" => ServerHardwareScope.RightSizedExplanation(d.AvgCpuPct, d.P95CpuPct, d.MaxCpuPct, d.GrantUtilizationPct, bpPct, azureSqlDb), "OVER_PROVISIONED" => ServerHardwareScope.OverProvisionedExplanation(d.AvgCpuPct, d.MaxCpuPct, bpPct, azureSqlDb), /* The reason comes from the same place as the verdict, so a server flagged for grant pressure or worker saturation is not explained as a memory ratio that no longer decides anything (#2246). */ diff --git a/Lite.Tests/AzureSqlDatabaseMemoryScopeTests.cs b/Lite.Tests/AzureSqlDatabaseMemoryScopeTests.cs index 83603ffb6f..fd351a85d8 100644 --- a/Lite.Tests/AzureSqlDatabaseMemoryScopeTests.cs +++ b/Lite.Tests/AzureSqlDatabaseMemoryScopeTests.cs @@ -141,8 +141,8 @@ UtilizationEfficiencyRow Row(int edition, int physicalMb) => Scored(new Utilizat [Fact] public void RightSizedSentence_OnAzureSqlDatabase_CitesTheBufferPoolShare_OfTheDatabasesMemoryLimit() { - var onAzure = ServerHardwareScope.RightSizedExplanation(40m, 62m, 62m, 71.0, azureSqlDatabase: true); - var onBox = ServerHardwareScope.RightSizedExplanation(40m, 62m, 62m, 71.0, azureSqlDatabase: false); + var onAzure = ServerHardwareScope.RightSizedExplanation(40m, 62m, 62, 0m, 71.0, azureSqlDatabase: true); + var onBox = ServerHardwareScope.RightSizedExplanation(40m, 62m, 62, 0m, 71.0, azureSqlDatabase: false); Assert.Equal( "CPU is moderately loaded (avg 40.0%, p95 62.0%) and memory is well-utilized (buffer pool uses 71% of the database's memory limit). No action needed.", @@ -154,21 +154,62 @@ public void RightSizedSentence_OnAzureSqlDatabase_CitesTheBufferPoolShare_OfTheD } /// #6646: RIGHT_SIZED is also the verdict for an idle average with one sample at 40% or more. The sentence names the test that - /// decided, and says "well-utilized" only for a buffer pool holding at least half of its basis. + /// decided, says "well-utilized" only for a buffer pool holding at least half of its basis, and names the target the way the + /// edition does ("database" on an Azure SQL Database, "server" elsewhere). [Fact] public void RightSizedSentence_ForAnIdleAverageWithOneBusySample_NamesThePeak_NotAModerateLoadOrWellUtilizedMemory() { - var peak = ServerHardwareScope.RightSizedExplanation(0.1m, 0m, 40m, 8.0, azureSqlDatabase: false); - Assert.DoesNotContain("moderately loaded", peak, StringComparison.Ordinal); - Assert.DoesNotContain("well-utilized", peak, StringComparison.Ordinal); Assert.Equal( - "CPU averaged 0.1% (p95 0.0%), but one sample reached 40%, so this server is not rated over-provisioned and buffer pool uses 8% of physical RAM. No action needed.", - peak); + "CPU averaged 0.1% (p95 0.0%), but one sample reached 40%, so this server is not rated over-provisioned and the buffer pool uses 8% of physical RAM. No action needed.", + ServerHardwareScope.RightSizedExplanation(0.1m, 0m, 40, 10m, 8.0, azureSqlDatabase: false)); + Assert.Equal( + "CPU averaged 0.1% (p95 0.0%), but one sample reached 40%, so this database is not rated over-provisioned and the buffer pool uses 8% of the database's memory limit. No action needed.", + ServerHardwareScope.RightSizedExplanation(0.1m, 0m, 40, 10m, 8.0, azureSqlDatabase: true)); + } + + /// #6646: with an idle average and no busy sample, only the measured grant utilization holds the verdict at RIGHT_SIZED, so + /// the sentence prints that measurement next to the bar, not the bar alone. + [Fact] + public void RightSizedSentence_ForAnIdleServerHeldByGrantUse_PrintsTheMeasuredGrantUtilization() + { + Assert.Equal( + "CPU is lightly loaded (avg 5.0%, p95 8.0%), but its memory grants peaked at 62% of their target (threshold: 50%), so this database is not rated over-provisioned and memory is well-utilized (buffer pool uses 60% of the database's memory limit). No action needed.", + ServerHardwareScope.RightSizedExplanation(5m, 8m, 12, 62m, 60.0, azureSqlDatabase: true)); + Assert.Equal( + "CPU is lightly loaded (avg 5.0%, p95 8.0%), but its memory grants peaked at 97% of their target (threshold: 50%), so this server is not rated over-provisioned and the buffer pool uses 35% of physical RAM. No action needed.", + ServerHardwareScope.RightSizedExplanation(5m, 8m, 12, 97m, 35.0, azureSqlDatabase: false)); + } - var grants = ServerHardwareScope.RightSizedExplanation(5m, 8m, 12m, 60.0, azureSqlDatabase: true); - Assert.DoesNotContain("moderately loaded", grants, StringComparison.Ordinal); - Assert.Contains("memory grants use 50% or more of their target", grants, StringComparison.Ordinal); - Assert.Contains("memory is well-utilized (buffer pool uses 60% of the database's memory limit)", grants, StringComparison.Ordinal); + /// #6646: the sentence names the arm that ProvisioningVerdict.Evaluate used for the same inputs. Moving a cut point in + /// Evaluate without the sentence (or the reverse) leaves a RIGHT_SIZED server explained by a cause it does not have. + [Fact] + public void RightSizedSentence_NamesTheArmThatProvisioningVerdictEvaluateUsed() + { + const string Moderate = "moderately loaded"; + const string Peak = "one sample reached"; + const string Grants = "memory grants peaked at"; + + (decimal Avg, int Max, decimal P95, decimal Grant, string Arm)[] cases = + [ + (40m, 62, 62m, 0m, Moderate), + (15m, 5, 8m, 0m, Moderate), + (14.9m, 40, 20m, 0m, Peak), + (0.1m, 84, 30m, 0m, Peak), + (5m, 12, 8m, 50m, Grants), + (14.9m, 39, 8m, 99m, Grants), + ]; + + foreach (var (avg, max, p95, grant, arm) in cases) + { + var verdict = ProvisioningVerdict.Evaluate(avg, max, p95, 0, 0, 0, grant, 512, 100); + Assert.Equal(ProvisioningVerdict.RightSized, verdict); + + var sentence = ServerHardwareScope.RightSizedExplanation(avg, p95, max, grant, 30.0, azureSqlDatabase: false); + foreach (var other in new[] { Moderate, Peak, Grants }) + { + Assert.Equal(other == arm, sentence.Contains(other, StringComparison.Ordinal)); + } + } } [Fact] diff --git a/Lite/Controls/FinOpsTab.xaml.cs b/Lite/Controls/FinOpsTab.xaml.cs index d19551f5bf..ce0c75b69e 100644 --- a/Lite/Controls/FinOpsTab.xaml.cs +++ b/Lite/Controls/FinOpsTab.xaml.cs @@ -539,7 +539,7 @@ scheduler count it can see is never shown as the CPU it is given. */ /* Contextual explanation — one sentence describing WHY this classification */ ClassificationExplanation.Text = data.ProvisioningStatus switch { - "RIGHT_SIZED" => ServerHardwareScope.RightSizedExplanation(data.AvgCpuPct, data.P95CpuPct, data.MaxCpuPct, bpPct, azureSqlDb), + "RIGHT_SIZED" => ServerHardwareScope.RightSizedExplanation(data.AvgCpuPct, data.P95CpuPct, data.MaxCpuPct, data.GrantUtilizationPct, bpPct, azureSqlDb), "OVER_PROVISIONED" => ServerHardwareScope.OverProvisionedExplanation(data.AvgCpuPct, data.MaxCpuPct, bpPct, azureSqlDb), /* The reason comes from the same place as the verdict. This branch used to read "P95CpuPct > 85 ? CPU : memory ratio is {x} (threshold: 0.95)", so a server flagged for grant diff --git a/PerformanceMonitor.Common/ProvisioningVerdict.cs b/PerformanceMonitor.Common/ProvisioningVerdict.cs index 91b48abc3f..1f94f6316b 100644 --- a/PerformanceMonitor.Common/ProvisioningVerdict.cs +++ b/PerformanceMonitor.Common/ProvisioningVerdict.cs @@ -78,6 +78,10 @@ public static class ProvisioningVerdict /// The one place the number lives. It is also where the Stolen Mem % figure starts to read amber. public const decimal HighStolenMemoryPercent = 60m; + /// A chosen value, not a measured one (#6646): the share of the memory basis the buffer pool must hold for a RIGHT_SIZED + /// sentence to call memory "well-utilized". It decides wording only, never the verdict. + public const double WellUtilizedBufferPoolPercent = 50.0; + /// Too few CPU samples in the window to say (). public const string NotEnoughData = "NOT_ENOUGH_DATA"; diff --git a/PerformanceMonitor.Common/ServerHardwareScope.cs b/PerformanceMonitor.Common/ServerHardwareScope.cs index f8e1d7ccd5..96933df1e6 100644 --- a/PerformanceMonitor.Common/ServerHardwareScope.cs +++ b/PerformanceMonitor.Common/ServerHardwareScope.cs @@ -229,29 +229,29 @@ public static string MemoryTabAvailableLabel(int? engineEdition) => /// /// The FinOps utilization verdict sentence for a server whose provisioning is RIGHT_SIZED. Off an Azure SQL Database it is - /// the long-standing sentence, byte for byte, when the average CPU is at or above . - /// On one it says the same, with the share named against the database's memory limit instead of physical RAM. + /// the long-standing sentence, byte for byte, when the average CPU is at or above + /// and the buffer pool holds at least of the memory basis. + /// On an Azure SQL Database it says the same, with the share named against the database's memory limit instead of physical RAM, + /// and "database" where the server would be named. /// #6646: RIGHT_SIZED is also the answer for a server whose average is below that bar, so the CPU clause names the test /// that decided: one sample at or above is real peak demand, so the server is - /// not rated over-provisioned; otherwise grant or memory pressure held it back. "Well-utilized" is said only when the buffer - /// pool holds at least half of the basis. + /// not rated over-provisioned; otherwise the measured grant utilization held it back. "Well-utilized" is said only when the buffer + /// pool holds at least of the basis. /// - public static string RightSizedExplanation(decimal avgCpuPct, decimal p95CpuPct, decimal maxCpuPct, double bufferPoolPct, bool azureSqlDatabase) + public static string RightSizedExplanation(decimal avgCpuPct, decimal p95CpuPct, int maxCpuPct, decimal grantUtilizationPct, double bufferPoolPct, bool azureSqlDatabase) { + var target = azureSqlDatabase ? "database" : "server"; var cpu = avgCpuPct >= ProvisioningVerdict.IdleAvgCpuPercent ? string.Create(CultureInfo.CurrentCulture, $"CPU is moderately loaded (avg {avgCpuPct:N1}%, p95 {p95CpuPct:N1}%)") : maxCpuPct >= ProvisioningVerdict.IdleMaxCpuPercent - ? string.Create(CultureInfo.CurrentCulture, $"CPU averaged {avgCpuPct:N1}% (p95 {p95CpuPct:N1}%), but one sample reached {maxCpuPct:N0}%, so this server is not rated over-provisioned") - : string.Create(CultureInfo.CurrentCulture, $"CPU is lightly loaded (avg {avgCpuPct:N1}%, p95 {p95CpuPct:N1}%), but its memory grants use {ProvisioningVerdict.IdleGrantUtilizationPercent:N0}% or more of their target, so this server is not rated over-provisioned"); - var memory = bufferPoolPct >= RightSizedWellUtilizedBufferPoolPercent + ? string.Create(CultureInfo.CurrentCulture, $"CPU averaged {avgCpuPct:N1}% (p95 {p95CpuPct:N1}%), but one sample reached {maxCpuPct:N0}%, so this {target} is not rated over-provisioned") + : string.Create(CultureInfo.CurrentCulture, $"CPU is lightly loaded (avg {avgCpuPct:N1}%, p95 {p95CpuPct:N1}%), but its memory grants peaked at {grantUtilizationPct:N0}% of their target (threshold: {ProvisioningVerdict.IdleGrantUtilizationPercent:N0}%), so this {target} is not rated over-provisioned"); + var memory = bufferPoolPct >= ProvisioningVerdict.WellUtilizedBufferPoolPercent ? string.Create(CultureInfo.CurrentCulture, $"memory is well-utilized (buffer pool uses {bufferPoolPct:N0}% of {MemoryBasis(azureSqlDatabase)})") - : string.Create(CultureInfo.CurrentCulture, $"buffer pool uses {bufferPoolPct:N0}% of {MemoryBasis(azureSqlDatabase)}"); + : string.Create(CultureInfo.CurrentCulture, $"the buffer pool uses {bufferPoolPct:N0}% of {MemoryBasis(azureSqlDatabase)}"); return cpu + " and " + memory + ". No action needed."; } - /// The share of the memory basis the buffer pool must hold for a RIGHT_SIZED sentence to call memory well-utilized (#6646). - private const double RightSizedWellUtilizedBufferPoolPercent = 50.0; - /// /// The FinOps utilization verdict sentence for a server whose provisioning is OVER_PROVISIONED. Same rule as /// : the long-standing sentence off an Azure SQL Database, and on one the same share named