metrics

Metrics Utilities (core/metrics)

The metrics package provides reusable helpers for emitting counters, timers, histograms, and gauges on a tally.Scope. It standardizes metric names across controllers and integrates with core/errs for automatic error classification tags.

Design

Free functions on tally.Scope — no wrapper types. Existing constructors accept tally.Scope and don't need to change.

Operation lifecycle — Begin and Complete tie the full metrics lifecycle together. Begin captures the start time and emits {name}.called; Complete emits succeeded/failed counters, a latency timer, and a latency histogram. This prevents mismatched or forgotten metrics calls.

Error-aware tagging — ErrorTags integrates with core/errs to produce error_origin=user|infra, retryable=true|false, and dependency=true tags automatically. Complete uses these to tag latency metrics on failure.

Consistent naming — all Named helpers follow the {name}.{sub} sub-scope pattern, producing structured metric paths like process.called, publish.attempts, consumer.pending_messages.

Operation Lifecycle

For any operation with a clear start/end, use Begin/Complete:

// RPC controller
func (c *LandController) Land(ctx context.Context, req *pb.LandRequest) (resp *pb.LandResponse, retErr error) {
    op := metrics.Begin(c.scope, "land")
    defer func() { op.Complete(retErr) }()

    // ... business logic ...
    return &pb.LandResponse{Sqid: request.ID}, nil
}

// Queue controller
func (c *Controller) Process(ctx context.Context, delivery consumer.Delivery) (retErr error) {
    op := metrics.Begin(c.scope, "process")
    defer func() { op.Complete(retErr) }()

    // ... business logic ...
    return nil
}

On success, Complete emits:

• {name}.succeeded counter +1
• {name}.latency timer tagged result=success
• {name}.latency_histogram histogram tagged result=success

On failure, Complete emits:

• {name}.failed counter +1
• {name}.latency timer tagged result=error, error_origin=user|infra, retryable=true|false, and optionally dependency=true
• {name}.latency_histogram histogram with the same tags

Named Helpers

For ad-hoc metrics that don't fit the Begin/Complete lifecycle. All follow the {name}.{sub} sub-scope pattern:

// Count a specific sub-event
metrics.NamedCounter(c.scope, "publish", "attempts", 1)

// Record a specific sub-latency
metrics.NamedTimer(c.scope, "publish", "queue_latency", elapsed)

// Track current queue depth (goes up and down)
metrics.NamedGauge(c.scope, "consumer", "pending_messages", float64(len(pending)))

// Create a reusable histogram (store on struct, call RecordDuration per invocation)
h := metrics.NamedHistogram(c.scope, "process", "duration", tally.DurationBuckets{...})
h.RecordDuration(elapsed)

Error Tags

ErrorTags classifies errors using core/errs and returns tags for dimensional filtering:

tags := metrics.ErrorTags(err)
// Generic error:     [{error_origin, infra}, {retryable, false}]
// User error:        [{error_origin, user},  {retryable, false}]
// Retryable error:   [{error_origin, infra}, {retryable, true}]
// Dependency error:  [{error_origin, infra}, {retryable, false}, {dependency, true}]

Tags

Use NewTag to pass additional dimensional tags to any helper:

op := metrics.Begin(c.scope, "process", metrics.NewTag("queue", req.Queue))
defer func() { op.Complete(retErr) }()

metrics.NamedCounter(c.scope, "publish", "attempts", 1, metrics.NewTag("topic", c.topic))

Latency Buckets

Complete uses default latency buckets (5ms to 4h) automatically, suitable for both fast RPCs and long-running operations like builds and merges:

5ms, 10ms, 25ms, 50ms, 100ms, 250ms, 500ms, 1s, 2.5s, 5s, 10s, 30s, 1m, 2m, 5m, 10m, 30m, 1h, 2h, 4h

For custom histograms, pass your own buckets to NamedHistogram:

h := metrics.NamedHistogram(c.scope, "build", "duration", tally.DurationBuckets{...})