151 lines
5.0 KiB
Markdown
151 lines
5.0 KiB
Markdown
---
|
|
title: Automatic Instrumentation
|
|
linkTitle: Automatic
|
|
weight: 2
|
|
spelling: cSpell:ignore userland phar AUTOLOAD tracecontext myapp configurator
|
|
spelling: cSpell:ignore packagist pecl shortcode unindented
|
|
---
|
|
|
|
Automatic instrumentation with PHP requires at least PHP 8.0, and
|
|
[the OpenTelemetry PHP extension](https://github.com/open-telemetry/opentelemetry-php-instrumentation).
|
|
The extension allows developers code to hook into classes and methods, and
|
|
execute userland code before and after the hooked method runs.
|
|
|
|
## Example
|
|
|
|
```php
|
|
<?php
|
|
OpenTelemetry\Instrumentation\hook(
|
|
'class': DemoClass::class,
|
|
'function': 'run',
|
|
'pre': static function (DemoClass $demo, array $params, string $class, string $function, ?string $filename, ?int $lineno) use ($tracer) {
|
|
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) use ($tracer) {
|
|
$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](https://github.com/FriendsOfPHP/pickle) or
|
|
[php-extension-installer](https://github.com/mlocati/docker-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 >}}
|
|
|
|
2. 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 >}}
|
|
|
|
<!-- The remaining shortcode lines must be unindented so that tab content is unindented in the generated page -->
|
|
<!-- prettier-ignore-start -->
|
|
{{< 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 >}}
|
|
<!-- prettier-ignore-end -->
|
|
|
|
3. Add the extension to your `php.ini` file:
|
|
|
|
```ini
|
|
[opentelemetry]
|
|
extension=opentelemetry.so
|
|
```
|
|
|
|
4. Verify that the extension is installed and enabled:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
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
|
|
|
|
```php
|
|
<?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](https://packagist.org/search/?query=open-telemetry&tags=instrumentation).
|
|
|
|
## Next steps
|
|
|
|
After you have automatic instrumentation configured for your app or service, you
|
|
might want to add [manual instrumentation](../manual) to collect custom
|
|
telemetry data.
|