PHP

Before integration, enable the DataKit OpenTelemetry collector.

Prerequisites¶

PHP 8.1, 8.2, 8.3, or 8.4;
Composer;
Network connectivity on the required port between DataKit and the PHP application.

1. Zero-code Instrumentation¶

Install the Extension¶

Check the PHP version, thread safety mode, and extension directory:

php -r 'printf("PHP=%s.%s MODE=%s EXT=%s\n", PHP_MAJOR_VERSION, PHP_MINOR_VERSION, PHP_ZTS ? "ts" : "nts", ini_get("extension_dir"));'
uname -m

From the Releases page, download the asset matching the PHP version, ts/nts mode, operating system, and CPU architecture. For example, for PHP 8.2 NTS on Linux x86_64, use:

php_opentelemetry-1.3.4-gtrace-8.2-nts-linux-x86_64.tar.gz

Install the extension:

tar -xzf php_opentelemetry-1.3.4-gtrace-8.2-nts-linux-x86_64.tar.gz
sudo install -m 0755 \
  php_opentelemetry-1.3.4-gtrace-8.2-nts-linux-x86_64/opentelemetry.so \
  "$(php -r 'echo ini_get("extension_dir");')/opentelemetry.so"
php --ini

Create 99-opentelemetry.ini in a configuration directory scanned by PHP:

extension=opentelemetry.so
opentelemetry.attr_hooks_enabled=On

Restart PHP-FPM, Apache, or the application process, and then check the extension:

php --ri opentelemetry

Install Auto-instrumentation Dependencies¶

The auto-instrumentation packages must correspond to the frameworks and components used by the application. The following example uses Slim and PSR-18:

composer config allow-plugins.php-http/discovery false
composer require \
  open-telemetry/sdk \
  open-telemetry/exporter-otlp \
  open-telemetry/opentelemetry-auto-slim \
  open-telemetry/opentelemetry-auto-psr18 \
  php-http/guzzle7-adapter \
  nyholm/psr7

Configure Export¶

When the application and DataKit run on the same host, export data through the loopback address:

export OTEL_PHP_AUTOLOAD_ENABLED=true
export OTEL_SERVICE_NAME=my-php-service
export OTEL_SERVICE_VERSION=1.0.0
export OTEL_RESOURCE_ATTRIBUTES=deployment.environment.name=prod
export OTEL_TRACES_EXPORTER=otlp
export OTEL_METRICS_EXPORTER=none
export OTEL_LOGS_EXPORTER=none
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:9529/otel
export OTEL_PROPAGATORS=baggage,tracecontext

php -S 0.0.0.0:8080 -t public

For deployments using PHP-FPM, Supervisor, systemd, or containers, add these variables to the corresponding process startup environment and restart the process.

To use OTLP/gRPC on port 4317, also install the PHP grpc extension and the Composer transport package:

composer require open-telemetry/transport-grpc

export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4317

Verification¶

After requesting an application route, check the DataKit receiver log:

curl http://127.0.0.1:8080/
tail -f /usr/local/datakit/log/gin.log | grep '/otel/v1/traces'

If the log contains POST /otel/v1/traces with status code 200, the Trace has been received by DataKit.

2. SDK-based Instrumentation¶

With SDK-based instrumentation, application code creates Spans directly, without requiring the auto-instrumentation extension.

Install Dependencies¶

composer config allow-plugins.php-http/discovery false
composer require \
  open-telemetry/sdk \
  open-telemetry/exporter-otlp \
  php-http/guzzle7-adapter \
  nyholm/psr7

Create a Span¶

<?php

declare(strict_types=1);

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

use OpenTelemetry\API\Trace\StatusCode;
use OpenTelemetry\Contrib\Otlp\OtlpHttpTransportFactory;
use OpenTelemetry\Contrib\Otlp\SpanExporter;
use OpenTelemetry\SDK\Common\Attribute\Attributes;
use OpenTelemetry\SDK\Resource\ResourceInfo;
use OpenTelemetry\SDK\Resource\ResourceInfoFactory;
use OpenTelemetry\SDK\Trace\SpanProcessor\BatchSpanProcessorBuilder;
use OpenTelemetry\SDK\Trace\TracerProvider;

$resource = ResourceInfoFactory::defaultResource()->merge(
    ResourceInfo::create(Attributes::create([
        'service.name' => 'my-php-service',
        'service.version' => '1.0.0',
        'deployment.environment.name' => 'prod',
    ]))
);

$transport = (new OtlpHttpTransportFactory())->create(
    'http://127.0.0.1:9529/otel/v1/traces',
    'application/x-protobuf'
);
$exporter = new SpanExporter($transport);
$processor = (new BatchSpanProcessorBuilder($exporter))->build();
$tracerProvider = TracerProvider::builder()
    ->setResource($resource)
    ->addSpanProcessor($processor)
    ->build();

$tracer = $tracerProvider->getTracer('application');
$span = $tracer->spanBuilder('order.submit')->startSpan();
$scope = $span->activate();

try {
    $span->setAttribute('order.id', 'A1001');
    // Application code
} catch (Throwable $exception) {
    $span->recordException($exception);
    $span->setStatus(StatusCode::STATUS_ERROR, $exception->getMessage());
    throw $exception;
} finally {
    $scope->detach();
    $span->end();
    $tracerProvider->shutdown();
}

PHP