suaveplan/packages/devtools/tooling/profiler/README.md

@suaveplan/profiler - Universal runtime performance profiler — Profiler/Sampler/MemoryProfiler/BottleneckDetector/ProfileComparator/FlameGraphGenerator/ProfileReporter/OtelExporter with injectable Clock+TimersLike+HeapCapture, PROFILER_CODES error registry, and OTel self-telemetry.

Universal runtime performance profiler.

Documentation tree

• bottleneck — BottleneckDetector analyses arrays of ProfileEntry records to surface performance bottlenecks. It groups entries by…
  • bottleneck — BottleneckDetector analyses arrays of ProfileEntry records to surface performance bottlenecks. It groups entries by…
• comparison — ProfileComparator diffs two sets of profiling data — either raw ProfileEntry[] arrays or pre-aggregated `ProfileRep…
  • comparison — ProfileComparator diffs two sets of profiling data — either raw ProfileEntry[] arrays or pre-aggregated `ProfileRep…
• error-codes — Defines the stable error-code registry for @suaveplan/profiler and the typed ProfilerError class consumers throw fr…
  • error-codes — Defines the stable error-code registry for @suaveplan/profiler and the typed ProfilerError class consumers throw fr…
• flamegraph — FlameGraphGenerator builds a flame-graph data structure from ProfileEntry arrays by nesting entries on start/end-ti…
  • flamegraph — FlameGraphGenerator builds a flame-graph data structure from ProfileEntry arrays by nesting entries on start/end-ti…
• memory — MemoryProfiler captures periodic heap snapshots, records labelled allocation totals, tracks a peak-heap watermark, an…
  • memory — MemoryProfiler captures periodic heap snapshots, records labelled allocation totals, tracks a peak-heap watermark, an…
• otel — OtelExporter converts ProfileEntry records to OTLP-compatible spans and optionally exports them to a collector endp…
  • otel — OtelExporter converts ProfileEntry records to OTLP-compatible spans and optionally exports them to a collector endp…
• profiler — Profiler is the core measurement primitive of @suaveplan/profiler. It records timing entries between paired `start(…
  • profiler — Profiler is the core measurement primitive of @suaveplan/profiler. It records timing entries between paired `start(…
• reporter — ProfileReporter computes summary statistics from profiling entries — count, min, max, mean, median, configurable perc…
  • reporter — ProfileReporter computes summary statistics from profiling entries — count, min, max, mean, median, configurable perc…
• sampler — Sampler collects periodic snapshots of runtime metrics (memory usage by default, plus caller-supplied custom metrics)…
  • sampler — Sampler collects periodic snapshots of runtime metrics (memory usage by default, plus caller-supplied custom metrics)…
• telemetry — Owns the OpenTelemetry meter, counters, and histograms emitted by @suaveplan/profiler itself. Every public completion…
  • telemetry — Owns the OpenTelemetry meter, counters, and histograms emitted by @suaveplan/profiler itself. Every public completion…

Modules

• profiler/ — Profiler: start/stop/mark/measure with injectable Clock.
• sampler/ — Sampler: periodic metric collection driven by TimersLike.
• memory/ — MemoryProfiler: heap snapshots, allocation tracking, leak detection.
• bottleneck/ — BottleneckDetector: hot-spot + budget-violation analysis.
• comparison/ — ProfileComparator: regressions / improvements / unchanged.
• flamegraph/ — FlameGraphGenerator: containment-tree builder + d3 JSON.
• reporter/ — ProfileReporter: percentile stats + text format.
• otel/ — OtelExporter: OTLP-compatible JSON exporter.
• error-codes/ — PROFILER_CODES + ProfilerError.
• telemetry/ — OTel meter for the profiler itself.

Install

bun add @suaveplan/profiler

Usage

import { Profiler, ProfileReporter, OtelExporter } from "@suaveplan/profiler";

const profiler = new Profiler();
profiler.start("render", "ui");
// ... work ...
profiler.stop("render");

const reporter = new ProfileReporter({ alertThreshold: 16 });
console.log(reporter.formatReport(reporter.generateReport(profiler.getEntries())));

const exporter = new OtelExporter({ serviceName: "my-app" });
await exporter.export(exporter.convertEntries(profiler.getEntries()));

License

MIT