open-telemetry/context

Context implementation for OpenTelemetry PHP.

1.4.0 2025-09-19 00:05 UTC

Requires

• php: ^8.1
• symfony/polyfill-php82: ^1.26

Suggests

• ext-ffi: To allow context switching in Fibers

Apache-2.0

• opentelemetry-php contributors

• Context
• opentelemetry
• otel

README

OpenTelemetry Context

Immutable execution scoped propagation mechanism, for further details see opentelemetry-specification.

Installation

composer require open-telemetry/context

Usage

Implicit propagation

$context = Context::getCurrent();
// modify context
$scope = $context->activate();
try {
    // run within new context
} finally {
    $scope->detach();
}

It is recommended to use a try-finally statement after ::activate() to ensure that the created scope is properly ::detach()ed.

Debug scopes

By default, scopes created by ::activate() warn on invalid and missing calls to ::detach() in non-production environments. This feature can be disabled by setting the environment variable OTEL_PHP_DEBUG_SCOPES_DISABLED to a truthy value. Disabling is only recommended for applications using exit / die to prevent unavoidable notices.

Async applications

Fiber support - automatic context propagation to newly created fibers

Requires an NTS build, ext-ffi, and setting the environment variable OTEL_PHP_FIBERS_ENABLED to a truthy value. Additionally vendor/autoload.php has to be preloaded for non-CLI SAPIs if ffi.enable is set to preload.

Event loops

Event loops have to restore the original context on callback execution. A basic implementation could look like the following, though implementations should avoid keeping unnecessary references to arguments if possible:

function bindContext(Closure $closure): Closure {
    $context = Context::getCurrent();
    return static function (mixed ...$args) use ($closure, $context): mixed {
        $scope = $context->activate();
        try {
            return $closure(...$args);
        } finally {
            $scope->detach();
        }
    };
}

Contributing

This repository is a read-only git subtree split. To contribute, please see the main OpenTelemetry PHP monorepo.