README

This is a read-only subtree split of https://github.com/open-telemetry/opentelemetry-php-contrib.

OpenTelemetry PHP Runtime Metrics

Collects PHP runtime metrics — memory, garbage collection, OPcache, and CPU usage — and exposes them as OpenTelemetry observable instruments.

Requirements

• PHP 8.1+
• OpenTelemetry API

Installation

composer require open-telemetry/opentelemetry-metrics-runtime

Usage

Automatic (recommended)

The package registers itself via SPI as an Instrumentation. When the OpenTelemetry SDK calls SdkAutoloader::autoload(), metrics are registered automatically with the configured MeterProvider. No additional code is required.

OTEL_PHP_AUTOLOAD_ENABLED=true
OTEL_METRICS_EXPORTER=otlp
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318

Manual

If you need to control when metrics are registered:

use OpenTelemetry\Contrib\Metrics\Runtime\RuntimeMetrics;
use OpenTelemetry\Contrib\Metrics\Runtime\RuntimeMetricsConfig;

RuntimeMetrics::register($meterProvider);

// Optionally, disable individual groups (memory, gc, opcache, cpu):
RuntimeMetrics::register($meterProvider, new RuntimeMetricsConfig(disabled: ['opcache', 'cpu']));

Metrics

Memory (memory)

Garbage Collection (gc)

OPcache (opcache)

Registered only when OPcache is enabled (opcache.enable=1). In CLI context, also requires opcache.enable_cli=1.

CPU (cpu)

Registered only on platforms where getrusage() is available (Linux, macOS, Windows).

Configuration

Disable the entire package

OTEL_PHP_DISABLED_INSTRUMENTATIONS=metrics-runtime

Disable individual metric groups

Option 1: via OTEL_PHP_DISABLED_INSTRUMENTATIONS — lightweight, no config file needed. Each group is addressed as metrics-runtime-{group}:

# Disable OPcache and CPU metrics only
OTEL_PHP_DISABLED_INSTRUMENTATIONS=metrics-runtime-opcache,metrics-runtime-cpu

# Disable GC metrics only
OTEL_PHP_DISABLED_INSTRUMENTATIONS=metrics-runtime-gc

Option 2: via OTEL_CONFIG_FILE — standard OTel SDK configuration, supports fine-grained control (e.g. filtering by attributes). Each group uses its own meter named io.opentelemetry.contrib.php.runtime.{group}, which can be targeted with meter configurators or views:

# otel-config.yaml
meter_provider:
  views:
    - selector:
        meter_name: io.opentelemetry.contrib.php.runtime.opcache
      stream:
        aggregation:
          drop:

OTEL_CONFIG_FILE=/path/to/otel-config.yaml

Maintainer

@intuibase