recordGcCycle method

void recordGcCycle({
  1. String? gcType,
  2. double? cumulativePauseSeconds,
  3. bool pauseAttributable = false,
  4. String? reason,
  5. int? heapUsedBytes,
  6. int? eventTimestampMs,
})

Record a single completed GC cycle.

Called by the controller's SleuthController._onGcEvent handler which listens to the VM's authoritative per-cycle GC stream. Each call contributes exactly one event to the sliding window.

gcType is the event's raw gcType value, classified by _classifyGc. The split is stamped on gc_pressure and does not change the rule.

cumulativePauseSeconds is the event's new.time + old.time: the VM's running total of GC pause time for the isolate group. pauseAttributable is true only when the event is known to come from the app's own isolate group. The difference from the previous attributable event is this event's pause. Anything else breaks continuity, and the next attributable event only sets a new baseline. The baseline is kept while the detector is disabled, so re-enabling it does not book the disabled interval's pauses into the current window.

reason, heapUsedBytes (new.used + old.used after the collection) and eventTimestampMs (the event's timestamp) feed the heap_growing floor leg, which only uses events that pauseAttributable marks as the app's own.

Implementation

void recordGcCycle({
  String? gcType,
  double? cumulativePauseSeconds,
  bool pauseAttributable = false,
  String? reason,
  int? heapUsedBytes,
  int? eventTimestampMs,
}) {
  final pauseUs = _advancePauseBaseline(
    pauseAttributable ? cumulativePauseSeconds : null,
  );
  if (!_isEnabled) return;
  final now = _clock();
  _gcWindow.add((ts: now, gcClass: _classifyGc(gcType), pauseUs: pauseUs));
  if (_floorLegEnabled && pauseAttributable) {
    _floor.addCollection(
      gcType: gcType,
      reason: reason,
      heapUsedBytes: heapUsedBytes,
      eventMs: eventTimestampMs,
      arrivalMs: now.millisecondsSinceEpoch,
    );
  }
  _evaluate();
}