Skip to content

Latest commit

 

History

History
85 lines (58 loc) · 3.57 KB

README.md

File metadata and controls

85 lines (58 loc) · 3.57 KB

errx/contrib/prometheus — error metrics for Go by stable identity

Go Reference Go Report Card CI license Go part of errx

Increment a Prometheus errx_errors_total counter from errx errors, labelled by the stable identity — code, domain, severity, class. Labels come from the machine identity, not the variable message, so cardinality stays bounded and the counter groups the same way the fingerprint, Sentry and logs do.

Contents

Why

Counting errors by message explodes Prometheus cardinality (every id/count is a new series) and never aligns with how Sentry groups them. errx already has a stable (domain, code) identity; this adapter uses exactly that for labels, so dashboards, alerts, Sentry issues and logs all pivot on the same key.

Install

go get github.com/ubgo/errx/contrib/prometheus

Pulls github.com/prometheus/client_golang.

Step by step

  1. Create the sink with your registry (once, at startup) — it registers the collector:

    import (
        "github.com/prometheus/client_golang/prometheus"
        "github.com/prometheus/client_golang/prometheus/promhttp"
        "github.com/ubgo/errx"
        promx "github.com/ubgo/errx/contrib/prometheus"
    )
    
    reg := errx.NewRegistry().Add(promx.New(prometheus.DefaultRegisterer))
    http.Handle("/metrics", promhttp.Handler())
  2. Report errors through the registry (typically in middleware):

    if err != nil {
        reg.Report(r.Context(), err) // increments errx_errors_total{...}
    }

That's it — every reported error bumps the counter with its identity labels.

Metric

errx_errors_total{code="…", domain="…", severity="…", class="…"}  counter

code and domain default to "unknown" when the error has none. severity is debug|info|warn|error|fatal; class is expected|defect|cancelled.

Example queries

# error rate by code over 5m
sum by (code) (rate(errx_errors_total[5m]))

# defects (bugs) only — alert on any
sum(rate(errx_errors_total{class="defect"}[5m])) > 0

# top noisy domains
topk(5, sum by (domain) (increase(errx_errors_total[1h])))

API

Symbol Purpose
promx.New(reg prometheus.Registerer) *Sink Create + register the errx_errors_total CounterVec; returns the sink. Pass nil to skip registration (advanced/testing).
(*Sink).Name() string "prometheus".
(*Sink).Emit(ctx, *errx.Report) error Implements errx.Sink; increments the counter.

New calls MustRegister; a duplicate-collector panic at startup is a programming error worth surfacing loudly.

See the root README and docs/use-cases.md for full observability wiring (Sentry + OTel + Prometheus sharing one fingerprint).