Part 23: Metrics📋

Typed Counters, Gauges, Histograms📋

A metrics library that lets you increment a gauge or decrement a counter is a library that has confused the three primitives. @frenchexdev/ddd-metrics reifies metrics as a port where each primitive is its own type — a counter has increment, a gauge has set, a histogram has observe, and the type system refuses the wrong operation on the wrong primitive.

What Metrics Reifies📋

The Prometheus model has been adopted widely enough that the three primitives — counter (monotonic up), gauge (free-floating value), histogram (distribution of observations bucketed) — are the lingua franca of operational metrics. The port reifies the three as distinct types and provides a fluent declaration shape: metrics.counter('subscription_started_total', ['plan']) returns a typed counter that increments with inc({ plan: 'pro' }). The plan label dimension is typed against the declaration; passing a label the counter does not know about is a compile error.

The reason it matters: a team that emits operational metrics typed as Record<string, number> ends up with metrics names that drift, label dimensions that disagree across services, and a Grafana dashboard that breaks when somebody renames a label in one service but not the other. The typed port survives renames because every emit site is type-checked against the declaration.

The Runtime: ddd-metrics and adapter📋

Two packages — ddd-metrics, ddd-metrics-prometheus-adapter — both M4/M5 stubs pinned to TelemetryStructuredObservabilityRequirement. The Prometheus adapter exposes the /metrics endpoint in the application's HTTP surface; alternative adapters (StatsD, OpenTelemetry's metrics SDK) satisfy the same port.

The Analyzer: ddd-metrics-analyzer📋

Spec-first (spec.ts). Priority Medium. One info-severity rule, DDD-METRICS-001, recommending the Metric suffix. As with the other telemetry ports, the deeper invariants (typed dimensions, naming conventions) live in the port's TypeScript surface — not in an analyzer rule the team would have to maintain separately.

Cross-Links📋

• Telemetry trio member with @Log and @Tracing.
• Emitted by @CommandHandlers and @QueryHandlers for latency and outcome counts.
• A @Projection may emit metrics during replay so the rebuild rate is observable.
• Lives behind @Port/@Adapter; the conformance suite covers the Prometheus exposition shape.

Back to the series index.