---
title: "Instrument a PHP application | OpenTelemetry documentation"
description: "Instrument a PHP application with OpenTelemetry for Application Observability."
---

# Instrument a PHP application

If you need process-level telemetry for PHP, follow this guide to set up the [upstream OpenTelemetry SDK for PHP](https://opentelemetry.io/docs/languages/php/) for Application Observability.

## Recommended setup for Grafana Cloud

Grafana Labs recommends that you set up OpenTelemetry components, including instrumentation and an OpenTelemetry Collector distribution, using one of the [Grafana Cloud setup guides](/docs/opentelemetry/grafana-cloud/).

These opinionated guides make it easy to get started. They include all the binaries, configuration, and connection parameters you need to set up OpenTelemetry for [Grafana Cloud](/products/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.

> Note
> 
> While the OpenTelemetry SDK for PHP supports PHP 8.0+, we recommend PHP 8.2+ because it provides automatic observability of native extensions and database connectors. This gives you more detailed insights into database connections, HTTP requests, and cache operations without manual instrumentation. For a full list of supported extensions, refer to the [PHP instrumentation registry](https://opentelemetry.io/ecosystem/registry/?language=php&component=instrumentation).

Use either PECL or Composer to install the package.

**PECL:**

Install the opentelemetry and protobuf extensions with the following commands:

sh ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```sh
pecl install opentelemetry
pecl install protobuf
```

Add the extensions to your `php.ini` file:

ini ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```ini
extension=protobuf.so

[opentelemetry]
extension=opentelemetry.so
```

**Composer:**

Run the following command in your project folder:

sh ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```sh
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](https://getcomposer.org/doc/01-basic-usage.md#autoloading) enabled, modify your application entry point to include:

php ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```php
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](https://opentelemetry.io/ecosystem/registry/?language=php&component=instrumentation) and filter for PHP instrumentation.

### Collect logs

To collect logs for your PHP application:

1. Use a PSR-3 compatible logger such as [monolog](https://github.com/Seldaek/monolog).
2. Add auto-instrumentation for PSR-3 Loggers to automatically collect logs.

Install the package from the command line:

sh ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```sh
composer require open-telemetry/opentelemetry-auto-psr3
```

OpenTelemetry now automatically instruments logs. For example:

php ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```php
/** @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 code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```sh
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](https://opentelemetry.io/docs/specs/semconv/attributes-registry/service/#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](https://github.com/grafana/docker-otel-lgtm/?tab=readme-ov-file#run-example-apps-in-different-languages) for a complete example setup.

## Resources

1. [PHP OpenTelemetry documentation](https://opentelemetry.io/docs/languages/php/)
2. [opentelemetry package on PECL](https://pecl.php.net/package/opentelemetry)
3. [opentelemetry-php-instrumentation on GitHub](https://github.com/open-telemetry/opentelemetry-php-instrumentation)