# Bitpacker Compressed OTel Instruments

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->
## Purpose

OTel meter, tracer, counter, and histogram declarations for `@suaveplan/bitpacker-compressed`. Ships canonical instrumentation primitives for the compression/decompression pipeline (`gzip`, `deflate`, `none`, `rle`, future custom adapters) plus the `CompressedBitPacker.pack` / `unpack` boundaries that wrap the compression step. Every operation can be observed with the same vocabulary regardless of which adapter is selected.

The metric and span names follow the suaveplan convention with snake-case for the multi-word package: tracer/meter named `@suaveplan/bitpacker-compressed`; spans named `bitpacker_compressed.<operation>`; counters/histograms named `bitpacker_compressed.<scope>.<metric>`.

## Features

- `getBitPackerCompressedTracer()` — returns the package's tracer
- `compressionOpsTotal` — counter labelled by `op`, `algorithm`, `success`
- `compressionOpDurationMs` — histogram of compress/decompress duration
- `compressionRatio` — histogram of `output_bytes / input_bytes` per successful compress
- `BITPACKER_COMPRESSED_SPAN_NAMES` — four canonical span names

## Usage: Basic Example

```ts
import {
    BITPACKER_COMPRESSED_SPAN_NAMES,
    compressionOpsTotal,
    getBitPackerCompressedTracer,
} from "@suaveplan/bitpacker-compressed";

const tracer = getBitPackerCompressedTracer();
tracer.startActiveSpan(
    BITPACKER_COMPRESSED_SPAN_NAMES.compress,
    (span) => {
        try {
            // compress work
            compressionOpsTotal.add(1, {
                op: "compress",
                algorithm: "gzip",
                success: "true",
            });
        } finally {
            span.end();
        }
    }
);
```

## Usage: Advanced Example

```ts
import { compressionRatio } from "@suaveplan/bitpacker-compressed";

function recordCompressionRatio(input: Uint8Array, output: Uint8Array, algorithm: string) {
    compressionRatio.record(output.byteLength / input.byteLength, { algorithm });
}
```

## API Reference

### `getBitPackerCompressedTracer(): Tracer`

Returns the OTel `Tracer` instance for the package.

### `compressionOpsTotal: Counter`

Counter labelled by `op: "compress" | "decompress"`, `algorithm: string`, `success: "true" | "false"`.

### `compressionOpDurationMs: Histogram`

Histogram of elapsed milliseconds per compress/decompress call.

### `compressionRatio: Histogram`

Histogram of compression ratio (`output_bytes / input_bytes`), labelled by `algorithm`. Recorded only on successful `compress` calls — decompress doesn't have a meaningful ratio.

### `BITPACKER_COMPRESSED_SPAN_NAMES`

Const map: `{ compress, decompress, pack, unpack }` → canonical span names.

## Implementation Notes

- **Algorithm is a label, not a counter prefix.** `compressionOpsTotal{algorithm="gzip"}` is more flexible than separate `gzip_compress_total` / `deflate_compress_total` counters; new adapters fold in without schema changes.
- **`compressionRatio` is not a counter.** The ratio is per-call and stored as a histogram so dashboards can plot p50/p95/p99 ratios over time. A counter would only show throughput, not effectiveness.
- **No per-chunk spans.** Compression adapters often process bytes in internal chunks; one span each would explode trace volume on large inputs.