Weave Code
Transport Grpc Laravel Package
open-telemetry/transport-grpc
gRPC transport for OpenTelemetry PHP, enabling OTLP trace, metric, and log export over gRPC. Integrates with the OpenTelemetry SDK and supports efficient protobuf-based telemetry delivery to collectors and observability backends.
gRPC transport for OpenTelemetry PHP.
Frequently asked questions about Transport Grpc
- How do I install open-telemetry/transport-grpc in a Laravel app?
- Install it with Composer using composer require open-telemetry/transport-grpc, and make sure the ext-grpc PHP extension is compiled and enabled in the runtime. There is no Laravel service provider, config file, or container binding to register. You pass the transport factory into an OpenTelemetry OTLP exporter, which you then wire into the SDK tracer, meter, and logger providers. Endpoint, headers, and timeout come from environment variables rather than a config file.
- Does this package support Laravel 10, 11, and 12?
- Yes, indirectly, because the package has no Laravel coupling at all. It targets supported PHP versions such as PHP 8.2 through 8.4 and implements the OpenTelemetry PHP SDK transport contract, so it works the same across Laravel 10, 11, and 12 as long as the SDK and exporter versions are compatible. That also means it survives Laravel major upgrades without code changes. The real constraint is the ext-grpc extension and the open-telemetry/sdk version pair, not the Laravel version.
- How do I configure the gRPC endpoint, headers, and timeout for OTLP?
- Configuration is environment-driven: set OTEL_EXPORTER_OTLP_ENDPOINT to your collector address (the default OTLP/gRPC port is 4317), set OTEL_EXPORTER_OTLP_PROTOCOL to grpc, and provide authentication headers and timeouts through the corresponding OTEL_EXPORTER_OTLP_HEADERS and timeout variables. Per-signal overrides also exist if you want traces, metrics, and logs sent to different collectors. Because everything is env-based, you can toggle or disable export per environment without touching application code.
- Do I need ext-grpc installed, and is there a pure-PHP fallback?
- Yes, ext-grpc is a hard requirement, and there is no pure-PHP fallback for this transport. It is a compiled PECL extension that must be present in every runtime that emits telemetry, including php-fpm images, Octane or Swoole workers, Horizon containers, CI runners, and serverless runtimes such as Laravel Vapor, which needs a custom PHP layer. If you cannot guarantee the extension across your whole runtime matrix, use the OTLP/HTTP transport for those workloads instead. A split-transport estate is fine as long as it is a documented decision rather than drift.
- Should I use this gRPC transport or the OTLP/HTTP transport?
- Choose gRPC when you can guarantee ext-grpc everywhere and want lower serialization and framing overhead with native collector semantics. Choose OTLP/HTTP when infrastructure simplicity matters more, since it works without a compiled extension and is far easier to package for serverless and mixed runtime estates. On php-fpm the gRPC channel is set up per request, so the performance advantage is smaller, while on long-lived workers like Octane it amortizes well. Validate that gRPC actually beats HTTP on your throughput targets before accepting the extra extension risk.
- Does this transport work with Laravel Octane and long-lived Swoole workers?
- It works, and it is arguably where gRPC fits best because a long-lived worker can reuse the channel across many exports instead of paying setup cost per request. That said, you should still confirm that the exporter and batch processor are not holding stale state between requests and that timeouts are short enough to protect worker responsiveness. Watch memory growth and connection resets under sustained load, especially when the collector restarts. Test under Octane specifically rather than assuming php-fpm behavior carries over.
- Will a slow or unreachable collector add latency to my users' requests?
- The exporter runs inside the request lifecycle, so without deliberate settings a slow or retrying collector can add tail latency to user traffic. Set explicit export timeouts, rely on the batch processor to move export off the hot path where possible, and decide explicitly whether the policy is fail-open (drop telemetry to protect latency) or fail-closed (retry and risk slowdowns). That decision should have a named owner and be documented. Many teams also place an OpenTelemetry Collector close to the app so retries and fan-out happen outside the application.
- Can I send traces, metrics, and logs with this package?
- Yes, it provides full OTLP/gRPC support for traces, metrics, and logs, so a single transport can carry all three signals to an OTLP-compatible collector. Serialization uses generated protobuf classes, which keeps payloads spec-compliant and compact. You can still configure per-signal endpoints and headers if you route signals to different backends. It works with the OpenTelemetry Collector and the many vendor backends that accept OTLP.
- How do I test that telemetry is actually reaching the collector over gRPC?
- Run a local OpenTelemetry Collector listening on 4317 with a debug or logging exporter, point OTEL_EXPORTER_OTLP_ENDPOINT at it, and confirm spans, metrics, and logs appear. This matters because a mismatch between the google/protobuf C extension and the pure-PHP implementation can cause silent serialization failure, where telemetry simply disappears with no error surfaced to users. Add a smoke test in CI that asserts the collector received data, not just that the code ran. Also verify your production images use the same protobuf path as your test environment.
- Who maintains open-telemetry/transport-grpc, and is it actively developed?
- It is published from the open-telemetry/opentelemetry-php monorepo as a READONLY subtree split, so the repository you see for this package reflects publishing mechanics rather than independent adoption or health. Issues, pull requests, and security advisories route to the upstream monorepo, which means star counts and dependent counts on the split repo are misleading signals. Judge maintenance by the upstream monorepo's release cadence and by whether the transport version stays aligned with your open-telemetry/sdk version. Pin and review the SDK plus transport pair together as part of your upgrade process.
Weaver
How can I help you explore Laravel packages today?