Initial Commit

packages/foundation/bitpacker/bitpacker-compressed/src/otel/instruments.md

@@ -0,0 +1,83 @@
+# 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.