Migrate PHP OpenTelemetry APM

Overview

The OpenTelemetry PHP SDK provides APIs for manual trace instrumentation and supports automatic instrumentation via contrib packages for popular frameworks and libraries. This page covers installing the SDK, setting up instrumentation, and configuring the OTLP exporter to send traces to Kloudfuse.

Install

Run these commands to install the core PHP packages and the OTLP HTTP exporter:

composer require open-telemetry/api open-telemetry/sdk open-telemetry/sem-conv
composer require open-telemetry/exporter-otlp php-http/guzzle7-adapter

Set Up Instrumentation

Initialize the tracer provider and register it globally before any application code runs. Place this in your application bootstrap or front controller (for example, public/index.php):

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

use OpenTelemetry\SDK\Trace\TracerProvider;
use OpenTelemetry\SDK\Trace\SpanProcessor\SimpleSpanProcessor;
use OpenTelemetry\Contrib\Otlp\OtlpHttpExporter;

$exporter = OtlpHttpExporter::fromConnectionString(
    getenv('OTEL_EXPORTER_OTLP_ENDPOINT')
);

$tracerProvider = new TracerProvider(
    new SimpleSpanProcessor($exporter)
);

\OpenTelemetry\API\Globals::registerInitializer(function () use ($tracerProvider) {
    return $tracerProvider;
});

$tracer = $tracerProvider->getTracer('my-service');
php

Create spans in your application logic:

$span = $tracer->spanBuilder('my-operation')->startSpan();
$scope = $span->activate();
try {
    // your work here
} finally {
    $span->end();
    $scope->detach();
}
php

For full setup details, follow the OpenTelemetry documentation on Instrumentation.

Send to Kloudfuse

Configure the OTLP exporter by setting the following environment variables before starting your application:

export OTEL_EXPORTER_OTLP_ENDPOINT="https://<kloudfuse-hostname>/ingester/otlp"   (1)
export OTEL_EXPORTER_OTLP_HEADERS="Kf-Api-Key=<api-key>"                          (2)
export OTEL_SERVICE_NAME="my-service"
export OTEL_RESOURCE_ATTRIBUTES="deployment.environment=production"
1 Replace <kloudfuse-hostname> with your Kloudfuse cluster hostname.
2 Replace <api-key> with your Kloudfuse API key.

Instrumentation Libraries

OpenTelemetry PHP provides contrib packages that automatically instrument popular PHP libraries and frameworks. Review the OpenTelemetry documentation on Using instrumentation libraries.

Troubleshooting

No Traces Appear

Confirm that vendor/autoload.php is included before your bootstrap code initializes the tracer provider. If autoloading is missing or the SDK packages are not installed, the tracer provider will not be registered and no spans will be created.

Spans Show Incorrect Parent-Child Relationships

Call $scope→detach() in a finally block to correctly close the active context after each span. If detach() is not called, subsequent spans will incorrectly appear as children of the current span.

Environment Variables Not Picked Up in FPM/Web Server Contexts

PHP-FPM and web server environments do not inherit shell environment variables. Set OTEL_EXPORTER_OTLP_ENDPOINT and related variables in the PHP-FPM pool configuration (www.conf) or in the web server virtual host configuration.

External References