跳转至

Automatic Instrumentation

Automatic instrumentation with PHP requires at least PHP 8.0, and the OpenTelemetry PHP extension. The extension allows developers code to hook into classes and methods, and execute userland code before and after the hooked method runs.

Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
<?php
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($class)->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();
    }
);

$demo = new DemoClass();
$demo->run();

Here, we provide pre and post functions, which are executed before and after DemoClass::run. The pre function starts and activates a span, and the post function ends it. If an exception was thrown by DemoClass::run(), the post function will record it, without affecting exception propagation.

Installation

The extension can be installed via pecl, pickle or php-extension-installer (docker specific).

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

{{< tabpane lang=shell persistLang=false >}}

{{< tab "Linux (apt)" >}}sudo apt-get install gcc make autoconf{{< /tab >}}

{{< tab "MacOS (homebrew)" >}}brew install gcc make autoconf{{< /tab >}}

{{< /tabpane >}}

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

{{< tabpane lang=shell persistLang=false >}}

{{< tab pecl >}}pecl install opentelemetry-beta{{< /tab >}}

{{< tab pickle >}} php pickle.phar install --source https://github.com/open-telemetry/opentelemetry-php-instrumentation.git#1.0.0beta2 {{< /tab >}}

{{< tab "php-extension-installer (docker)" >}} install-php-extensions opentelemetry {{< /tab >}}

{{< /tabpane >}}

  1. Add the extension to your php.ini file:
1
2
[opentelemetry]
extension=opentelemetry.so
  1. Verify that the extension is installed and enabled:
1
php -m | grep opentelemetry

Zero-code configuration for automatic instrumentation

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

1
2
3
4
5
6
7
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

Manual setup for automatic instrumentation

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
<?php
OpenTelemetry\API\Common\Instrumentation\Globals::registerInitializer(function (Configurator $configurator) {
    $propagator = TraceContextPropagator::getInstance();
    $spanProcessor = new BatchSpanProcessor(/*params*/);
    $tracerProvider = (new TracerProviderBuilder())
        ->addSpanProcessor($spanProcessor)
        ->setSampler(new ParentBased(new AlwaysOnSampler()))
        ->build();

    ShutdownHandler::register([$tracerProvider, 'shutdown']);

    return $configurator
        ->withTracerProvider($tracerProvider)
        ->withPropagator($propagator);
});

//instrumentation libraries can access the configured providers (or a no-op implementation) via `Globals`
$tracer = Globals::tracerProvider()->getTracer('example');
//or, via CachedInstrumentation
$instrumentation = new CachedInstrumentation('example');
$tracerProvider = $instrumentation->tracer();

Supported libraries and frameworks

Automatic Instrumentation comes with a number of instrumentation libraries for commonly used PHP libraries. For the full list, see instrumentation libraries on packagist.

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.