spiral / roadrunner-metrics

3.4.0 2026-10-10 13:02 UTC

Requires

• php: >=8.2
• psr/log: ^2.0 || ^3.0
• roadrunner/goridge: ^4.5
• spiral/roadrunner: ^3.0

Requires (Dev)

• jetbrains/phpstorm-attributes: ^1.0
• mockery/mockery: ^1.6
• spiral/code-style: ^2.3.1
• testo/bridge-mockery: ^0.1.2
• testo/testo: ^0.10.55
• vimeo/psalm: ^6 || ^7

Suggests

• roadrunner/cli: Provides RoadRunner installation and management CLI tools

Replaces

• spiral/roadrunner-metrics: 3.4.0

MIT

• Anton Titov
• Pavel Buchnev
• Aleksei Gagarin
• Maksim Smakouz
• Kirill Nesmeyanov
• RoadRunner Community

• rpc
• Metrics
• prometheus
• roadrunner
• observability

Published on Packagist.org on 2026-10-10 13:02 UTC

README

Prometheus metrics for PHP workers via RoadRunner RPC

PHP client for the RoadRunner metrics plugin. It lets application workers declare Prometheus collectors and publish values to them over RPC.

Get Started

Installation

composer require roadrunner/metrics

The package requires PHP 8.2+ and RoadRunner v3. You can use the convenient installer to download the latest available compatible version of RoadRunner assembly:

composer require roadrunner/cli --dev
vendor/bin/rr get

Configuration

Enable metrics service in your .rr.yaml file:

rpc:
    listen: tcp://127.0.0.1:6001

server:
    command: "php worker.php"

http:
    address: "0.0.0.0:8080"

metrics:
    address: "0.0.0.0:2112"

See the metrics plugin documentation for all options.

Usage

To publish metrics from your application worker:

<?php

declare(strict_types=1);

use Nyholm\Psr7\Factory\Psr17Factory;
use Nyholm\Psr7\Response;
use Spiral\Goridge\RPC\RPC;
use Spiral\RoadRunner;
use Spiral\RoadRunner\Metrics\Collector;
use Spiral\RoadRunner\Metrics\Metrics;

include 'vendor/autoload.php';

$factory = new Psr17Factory();
$worker = new RoadRunner\Http\PSR7Worker(RoadRunner\Worker::create(), $factory, $factory, $factory);

# Create metrics client
$metrics = new Metrics(
    RPC::create(RoadRunner\Environment::fromGlobals()->getRPCAddress()),
);

# Declare counter
$metrics->declare(
    'http_requests',
    Collector::counter()
        ->withHelp('Collected HTTP requests.')
        ->withLabels('status', 'method'),
);

while ($request = $worker->waitRequest()) {
    try {
        $response = new Response();
        $response->getBody()->write('hello world');

        # Publish metrics for each request with labels (status, method)
        $metrics->add('http_requests', 1, [
            (string) $response->getStatusCode(),
            $request->getMethod(),
        ]);

        $worker->respond($response);
    } catch (\Throwable $e) {
        $worker->getWorker()->error((string) $e);

        $metrics->add('http_requests', 1, ['503', $request->getMethod()]);
    }
}

Collectors are created with Collector::counter(), Collector::gauge(), Collector::histogram(...$buckets) and Collector::summary(); values are published with add(), sub(), set() and observe().

Retries and error suppression

MetricsFactory wraps the client according to MetricsOptions: it retries failed calls (3 attempts by default), can suppress and log exceptions, and can skip waiting for RPC responses when given an AsyncRPCInterface:

use Spiral\RoadRunner\Metrics\MetricsFactory;
use Spiral\RoadRunner\Metrics\MetricsOptions;

$metrics = MetricsFactory::createMetrics(
    $rpc,
    new MetricsOptions(
        retryAttempts: 3,
        retrySleepMicroseconds: 50,
        suppressExceptions: true,
        ignoreResponsesWherePossible: true,
    ),
    $logger, // any PSR-3 logger
);