feat(metrics): add PHP runtime metrics package#645
Open
intuibase wants to merge 12 commits into
Open
Conversation
Adds open-telemetry/opentelemetry-metrics-runtime — a new contrib package that auto-registers OTel observable instruments for PHP runtime internals: memory usage/peak/limit, garbage collection stats (including PHP 8.3+ timing fields), OPcache memory and hit-rate, and CPU time via getrusage(). - Disable entire package: OTEL_PHP_DISABLED_INSTRUMENTATIONS=metrics-runtime - Disable metric groups: OTEL_PHP_DISABLED_METRICS=opcache,cpu - OPcache and CPU metrics are skipped when underlying functions are unavailable - Supports PHP 8.1–8.5; phan stub created via post-install-cmd on PHP 8.5+
Codecov Report❌ Patch coverage is Additional details and impacted files@@ Coverage Diff @@
## main #645 +/- ##
============================================
+ Coverage 80.72% 81.02% +0.30%
- Complexity 1446 1466 +20
============================================
Files 95 102 +7
Lines 5343 5508 +165
============================================
+ Hits 4313 4463 +150
- Misses 1030 1045 +15 Flags with carried forward coverage won't be shown. Click here to find out more.
... and 1 file with indirect coverage changes Continue to review full report in Codecov by Harness.
🚀 New features to boost your workflow:
|
Nevay
reviewed
Jun 29, 2026
- Use batchObserve() in CpuMetrics, GarbageCollectionMetrics and
OpcacheMetrics so getrusage()/gc_status()/opcache_get_status() are
called only once per collection cycle
- Handle missing ru_nvcsw/ru_nivcsw keys on OSes that omit them (macOS)
- Fix instrument units to singular form per OTel semconv: {run},
{object}, {switch}, {hit}, {miss}, {script}, {string}
- Replace custom parseMemoryLimit() with ini_parse_quantity(); add
symfony/polyfill-php82 to support PHP 8.1
- Register via Instrumentation SPI instead of autoload.files so metrics
are registered after SdkAutoloader initialises Globals; remove
_register.php
- Use separate meters per group (io.opentelemetry.contrib.php.runtime.
{group}) to allow disabling via OTEL_CONFIG_FILE meter configurators
or views; keep OTEL_PHP_DISABLED_METRICS as a lightweight fallback
- Depend on open-telemetry/api ^1.1 instead of sdk; move sdk to
require-dev
Contributor
Author
|
Thanks for the thorough review @Nevay! All points addressed. |
ChrisLightfootWild
left a comment
Contributor
There was a problem hiding this comment.
Awesome stuff.
Could we add a .gitattributes also to this package? 💪
Nevay
reviewed
Jul 5, 2026
- Only observe ru_nvcsw/ru_nivcsw when getrusage() actually reports them (absent on some OSes) instead of defaulting to 0 - Merge voluntary/involuntary context switches into the standard process.context_switches metric with a process.context_switch.type attribute, so it stays meaningful when that attribute is dropped - Split memory usage into additive emalloc/overhead components instead of overlapping real/emalloc values, for the same reason - Mark per-group metric classes as @internal - Drop the process.runtime. prefix from PHP-specific metrics per the runtime metrics semantic conventions - Pass an instrumentation version to each meter via InstalledVersions - Add a _register.php fallback (via ServiceLoader::register()) so the instrumentation still registers when the tbachert/spi composer plugin is not allowed to run
…TATIONS Reuse the standard OTEL_PHP_DISABLED_INSTRUMENTATIONS env var (metrics-runtime-memory/-gc/-opcache/-cpu, or metrics-runtime/all for everything) instead of the ad-hoc OTEL_PHP_DISABLED_METRICS variable.
Nevay
reviewed
Jul 6, 2026
Avoid measuring emalloc/real memory usage across observer.observe() calls, which could allocate memory and skew the overhead calculation. Skip reporting php.memory.limit when unlimited to keep avg/min aggregations meaningful.
Co-authored-by: Chris Lightfoot-Wild <github-clw@wild.me.uk>
…meMetrics::register()
Follows the experimental split from PR open-telemetry#634: give Metrics/Runtime its own path-filtered workflow calling php-contrib.yml and drop it from the monolithic php.yml matrix.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds open-telemetry/opentelemetry-metrics-runtime — a new contrib package that auto-registers OTel observable instruments for PHP runtime internals: memory usage/peak/limit, garbage collection stats (including PHP 8.3+ timing fields), OPcache memory and hit-rate, and CPU time via getrusage().