# 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.