first commit

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

@@ -0,0 +1,83 @@
+# Bitpacker Network OTel Instruments
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## 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
+
+```ts
+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
+
+```ts
+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.