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

Bitpacker Strategies OTel Instruments

(no submodules)

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

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

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.