# 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.