metrics

README

Application Metrics

RoadRunner server includes an embedded metrics server based on Prometheus.

Enable Metrics

To enable metrics add metrics section to your configuration:

version: "2.7"

metrics:
  address: localhost:2112

Once complete you can access Prometheus metrics using http://localhost:2112/metrics url.

Make sure to install metrics extension:

composer require spiral/roadrunner-metrics

Application metrics

You can also publish application-specific metrics using an RPC connection to the server. First, you have to register a metric in your configuration file:

version: "2.7"

metrics:
  address: localhost:2112
  collect:
    app_metric_counter:
      type: counter
      help: "Application counter."

To send metric from the application:

$metrics = new Spiral\RoadRunner\Metrics\Metrics(
    Spiral\Goridge\RPC\RPC::create(Spiral\RoadRunner\Environment::fromGlobals()->getRPCAddress())
);

$metrics->add('app_metric_counter', 1);

Supported types: gauge, counter, summary, histogram.

Tagged metrics

You can use tagged (labels) metrics to group values:

version: "2.7"

metrics:
  address: localhost:2112
  collect:
    app_type_duration:
      type: histogram
      help: "Application counter."
      labels: ["label_1", "label_2"]

You should specify values for your labels while pushing the metric:

$metrics = new Spiral\RoadRunner\Metrics\Metrics(
    Spiral\Goridge\RPC\RPC::create(Spiral\RoadRunner\Environment::fromGlobals()->getRPCAddress())
);
/**
 * @var array<array-key, string>
 */
$labels = ['label_1_value', 'label_2_value'];

$metrics->add('app_type_duration', 0.5, $labels);

Declare metrics

You can declare metric from PHP application itself:

$metrics->declare(
    'test',
    Spiral\RoadRunner\Metrics\Collector::counter()->withHelp('Test counter')
);

Documentation

Index

• Constants
• type Collector
• type CollectorType
• type Config
  • func (c *Config) InitDefaults()
• type Configurer
• type Metric
• type NamedCollector
• type Plugin
  • func (p *Plugin) AddStatProvider(stat StatProvider) error
  • func (p *Plugin) Collects() []any
  • func (p *Plugin) Init(cfg Configurer, log *zap.Logger) error
  • func (p *Plugin) Name() string
  • func (p *Plugin) RPC() any
  • func (p *Plugin) Register(c prometheus.Collector) error
  • func (p *Plugin) Serve() chan error
  • func (p *Plugin) Stop() error
• type StatProvider

Constants

const (
	// PluginName declares plugin name.
	PluginName = "metrics"
)

Types

type Collector

type Collector struct {
	// Namespace of the metric.
	Namespace string `json:"namespace,omitempty"`
	// Subsystem of the metric.
	Subsystem string `json:"subsystem,omitempty"`
	// Collector type (histogram, gauge, counter, summary).
	Type CollectorType `json:"type"`
	// Help of collector.
	Help string `json:"help"`
	// Labels for vectorized metrics.
	Labels []string `json:"labels"`
	// Buckets for histogram metric.
	Buckets []float64 `json:"buckets"`
	// Objectives for the summary opts
	Objectives map[float64]float64 `json:"objectives,omitempty"`
}

Collector describes single application specific metric.

type CollectorType

type CollectorType string

CollectorType represents prometheus collector types

const (
	// Histogram type
	Histogram CollectorType = "histogram"

	// Gauge type
	Gauge CollectorType = "gauge"

	// Counter type
	Counter CollectorType = "counter"

	// Summary type
	Summary CollectorType = "summary"
)

type Config

type Config struct {
	// Address to listen
	Address string `mapstructure:"address"`

	// Collect define application specific metrics.
	Collect map[string]Collector `mapstructure:"collect"`
}

Config configures metrics service.

func (*Config) InitDefaults

func (c *Config) InitDefaults()

type Configurer

type Configurer interface {
	// UnmarshalKey takes a single key and unmarshal it into a Struct.
	UnmarshalKey(name string, out any) error

	// Has checks if config section exists.
	Has(name string) bool
}

type Metric

type Metric struct {
	// Collector name.
	Name string `msgpack:"alias:name"`

	// Collector value.
	Value float64 `msgpack:"alias:value"`

	// Labels associated with metric. Only for vector metrics. Must be provided in a form of label values.
	Labels []string `msgpack:"alias:labels"`
}

Metric represent single metric produced by the application.

type NamedCollector

type NamedCollector struct {
	// Name of the collector
	Name string `json:"name"`

	// Collector structure
	Collector `json:"collector"`
}

type Plugin

type Plugin struct {
	// contains filtered or unexported fields
}

Plugin to manage application metrics using Prometheus.

func (*Plugin) AddStatProvider

func (p *Plugin) AddStatProvider(stat StatProvider) error

AddStatProvider adds a metrics provider

func (*Plugin) Collects

func (p *Plugin) Collects() []any

Collects used to collect all plugins which implement metrics.StatProvider interface (and Named)

func (*Plugin) Init

func (p *Plugin) Init(cfg Configurer, log *zap.Logger) error

Init service.

func (*Plugin) Name

func (p *Plugin) Name() string

Name returns user friendly plugin name

func (*Plugin) RPC

func (p *Plugin) RPC() any

RPC interface satisfaction

func (*Plugin) Register

func (p *Plugin) Register(c prometheus.Collector) error

Register new prometheus collector.

func (*Plugin) Serve

func (p *Plugin) Serve() chan error

Serve prometheus metrics service.

func (*Plugin) Stop

func (p *Plugin) Stop() error

Stop prometheus metrics service.

type StatProvider

type StatProvider interface {
	MetricsCollector() []prometheus.Collector
}

StatProvider used to collect all plugins which might report to the prometheus