PHP OpenTelemetry instrumentation

Instrument a PHP application with OpenTelemetry using the opentelemetry PHP extension for zero-code auto-instrumentation. Once the extension and the SDK are installed, incoming requests, database queries, and outbound HTTP calls are traced without changes to your application code.

Fastest path. Run this in your AI IDE and the Instrumentation Agent wires this service up for you.

/osuite-instrument php

The agent installs the OpenTelemetry extension and Composer packages, adds the auto-instrumentation for your framework, and sets the exporter environment variables.

Prefer to do it by hand? Follow the manual steps below — they are the complete path.

Prerequisites

• PHP 8.1 or newer (zero-code instrumentation requires the extension, which needs PHP 8.0+; the Laravel auto-instrumentation needs 8.1+).
• Composer and PECL for installing the extension.
• Your Osuite ingest token and region.

Install and configure

1. Install and enable the opentelemetry extension. It provides the hooks the auto-instrumentation libraries attach to.

   pecl install opentelemetry

   Enable it by adding this line to your php.ini, then confirm it loaded with php -m | grep opentelemetry:

   extension=opentelemetry.so

2. Install the SDK, the OTLP exporter, a PSR-18 HTTP client, and the Laravel auto-instrumentation with Composer.

   composer require \
     open-telemetry/sdk \
     open-telemetry/exporter-otlp \
     open-telemetry/opentelemetry-auto-laravel \
     php-http/guzzle7-adapter

   open-telemetry/exporter-otlp sends data over OTLP, and php-http/guzzle7-adapter satisfies the PSR-18 client the HTTP exporter needs. For a non-Laravel app, swap opentelemetry-auto-laravel for the auto-instrumentation matching your framework — for example open-telemetry/opentelemetry-auto-slim for Slim, or open-telemetry/opentelemetry-auto-symfony for Symfony.

3. Set the exporter environment variables. Provide them wherever your app runs — the PHP-FPM pool, the web server environment, or a .env loaded at boot.

   export OTEL_PHP_AUTOLOAD_ENABLED=true
   export OTEL_SERVICE_NAME=<service-name>
   export OTEL_RESOURCE_ATTRIBUTES=service.environment=production
   export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
   export OTEL_EXPORTER_OTLP_ENDPOINT=https://ingest.<region>.osuite.io:443
   export OTEL_EXPORTER_OTLP_HEADERS=x-osuite-ingest-token=<your-ingest-token>
   export OTEL_TRACES_EXPORTER=otlp
   export OTEL_LOGS_EXPORTER=otlp
   export OTEL_METRICS_EXPORTER=otlp

   OTEL_PHP_AUTOLOAD_ENABLED=true is what activates zero-code instrumentation at startup. The https:// scheme on the endpoint is required — the SDK exporter takes a URL and Osuite only accepts OTLP over TLS.

Run Laravel with instrumentation

With the extension enabled and the environment variables set, open-telemetry/opentelemetry-auto-laravel hooks into the framework’s request lifecycle automatically. No code changes are needed: run your app as usual and requests, Eloquent queries, and queue jobs are traced.

php artisan serve

gRPC instead of HTTP

To export over gRPC rather than HTTP, install the grpc PECL extension and open-telemetry/transport-grpc, then set OTEL_EXPORTER_OTLP_PROTOCOL=grpc. The HTTP/protobuf path above needs no extra extension beyond the Guzzle adapter.

Verify in Osuite

What you should see

Send a request to any route. The service appears in APM within a minute with a trace per request, showing the controller, Eloquent queries, and outbound HTTP calls as nested spans. Application logs appear in the Logs explorer tagged with the matching trace ID.

Troubleshooting

If no traces appear, confirm the extension is loaded (php -m | grep opentelemetry) and that OTEL_PHP_AUTOLOAD_ENABLED=true is set in the same environment the app runs in — PHP-FPM does not inherit your shell’s variables unless you pass them through the pool config.

No data in Osuite after a few minutes? Work through these checks.

• Endpoint — confirm the exporter targets exactly ingest.<region>.osuite.io:443 for your region, over TLS.
• Token — confirm the ingest header carries a valid <your-ingest-token> and has not been rotated.
• Pipeline — confirm the signal you expect (traces, logs, or metrics) is wired into an active pipeline with the otlp/osuite exporter attached.
• Export errors — check the application or Collector logs for OTLP export failures (auth, DNS, TLS, connection refused).
• Network — confirm the host has outbound access to the ingest endpoint on port 443.
• Timing — allow up to a minute for the first data to appear before assuming a failure.

Still stuck? Ask the Investigation Agent or contact support.

Next steps

Already using OpenTelemetry? Point an existing OpenTelemetry setup at Osuite by changing the endpoint.

Explore traces Open the trace explorer and service map in Osuite.

Correlate logs with traces Link application logs to the traces that produced them.