From bdd8b188184f03d1137a3f6766e34421ba0768c0 Mon Sep 17 00:00:00 2001
From: ToshY <31921460+ToshY@users.noreply.github.com>
Date: Sun, 5 Jul 2026 12:40:17 +0200
Subject: [PATCH] seperate otel from otel-grpc due to condition causing mutex
 corruption when grpc is enabled

---
 .github/workflows/security.yml |  8 ++++
 Dockerfile                     | 16 +++++++-
 docker-bake.hcl                |  4 +-
 docs/images.md                 | 67 +++++++++++++++++++++++++++++++---
 4 files changed, 86 insertions(+), 9 deletions(-)

diff --git a/.github/workflows/security.yml b/.github/workflows/security.yml
index 2404c3b..0456792 100644
--- a/.github/workflows/security.yml
+++ b/.github/workflows/security.yml
@@ -32,6 +32,14 @@ jobs:
           - ghcr.io/toshy/php:8.3-fpm-trixie-otel-ffmpeg
           - ghcr.io/toshy/php:8.4-fpm-trixie-otel-ffmpeg
           - ghcr.io/toshy/php:8.5-fpm-trixie-otel-ffmpeg
+          - ghcr.io/toshy/php:8.2-fpm-trixie-otel-grpc
+          - ghcr.io/toshy/php:8.3-fpm-trixie-otel-grpc
+          - ghcr.io/toshy/php:8.4-fpm-trixie-otel-grpc
+          - ghcr.io/toshy/php:8.5-fpm-trixie-otel-grpc
+          - ghcr.io/toshy/php:8.2-fpm-trixie-otel-grpc-ffmpeg
+          - ghcr.io/toshy/php:8.3-fpm-trixie-otel-grpc-ffmpeg
+          - ghcr.io/toshy/php:8.4-fpm-trixie-otel-grpc-ffmpeg
+          - ghcr.io/toshy/php:8.5-fpm-trixie-otel-grpc-ffmpeg
     steps:
       - name: Scan for vulnerabilities
         uses: crazy-max/ghaction-container-scan@a0a3900b79d158c85ccf034e5368fae620a9233a # v4.0.0
diff --git a/Dockerfile b/Dockerfile
index 543687d..d3ff35c 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -74,10 +74,16 @@ EOT
 RUN <<EOT sh
   set -ex
   install-php-extensions opentelemetry \
-    grpc \
     protobuf
 EOT
 
+FROM otel AS otel-grpc
+
+RUN <<EOT sh
+  set -ex
+  install-php-extensions grpc
+EOT
+
 FROM common AS otel-ffmpeg
 
 # hadolint ignore=DL3008
@@ -97,6 +103,12 @@ EOT
 RUN <<EOT sh
   set -ex
   install-php-extensions opentelemetry \
-    grpc \
     protobuf
 EOT
+
+FROM otel-ffmpeg AS otel-grpc-ffmpeg
+
+RUN <<EOT sh
+  set -ex
+  install-php-extensions grpc
+EOT
diff --git a/docker-bake.hcl b/docker-bake.hcl
index 9e87940..5618899 100644
--- a/docker-bake.hcl
+++ b/docker-bake.hcl
@@ -55,7 +55,9 @@ variable "TARGETS" {
         "base",
         "ffmpeg",
         "otel",
-        "otel-ffmpeg"
+        "otel-ffmpeg",
+        "otel-grpc",
+        "otel-grpc-ffmpeg"
     ]
 }
 
diff --git a/docs/images.md b/docs/images.md
index 5d2731b..c51bc93 100644
--- a/docs/images.md
+++ b/docs/images.md
@@ -15,8 +15,8 @@ mlocati/php-extension-installer:2.8
 mysqli
 pdo_mysql
 exif
+ftp
 gd
-imagick
 opcache
 soap
 zip
@@ -76,11 +76,10 @@ libimage-exiftool-perl
 
 ### OTEL
 
-Contains additional [OpenTelemetry](https://opentelemetry.io/) **PHP extensions** that are useful for observability.
+Contains additional [OpenTelemetry](https://opentelemetry.io/) **PHP extensions** for observability. Uses the `http/protobuf` transport, which is fork-safe and works with PHP-FPM without any additional extensions.
 
 ```text
 opentelemetry
-grpc
 protobuf
 ```
 
@@ -92,8 +91,7 @@ protobuf
 !!! info
 
     - [`opentelemetry`](https://opentelemetry.io/docs/what-is-opentelemetry/): High-quality, ubiquitous, and portable telemetry to enable effective observability.
-    - [`grpc`](https://github.com/grpc/grpc): A modern, open source, high-performance remote procedure call (RPC) framework that can run anywhere.
-    - [`protobuf`](https://github.com/protocolbuffers/protobuf/tree/main/php): Significant performance improvement for otlp+protobuf exporting.
+    - [`protobuf`](https://github.com/protocolbuffers/protobuf/tree/main/php): Significant performance improvement for `http/protobuf` OTLP exporting.
 
 !!! note
     The `otel` image inherits the libraries from the `base` image.
@@ -106,7 +104,6 @@ Combines the `otel` PHP extensions with the `ffmpeg` media-processing libraries
 
 ```text
 opentelemetry
-grpc
 protobuf
 ```
 
@@ -128,3 +125,61 @@ libimage-exiftool-perl
 !!! note
     The `otel-ffmpeg` image inherits the libraries from the `base` image and combines the additions of the `ffmpeg` and `otel` targets.
 
+### OTEL (gRPC)
+
+Extends the `otel` image with the `grpc` PHP extension for services that use the `grpc` OTLP transport.
+
+```text
+opentelemetry
+protobuf
+grpc
+```
+
+!!!tip "Container suffixed with `-otel-grpc`"
+    ```shell
+    ghcr.io/toshy/php:8.5-fpm-trixie-otel-grpc
+    ```
+
+!!! info
+
+    - [`grpc`](https://github.com/grpc/grpc): A modern, open source, high-performance remote procedure call (RPC) framework that can run anywhere.
+
+!!! warning
+    `ext-grpc` initialises background threads at extension load time. Under PHP-FPM, which uses `fork()` to spawn workers, this can cause mutex corruption in long-running workers (SIGABRT from abseil's `mutex.cc`). This image is intended for PHP CLI / Messenger consumers that do not fork. For PHP-FPM use the `otel` image with `http/protobuf` transport instead.
+
+!!! note
+    The `otel-grpc` image inherits the libraries from the `base` image and the extensions from the `otel` target.
+
+### OTEL (gRPC) + FFmpeg
+
+Combines the `otel-grpc` PHP extensions with the `ffmpeg` media-processing libraries.
+
+**PHP extensions** (in addition to `common`):
+
+```text
+opentelemetry
+protobuf
+grpc
+```
+
+**Libraries** (in addition to `common`):
+
+```text
+zip
+unzip
+ffmpeg
+mkvtoolnix
+libimage-exiftool-perl
+```
+
+!!!tip "Container suffixed with `-otel-grpc-ffmpeg`"
+    ```shell
+    ghcr.io/toshy/php:8.5-fpm-trixie-otel-grpc-ffmpeg
+    ```
+
+!!! warning
+    See the gRPC warning in the `otel-grpc` section above.
+
+!!! note
+    The `otel-grpc-ffmpeg` image inherits the libraries from the `base` image and combines the additions of the `ffmpeg` and `otel-grpc` targets.
+