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
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_pressure fires. 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_growing episodes 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 own heapCapacity grows 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_growing was 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.resetCaptureState calls 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_growing legs 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_capacity reads: the last this many.
nativeGrowthThresholdBytesPerSec → const int
native_memory_growing threshold in bytes per second (1 MiB/s).
nativeMinSamplesPerHalf → const int
Fewest heap samples each half of the window needs before native_memory_growing evaluates.
sustainedGrowthDurationSec → const int
Seconds a growth rate must stay above its threshold before heap_growing (sample leg) or native_memory_growing emits.