TrackedResourceDetector class
Opt-in retention tracker. Users register resources via
Sleuth.trackResource; emits with confirmed confidence.
Emission paths:
- concurrentStableId: live count under one name exceeds DetectorThresholds.trackedResourceMaxConcurrent.
- longLivedStableId: a single instance under one name has been alive past DetectorThresholds.trackedResourceLongLivedSeconds.
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
-
- Object
- BaseDetector
- TrackedResourceDetector
- Mixed-in types
- Annotations
-
- @experimental
Constructors
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
trackcalls dropped because the target type was unsupported (primitive, record, orWeakReferenceconstruction 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
markScenarioEndso 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
namefrom 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-checksexpectedMagnitude.observedagainst 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-checksexpectedMagnitude.observedagainst 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, andisEnabled = false— override is config, not registration. -
resetCaptureState(
) → void -
Clears per-leg observable state + every bucket's
concurrentFirstCrossMicros/longLivedFirstCrossMicrosso the next post-reset emission stamps a freshdedupIdentityMicrosand 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
identicaltoresourceundername, 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
resourceundername. 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
namewhose target isidenticaltoresourceand detaches its Finalizer entry. Silent no-op whennameis 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 whennameis unknown. Preserves the per-name threshold override (clear viaSleuth.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".