Skip to content

ADR-0002 — Spanmetrics connector over Prisma native /metrics

Status: Accepted Date: 2026-04-16 Author(s): Platform engineering

Context

Grafana RED dashboards need histogram-shaped metrics for Prisma queries and ioredis commands. Two approaches were available:

  1. Prisma's previewFeatures = ["metrics"] exposes a /metrics HTTP endpoint on the Prisma engine, but it produces Prisma-specific metric names that don't align with OTel semantic conventions and require per-model scrape configuration.
  2. The OTel Collector's spanmetrics connector derives histogram metrics from trace spans — any span producer (Prisma, ioredis, HTTP, etc.) automatically gets RED metrics in Prometheus without per-service code changes.

Decision

Use the spanmetrics connector in observability/otel-collector.yml. Configure it with explicit histogram buckets and dimension keys for db.system, db.operation, db.sql.table, prisma.model, and prisma.method. The connector sits between the traces pipeline output and the metrics pipeline input — spans flow through it on their way to Jaeger and automatically produce traces_spanmetrics_* histograms in Prometheus.

Alternatives considered

  1. Prisma previewFeatures = ["metrics"] endpoint. Rejected: produces non-OTel metric names; requires Prometheus scrape config per Prisma instance; doesn't cover ioredis, HTTP, or BullMQ spans; would need a separate metrics solution for each instrumentation library.

  2. Manual tracer.startSpan + histogram recording in service code. Rejected: high maintenance cost across every service; spans already carry the necessary timing and attribute data — deriving metrics from them avoids duplication.

  3. No metrics — rely on Jaeger queries for latency analysis. Rejected: Jaeger is optimised for single-trace debugging, not aggregate RED dashboards. Prometheus + Grafana provide time-series alerting and trend visualization that Jaeger does not.

Consequences

  • Every new span-producing instrumentation automatically gets RED metrics. No per-service configuration needed.
  • The spanmetrics connector adds memory overhead proportional to the cardinality of the dimension keys. The chosen dimensions (prisma.model, prisma.method, db.system, db.operation, db.sql.table) are bounded by the schema size — acceptable for a local dev stack.
  • Prisma's native /metrics preview feature stays enabled (previewFeatures = ["tracing"] implies some metric support) but is not scraped. If a future need arises for engine-internal metrics (connection pool stats, query plan cache), it can be added alongside spanmetrics.

References

  • observability/otel-collector.yml:46-57 — spanmetrics connector configuration
  • observability/otel-collector.yml:92-95 — traces pipeline with spanmetrics exporter
  • observability/grafana/provisioning/dashboards/prisma-postgres.json — dashboard consuming spanmetrics