PHP zero-code instrumentation

Requirements

Automatic instrumentation with PHP requires:

Install the OpenTelemetry extension

The extension can be installed via pecl, pickle or php-extension-installer (docker specific). There are also packaged versions of the extension available for some Linux package managers.

Linux packages

RPM and APK packages are provided by the following:

#this example is for CentOS 7. The PHP version can be changed by
#enabling remi-<version>, eg "yum config-manager --enable remi-php83"
yum update -y
yum install -y epel-release yum-utils
yum install -y http://rpms.remirepo.net/enterprise/remi-release-7.rpm
yum-config-manager --enable remi-php81
yum install -y php php-pecl-opentelemetry

php --ri opentelemetry

#At the time of writing, PHP 8.1 was the default PHP version. You may need to
#change "php81" if the default changes. You can alternatively choose a PHP
#version with "apk add php<version>", eg "apk add php83".
echo "@testing https://dl-cdn.alpinelinux.org/alpine/edge/testing" >> /etc/apk/repositories
apk add php php81-pecl-opentelemetry@testing
php --ri opentelemetry

PECL

  1. Setup development environment. Installing from source requires proper development environment and some dependencies:

    sudo apt-get install gcc make autoconf

    brew install gcc make autoconf

  2. Build/install the extension. With your environment set up you can install the extension:

    pecl install opentelemetry

    php pickle.phar install opentelemetry

    install-php-extensions opentelemetry

  3. Add the extension to your php.ini file:

    [opentelemetry]
extension=opentelemetry.so

  4. Verify that the extension is installed and enabled:

    php -m | grep opentelemetry

Install SDK and instrumentation libraries

Now that the extension is installed, install the OpenTelemetry SDK and one or more instrumentation libraries.

Automatic instrumentation is available for a number commonly used PHP libraries. For the full list, see instrumentation libraries on packagist.

Let’s assume that your application uses Slim Framework and a PSR-18 HTTP client. You would then install the SDK and corresponding auto-instrumentation packages for these:

composer require \
    open-telemetry/sdk \
    open-telemetry/opentelemetry-auto-slim \
    open-telemetry/opentelemetry-auto-psr18

Configuration

When used in conjunction with the OpenTelemetry SDK, you can use environment variables or the php.ini file to configure auto-instrumentation.

Environment configuration

OTEL_PHP_AUTOLOAD_ENABLED=true \
OTEL_SERVICE_NAME=your-service-name \
OTEL_TRACES_EXPORTER=otlp \
OTEL_EXPORTER_OTLP_PROTOCOL=grpc \
OTEL_EXPORTER_OTLP_ENDPOINT=http://collector:4317 \
OTEL_PROPAGATORS=baggage,tracecontext \
php myapp.php

php.ini configuration

Append the following to php.ini, or another ini file that will be processed by PHP:

OTEL_PHP_AUTOLOAD_ENABLED=true
OTEL_SERVICE_NAME=your-service-name
OTEL_TRACES_EXPORTER=otlp
OTEL_EXPORTER_OTLP_PROTOCOL=grpc
OTEL_EXPORTER_OTLP_ENDPOINT=http://collector:4317
OTEL_PROPAGATORS=baggage,tracecontext

Run your application

After all of the above is installed and configured, start your application as you normally would.

The traces you see exported to the OpenTelemetry Collector depend on the instrumentation libraries you have installed, and the code path that was taken inside the application. In the previous example, using Slim Framework and PSR-18 instrumentation libraries, you should expect to see spans such as:

  • A root span representing the HTTP transaction
  • A span for the action that was executed
  • A span for each HTTP transaction that the PSR-18 client sent

Note that the PSR-18 client instrumentation appends distributed tracing headers to outgoing HTTP requests.

How it works

The extension enables registering observer functions as PHP code against classes and methods, and executing those functions before and after the observed method runs.

If there is not an instrumentation library for your framework or application, you can write your own. The following example provides some code to be instrumented, and then illustrates how to use the OpenTelemetry extension to trace the execution of that code.

<?php

use OpenTelemetry\API\Common\Instrumentation\CachedInstrumentation;
use OpenTelemetry\API\Trace\Span;
use OpenTelemetry\API\Trace\StatusCode;
use OpenTelemetry\Context\Context;

require 'vendor/autoload.php';

/* The class to be instrumented */
class DemoClass
{
    public function run(): void
    {
        echo 'Hello, world';
    }
}

/* The auto-instrumentation code */
OpenTelemetry\Instrumentation\hook(
    class: DemoClass::class,
    function: 'run',
    pre: static function (DemoClass $demo, array $params, string $class, string $function, ?string $filename, ?int $lineno) {
        static $instrumentation;
        $instrumentation ??= new CachedInstrumentation('example');
        $span = $instrumentation->tracer()->spanBuilder('democlass-run')->startSpan();
        Context::storage()->attach($span->storeInContext(Context::getCurrent()));
    },
    post: static function (DemoClass $demo, array $params, $returnValue, ?Throwable $exception) {
        $scope = Context::storage()->scope();
        $scope->detach();
        $span = Span::fromContext($scope->context());
        if ($exception) {
            $span->recordException($exception);
            $span->setStatus(StatusCode::STATUS_ERROR);
        }
        $span->end();
    }
);

/* Run the instrumented code, which will generate a trace */
$demo = new DemoClass();
$demo->run();

The previous example defines DemoClass, then registers pre and post hook functions on its run method. The hook functions run before and after each execution of the DemoClass::run() method. The pre function starts and activates a span, while the post function ends it.

If DemoClass::run() throws an exception, the post function records it without affecting exception propagation.

Next steps

After you have automatic instrumentation configured for your app or service, you might want to add manual instrumentation to collect custom telemetry data.

For more examples, see opentelemetry-php-contrib/examples.


Last modified August 6, 2024: rework php zero-code page (#4952) (291ff16f)