70 lines
5.3 KiB
Markdown
70 lines
5.3 KiB
Markdown
# @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
|
|
|