Documentation
¶
Overview ¶
Package pool provides a thread-safe registry for managing Prometheus metrics.
This package offers a centralized way to store, retrieve, and manage Prometheus metrics throughout an application lifecycle. It provides automatic registration, de-registration, and lifecycle management of metrics.
Basic Usage ¶
Creating a pool and adding metrics:
pool := pool.New(contextFunc)
metric := metrics.NewMetrics("http_requests_total", types.Counter)
metric.SetDesc("Total HTTP requests")
metric.AddLabel("method", "status")
metric.SetCollect(func(ctx context.Context, m metrics.Metric) {
// Custom collection logic
})
err := pool.Add(metric)
if err != nil {
log.Fatal(err)
}
Thread Safety ¶
All pool operations are thread-safe and can be called concurrently from multiple goroutines. The pool uses github.com/nabbar/golib/context for internal storage.
For more details on metrics, see: https://github.com/nabbar/golib/tree/main/prometheus/metrics For context management, see: https://github.com/nabbar/golib/tree/main/context
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type FuncAdd ¶
FuncAdd is a function type for adding a metric to a collection. Returns an error if the metric cannot be added.
type FuncGet ¶
FuncGet is a function type for retrieving a metric by name. This is typically used for custom metric access patterns.
type FuncWalk ¶
type FuncWalk func(pool MetricPool, key string, val libmet.Metric) bool
FuncWalk is a function type for iterating over metrics in the pool. The function receives the pool reference, metric key, and metric value. Return false to stop the iteration early, true to continue.
type MetricPool ¶
type MetricPool interface {
// Get retrieves a metric by its name from the pool.
//
// Returns nil if the metric doesn't exist or if the stored value
// is not a valid Metric instance.
//
// Thread-safe: can be called concurrently from multiple goroutines.
Get(name string) libmet.Metric
// Add registers a new metric in the pool and with Prometheus.
//
// This method performs several validation checks:
// - The metric name cannot be empty
// - The metric must have a collection function set
// - The metric must be successfully registered with Prometheus
//
// If any validation fails, an error is returned and the metric is not added.
//
// Returns an error if:
// - The metric name is empty
// - The collect function is nil
// - Prometheus registration fails (e.g., duplicate metric name)
//
// Thread-safe: can be called concurrently from multiple goroutines.
Add(metric libmet.Metric) error
// Set directly stores a metric in the pool without validation or registration.
//
// Unlike Add, this method:
// - Does not validate the metric
// - Does not register the metric with Prometheus
// - Allows using a key different from the metric name
// - Can replace an existing metric at the same key
//
// Use Add for normal metric registration. Use Set for advanced scenarios
// where you need custom keys or manual registration control.
//
// Thread-safe: can be called concurrently from multiple goroutines.
Set(key string, metric libmet.Metric)
// Del removes a metric from the pool and unregisters it from Prometheus.
//
// If the metric exists, it will be:
// - Removed from the pool
// - Unregistered from Prometheus registry
//
// This is a no-op if the metric doesn't exist or is not a valid Metric.
//
// Thread-safe: can be called concurrently from multiple goroutines.
Del(key string) error
// List returns a slice containing the names of all metrics in the pool.
//
// The returned slice is a snapshot at the time of the call and will not
// reflect subsequent changes to the pool.
//
// Returns an empty slice (never nil) if the pool is empty.
//
// Thread-safe: can be called concurrently from multiple goroutines.
List() []string
// Walk iterates over metrics in the pool, calling the provided function for each.
//
// The iteration continues until either:
// - All metrics have been visited
// - The function returns false
// - All specified limit keys have been visited (if limit is provided)
//
// Parameters:
// - fct: Function to call for each metric
// - limit: Optional list of specific metric keys to visit
//
// Returns true if all metrics were visited, false if stopped early.
//
// Thread-safe: can be called concurrently from multiple goroutines.
//
// Example:
//
// // Visit all metrics
// pool.Walk(func(p MetricPool, key string, val libmet.Metric) bool {
// fmt.Printf("Metric: %s, Type: %s\n", key, val.GetType())
// return true
// })
//
// // Visit only specific metrics
// pool.Walk(func(p MetricPool, key string, val libmet.Metric) bool {
// val.Collect(context.Background())
// return true
// }, "metric1", "metric2")
Walk(fct FuncWalk, limit ...string)
// Clear removes all metrics from the pool and unregisters them from Prometheus.
//
// This method iterates through all metrics in the pool, unregisters each one
// from the Prometheus registry, and then removes it from the pool.
//
// Returns a slice of errors encountered during unregistration. An empty slice
// indicates all metrics were successfully cleared.
//
// Use cases:
// - Cleaning up before application shutdown
// - Resetting metrics between test runs
// - Clearing metrics when reconfiguring monitoring
//
// Thread-safe: can be called concurrently from multiple goroutines.
//
// Example:
//
// errors := pool.Clear()
// if len(errors) > 0 {
// for _, err := range errors {
// log.Printf("Error clearing metric: %v", err)
// }
// }
Clear() []error
}
MetricPool is the interface for managing a collection of Prometheus metrics.
It provides thread-safe operations for storing, retrieving, and managing metrics throughout the application lifecycle. All methods are safe for concurrent use.
Example (Lifecycle) ¶
ExampleMetricPool_lifecycle demonstrates the full lifecycle of metrics in a pool.
package main
import (
"context"
"fmt"
prmmet "github.com/nabbar/golib/prometheus/metrics"
prmpool "github.com/nabbar/golib/prometheus/pool"
prmtps "github.com/nabbar/golib/prometheus/types"
prmsdk "github.com/prometheus/client_golang/prometheus"
)
func main() {
pool := prmpool.New(context.Background(), prmsdk.NewRegistry())
// 1. Create a metric
counter := prmmet.NewMetrics("http_requests", prmtps.Counter)
counter.SetDesc("HTTP request counter")
counter.AddLabel("method")
counter.SetCollect(func(ctx context.Context, m prmmet.Metric) {})
// 2. Add to pool (automatically registers)
if err := pool.Add(counter); err != nil {
fmt.Printf("Add failed: %v\n", err)
return
}
fmt.Println("1. Metric added")
// 3. Retrieve and use
m := pool.Get("http_requests")
if m != nil {
fmt.Println("2. Metric retrieved")
}
// 4. List all metrics
fmt.Printf("3. Pool contains %d metrics\n", len(pool.List()))
// 5. Clean up when done
pool.Del("http_requests")
fmt.Println("4. Metric removed")
}
Output: 1. Metric added 2. Metric retrieved 3. Pool contains 1 metrics 4. Metric removed
func New ¶
func New(ctx context.Context, reg prmsdk.Registerer) MetricPool
New creates a new MetricPool instance.
The pool uses the provided context function for internal storage management. The context function should return a valid context that will be used throughout the pool's lifetime.
Parameters:
- ctx: Function that returns the context for the pool
Returns a new MetricPool ready to use.
Example:
pool := pool.New(func() context.Context {
return context.Background()
})
Example ¶
ExampleNew demonstrates creating a new metric pool.
package main
import (
"context"
"fmt"
prmpool "github.com/nabbar/golib/prometheus/pool"
prmsdk "github.com/prometheus/client_golang/prometheus"
)
func main() {
// Create a new pool
pool := prmpool.New(context.Background(), prmsdk.NewRegistry())
if pool != nil {
fmt.Println("Pool created successfully")
}
}
Output: Pool created successfully
Source Files