Download the PHP package performance-x/opentelemetry-php-instrumentation-trait without Composer

OpenTelemetry PHP Instrumentation Trait

A trait to simplify creating OpenTelemetry instrumentations for PHP classes, interfaces, and functions.

Installation

Usage

The trait is designed to be used in instrumentation classes that register OpenTelemetry hooks for specific targets.

Features

• Easy initialization of OpenTelemetry instrumentation
• Support for both class methods and standalone functions
• Configurable span kind (defaults to INTERNAL)
• Automatic prefix for all span attributes via getAttributeName()
• Parameter mapping to span attributes
• Support for pre and post handlers with span access
• Automatic exception handling
• Return value capturing
• Code location attributes (function, namespace, file, line)

Configuration Options

The create() method accepts:

• instrumentation: Optional pre-configured instrumentation instance
• prefix: Optional prefix for all span attributes
• spanKind: Kind of spans to create (default: INTERNAL)
• className: Optional target class name
• name: Name of the instrumentation if no instrumentation instance provided

At least one of instrumentation or name must be provided.

Hook Configuration

The helperHook() method accepts:

• methodName: The method or function to hook
• paramMap: Array of parameters to capture as attributes
• returnValueKey: Optional key for the return value attribute
• preHandler: Optional callback for custom span building
• postHandler: Optional callback for custom span finishing
• className: Optional override of target class name

Dynamic Span Names

The trait supports updating span names dynamically during span creation. This is particularly useful when the span name depends on runtime information:

This approach is necessary because span names can only be set during span creation, but sometimes the desired name depends on runtime information available in the pre-handler. By setting the X-PerformanceX-OpenTelemetry-Update-Name attribute (available as InstrumentationTrait::UPDATE_NAME), the trait will automatically update the span name during creation.

Parameter Mapping

The paramMap argument in helperHook() supports several ways to map method parameters to span attributes:

Value Handling

The trait automatically handles different parameter types appropriately. For example, with Drupal's cache set method:

Simple Parameter Mapping

Custom Attribute Names

Multiple Parameters with Custom Names

Return Value Handling

The trait can capture method return values. For example, with Drupal's cache get method:

Combined with Custom Handlers

Error Handling

The trait automatically handles exceptions, but you can customize error handling using post handlers.

Note: While these examples show detailed error capturing, in practice, OpenTelemetry tracing is best combined with proper logging. The trace ID can be added to log entries, allowing you to correlate traces with detailed log messages. This provides better observability than putting log-like information into spans.

Requirements

• PHP 8.2+
• OpenTelemetry PHP SDK

License

MIT License