Instrument a PHP application

For most use cases Grafana Labs recommends Beyla, eBPF network-level auto-instrumentation, which is easy to set up and supports all languages and frameworks.

If you need process-level telemetry for PHP, follow this documentation to set up the upstream OpenTelemetry SDK for PHP for Application Observability.

Before you begin

The is the first step to get telemetry data into Application Observability, you need:

A PHP development environment 8.0+.
PECL.
Composer.

Install the SDK

Before you begin ensure you have a PHP 8.0+ development environment, PECL or Composer, and a PHP application to instrument.

Use either the PECL or Composer to install the package.

PECL:

Install the opentelemetry and protobuf extensions with the following commands:

pecl install opentelemetry
pecl install protobuf

Add the extensions to your php.ini file:

extension=protobuf.so

[opentelemetry]
extension=opentelemetry.so

Composer:

Run the following command in the project folder:

sh
composer require \
  open-telemetry/sdk \
  open-telemetry/exporter-otlp \
  php-http/guzzle7-adapter

The php-http/guzzle7-adapter packages fulfills the psr/http-client-implementation and psr/http-factory-implementation OpenTelemetry requirements.

If you don’t have Composer autoloading enabled, modify the application entry point to include:

require __DIR__ . '/vendor/autoload.php';

Auto-instrumentation

Many open source PHP projects have robust auto-instrumentation support so that you don’t have to manually instrument your application.

For a list of PHP frameworks and applications with auto-instrumentation packages, consult the OpenTelemetry Registry and filter for PHP instrumentation.

Collect logs

To collect logs for your PHP application:

Use a PSR-3 compatible logger such as monolog.
Add auto-instrumentation for PSR-3 Loggers to automatically collect logs.

Install the the package from the command line:

composer require open-telemetry/opentelemetry-auto-psr3

Now OpenTelemetry automatically instrument logs, for example:

/** @var \Psr\Log\LoggerInterface $logger */
$logger->info('This message will be sent to Grafana Cloud via OTLP');

Instrument your application

Export the following environment variables before starting your application to enable auto-instrumentation:

sh
export OTEL_PHP_AUTOLOAD_ENABLED=true
export OTEL_TRACES_EXPORTER=otlp
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_PROPAGATORS=baggage,tracecontext

Test your instrumentation

To test if you’ve successfully instrumented your application, run your application, generate some traffic, and you should see metrics and logs outputted to the console.