skills/plugins/library-navigator/skills/sp-events-metrics/SKILL.md

name, description

name	description
sp-events-metrics	OTel metrics companion for @suaveplan/events — dispatch counters, latency histograms, queue-depth gauges via interceptor API.

Architecture

Component	Responsibility
attachEventMetrics	Attaches OTel metrics instrumentation to an EventBus via public interceptor API
EventMetricsHandle	Returned handle providing snapshot() and detach() for lifecycle management
MetricsSnapshot	Typed snapshot of dispatch totals, listener error counts, and latency histograms per event name
METRIC_NAMES	Canonical OTel instrument names (events.dispatch_total, events.listener_errors_total, etc.)
ATTRIBUTE_KEYS	Standard attribute keys for metric dimensions
EVENTS_METRICS_CODES + EventsMetricsError	Structured error registry for metrics attachment failures

File Structure

packages/networking/events/events-metrics/src/
  core/attach-event-metrics/   attachEventMetrics, EventMetricsHandle, MetricsSnapshot
  metrics/metric-names/        METRIC_NAMES and ATTRIBUTE_KEYS
  error-codes/                 EVENTS_METRICS_CODES and EventsMetricsError

Sibling packages

• @suaveplan/events — EventBus that this package instruments
• @suaveplan/opentelemetry — OTel SDK setup helpers
• @suaveplan/error — structured error registry via defineCodes
• @suaveplan/types — shared TypeScript primitives
• @suaveplan/testing — unit test infrastructure

Patterns

Quick Start

import { EventBus } from "@suaveplan/events";
import { attachEventMetrics } from "@suaveplan/events-metrics";

const bus = new EventBus();
const handle = attachEventMetrics(bus);

await bus.emitAsync("user.created", { id: "u-1" });
console.log(handle.snapshot().dispatchTotal["user.created"]); // 1
handle.detach();

Inspect metrics snapshot

const snapshot = handle.snapshot();
console.log(snapshot.dispatchTotal);
console.log(snapshot.listenerErrorTotal);
console.log(snapshot.latencyHistogram);

Constraints

• Attaches via @suaveplan/events public interceptor API (no private state access)
• Metrics are no-ops when no MeterProvider is registered
• detach() removes all instrumentation without affecting the bus
• OTel counters tagged by event name; histograms record dispatch latency in ms

Checklist

• Verify attachEventMetrics works with both sync and async EventBus emitters
• Confirm EVENTS_METRICS_CODES registered via defineCodes("EVENTS_METRICS", [...])
• Check subpath exports in package.json align with src/ modules
• Run bunx turbo lint typecheck test build --filter=@suaveplan/events-metrics
• Confirm metrics are no-ops when no OTel SDK is registered