first commit

docs/devtools/tooling/profiler/README.md

@@ -0,0 +1,69 @@
+# @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.
+
+<!-- begin:auto-docs -->
+## Documentation tree
+
+- [bottleneck](./src/bottleneck/bottleneck.md) — `BottleneckDetector` analyses arrays of `ProfileEntry` records to surface performance bottlenecks. It groups entries by…
+  - [bottleneck](./src/bottleneck/bottleneck.md) — `BottleneckDetector` analyses arrays of `ProfileEntry` records to surface performance bottlenecks. It groups entries by…
+- [comparison](./src/comparison/comparison.md) — `ProfileComparator` diffs two sets of profiling data — either raw `ProfileEntry[]` arrays or pre-aggregated `ProfileRep…
+  - [comparison](./src/comparison/comparison.md) — `ProfileComparator` diffs two sets of profiling data — either raw `ProfileEntry[]` arrays or pre-aggregated `ProfileRep…
+- [error-codes](./src/error-codes/error-codes.md) — Defines the stable error-code registry for `@suaveplan/profiler` and the typed `ProfilerError` class consumers throw fr…
+  - [error-codes](./src/error-codes/error-codes.md) — Defines the stable error-code registry for `@suaveplan/profiler` and the typed `ProfilerError` class consumers throw fr…
+- [flamegraph](./src/flamegraph/flamegraph.md) — `FlameGraphGenerator` builds a flame-graph data structure from `ProfileEntry` arrays by nesting entries on start/end-ti…
+  - [flamegraph](./src/flamegraph/flamegraph.md) — `FlameGraphGenerator` builds a flame-graph data structure from `ProfileEntry` arrays by nesting entries on start/end-ti…
+- [memory](./src/memory/memory.md) — `MemoryProfiler` captures periodic heap snapshots, records labelled allocation totals, tracks a peak-heap watermark, an…
+  - [memory](./src/memory/memory.md) — `MemoryProfiler` captures periodic heap snapshots, records labelled allocation totals, tracks a peak-heap watermark, an…
+- [otel](./src/otel/otel.md) — `OtelExporter` converts `ProfileEntry` records to OTLP-compatible spans and optionally exports them to a collector endp…
+  - [otel](./src/otel/otel.md) — `OtelExporter` converts `ProfileEntry` records to OTLP-compatible spans and optionally exports them to a collector endp…
+- [profiler](./src/profiler/profiler.md) — `Profiler` is the core measurement primitive of `@suaveplan/profiler`. It records timing entries between paired `start(…
+  - [profiler](./src/profiler/profiler.md) — `Profiler` is the core measurement primitive of `@suaveplan/profiler`. It records timing entries between paired `start(…
+- [reporter](./src/reporter/reporter.md) — `ProfileReporter` computes summary statistics from profiling entries — count, min, max, mean, median, configurable perc…
+  - [reporter](./src/reporter/reporter.md) — `ProfileReporter` computes summary statistics from profiling entries — count, min, max, mean, median, configurable perc…
+- [sampler](./src/sampler/sampler.md) — `Sampler` collects periodic snapshots of runtime metrics (memory usage by default, plus caller-supplied custom metrics)…
+  - [sampler](./src/sampler/sampler.md) — `Sampler` collects periodic snapshots of runtime metrics (memory usage by default, plus caller-supplied custom metrics)…
+- [telemetry](./src/telemetry/telemetry.md) — Owns the OpenTelemetry meter, counters, and histograms emitted by `@suaveplan/profiler` itself. Every public completion…
+  - [telemetry](./src/telemetry/telemetry.md) — Owns the OpenTelemetry meter, counters, and histograms emitted by `@suaveplan/profiler` itself. Every public completion…
+<!-- end:auto-docs -->
+
+## Modules
+
+- [`profiler/`](./src/profiler/profiler.md) — `Profiler`: start/stop/mark/measure with injectable `Clock`.
+- [`sampler/`](./src/sampler/sampler.md) — `Sampler`: periodic metric collection driven by `TimersLike`.
+- [`memory/`](./src/memory/memory.md) — `MemoryProfiler`: heap snapshots, allocation tracking, leak detection.
+- [`bottleneck/`](./src/bottleneck/bottleneck.md) — `BottleneckDetector`: hot-spot + budget-violation analysis.
+- [`comparison/`](./src/comparison/comparison.md) — `ProfileComparator`: regressions / improvements / unchanged.
+- [`flamegraph/`](./src/flamegraph/flamegraph.md) — `FlameGraphGenerator`: containment-tree builder + d3 JSON.
+- [`reporter/`](./src/reporter/reporter.md) — `ProfileReporter`: percentile stats + text format.
+- [`otel/`](./src/otel/otel.md) — `OtelExporter`: OTLP-compatible JSON exporter.
+- [`error-codes/`](./src/error-codes/error-codes.md) — `PROFILER_CODES` + `ProfilerError`.
+- [`telemetry/`](./src/telemetry/telemetry.md) — OTel meter for the profiler itself.
+
+## Install
+
+```bash
+bun add @suaveplan/profiler
+```
+
+## Usage
+
+```ts
+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
+