Add first-party OpenTelemetry support (opentelemetry extension + PHP_OPENTELEMETRY_* env vars)

[aagjalpankaj]

👉 Describe the problem

There is currently no first-party way to instrument an application running on serversideup/php with OpenTelemetry, and the workarounds that people reach for fight the image's architecture.

The common approach — running a vendor APM agent as a sidecar process inside the container — collides directly with S6 Overlay. This is not hypothetical: #292 (Datadog APM on Google Cloud Run) shows a user hitting s6-overlay-suexec: fatal: can only run as pid 1 while trying to instrument 8.1-fpm-nginx, and a second user reporting the same failure and having to install the agent through a custom S6 oneshot service with a runtime-only API key.

OpenTelemetry avoids that entire problem class, because the PHP implementation is in-process: a PHP extension plus Composer packages. There is no second process, no PID 1 conflict, and nothing for S6 Overlay to argue with. But today the extension is not present in any image, so every user who wants it has to discover install-php-extensions, write a custom Dockerfile, and work out the correct configuration themselves.

👥 Problem evidence & reach

Concrete evidence in this repository:

• #292 — two separate users unable to get APM/tracing working because of the S6 Overlay interaction.

I want to be straight about in-repo demand: OpenTelemetry specifically has not been requested here before, and this is the first discussion about it. The reach argument is mostly external.

Evidence of reach in the wider PHP/Laravel ecosystem (Packagist download counts, at time of writing):

Package	Total downloads	Downloads / month
open-telemetry/exporter-otlp	26,560,853	1,949,935
open-telemetry/opentelemetry-auto-laravel	3,420,048	340,186
open-telemetry/opentelemetry	1,523,408	84,627

The Laravel auto-instrumentation package alone is pulled ~340k times a month. Given this project describes itself as optimized for Laravel, that is the population most likely to want this.

OpenTelemetry is also the vendor-neutral CNCF standard, so supporting it serves Datadog, New Relic, Grafana, Honeycomb, Signoz, Jaeger and self-hosted collector users with one implementation, rather than the project ever needing to take a position on a specific APM vendor.

🏆 How to solve this problem

Ship the opentelemetry extension in the images, expose its INI directives through the existing PHP_* environment variable convention, and document the setup. Defaults stay exactly as they are today, so nothing changes for existing users until someone opts in by installing the Composer SDK.

Detail 1 — Install the extension, guarded to PHP 8.x

The extension requires PHP 8.0+. I verified that install-php-extensions opentelemetry fails on PHP 7.4 (pecl/opentelemetry requires PHP (version >= 8.0.0), installed version is 7.4.33 → install failed), so it cannot simply be appended to the shared DEPENDENCY_PHP_EXTENSIONS list — that would break every 7.4 build.

• Add a separate DEPENDENCY_PHP_EXTENSIONS_PHP8='opentelemetry' build ARG
• Install it behind a case "${PHP_VERSION}" in 8.*) guard, so 7.4 images are untouched
• Note: ARG PHP_VERSION is currently declared only before the first FROM in all five variation Dockerfiles. Because Docker global ARGs do not carry into build stages, it must be re-declared inside the stage or the guard would silently skip on every version

Detail 2 — Expose configuration via the existing PHP_* convention

The extension exposes a small set of INI directives. Four are worth surfacing, each defaulting to the upstream value:

Environment variable	Default	Purpose
PHP_OPENTELEMETRY_ATTR_HOOKS_ENABLED	0	Enables #[WithSpan] attribute instrumentation
PHP_OPENTELEMETRY_ALLOW_STACK_EXTENSION	0	Required by some multi-hook SDK setups
PHP_OPENTELEMETRY_VALIDATE_HOOK_FUNCTIONS	1	Matches upstream default
PHP_OPENTELEMETRY_DISPLAY_WARNINGS	0	Debugging aid

These would live in serversideup-docker-php.ini alongside the other module sections. There is precedent for this: that file already carries an [intl] section even though intl is not installed by default, and PHP silently ignores INI directives belonging to an unloaded extension — so the block is harmless on 7.4.

Detail 3 — What this deliberately does not include

Keeping the image lean is the point, so the scope stops well short of "bundle observability":

• ❌ grpc — not included. OTLP export over HTTP+protobuf does not need it, and it is by far the largest cost (see measurements below)
• ❌ protobuf — not included. It is an application-level performance choice
• ❌ open-telemetry/* Composer packages — these belong in the application, not the image
• ❌ Spec-defined OTEL_* variables (OTEL_SERVICE_NAME, OTEL_EXPORTER_OTLP_ENDPOINT, …) — deliberately not set. The SDK reads these from the environment itself; baking in defaults would silently override user intent and break spec compliance. They should be documented, not set

Measured image size impact

Given that intl is excluded from these images specifically because it costs ~40 MB, I measured the actual cost before proposing this. Built locally from the published 8.4-cli images on linux/arm64:

Image	Size	Delta
serversideup/php:8.4-cli (baseline)	528.42 MB	—
+ opentelemetry	528.62 MB	+0.20 MB
+ opentelemetry protobuf	529.09 MB	+0.66 MB
+ opentelemetry protobuf grpc	544.63 MB	+16.20 MB
serversideup/php:8.4-cli-alpine (baseline)	112.75 MB	—
+ opentelemetry	113.02 MB	+0.27 MB (+0.24%)
+ opentelemetry protobuf	113.48 MB	+0.74 MB (+0.65%)
+ opentelemetry protobuf grpc	130.02 MB	+17.27 MB (+15.32%)

The extension on its own costs ~200–270 KB, roughly 1/150th of what excluded intl.

The grpc rows are the reason it is explicitly out of scope. On Alpine it would inflate the image by 15.32% — 64× the cost of the OpenTelemetry extension itself — for a transport that OTLP over HTTP+protobuf does not require. Users who genuinely need OTLP/gRPC can still add it in their own Dockerfile; everyone else should not pay for it.

🥰 Describe the "impact" on users?

• Instrumentation stops fighting the container. Users get tracing without a sidecar agent, which is the specific failure in #292
• Zero config to enable, consistent with the project's philosophy. Add the Composer packages, set the standard OTEL_* variables, done — no custom Dockerfile and no rebuild
• Vendor-neutral. One implementation serves every OTLP-compatible backend, so the project never has to bless a particular APM vendor
• No cost to anyone who does not use it. Defaults are unchanged and the extension stays inert until the application installs the SDK. The size cost is ~0.04% (Debian) / ~0.24% (Alpine)
• 7.4 users are unaffected, by design

💯 How do we validate the problem is solved?

1. Builds stay green across the matrix. Build all five variations against 7.4 (Debian), 8.0 (Alpine), 8.4 (Debian) and 8.5 (Alpine) via scripts/dev.sh. Assert 7.4 still builds and does not contain the extension; assert 8.x does
2. No behavior change by default. php --ri opentelemetry on a stock 8.x image reports the extension present with upstream defaults, and an app with no OTel Composer packages behaves identically to today
3. Env vars actually take effect. Setting PHP_OPENTELEMETRY_ATTR_HOOKS_ENABLED=1 is reflected in php --ri opentelemetry
4. End-to-end trace export. Run a Laravel app with open-telemetry/opentelemetry-auto-laravel against a local OTel Collector and confirm spans arrive — with no custom Dockerfile and no sidecar
5. Size stays within budget. Confirm the measured delta holds in CI-built images

---

I have measured the size impact and verified the PHP 7.4 and ARG scoping constraints described above, and I am happy to do the implementation work and open the PR if there is appetite for it. Wanted to follow the process in #66 and check for interest first.