prometheus

Prometheus Adapter

Prometheus implementations of the metrics interfaces for all three clstr pillars (ES, Actor, Cluster).

Overview

This adapter provides production-ready Prometheus metrics for observing your clstr-based applications. All metrics follow Prometheus naming conventions and use appropriate metric types (Counter, Gauge, Histogram).

Import

import promadapter "github.com/codewandler/clstr-go/adapters/prometheus"

Quick Start

Combined Usage (Recommended)

When using all three pillars together:

import (
    "github.com/prometheus/client_golang/prometheus"
    promadapter "github.com/codewandler/clstr-go/adapters/prometheus"
)

// Create metrics for all pillars at once
metrics := promadapter.NewAllMetrics(prometheus.DefaultRegisterer)

// Use with ES
env := es.NewEnv(
    es.WithMetrics(metrics.ES),
    // ... other options
)

// Use with Actor
a := actor.New(actor.Options{
    Metrics: metrics.Actor,
    // ... other options
}, handler)

// Use with Cluster
client, _ := cluster.NewClient(cluster.ClientOptions{
    Metrics: metrics.Cluster,
    // ... other options
})

node := cluster.NewNode(cluster.NodeOptions{
    Metrics: metrics.Cluster,
    // ... other options
})

Standalone Usage

For using individual pillars:

// ES only
esMetrics := promadapter.NewESMetrics(prometheus.DefaultRegisterer)
env := es.NewEnv(es.WithMetrics(esMetrics), ...)

// Actor only
actorMetrics := promadapter.NewActorMetrics(prometheus.DefaultRegisterer)
a := actor.New(actor.Options{Metrics: actorMetrics, ...}, handler)

// Cluster only
clusterMetrics := promadapter.NewClusterMetrics(prometheus.DefaultRegisterer)
client, _ := cluster.NewClient(cluster.ClientOptions{Metrics: clusterMetrics, ...})

Custom Registry

For isolated metric registries (useful in tests):

reg := prometheus.NewRegistry()
metrics := promadapter.NewAllMetrics(reg)

// Expose via HTTP
http.Handle("/metrics", promhttp.HandlerFor(reg, promhttp.HandlerOpts{}))

ES Metrics

Actor Metrics

Cluster Metrics

Transport Error Types:

• no_subscriber — No handler registered for shard
• timeout — Handler exceeded deadline
• ttl_expired — Request TTL exceeded before processing
• closed — Transport was closed

Histogram Buckets

All duration histograms use the following bucket boundaries (in seconds):

.001, .0025, .005, .01, .025, .05, .1, .25, .5, 1, 2.5, 5, 10

These buckets are optimized for typical microservice latencies, covering sub-millisecond to multi-second operations.

Example: Full Application

package main

import (
    "context"
    "log/slog"
    "net/http"

    "github.com/prometheus/client_golang/prometheus"
    "github.com/prometheus/client_golang/prometheus/promhttp"

    promadapter "github.com/codewandler/clstr-go/adapters/prometheus"
    "github.com/codewandler/clstr-go/core/actor/v2"
    "github.com/codewandler/clstr-go/core/cluster"
    "github.com/codewandler/clstr-go/core/es"
)

func main() {
    ctx := context.Background()

    // Initialize Prometheus metrics
    metrics := promadapter.NewAllMetrics(prometheus.DefaultRegisterer)

    // Expose metrics endpoint
    http.Handle("/metrics", promhttp.Handler())
    go http.ListenAndServe(":9090", nil)

    // Create ES environment with metrics
    env := es.NewEnv(
        es.WithInMemory(),
        es.WithMetrics(metrics.ES),
        es.WithAggregates(&MyAggregate{}),
    )
    env.Start()
    defer env.Shutdown()

    // Create actor with metrics
    a := actor.TypedHandlers(
        actor.HandleMsg[MyMessage](handleMessage),
    ).ToActor(actor.Options{
        Context: ctx,
        Metrics: metrics.Actor,
    })

    // Create cluster with metrics
    tr := cluster.NewInMemoryTransport()
    client, _ := cluster.NewClient(cluster.ClientOptions{
        Transport: tr,
        NumShards: 256,
        Metrics:   metrics.Cluster,
    })

    // ... use env, actor, client
}

Grafana Dashboards

Example PromQL queries for building dashboards:

# Request rate by message type
rate(clstr_cluster_requests_total[5m])

# P99 latency for repository saves
histogram_quantile(0.99, rate(clstr_es_repo_save_duration_seconds_bucket[5m]))

# Actor message processing rate
sum(rate(clstr_actor_messages_total[5m])) by (message_type)

# Consumer lag
clstr_es_consumer_lag

# Error rate
rate(clstr_cluster_requests_total{success="false"}[5m])
  / rate(clstr_cluster_requests_total[5m])

Zero-Overhead Default

When no metrics are provided, all pillars use a no-op implementation with zero overhead. This means you can optionally enable metrics without any performance impact when disabled.