README

One tag, full visibility — every method call in your PHP app shows up in your traces, no boilerplate, no framework required.

This is a read-only sub-split. Please open issues and pull requests in the monorepo.

The framework-agnostic engine — the Laravel and Symfony integrations build on it to discover and register your classes automatically.

Installation

composer require eerzho/opentelemetry-auto-class

Requirements:

• ext-opentelemetry
• PHP 8.2+

Usage

Start with a plain service — we'll add tracing to it one attribute at a time:

namespace App\Service;

class OrderService
{
    public function pay(int $orderId, string $card, Address $address): void {}
    public function healthCheck(): bool {}
}

class Address
{
    public function __construct(public string $city, public string $zip) {}
}

1. #[Trace] — a span per method

use Eerzho\Instrumentation\Class\Attribute\Trace;

#[Trace(exclude: ['healthCheck'])]   // trace every public method but healthCheck
// #[Trace(include: ['pay'])]        // or: only pay
class OrderService
{
    public function pay(int $orderId, string $card, Address $address): void {}
    public function healthCheck(): bool {}
}

2. #[TraceArguments] — pick the captured arguments

use Eerzho\Instrumentation\Class\Attribute\TraceArguments;

#[TraceArguments(exclude: ['card'])]       // capture every arg but card
// #[TraceArguments(include: ['orderId'])] // or: only orderId
public function pay(int $orderId, string $card, Address $address): void {}

3. #[TraceProperties] — expand an object argument

use Eerzho\Instrumentation\Class\Attribute\TraceProperties;

#[TraceProperties(exclude: ['zip'])]     // expand every prop but zip
// #[TraceProperties(include: ['city'])] // or: only city
class Address
{
    public function __construct(public string $city, public string $zip) {}
}

4. Register

Once the attributes are in place, scan the classes and register the hooks — once, at bootstrap:

use Eerzho\Instrumentation\Class\AttributeScanner;
use Eerzho\Instrumentation\Class\ClassInstrumentation;

ClassInstrumentation::register(AttributeScanner::scan([OrderService::class]));

Manual registration

Skip AttributeScanner and hand register() the method map directly:

ClassInstrumentation::register([
    OrderService::class => [
        'pay'    => ['orderId' => 0],  // trace, capture orderId only
        'cancel' => [],                // trace, capture nothing
        // methods not listed are not traced
    ],
]);

Each entry maps a class → its methods → each method's arguments (name => position). Anything not listed is not traced or not captured.

Traced output

Selecting what to trace

include and exclude behave the same wherever they appear — #[Trace], #[TraceArguments], #[TraceProperties]:

An empty include means "no allowlist" (everything), not "nothing".

Only public methods are traced and only public properties are expanded — protected and private are ignored.

Argument serialization

Each captured argument is serialized to a span-compatible value:

Object expansion via #[TraceProperties]:

• Each public property becomes its own attribute, keyed argument.property (e.g. address.city).
• Recursive and unbounded — a nested property keeps expanding while its class also has #[TraceProperties]; otherwise it falls back to the rules above.
• An uninitialized typed property is recorded as "uninitialized".
• Circular references are broken — a repeated object degrades to its class name.
• Any reflection or __toString() failure falls back to the class name, so serialization never breaks the traced call. (A failed array encode falls back to "array".)

Span structure

Each traced call produces an INTERNAL span named ClassName::methodName, with:

If the method throws, the span records an exception event and its status is set to ERROR:

How it works

AttributeScanner::scan() reflects over the classes you pass it:

1. Skips abstract classes, interfaces, traits, and enums.
2. Reads #[Trace] on the class — no attribute, no instrumentation.
3. Collects the public methods allowed by include / exclude, and for each the arguments allowed by #[TraceArguments].

It returns a class → method → {argument: position} map. ClassInstrumentation::register() then installs an ext-opentelemetry hook on every mapped method:

• pre — opens the span and attaches the code.* attributes and serialized arguments.
• post — records the exception and sets ERROR status if the method threw, then ends the span.

Disabling instrumentation

OTEL_PHP_DISABLED_INSTRUMENTATIONS=class