first commit

docs/foundation/bitpacker/bitpacker-strategies/src/otel/instruments.md

@@ -0,0 +1,76 @@
+# Bitpacker Strategies OTel Instruments
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+OTel meter, tracer, counter, and histogram declarations for `@suaveplan/bitpacker-strategies`. The package's only public boundary is `registerDefaultStrategies(manager)` — strategies are stateless chain handlers invoked from inside the parent `bitpacker.pack` / `bitpacker.unpack` span owned by `@suaveplan/bitpacker`. Per the proposal "one span per top-level call; per-chunk events nested", strategy invocations do NOT get their own spans; only the bootstrap call `registerDefaultStrategies` is instrumented.
+
+The metric and span names follow the suaveplan convention with snake-case for the multi-word package: tracer/meter named `@suaveplan/bitpacker-strategies`; span named `bitpacker_strategies.register`; counter/histogram named `bitpacker_strategies.register.<metric>`.
+
+## Features
+
+- `getBitPackerStrategiesTracer()` — returns the package's tracer
+- `registerStrategiesTotal` — counter labelled by `success`
+- `registerStrategiesDurationMs` — histogram of bootstrap duration
+- `BITPACKER_STRATEGIES_SPAN_NAMES` — `{ register: "bitpacker_strategies.register" }`
+
+## Usage: Basic Example
+
+```ts
+import { PackingStrategyManager } from "@suaveplan/bitpacker";
+import { registerDefaultStrategies } from "@suaveplan/bitpacker-strategies";
+
+const manager = new PackingStrategyManager();
+registerDefaultStrategies(manager);
+// One span emitted: "bitpacker_strategies.register"
+// Counter incremented: bitpacker_strategies.register.total{success="true"}
+// Histogram recorded: bitpacker_strategies.register.duration_ms
+```
+
+## Usage: Advanced Example
+
+```ts
+import { trace } from "@opentelemetry/api";
+import { PackingStrategyManager } from "@suaveplan/bitpacker";
+import {
+    BITPACKER_STRATEGIES_SPAN_NAMES,
+    registerDefaultStrategies,
+} from "@suaveplan/bitpacker-strategies";
+
+trace
+    .getTracer("my-app")
+    .startActiveSpan(
+        BITPACKER_STRATEGIES_SPAN_NAMES.register + ".wrapper",
+        (span) => {
+            const manager = new PackingStrategyManager();
+            registerDefaultStrategies(manager);
+            // bitpacker_strategies.register is a child span here.
+            span.end();
+        }
+    );
+```
+
+## API Reference
+
+### `getBitPackerStrategiesTracer(): Tracer`
+
+Returns the OTel `Tracer` instance for the package.
+
+### `registerStrategiesTotal: Counter`
+
+Counter incremented once per `registerDefaultStrategies` call. Labels: `success: "true" | "false"`.
+
+### `registerStrategiesDurationMs: Histogram`
+
+Histogram of elapsed wall-clock milliseconds per bootstrap call. No labels.
+
+### `BITPACKER_STRATEGIES_SPAN_NAMES`
+
+Const map: `{ register: "bitpacker_strategies.register" }`.
+
+## Implementation Notes
+
+- **No per-strategy spans.** The 30 shipped strategies are invoked thousands of times per pack/unpack on large schemas; one span each would explode trace volume. They run inside the parent `bitpacker.pack` / `bitpacker.unpack` span without instrumentation.
+- **Bootstrap-only counter.** `registerStrategiesTotal` is incremented once per `registerDefaultStrategies` call. A consumer can reason about chain-bootstrap frequency from this counter without correlating across packages.