Initial Commit

packages/networking/events/events-metrics/src/metrics/metric-names/metric-names.md

@@ -0,0 +1,61 @@
+# metric-names
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+Exports the stable constant objects `METRIC_NAMES` and `ATTRIBUTE_KEYS` that define every OTel metric name and span attribute key used across `@suaveplan/events-metrics`. Centralising these names prevents typos, enables IDE completion, and makes it easy to audit the full observability surface of the package.
+
+These constants are the single source of truth consumed by both the instrumentation code and the tests that assert metric names are correct.
+
+## Features
+
+- `METRIC_NAMES` — all five OTel metric names: dispatch total, listener error total, dispatch latency histogram, queue depth gauge, active subscribers gauge
+- `ATTRIBUTE_KEYS` — all four OTel attribute keys: event name, event category, listener ID, bus ID
+- Both objects use `as const` for full literal-type narrowing
+
+## Usage: Basic Example
+
+```ts
+import { METRIC_NAMES, ATTRIBUTE_KEYS } from "@suaveplan/events-metrics";
+
+console.log(METRIC_NAMES.DISPATCH_TOTAL);   // "suaveplan.events.dispatch.total"
+console.log(ATTRIBUTE_KEYS.EVENT_NAME);      // "event.name"
+```
+
+## Usage: Advanced Example
+
+```ts
+import { METRIC_NAMES, ATTRIBUTE_KEYS } from "@suaveplan/events-metrics";
+import { metrics } from "@opentelemetry/api";
+
+const meter = metrics.getMeter("my-app");
+const counter = meter.createCounter(METRIC_NAMES.DISPATCH_TOTAL);
+counter.add(1, { [ATTRIBUTE_KEYS.EVENT_NAME]: "user.created" });
+```
+
+## API Reference
+
+### `METRIC_NAMES`
+
+| Key | Value |
+|---|---|
+| `DISPATCH_TOTAL` | `"suaveplan.events.dispatch.total"` |
+| `LISTENER_ERROR_TOTAL` | `"suaveplan.events.listener.error.total"` |
+| `DISPATCH_LATENCY_MS` | `"suaveplan.events.dispatch.latency_ms"` |
+| `QUEUE_DEPTH` | `"suaveplan.events.queue.depth"` |
+| `ACTIVE_SUBSCRIBERS` | `"suaveplan.events.subscribers.active"` |
+
+### `ATTRIBUTE_KEYS`
+
+| Key | Value |
+|---|---|
+| `EVENT_NAME` | `"event.name"` |
+| `EVENT_CATEGORY` | `"event.category"` |
+| `LISTENER_ID` | `"listener.id"` |
+| `BUS_ID` | `"bus.id"` |
+
+## Implementation Notes
+
+The constants are defined in `src/constants/index.ts` and re-exported from this module to follow the package structure convention. Consumers should import from `@suaveplan/events-metrics` (the root barrel) rather than the internal path to benefit from tree-shaking and future path changes.