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

Bitpacker Compressed OTel Instruments

(no submodules)

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

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

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.