Documentation OpenTelemetry Instrument an application PHP

Instrument a PHP application

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

Recommended setup for Grafana Cloud

Grafana Labs recommends setting up OpenTelemetry components, including instrumentation and an OpenTelemetry Collector distribution, using one of the Grafana Cloud onboarding workflows. These opinionated guides make it easy to get started and include all the binaries, configuration, and connection parameters you need to set up OpenTelemetry for Grafana Cloud.

There isn’t a dedicated guide for PHP. You can use the guided workflow for Beyla or manually set up instrumentation by following the rest of this documentation.

Before you begin

To get telemetry data into Application Observability, you need:

1. A PHP development environment 8.2+ (strongly recommended) or 8.0+ (minimal support).
2. PECL.
3. Composer.

Install the SDK

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

Use either PECL or Composer to install the package.

PECL:

Install the opentelemetry and protobuf extensions with the following commands:

sh Copy

pecl install opentelemetry
pecl install protobuf

Add the extensions to your php.ini file:

ini Copy

extension=protobuf.so

[opentelemetry]
extension=opentelemetry.so

Composer:

Run the following command in your project folder:

sh Copy

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

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

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

php Copy

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

Auto-instrumentation

Many open source PHP projects offer robust auto-instrumentation support, so 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:

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

Install the package from the command line:

sh Copy

composer require open-telemetry/opentelemetry-auto-psr3

OpenTelemetry now automatically instruments logs. For example:

php Copy

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

Run your application

Run your application with the following command:

sh Copy

OTEL_RESOURCE_ATTRIBUTES="service.name=<name>,service.namespace=<namespace>,deployment.environment=<environment>" \
OTEL_EXPORTER_OTLP_ENDPOINT=<endpoint> \
OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf" \
php -S localhost:8080

Replace variables in <...> with values specific to your application and backend. For more details, see the OpenTelemetry service attributes documentation.

• <name>: your service name, for example, shoppingcart
• <namespace>: a string to group related services, such as ecommerce for a team that manages several services
• <environment>: the deployment environment, for example, the production deployment tier

Some backends, such as Grafana Cloud, also require you to set authentication headers in the OTEL_EXPORTER_OTLP_HEADERS environment variable.

Example application

See the Rolldice service for a complete example setup.

Resources

1. PHP OpenTelemetry documentation
2. opentelemetry package on PECL
3. opentelemetry-php-instrumentation on GitHub