Create Metrics Collector

Metrics Collector Generator

Creates metrics collection infrastructure for application observability and monitoring.

When to Use

Component Characteristics

MetricsCollectorInterface

• Metrics contract for increment, gauge, histogram operations
• Backend-agnostic: swap Prometheus for StatsD or custom
• Supports labels for dimensional metrics

Counter

• Monotonically increasing metric wrapper
• Tracks totals: requests, errors, processed items
• Supports labels for per-endpoint counts

Gauge

• Point-in-time value metric wrapper
• Tracks current state: active connections, queue size
• Can increase and decrease

Histogram

• Distribution metric wrapper
• Tracks request duration, response size
• Configurable bucket boundaries

PrometheusMetricsCollector

• Prometheus PHP client adapter
• Registers counters, gauges, histograms
• Thread-safe with shared storage

MetricsMiddleware

• PSR-15 middleware collecting RED metrics automatically
• Rate: total request count per endpoint
• Errors: error count by status code
• Duration: response time histogram

MetricsAction

• /metrics endpoint exposing Prometheus format
• Returns text/plain with all registered metrics

NullMetricsCollector

• Null Object pattern for testing and development
• All operations are no-ops
• Drop-in replacement without side effects

Generation Process

Step 1: Generate Core Components

Path: src/Infrastructure/Metrics/

1. MetricsCollectorInterface.php — Metrics contract
2. Counter.php — Counter metric wrapper
3. Gauge.php — Gauge metric wrapper
4. Histogram.php — Histogram metric wrapper

Step 2: Generate Implementations

Path: src/Infrastructure/Metrics/

1. PrometheusMetricsCollector.php — Prometheus adapter
2. NullMetricsCollector.php — Null Object for testing

Step 3: Generate HTTP Components

Path: src/Infrastructure/Metrics/

1. MetricsMiddleware.php — PSR-15 RED metrics middleware
2. MetricsAction.php — /metrics endpoint action

Step 4: Generate Tests

1. NullMetricsCollectorTest.php — Null object behavior tests
2. MetricsMiddlewareTest.php — Middleware metrics tests

File Placement

Naming Conventions

Quick Template Reference

MetricsCollectorInterface

interface MetricsCollectorInterface
{
    /** @param array<string, string> $labels */
    public function increment(string $name, array $labels = [], float $value = 1.0): void;

    /** @param array<string, string> $labels */
    public function gauge(string $name, float $value, array $labels = []): void;

    /** @param array<string, string> $labels */
    public function histogram(string $name, float $value, array $labels = []): void;
}

MetricsMiddleware

final readonly class MetricsMiddleware implements MiddlewareInterface
{
    public function process(
        ServerRequestInterface $request,
        RequestHandlerInterface $handler
    ): ResponseInterface;
}

NullMetricsCollector

final readonly class NullMetricsCollector implements MetricsCollectorInterface
{
    public function increment(string $name, array $labels = [], float $value = 1.0): void {}
    public function gauge(string $name, float $value, array $labels = []): void {}
    public function histogram(string $name, float $value, array $labels = []): void {}
}

Usage Example

// Middleware auto-collects RED metrics
$middleware = new MetricsMiddleware($collector);

// Manual metrics in use cases
$collector->increment('orders_created_total', ['channel' => 'web']);
$collector->gauge('active_connections', $pool->activeCount());
$collector->histogram('payment_duration_seconds', $elapsed, ['gateway' => 'stripe']);

// Expose via /metrics endpoint
$app->get('/metrics', new MetricsAction($collector));

RED Metrics Pattern

Rate     ──→ http_requests_total{method, path, status}
Errors   ──→ http_requests_total{status=~"5.."}
Duration ──→ http_request_duration_seconds{method, path}

Anti-patterns to Avoid

References

For complete PHP templates and examples, see:

• references/templates.md — MetricsCollectorInterface, Counter, Gauge, Histogram, Prometheus, Middleware templates
• references/examples.md — Integration examples and tests