MemoryPressureDetector class
Detects memory pressure using VM GC events and heap growth trends.
VM-Only Detector — monitors GC frequency, heap growth rate via linear regression over a rolling window, and process memory (RSS) against an optional app-supplied budget.
Capture-mode timing. Calling reset (auto-invoked by
Sleuth.markScenarioBegin via SleuthController.resetCaptureState)
clears _heapSamples, _firstHeapSampleTime, the sample leg's
sustain start and the floor leg's points, so the heap-trend
evaluation starts fresh on every scenario. Effective first-fire latency post-reset:
~3 s warmup + ~2 s sample-accumulation (4-sample minimum) + slope-
cross + 10 s sustained = ~14-15 s of scenario allocation before the
first heap_growing issue can fire. Capture procedures should
allocate ≥30 s for comfortable margin.
- Inheritance
-
- Object
- BaseDetector
- MemoryPressureDetector
- Mixed-in types
- Annotations
-
- @experimental
Constructors
- MemoryPressureDetector({DateTime clock()?, int warmupDurationMs = 3000, int growthThresholdBytesPerSec = 512000, double capacityThresholdPercent = 0.80, int? memoryBudgetBytes, int gcRateThresholdPerMin = _defaultGcRateThresholdPerMin, bool captureMode = false, int floorStartupWindowMs = 30000, int floorCycleGapMs = 100, int floorWindowMs = 60000, int floorMinPoints = 3, int floorMinSpanMs = 10000, int floorFreshnessMs = 30000})
Properties
- capacityThresholdPercent → double
-
Fraction of memoryBudgetBytes (0.0–1.0) at or above which process
RSS counts toward
heap_near_capacity.final - captureMode → bool
-
Whether this detector runs in a capture session. Only then does
setLegsEnabledForCapture change anything.
final
- description → String
-
Short description of what this detector checks.
finalinherited
- floorStartupWindowMs → int
-
Idle-collection points whose event time falls within this many
milliseconds of the detector's construction are ignored, so the
floor leg does not report the retention of app startup as growth.
reset does not move this boundary.
final
- floorVerdict → HeapFloorVerdict
-
The floor leg's verdict now: the heap measured right after idle full
collections.
no setter
- gcRateThresholdPerMin → int
-
Young-generation collections (scavenges) per minute, extrapolated
from a 10 s sliding window, above which
gc_pressurefires. Old-generation sweeps and concurrent-marking starts do not count: on animated screens they follow promotion and pause the app briefly. On an iPhone 12 and a Galaxy A07 at 60 Hz, ordinary screens ran 168 scavenges a minute or fewer, and the GC Churn demo ran 390 to 810. Scavenges rise with the frame rate: Live Waveform at 90 Hz on the Galaxy ran 186 to 246 a minute with 3.7 to 4.9 % of the time in GC pauses, more than the churn demo. Each emission stamps the young-generation / old-generation / marking-start split of the window, and the GC pause time when it can be measured.final - gcWindowStats → ({int events, int markStarts, int old, bool pauseAvailable, double? pauseMs, int young})
-
GC events in the current 10 s window, by class, and their summed
pause time.
no setter
- growthThresholdBytesPerSec → int
-
Heap growth rate (bytes/sec) above which heap_growing is flagged.
final
- hashCode → int
-
The hash code for this object.
no setterinherited
- heapGrowingEpisode → int
-
Number of
heap_growingepisodes started so far. Changes when a new episode starts, also while the issue stays visible across the switch, so readers can tell one episode from the next.no setter -
heapSamples
→ List<
HeapSample> -
Unmodifiable view of the rolling heap sample window for session export.
no setter
-
highlights
→ List<
WidgetHighlight> -
Highlight candidates collected during the last scan.
Empty for detectors that don't produce visual highlights.
no setterinherited
- isEnabled ↔ bool
-
Whether this detector is currently active.
getter/setter pairoverride
-
issues
→ List<
PerformanceIssue> -
Current list of detected issues. Reset each analysis cycle.
no setteroverride
- key → String?
-
Stable identifier for config-driven gating of custom detectors.
finalinherited
- lifecycle → DetectorLifecycle
-
Lifecycle classification determining data source requirements.
finalinherited
- memoryBudgetBytes → int?
-
Process memory budget in bytes for
heap_near_capacity. Null (the default) disables the issue: without a known budget there is no ceiling to be near. Dart's ownheapCapacitygrows with usage, so the usage/capacity ratio sits at 0.85–0.97 in steady state and says nothing about how close the process is to being killed.final - name → String
-
Human-readable name of this detector (e.g., "Frame Timing").
finalinherited
- requiresTreeScan → bool
-
Whether this detector scans the widget/render tree.
no setterinherited
- requiresVm → bool
-
Whether this detector needs VM service data to function.
DetectorLifecycle.runtime detectors benefit from VM data but don't require it.
no setterinherited
- runtimeType → Type
-
A representation of the runtime type of the object.
no setterinherited
- type → DetectorType
-
The detector type identifier used for configuration.
finalinherited
- validationMetadata → DetectorMetadata
-
Metadata for this detector. Must be non-null on shipping detectors —
the audit test gates this.
no setteroverride
- vmConnected ← bool
-
Clear all session state on VM disconnect.
no getteroverride
- warmupDurationMs → int
-
Duration in milliseconds to suppress heap trend alerts after first sample.
Prevents false positives from normal startup allocation.
final
Methods
-
afterElement(
Element element) → void -
Called after an element's children have all been visited.
inherited
-
checkElement(
Element element) → void -
Check a single element during the unified tree walk.
inherited
-
dispose(
) → void -
Dispose of any resources held by this detector.
override
-
enrichHeapGrowingIssue(
List< AllocationEntry> allocators) → void - Enrich the existing heap_growing issue with top allocator data. Called by the controller after getAllocationProfile returns (phase 2).
-
evaluateNow(
) → void -
Triggers issue evaluation using whatever data has been staged.
inherited
-
finalizeScan(
) → void -
Finalise the scan: process accumulated data and create issues.
inherited
-
isHeapGrowingActive(
[int? windowMicros]) → bool -
Whether
heap_growingwas emitted within the recency window. -
noSuchMethod(
Invocation invocation) → dynamic -
Invoked when a nonexistent method or property is accessed.
inherited
-
notifyWalkCompleted(
) → void -
Called when the tree walk completed without exceptions.
inherited
-
prepareScan(
BuildContext context) → void -
Prepare for a new scan cycle. Called once before the unified tree walk.
inherited
-
processFrame(
FrameStats frame) → void -
Process one presented frame from
FrameTiming.inherited -
processHeapSample(
HeapSample sample) → void - Process a heap memory sample from the VM service.
-
processTimelineData(
ParsedTimelineData data) → void -
Process VM timeline data.
inherited
-
recordGcCycle(
{String? gcType, double? cumulativePauseSeconds, bool pauseAttributable = false, String? reason, int? heapUsedBytes, int? eventTimestampMs}) → void - Record a single completed GC cycle.
-
reset(
) → void -
Clears every window, issue and episode. It keeps the GC pause
baseline, because
SleuthController.resetCaptureStatecalls this at every capture leg start and the first GC of the leg still has a measurable pause against the last one before it. It keeps the last gc_pressure identity too, so a new leg's identities never repeat an earlier one. -
scanTree(
BuildContext context) → void -
Scan the widget/render tree for issues.
inherited
-
setLegsEnabledForCapture(
{bool? floor, bool? sample}) → void -
Switches the two
heap_growinglegs on or off, so a capture can record each leg's evidence alone. Does nothing unless captureMode is true; a normal session always runs both legs. -
toString(
) → String -
A string representation of this object.
inherited
-
updateDebugSnapshot(
DebugSnapshot snapshot) → void -
Called with debug callback data when available.
inherited
Operators
-
operator ==(
Object other) → bool -
The equality operator.
inherited
Static Methods
-
continuedGrowthSlope(
List< HeapSample> samples) → double -
The slowest growth rate across
samples, in bytes/sec, over the whole window and over each half split at its time midpoint. Each rate is the lower of the native and RSS regressions. Zero while a half holds fewer than nativeMinSamplesPerHalf samples.
Constants
- budgetRequiredHits → const int
- Samples of the last budgetWindowSize that must be over budget.
- budgetWindowSize → const int
-
Heap samples
heap_near_capacityreads: the last this many. - nativeGrowthThresholdBytesPerSec → const int
-
native_memory_growingthreshold in bytes per second (1 MiB/s). - nativeMinSamplesPerHalf → const int
-
Fewest heap samples each half of the window needs before
native_memory_growingevaluates. - sustainedGrowthDurationSec → const int
-
Seconds a growth rate must stay above its threshold before
heap_growing(sample leg) ornative_memory_growingemits.