activity

Documentation

Overview

Package activity provides generic operation instrumentation for non-HTTP workloads.

ActivityMetrics is the core type, providing RED metrics (Rate, Errors, Duration) plus saturation tracking. WorkerMetrics extends ActivityMetrics with queue-specific metrics for job/worker patterns.

Quick Start

metrics, _ := activity.NewActivityMetrics(reg, activity.Config{
    Prefix: "myapp",
})

func processOrder(orderID string) error {
    done := metrics.Begin("process_order")
    defer done(nil)
    return doWork()
}

Metrics Exposed

ActivityMetrics exposes 4 metric families:

• {prefix}_operations_total: metric.Counter by activity, status
• {prefix}_operation_errors_total: metric.Counter by activity, error_type
• {prefix}_operation_duration_seconds: metric.Histogram by activity, status (with exemplars)
• {prefix}_operations_in_flight: metric.Gauge by activity

WorkerMetrics adds:

• {prefix}_queue_depth: Gauge by queue_name
• {prefix}_job_retries_total: Counter by queue_name, job_type

Error Classification

Errors are automatically classified into error_type labels:

• "timeout": context.DeadlineExceeded
• "cancelled": context.Canceled
• "panic": errors containing "panic"
• "error": all other errors

Custom classification is supported via the ErrorClassifier interface or its functional adapter ErrorClassifierFunc.

Français

Le package activity fournit une instrumentation générique pour les workloads non-HTTP.

ActivityMetrics est le type principal, fournissant les métriques RED (Rate, Errors, Duration) plus le suivi de saturation. WorkerMetrics étend ActivityMetrics avec des métriques spécifiques aux queues pour les patterns job/worker.

Les erreurs sont automatiquement classifiées en labels error_type :

• "timeout": context.DeadlineExceeded
• "cancelled": context.Canceled
• "panic": erreurs contenant "panic"
• "error": toutes les autres erreurs

Index

• Constants
• Variables
• type ActivityMetrics
  • func NewActivityMetrics(reg *registry.Registry, cfg Config) (*ActivityMetrics, error)
  • func (a *ActivityMetrics) Begin(activity string) func(err error)
  • func (a *ActivityMetrics) BeginWithTrace(activity, traceID string) func(err error)
  • func (a *ActivityMetrics) Prune() int
  • func (a *ActivityMetrics) Record(activity, status string, duration time.Duration, opErr error)
• type Config
• type ErrorClassifier
• type ErrorClassifierFunc
  • func (f ErrorClassifierFunc) Classify(err error) string
• type WorkerConfig
• type WorkerMetrics
  • func NewWorkerMetrics(reg *registry.Registry, cfg WorkerConfig) (*WorkerMetrics, error)
  • func (w *WorkerMetrics) BeginJob(queueName, jobType string) func(err error)
  • func (w *WorkerMetrics) BeginJobWithTrace(queueName, jobType, traceID string) func(err error)
  • func (w *WorkerMetrics) Prune() int
  • func (w *WorkerMetrics) RecordRetry(queueName, jobType string)
  • func (w *WorkerMetrics) SetQueueDepth(queueName string, depth int64)

Examples

• ActivityMetrics.Begin

Constants

const (
	StatusSuccess   = "success"
	StatusError     = "error"
	StatusCancelled = "cancelled"
	StatusTimeout   = "timeout"
)

Status constants for the status label.

Variables

var DefaultDurationBuckets = []float64{
	0.001, 0.002, 0.004, 0.008, 0.016, 0.032, 0.064, 0.128,
	0.256, 0.512, 1.0, 2.0, 4.0, 8.0, 16.0,
}

DefaultDurationBuckets provides exponential buckets from 1ms to 16s. Suitable for most operation durations.

DefaultDurationBuckets fournit des buckets exponentiels de 1ms à 16s. Adapté à la plupart des durées d'opération.

Types

type ActivityMetrics

type ActivityMetrics struct {
	// Total counts operations by activity and status.
	Total *metric.Family[*metric.Counter[uint64]]

	// Errors counts errors by activity and error_type.
	Errors *metric.Family[*metric.Counter[uint64]]

	// Duration tracks operation latency by activity and status, with exemplar support.
	Duration *metric.Family[*metric.Histogram]

	// InFlight tracks concurrent operations by activity.
	InFlight *metric.Family[*metric.Gauge[int64]]
	// contains filtered or unexported fields
}

ActivityMetrics provides RED metrics (Rate, Errors, Duration) plus saturation for generic operation instrumentation.

ActivityMetrics fournit les métriques RED (Rate, Errors, Duration) plus saturation pour l'instrumentation générique d'opérations.

func NewActivityMetrics

func NewActivityMetrics(reg *registry.Registry, cfg Config) (*ActivityMetrics, error)

NewActivityMetrics creates a new ActivityMetrics and registers all families.

NewActivityMetrics crée un nouveau ActivityMetrics et enregistre toutes les familles.

func (*ActivityMetrics) Begin

func (a *ActivityMetrics) Begin(activity string) func(err error)

Begin starts tracking an operation and returns a done function. Call done(err) when the operation completes. Pass nil for success.

Begin démarre le suivi d'une opération et retourne une fonction done. Appelez done(err) quand l'opération se termine. Passez nil pour succès.

Example:

done := metrics.Begin("process_order")
defer done(nil)
// ... do work ...

Example

package main

import (
	"fmt"

	"codeberg.org/nathanaelle/epimetheus/v2/activity"
	"codeberg.org/nathanaelle/epimetheus/v2/registry"
)

func main() {
	reg := registry.New()

	metrics, err := activity.NewActivityMetrics(reg, activity.Config{
		Prefix: "myapp",
	})
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	// Begin returns a done function — always call it (typically via defer)
	done := metrics.Begin("process_order")
	// ... do work ...
	done(nil) // nil = success

	// After one successful operation, the in-flight gauge is back to 0
	inflight, _ := metrics.InFlight.With()
	fmt.Printf("in-flight after done: %d\n", inflight.Value())

}

Output:
in-flight after done: 0

func (*ActivityMetrics) BeginWithTrace

func (a *ActivityMetrics) BeginWithTrace(activity, traceID string) func(err error)

BeginWithTrace starts tracking an operation with trace correlation. The traceID is attached as an exemplar to the duration histogram.

BeginWithTrace démarre le suivi d'une opération avec corrélation de trace. Le traceID est attaché comme exemplar à l'histogramme de durée.

Example:

traceID := trace.SpanFromContext(ctx).SpanContext().TraceID().String()
done := metrics.BeginWithTrace("process_order", traceID)
defer done(nil)

func (*ActivityMetrics) Prune

func (a *ActivityMetrics) Prune() int

Prune removes expired series from all metric families. Returns the total number of series removed.

Prune supprime les séries expirées de toutes les familles de métriques. Retourne le nombre total de séries supprimées.

func (*ActivityMetrics) Record

func (a *ActivityMetrics) Record(activity, status string, duration time.Duration, opErr error)

Record is a low-level method for recording a completed operation. Use Begin/BeginWithTrace for most use cases.

Record est une méthode bas niveau pour enregistrer une opération terminée. Utilisez Begin/BeginWithTrace pour la plupart des cas d'usage.

type Config

type Config struct {
	// Prefix for all metric names (e.g., "myapp" → "myapp_operations_total")
	// Préfixe pour tous les noms de métriques
	Prefix string

	// DurationBuckets for the histogram. Defaults to DefaultDurationBuckets.
	// Buckets pour l'histogramme. Par défaut : DefaultDurationBuckets.
	DurationBuckets []float64

	// TTL for series expiration. 0 disables expiration.
	// TTL pour l'expiration des séries. 0 désactive l'expiration.
	TTL time.Duration

	// ErrorClassifier for custom error classification. Defaults to DefaultClassifier.
	// ErrorClassifier pour une classification personnalisée. Par défaut : DefaultClassifier.
	ErrorClassifier ErrorClassifier

	// Logger for metric recording errors. nil disables logging (default).
	// Logger pour les erreurs d'enregistrement de métriques. nil désactive le logging (défaut).
	Logger *slog.Logger
}

Config configures an ActivityMetrics instance.

Config configure une instance ActivityMetrics.

type ErrorClassifier

type ErrorClassifier interface {
	Classify(err error) string
}

ErrorClassifier classifies errors into error_type labels. Implementations should return a short, lowercase string suitable for use as a Prometheus label value (e.g., "timeout", "not_found", "internal").

ErrorClassifier classifie les erreurs en labels error_type. Les implémentations doivent retourner une chaîne courte en minuscules adaptée à un label Prometheus (ex: "timeout", "not_found", "internal").

var DefaultClassifier ErrorClassifier = ErrorClassifierFunc(classifyError)

DefaultClassifier provides automatic error classification. It recognizes common error patterns:

• context.DeadlineExceeded → "timeout"
• context.Canceled → "cancelled"
• errors containing "panic" → "panic"
• all others → "error"

DefaultClassifier fournit une classification automatique des erreurs. Il reconnaît les patterns d'erreur courants :

• context.DeadlineExceeded → "timeout"
• context.Canceled → "cancelled"
• erreurs contenant "panic" → "panic"
• toutes les autres → "error"

type ErrorClassifierFunc

type ErrorClassifierFunc func(err error) string

ErrorClassifierFunc is a function adapter for ErrorClassifier.

func (ErrorClassifierFunc) Classify

func (f ErrorClassifierFunc) Classify(err error) string

Classify implements ErrorClassifier.

type WorkerConfig

type WorkerConfig struct {
	Config
}

WorkerConfig configures a WorkerMetrics instance. It embeds Config for the underlying ActivityMetrics.

WorkerConfig configure une instance WorkerMetrics. Elle intègre Config pour l'ActivityMetrics sous-jacent.

type WorkerMetrics

type WorkerMetrics struct {
	*ActivityMetrics

	// QueueDepth tracks the number of pending jobs by queue_name.
	QueueDepth *metric.Family[*metric.Gauge[int64]]

	// Retries counts job retry attempts by queue_name and job_type.
	Retries *metric.Family[*metric.Counter[uint64]]
	// contains filtered or unexported fields
}

WorkerMetrics extends ActivityMetrics with queue-specific metrics. It provides instrumentation for job/worker patterns (queues, cron, background tasks).

WorkerMetrics étend ActivityMetrics avec des métriques spécifiques aux queues. Il fournit l'instrumentation pour les patterns job/worker (queues, cron, tâches de fond).

func NewWorkerMetrics

func NewWorkerMetrics(reg *registry.Registry, cfg WorkerConfig) (*WorkerMetrics, error)

NewWorkerMetrics creates a new WorkerMetrics and registers all families.

NewWorkerMetrics crée un nouveau WorkerMetrics et enregistre toutes les familles.

func (*WorkerMetrics) BeginJob

func (w *WorkerMetrics) BeginJob(queueName, jobType string) func(err error)

BeginJob starts tracking a job execution. The activity label is constructed as queueName + "/" + jobType. Ensure neither queueName nor jobType contains "/" to avoid label collisions. A future version may use separate labels.

BeginJob démarre le suivi de l'exécution d'un job. Le label activity est défini à "{queueName}/{jobType}" pour un suivi granulaire.

func (*WorkerMetrics) BeginJobWithTrace

func (w *WorkerMetrics) BeginJobWithTrace(queueName, jobType, traceID string) func(err error)

BeginJobWithTrace starts tracking a job with trace correlation.

BeginJobWithTrace démarre le suivi d'un job avec corrélation de trace.

func (*WorkerMetrics) Prune

func (w *WorkerMetrics) Prune() int

Prune removes expired series from all metric families including worker-specific ones. Returns the total number of series removed.

Prune supprime les séries expirées de toutes les familles y compris celles du worker. Retourne le nombre total de séries supprimées.

func (*WorkerMetrics) RecordRetry

func (w *WorkerMetrics) RecordRetry(queueName, jobType string)

RecordRetry increments the retry counter for a job.

RecordRetry incrémente le compteur de retry pour un job.

func (*WorkerMetrics) SetQueueDepth

func (w *WorkerMetrics) SetQueueDepth(queueName string, depth int64)

SetQueueDepth sets the current queue depth for a named queue.

SetQueueDepth définit la profondeur actuelle de la queue nommée.