@aethervtt/shard-core 0.0.1 → 0.2.0

package/dist/scheduler/capture/recorder.js

@@ -0,0 +1,224 @@
+import { ShardError } from "../../error.js";
+import { spanName as spanNameOf, TRACK } from "../profiler.js";
+import { Capture } from "./capture.js";
+const WAITING = 0;
+const RECORDING = 1;
+const DRAINING = 2;
+const DONE = 3;
+const GPU_DRAIN_FRAMES = 4;
+const DEFAULT_EVENTS = 1 << 20;
+class CaptureRecorder {
+  mode;
+  capacity;
+  /** Resolves once the capture has every frame it wanted (or gave up waiting). */
+  done;
+  profiler;
+  starts;
+  durations;
+  ids;
+  bytes;
+  cursor = 0;
+  written = 0;
+  frameCap;
+  frameNumbers;
+  frameStarts;
+  frameCpu;
+  frameFirst;
+  frameCount = 0;
+  state = WAITING;
+  frames;
+  untilMs;
+  after;
+  timeoutMs;
+  startedAt = Number.NaN;
+  trigger = -1;
+  triggerMs = 0;
+  afterLeft = 0;
+  drainLeft = 0;
+  gpuSeen = false;
+  firstNumber = Number.POSITIVE_INFINITY;
+  lastNumber = Number.NEGATIVE_INFINITY;
+  timedOut = false;
+  truncatedFlag = false;
+  stopping = false;
+  devtools;
+  resolveDone;
+  constructor(profiler, options = {}) {
+    this.profiler = profiler;
+    this.mode = options.until ? "until" : "frames";
+    this.capacity = Math.max(16, options.events ?? DEFAULT_EVENTS);
+    const buffer = new ArrayBuffer(this.capacity * 16);
+    this.starts = new Float64Array(buffer);
+    this.durations = new Float32Array(buffer);
+    this.ids = new Uint16Array(buffer);
+    this.bytes = new Uint8Array(buffer);
+    this.frames = Math.max(1, options.frames ?? 300);
+    this.untilMs = options.until?.frameMs ?? Number.POSITIVE_INFINITY;
+    const before = Math.max(0, options.before ?? 120);
+    this.after = Math.max(0, options.after ?? 30);
+    this.timeoutMs = (options.timeout ?? 60) * 1e3;
+    this.frameCap = this.mode === "frames" ? this.frames : before + 1 + this.after;
+    this.frameNumbers = new Float64Array(this.frameCap);
+    this.frameStarts = new Float64Array(this.frameCap);
+    this.frameCpu = new Float64Array(this.frameCap);
+    this.frameFirst = new Float64Array(this.frameCap);
+    this.devtools = options.devtools;
+    this.done = new Promise((resolve) => {
+      this.resolveDone = resolve;
+    });
+  }
+  /** Starts listening: from the next frame on. Throws `perf/capture-running` if one already is. */
+  start() {
+    if (this.profiler.sink !== void 0) {
+      throw new ShardError("perf/capture-running", "A capture is already running on this app", {
+        hint: "Wait for it to finish (perf.capture resolves when it does), then capture again."
+      });
+    }
+    if (!this.profiler.enabled) {
+      throw new ShardError("perf/disabled", "The profiler is off (ProfilerSettings.enabled)", {
+        hint: "Turn it on with resource.set core/ProfilerSettings { enabled: true }."
+      });
+    }
+    this.profiler.sink = this;
+    this.startedAt = this.profiler.now();
+    return this;
+  }
+  /** Ends the capture now with what it has. */
+  stop() {
+    if (this.state === DONE) return;
+    this.finish();
+  }
+  get running() {
+    return this.state !== DONE;
+  }
+  // --- the sink ----------------------------------------------------------------
+  event(id, track, depth, start, ms, frame) {
+    const state = this.state;
+    if (state !== RECORDING && (state !== DRAINING || track !== TRACK.gpu)) return;
+    if (frame >= 0 && (frame < this.firstNumber || state === DRAINING && frame > this.lastNumber))
+      return;
+    if (this.mode === "frames" && this.written >= this.capacity) {
+      this.truncatedFlag = true;
+      this.stopping = true;
+      return;
+    }
+    const i = this.cursor;
+    this.starts[i * 2] = start;
+    this.durations[i * 4 + 2] = ms;
+    this.ids[i * 8 + 6] = id;
+    this.bytes[i * 16 + 14] = track;
+    this.bytes[i * 16 + 15] = depth > 255 ? 255 : depth;
+    this.cursor = i + 1 === this.capacity ? 0 : i + 1;
+    this.written++;
+    if (track === TRACK.gpu) this.gpuSeen = true;
+    if (this.devtools !== void 0) this.devtools(spanNameOf(id), track, start, ms);
+  }
+  frameStart(frame, at) {
+    if (this.state === WAITING) {
+      this.state = RECORDING;
+      this.firstNumber = frame;
+    }
+    if (this.state !== RECORDING) return;
+    const slot = this.frameCount % this.frameCap;
+    this.frameNumbers[slot] = frame;
+    this.frameStarts[slot] = at;
+    this.frameCpu[slot] = Number.NaN;
+    this.frameFirst[slot] = this.written;
+  }
+  frameEnd(_frame, ms) {
+    if (this.state === DRAINING) {
+      if (--this.drainLeft <= 0) this.complete();
+      return;
+    }
+    if (this.state !== RECORDING) return;
+    this.frameCpu[this.frameCount % this.frameCap] = ms;
+    this.frameCount++;
+    if (this.stopping) {
+      this.finish();
+      return;
+    }
+    if (this.mode === "frames") {
+      if (this.frameCount >= this.frames) this.finish();
+      return;
+    }
+    if (this.trigger < 0) {
+      if (ms > this.untilMs) {
+        this.trigger = this.frameNumbers[(this.frameCount - 1) % this.frameCap];
+        this.triggerMs = ms;
+        this.afterLeft = this.after;
+        if (this.afterLeft === 0) this.finish();
+      } else if (this.profiler.now() - this.startedAt > this.timeoutMs) {
+        this.timedOut = true;
+        this.finish();
+      }
+      return;
+    }
+    if (--this.afterLeft <= 0) this.finish();
+  }
+  // --- finishing ---------------------------------------------------------------
+  finish() {
+    if (this.frameCount > 0)
+      this.lastNumber = this.frameNumbers[(this.frameCount - 1) % this.frameCap];
+    if (this.gpuSeen && this.state === RECORDING) {
+      this.state = DRAINING;
+      this.drainLeft = GPU_DRAIN_FRAMES;
+      return;
+    }
+    this.complete();
+  }
+  complete() {
+    if (this.state === DONE) return;
+    this.state = DONE;
+    if (this.profiler.sink === this) this.profiler.sink = void 0;
+    this.resolveDone(this.result());
+  }
+  /** The recorded frames and events, in order. */
+  result() {
+    const frames = Math.min(this.frameCount, this.frameCap);
+    const firstFrame = this.frameCount - frames;
+    const oldest = Math.max(0, this.written - this.capacity);
+    let skip = 0;
+    while (skip < frames && this.frameFirst[(firstFrame + skip) % this.frameCap] < oldest) skip++;
+    const kept = frames - skip;
+    const frameNumbers = new Float64Array(kept);
+    const frameStarts = new Float64Array(kept);
+    const frameCpu = new Float64Array(kept);
+    for (let k = 0; k < kept; k++) {
+      const slot = (firstFrame + skip + k) % this.frameCap;
+      frameNumbers[k] = this.frameNumbers[slot];
+      frameStarts[k] = this.frameStarts[slot];
+      frameCpu[k] = this.frameCpu[slot];
+    }
+    const firstEvent = kept > 0 ? this.frameFirst[(firstFrame + skip) % this.frameCap] : this.written;
+    const count = this.written - Math.max(firstEvent, oldest);
+    const ids = new Uint16Array(count);
+    const tracks = new Uint8Array(count);
+    const depths = new Uint8Array(count);
+    const starts = new Float64Array(count);
+    const durations = new Float64Array(count);
+    for (let k = 0; k < count; k++) {
+      const n = this.written - count + k;
+      const i = n % this.capacity;
+      ids[k] = this.ids[i * 8 + 6];
+      tracks[k] = this.bytes[i * 16 + 14];
+      depths[k] = this.bytes[i * 16 + 15];
+      starts[k] = this.starts[i * 2];
+      durations[k] = this.durations[i * 4 + 2];
+    }
+    return new Capture({
+      frames: { numbers: frameNumbers, starts: frameStarts, cpu: frameCpu },
+      events: { ids, tracks, depths, starts, durations },
+      mode: this.mode,
+      truncated: this.truncatedFlag,
+      trigger: this.trigger < 0 ? void 0 : { frame: this.trigger, frameMs: this.triggerMs },
+      timedOut: this.timedOut
+    });
+  }
+}
+function startCapture(profiler, options = {}) {
+  return new CaptureRecorder(profiler, options).start();
+}
+export {
+  CaptureRecorder,
+  startCapture
+};

package/dist/scheduler/capture/samples.d.ts

@@ -0,0 +1,49 @@
+import type { HotFunction, TraceSample } from './capture.js';
+/** A V8 `.cpuprofile` (DevTools' `Profiler.Profile`), as `node:inspector` and `--cpu-prof` write it. */
+export interface CpuProfile {
+    nodes: {
+        id: number;
+        callFrame: {
+            functionName: string;
+            url: string;
+            lineNumber: number;
+            columnNumber?: number;
+        };
+        hitCount?: number;
+        children?: number[];
+    }[];
+    /** µs. */
+    startTime: number;
+    endTime: number;
+    samples?: number[];
+    /** µs between samples. */
+    timeDeltas?: number[];
+}
+/** What `new Profiler(...).stop()` resolves with (JS Self-Profiling). */
+export interface SelfProfileTrace {
+    resources: string[];
+    frames: {
+        name: string;
+        resourceId?: number;
+        line?: number;
+        column?: number;
+    }[];
+    stacks: {
+        frameId: number;
+        parentId?: number;
+    }[];
+    /** `timestamp` on the page's performance timeline (ms). */
+    samples: {
+        timestamp: number;
+        stackId?: number;
+    }[];
+}
+/** The functions with the most self time in a `.cpuprofile`. */
+export declare function hottestFromCpuProfile(profile: CpuProfile, limit?: number): HotFunction[];
+/** The functions on top of the stack most often in a JS Self-Profiling trace. */
+export declare function hottestFromSelfProfile(trace: SelfProfileTrace, intervalMs: number, limit?: number): HotFunction[];
+/**
+ * A JS Self-Profiling trace as stretches of the same top function, for the trace's samples track.
+ * `offset` moves the page's timeline onto the profiler's clock.
+ */
+export declare function samplesFromSelfProfile(trace: SelfProfileTrace, intervalMs: number, offset?: number): TraceSample[];

package/dist/scheduler/capture/samples.js

@@ -0,0 +1,91 @@
+const SKIP = /* @__PURE__ */ new Set(["(root)", "(idle)"]);
+function rank(byKey, total, limit) {
+  const out = [...byKey.values()];
+  for (const f of out) {
+    f.share = total > 0 ? Math.round(f.selfMs / total * 1e3) / 1e3 : 0;
+    f.selfMs = Math.round(f.selfMs * 1e3) / 1e3;
+  }
+  out.sort((a, b) => b.selfMs - a.selfMs || (a.name < b.name ? -1 : 1));
+  return out.slice(0, limit);
+}
+function hottestFromCpuProfile(profile, limit = 20) {
+  const self = /* @__PURE__ */ new Map();
+  const samples = profile.samples ?? [];
+  const deltas = profile.timeDeltas ?? [];
+  if (samples.length > 0 && deltas.length === samples.length) {
+    for (let i = 0; i < samples.length; i++) {
+      const dt = i + 1 < deltas.length ? deltas[i + 1] : 0;
+      self.set(samples[i], (self.get(samples[i]) ?? 0) + Math.max(0, dt) / 1e3);
+    }
+  } else {
+    let hits = 0;
+    for (const node of profile.nodes) hits += node.hitCount ?? 0;
+    const per = hits > 0 ? (profile.endTime - profile.startTime) / 1e3 / hits : 0;
+    for (const node of profile.nodes) self.set(node.id, (node.hitCount ?? 0) * per);
+  }
+  const byKey = /* @__PURE__ */ new Map();
+  let total = 0;
+  for (const node of profile.nodes) {
+    const ms = self.get(node.id) ?? 0;
+    const frame = node.callFrame;
+    if (ms <= 0 || SKIP.has(frame.functionName)) continue;
+    total += ms;
+    const name = frame.functionName || "(anonymous)";
+    const key = `${name}|${frame.url}|${frame.lineNumber}`;
+    let f = byKey.get(key);
+    if (!f) {
+      f = { name, selfMs: 0, share: 0 };
+      if (frame.url) f.url = frame.url;
+      if (frame.lineNumber >= 0) f.line = frame.lineNumber + 1;
+      byKey.set(key, f);
+    }
+    f.selfMs += ms;
+  }
+  return rank(byKey, total, limit);
+}
+function hottestFromSelfProfile(trace, intervalMs, limit = 20) {
+  const byKey = /* @__PURE__ */ new Map();
+  let total = 0;
+  for (let i = 0; i < trace.samples.length; i++) {
+    const s = trace.samples[i];
+    if (s.stackId === void 0) continue;
+    const next = trace.samples[i + 1];
+    const ms = next ? Math.min(next.timestamp - s.timestamp, intervalMs * 4) : intervalMs;
+    const frame = trace.frames[trace.stacks[s.stackId].frameId];
+    const url = frame.resourceId === void 0 ? void 0 : trace.resources[frame.resourceId];
+    const name = frame.name || "(anonymous)";
+    const key = `${name}|${url ?? ""}|${frame.line ?? -1}`;
+    let f = byKey.get(key);
+    if (!f) {
+      f = { name, selfMs: 0, share: 0 };
+      if (url) f.url = url;
+      if (frame.line !== void 0) f.line = frame.line;
+      byKey.set(key, f);
+    }
+    f.selfMs += ms;
+    total += ms;
+  }
+  return rank(byKey, total, limit);
+}
+function samplesFromSelfProfile(trace, intervalMs, offset = 0) {
+  const out = [];
+  for (let i = 0; i < trace.samples.length; i++) {
+    const s = trace.samples[i];
+    if (s.stackId === void 0) continue;
+    const name = trace.frames[trace.stacks[s.stackId].frameId].name || "(anonymous)";
+    const next = trace.samples[i + 1];
+    const ms = next ? Math.min(next.timestamp - s.timestamp, intervalMs * 4) : intervalMs;
+    const last = out[out.length - 1];
+    if (last && last.name === name && Math.abs(last.start + last.ms - (s.timestamp + offset)) < 1e-6) {
+      last.ms += ms;
+      continue;
+    }
+    out.push({ name, start: s.timestamp + offset, ms });
+  }
+  return out;
+}
+export {
+  hottestFromCpuProfile,
+  hottestFromSelfProfile,
+  samplesFromSelfProfile
+};

package/dist/scheduler/index.d.ts

@@ -1,3 +1,5 @@
-export { Profiler, ProfilerResource, type SystemTiming } from './profiler.js';
+export type { CaptureSummary, CaptureWarning, ChromeTrace, HeapStats, HotFunction, SpanStats, Stats, } from './capture/capture.js';
+export type { CaptureOptions } from './capture/recorder.js';
+export { type ClockInfo, clockInfo, defineSpan, internSpan, Profiler, type ProfilerOptions, ProfilerResource, ProfilerSettings, type ProfilerSettingsData, type ProfilerSink, type SpanAggregate, type SpanDef, type SystemTiming, spanCount, spanCovers, spanId, spanName, spanStats, spanTrack, TRACK, type TrackName, trackName, } from './profiler.js';
 export { defineSchedule, First, FixedUpdate, Last, PostUpdate, PreUpdate, Schedule, type ScheduleLabel, type ScheduleRunOptions, Startup, type SystemDescription, Update, } from './schedule.js';
 export { type Condition, condition, conditionLabel, defineSystem, defineSystemSet, type Label, not, SystemConfig, type SystemContext, type SystemDef, type SystemSetConfig, type SystemSetDef, type SystemSpec, } from './system.js';

package/dist/scheduler/index.js

@@ -1,4 +1,19 @@
-import { Profiler, ProfilerResource } from "./profiler.js";
+import {
+  clockInfo,
+  defineSpan,
+  internSpan,
+  Profiler,
+  ProfilerResource,
+  ProfilerSettings,
+  spanCount,
+  spanCovers,
+  spanId,
+  spanName,
+  spanStats,
+  spanTrack,
+  TRACK,
+  trackName
+} from "./profiler.js";
 import {
   defineSchedule,
   First,
@@ -26,14 +41,26 @@ export {
   PreUpdate,
   Profiler,
   ProfilerResource,
+  ProfilerSettings,
   Schedule,
   Startup,
   SystemConfig,
+  TRACK,
   Update,
+  clockInfo,
   condition,
   conditionLabel,
   defineSchedule,
+  defineSpan,
   defineSystem,
   defineSystemSet,
-  not
+  internSpan,
+  not,
+  spanCount,
+  spanCovers,
+  spanId,
+  spanName,
+  spanStats,
+  spanTrack,
+  trackName
 };

package/dist/scheduler/profiler.d.ts

@@ -1,3 +1,57 @@
+import { ShardError } from '../error.js';
+/** A span name. `defineSpan` registers nothing: the first `begin` (or `record`) interns it. */
+export interface SpanDef {
+    readonly name: string;
+    /** The interned id, or -1 before first use. */
+    id: number;
+}
+/** A span by name, for code that times itself: `const ENCODE = defineSpan('terrain/encode')`. */
+export declare function defineSpan(name: string): SpanDef;
+/**
+ * Timeline tracks. Workers are `TRACK.worker + n` for the pool's n-th thread, so track ids fit a
+ * u8 with room for 251 workers.
+ */
+export declare const TRACK: {
+    readonly main: 0;
+    readonly gpu: 1;
+    readonly async: 2;
+    readonly gc: 3;
+    readonly worker: 4;
+};
+export type TrackName = 'main' | 'gpu' | 'async' | 'gc' | 'worker';
+export declare function trackName(track: number): TrackName;
+/**
+ * Whether a budget key covers a span (0074, 0075): the key equals the name, or is a prefix of it
+ * ending at a `/`. `gpu:foliage` covers `gpu:foliage/place`, `render` covers `render/opaque`, and
+ * `render/` does too. `render` doesn't cover `renderer/x`.
+ */
+export declare function spanCovers(key: string, name: string): boolean;
+/** The id of a span name, interning it on first use. */
+export declare function internSpan(name: string, track?: number): number;
+/** How many span names are interned: ids run from 0 to this. Grows as new names are used. */
+export declare function spanCount(): number;
+/** A span's id, or -1 if no profiler has used the name yet. */
+export declare function spanId(name: string): number;
+/** A span's name by id. */
+export declare function spanName(id: number): string;
+/** The track a span was first used on. */
+export declare function spanTrack(id: number): number;
+/**
+ * Where a capture receives the timeline. Called in the hot path: implementations write into
+ * preallocated buffers.
+ */
+export interface ProfilerSink {
+    /**
+     * A span: `start` on the profiler's clock, `ms` long, `depth` on the main track's stack. `frame`
+     * is the frame it belongs to when that isn't the one running (GPU timings land frames later), or
+     * -1.
+     */
+    event(id: number, track: number, depth: number, start: number, ms: number, frame: number): void;
+    /** A frame starts (`frame` is `Time.frame` as it starts). */
+    frameStart(frame: number, at: number): void;
+    /** The frame that started last ends: its CPU time is `ms`. */
+    frameEnd(frame: number, ms: number): void;
+}
 export interface SystemTiming {
     /** Most recent run, in ms. */
     last: number;
@@ -7,13 +61,134 @@ export interface SystemTiming {
     /** Number of samples in the window. */
     samples: number;
 }
-/** Per-system CPU time over the last `window` runs, in a ring buffer. */
+/** A span's aggregates over the window, as `perf.describe` reports them. */
+export interface SpanAggregate extends SystemTiming {
+    span: string;
+    track: TrackName;
+    /** Median over the window, in ms. */
+    p50: number;
+    /** 95th percentile over the window, in ms. */
+    p95: number;
+    /** Under four steps of the clock: the numbers are mostly its resolution. */
+    coarse?: true;
+}
+export interface ProfilerSettingsData {
+    /** Off: spans, records and captures do nothing. Default true. */
+    enabled: boolean;
+    /** Runs each span's aggregates cover. Default 120. */
+    window: number;
+}
+export declare const ProfilerSettings: import("..").ResourceDef<ProfilerSettingsData>;
+/** The clock spans are timed with: its smallest step, and whether the page is isolated. */
+export interface ClockInfo {
+    resolutionMs: number;
+    /** False on a browser page that isn't cross-origin isolated (a coarsened clock). */
+    isolated: boolean;
+}
+export interface ProfilerOptions {
+    /** The clock, in ms. Default `performance.now`. */
+    now?: () => number;
+    /** Shared with `ProfilerSettings`, so toggling it there takes effect. */
+    settings?: ProfilerSettingsData;
+}
+/**
+ * The host clock's resolution: the smallest non-zero step `performance.now()` takes over a short
+ * spin. Measured once. Pages that aren't cross-origin isolated report a coarsened clock.
+ */
+export declare function clockInfo(): ClockInfo;
+/**
+ * Spans and their aggregates (0074): per-system, per-schedule and per-frame CPU time, GPU passes,
+ * worker jobs and async work, over the last `window` runs of each.
+ */
 export declare class Profiler {
-    readonly window: number;
-    private readonly series;
-    constructor(window?: number);
-    record(name: string, ms: number): void;
+    readonly settings: ProfilerSettingsData;
+    /** The clock, in ms. */
+    now: () => number;
+    /** Receives every span while a capture runs. */
+    sink: ProfilerSink | undefined;
+    /** Gets `perf/span-mismatch` and similar warnings; the app logs them. */
+    onWarning: ((warning: ShardError) => void) | undefined;
+    /** `Time.frame` of the frame running now (or that ran last). */
+    frame: number;
+    /** The last span `end` measured, in ms. */
+    lastMs: number;
+    /** What the renderer said about GPU timing: `unavailable` without timestamp queries. */
+    gpu: {
+        status: 'unknown' | 'available' | 'unavailable';
+        quantized: boolean;
+    };
+    private windowSize;
+    private series;
+    private readonly stackIds;
+    private readonly stackStarts;
+    private depth;
+    private frameStartAt;
+    private warned;
+    private readonly asyncIds;
+    private readonly asyncKeys;
+    private readonly asyncStarts;
+    private asyncCount;
+    private readonly frameSpan;
+    constructor(options?: ProfilerOptions | number);
+    get window(): number;
+    get enabled(): boolean;
+    /** Starts a span on the main track. Returns a token for `end`; -1 when the profiler is off. */
+    begin(span: SpanDef): number;
+    /** Ends the span `begin` returned `token` for, recording it. */
+    end(token: number): void;
+    /** Drops the span `token` and everything begun inside it, recording nothing (an exception unwound it). */
+    cancel(token: number): void;
+    /**
+     * Time measured elsewhere (a GPU pass, a worker job): its aggregate, and a timeline event on
+     * `track` that ended now, or started at `start`. `frame`: the frame it belongs to, when it lands
+     * later (GPU timings).
+     */
+    record(span: SpanDef | string, ms: number, track?: number, start?: number, frame?: number): void;
+    /** Only the aggregate (`render/<node>` sums its views into one sample a frame). */
+    sample(span: SpanDef | string, ms: number): void;
+    /** Only the timeline event, when a capture runs. */
+    event(span: SpanDef | string, track: number, start: number, ms: number, frame?: number): void;
+    /** Whether a capture is listening (callers skip work that only feeds the timeline). */
+    get capturing(): boolean;
+    /**
+     * Work that starts in one frame and ends in another (an asset load, a page fetch): an async span,
+     * matched to its `endAsync` by span and key.
+     */
+    beginAsync(span: SpanDef, key: number | string): void;
+    endAsync(span: SpanDef, key: number | string): void;
+    /**
+     * A frame starts: spans left open from before are dropped (and reported once), and the `frame`
+     * span begins. Returns its token for `endFrame`.
+     */
+    beginFrame(frame: number): number;
+    endFrame(token: number): void;
     timing(name: string): SystemTiming | undefined;
+    /** A span's samples over the window, in ring order (not by age); undefined if it never ran. */
+    samples(name: string): Float64Array | undefined;
+    /** Every span that ran, by name. */
     all(): Record<string, SystemTiming>;
+    /**
+     * How many samples a span has had since the profiler started (or its aggregates were reset), by
+     * id: 0 if none. Allocates nothing, for per-frame readers such as feature budgets (0075).
+     */
+    runsOf(id: number): number;
+    /**
+     * The span that was open around a span's latest sample (its parent on the main track), by id, or
+     * -1: what lets aggregates count time two covering keys share once (0075's slices).
+     */
+    parentOf(id: number): number;
+    /** A span's latest sample in ms, by id, or 0 if it has none. Allocates nothing. */
+    lastOf(id: number): number;
+    /** Names of every span with samples. */
+    names(): string[];
+    /** Forgets every aggregate (`perf.reset`). */
+    reset(): void;
+    private push;
+    private createSeries;
+    private resize;
+    /** Reports a problem once per span name. */
+    private warn;
 }
+/** A span's aggregates with its p50, p95 and track, or undefined if it never ran. */
+export declare function spanStats(profiler: Profiler, name: string): SpanAggregate | undefined;
 export declare const ProfilerResource: import("..").ResourceDef<Profiler>;