feat(metrics): add PHP runtime metrics package#645
Open
intuibase wants to merge 7 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.46% 81.17% +0.70%
+ Complexity 1669 1477 -192
============================================
Files 116 103 -13
Lines 6265 5582 -683
============================================
- Hits 5041 4531 -510
+ Misses 1224 1051 -173 Flags with carried forward coverage won't be shown. Click here to find out more.
... and 30 files 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
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
| ->observe(static function (ObserverInterface $observer): void { | ||
| $emalloc = memory_get_usage(false); | ||
| $observer->observe($emalloc, ['memory.type' => 'emalloc']); | ||
| $observer->observe(memory_get_usage(true) - $emalloc, ['memory.type' => 'overhead']); |
Contributor
There was a problem hiding this comment.
Should call memory_get_usage(true) immediately after memory_get_usage(false), calling $observer->observe() might allocate additional memory.
| 'Memory limit configured in php.ini (-1 means unlimited)', | ||
| ) | ||
| ->observe(static function (ObserverInterface $observer): void { | ||
| $limit = ini_get('memory_limit') ?: '-1'; |
Contributor
There was a problem hiding this comment.
I'm learning towards not reporting this value if unlimited to keep avg/min/... aggregations useful.
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
3 participants
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().