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

Bitpacker Network OTel Instruments

(no submodules)

Purpose

OTel meter, tracer, counter, and histogram declarations for @suaveplan/bitpacker-network. Ships canonical instrumentation primitives for the NetworkSimulator's send/receive boundaries plus the burst-loss event. Centralizing the metric/span vocabulary here lets a downstream consumer attach observability to the simulator without re-deriving names.

The metric and span names follow the suaveplan convention with snake-case for the multi-word package: tracer/meter named @suaveplan/bitpacker-network; spans named bitpacker_network.<operation> (send, receive, burst); counters/histograms named bitpacker_network.<scope>.<metric>.

Features

• getBitPackerNetworkTracer() — returns the package's tracer
• networkPacketsTotal — counter labelled by status (one of the five PacketStatus values)
• networkLatencyMs — histogram of simulated latency for delivered packets
• networkPacketBytes — histogram of per-packet byte size, labelled by status
• BITPACKER_NETWORK_SPAN_NAMES — three canonical span names

Usage: Basic Example

import {
    BITPACKER_NETWORK_SPAN_NAMES,
    networkPacketsTotal,
    getBitPackerNetworkTracer,
} from "@suaveplan/bitpacker-network";

const tracer = getBitPackerNetworkTracer();
tracer.startActiveSpan(BITPACKER_NETWORK_SPAN_NAMES.send, (span) => {
    try {
        // send work
        networkPacketsTotal.add(1, { status: "delivered" });
    } finally {
        span.end();
    }
});

Usage: Advanced Example

import {
    networkLatencyMs,
    networkPacketsTotal,
    PacketStatus,
} from "@suaveplan/bitpacker-network";

function recordOutcome(status: PacketStatus, latencyMs: number, bytes: number) {
    networkPacketsTotal.add(1, { status });
    if (status === PacketStatus.DELIVERED) {
        networkLatencyMs.record(latencyMs);
    }
}

API Reference

getBitPackerNetworkTracer(): Tracer

Returns the OTel Tracer instance for the package.

networkPacketsTotal: Counter

Counter labelled by status: "delivered" | "lost" | "duplicated" | "corrupted" | "reordered".

networkLatencyMs: Histogram

Histogram of simulated per-packet latency in milliseconds, recorded only on delivered packets.

networkPacketBytes: Histogram

Histogram of per-packet byte size, labelled by status.

BITPACKER_NETWORK_SPAN_NAMES

Const map: { send, receive, burst } → canonical span names.

Implementation Notes

• Status is a label, not separate counters. networkPacketsTotal{status="lost"} is more flexible than separate dropped_total/reordered_total/etc; new packet states fold in without schema churn.
• Latency only on delivered. Lost/dropped packets have no meaningful latency. Recording would distort the latency histogram with zeros.
• No per-packet spans. A simulator running 10k packets/s would produce 10k spans/s if each were instrumented. The counter-and-histogram pattern is sufficient at this rate.