TrackedResourceDetector class

Opt-in retention tracker. Users register resources via Sleuth.trackResource; emits with confirmed confidence.

Emission paths:

Storage is keyed by name → _Bucket of WeakReference<Object> entries. Tracker holds only weak references, so registration cannot prevent GC. Cross-isolate registration is a no-op (each isolate has its own controller).

Inheritance
Mixed-in types
Annotations
  • @experimental

Constructors

TrackedResourceDetector({int maxConcurrent = 5, int longLivedSeconds = 300, int maxDistinctNames = 1000, int sweepIntervalSeconds = 10, DateTime clock()?})

Properties

description → String
Short description of what this detector checks.
finalinherited
droppedOverridesCount → int
Diagnostic: count of override-registration calls dropped because the value was non-positive or the override map cap was reached.
no setter
droppedTargetsCount → int
Diagnostic: count of track calls dropped because the target type was unsupported (primitive, record, or WeakReference construction failure).
no setter
evictedNamesCount → int
Diagnostic: count of name buckets evicted by the LRU cap.
no setter
hashCode → int
The hash code for this object.
no setterinherited
hasTracked → bool
Whether a resource was ever registered with track.
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
lastObservedLiveCount → int
Aggregate last-observed peak across every bucket. Broader than the capture-procedure scope — use lastObservedLiveCountFor inside a capture screen.
no setter
lifecycle → DetectorLifecycle
Lifecycle classification determining data source requirements.
finalinherited
name → String
Human-readable name of this detector (e.g., "Frame Timing").
finalinherited
peakObservedLiveCount → int
Aggregate monotonic high-water mark across every bucket. Broader than the capture-procedure scope — use peakObservedLiveCountFor inside a capture screen so an ambient bucket cannot contaminate the magnitude the bracket validator cross-checks against.
no setter
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
Update VM connectivity state.
no getterinherited

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
evaluateNow() → void
Triggers issue evaluation using whatever data has been staged.
inherited
evaluateNowForTest() → void
Run a sweep immediately (instead of waiting for the timer). Tests
finalizeScan() → void
Finalise the scan: process accumulated data and create issues.
inherited
flushConcurrentEvaluation() → void
Synchronous sweep — prunes finalised refs, evaluates emission state, refreshes observables. Capture screens call this AFTER the workload registers all refs and BEFORE markScenarioEnd so the in-span trace record carries the scenario's steady-state count, not a partial first-cross.
lastObservedAgeSecondsFor(String name) → int
Last-observed oldest-instance age (seconds) for name from the most recent _sweep(). Real elapsed time since the bucket's oldest live ref was registered.
lastObservedLiveCountFor(String name) → int
Last-observed live count for name. Returns 0 when the name has never been swept or all refs were finalised.
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
peakObservedAgeSecondsFor(String name) → int
Monotonic high-water mark of lastObservedAgeSecondsFor since the last resetCaptureState. The long-lived bracket validator's 'max' axis reduction cross-checks expectedMagnitude.observed against this value; capture screens read the name-scoped value so the exported magnitude matches the scenario's intended bucket.
peakObservedLiveCountFor(String name) → int
Monotonic high-water mark of lastObservedLiveCountFor since the last resetCaptureState. The bracket validator's 'max' axis reduction cross-checks expectedMagnitude.observed against this value; capture screens MUST read the name-scoped value so the exported magnitude matches the scenario's intended bucket.
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
processTimelineData(ParsedTimelineData data) → void
Process VM timeline data.
inherited
registerNameOverride(String name, {int? maxConcurrent, int? longLivedSeconds}) → void
Override concurrent / long-lived thresholds for name. Survives empty-bucket sweep, LRU drops, and isEnabled = false — override is config, not registration.
resetCaptureState() → void
Clears per-leg observable state + every bucket's concurrentFirstCrossMicros / longLivedFirstCrossMicros so the next post-reset emission stamps a fresh dedupIdentityMicros and is not collapsed by the controller's composite-key dedup against the prior leg. Does NOT clear _buckets — call untrackAll per name when leg isolation requires it.
scanTree(BuildContext context) → void
Scan the widget/render tree for issues.
inherited
simulateFinalizerForTest(String name, Object resource) → void
Test seam matching the production Finalizer callback path. Locates the registration whose target is identical to resource under name, then dispatches _recordRelease(token) against its token. Deterministically simulates GC reclamation without depending on VM finalization timing.
snapshotLiveCounts() → Map<String, int>
Snapshot of currently tracked name → live count. For tests + demo screens; do not mutate the returned map.
snapshotNameOverrides() → Map<String, ({int? longLivedSeconds, int? maxConcurrent})>
Diagnostic: snapshot of per-name overrides for tests. Does not expose the live map.
toString() → String
A string representation of this object.
inherited
track(String name, Object resource) → void
Register resource under name. Repeated (name, resource) pairs are deduped by identity — identical() walk over same-name refs (hash equality cannot stand in for object identity). Held via WeakReference so registration cannot prevent GC.
untrack(String name, Object resource) → void
Removes any ref under name whose target is identical to resource and detaches its Finalizer entry. Silent no-op when name is unknown or no identity match found.
untrackAll(String name) → void
Drops every ref under name + detaches each Finalizer token + clears the per-name observables. Capture screens call this between legs to isolate each leg's workload. Silent no-op when name is unknown. Preserves the per-name threshold override (clear via Sleuth.setResourceThreshold(name)).
updateDebugSnapshot(DebugSnapshot snapshot) → void
Called with debug callback data when available.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited

Constants

concurrentStableId → const String
StableId for "more than maxConcurrent live instances of the same name".
longLivedStableId → const String
StableId for "single instance of a name alive past long-lived threshold".