Trace method

* feat(core): add TraceMethod attribute with return and exception control

Replace the argument-only TraceArguments attribute with a unified
TraceMethod attribute that governs all method-level tracing from one
place. Beyond capturing arguments, it can now record the return value
as a span attribute and toggle exception recording independently, so
callers can trace outcomes without leaking sensitive stack details.
When exception recording is off, the span is still marked as errored
without attaching the exception message.

* refactor(core): replace TraceArguments with TraceMethod

feat(core): capture return values and control exception recording

Remove the deprecated TraceArguments attribute now that TraceMethod
supersedes it, and migrate all fixtures, tests and benchmarks to the
new attribute. The scan map now carries per-method arguments, return
and exception flags instead of a bare argument-position map, so
callers can toggle argument capture, return-value recording and
exception details independently.

Raise the phpbench memory_limit to 512M to keep class-generation
benchmarks from exhausting memory.

---
Header is two lines because the change is genuinely both a rename and a feature; collapse to just the `refactor` line if you want one type. → skipped: nothing.

* refactor(docs): rename TraceArguments to TraceMethod

Align the READMEs with the renamed attribute, which now captures
the return value and records exceptions in addition to arguments.
Document the new `arguments`/`return`/`exception` flags on both
the attribute and the direct `register()` method map, plus the
`code.return` span attribute and the exception-event opt-out.

* feat(deps): pin internal package to self.version in bundles

Ensure the Laravel and Symfony bundles always require the exact
core package version from this monorepo instead of a loose ^0.3
constraint, keeping them in lockstep on every release.

Author: eerzho

benchmarks/ClassGenerator.php

@@ -48,7 +48,7 @@ public function update(int \$id, string \$name, ?array \$options = null): void {
                         public function delete(int \$id): void {}
                         public function import(array \$items, bool \$force, ?\\DateTimeImmutable \$scheduledAt = null): void {}
                         public function export(string \$format, array \$filters): string { return ''; }
-                        #[\\Eerzho\\Instrumentation\\Class\\Attribute\\TraceArguments(exclude: ['password', 'token'])]
+                        #[\\Eerzho\\Instrumentation\\Class\\Attribute\\TraceMethod(exclude: ['password', 'token'])]
                         public function authenticate(string \$login, string \$password, string \$token): bool { return true; }
                     }
                 ");

packages/core/README.md

@@ -30,7 +30,7 @@ namespace App\Service;
 
 class OrderService
 {
-    public function pay(int $orderId, string $card, Address $address): void {}
+    public function pay(int $orderId, string $card, Address $address): string {}
     public function healthCheck(): bool {}
 }
 
@@ -49,21 +49,23 @@ use Eerzho\Instrumentation\Class\Attribute\Trace;
 // #[Trace(include: ['pay'])]        // or: only pay
 class OrderService
 {
-    public function pay(int $orderId, string $card, Address $address): void {}
+    public function pay(int $orderId, string $card, Address $address): string {}
     public function healthCheck(): bool {}
 }
 ```
 
-### 2. `#[TraceArguments]` — pick the captured arguments
+### 2. `#[TraceMethod]` — capture arguments, return value, and exceptions
 
 ```php
-use Eerzho\Instrumentation\Class\Attribute\TraceArguments;
+use Eerzho\Instrumentation\Class\Attribute\TraceMethod;
 
-#[TraceArguments(exclude: ['card'])]       // capture every arg but card
-// #[TraceArguments(include: ['orderId'])] // or: only orderId
-public function pay(int $orderId, string $card, Address $address): void {}
+#[TraceMethod(exclude: ['card'])]       // capture every arg but card
+// #[TraceMethod(include: ['orderId'])] // or: only orderId
+public function pay(int $orderId, string $card, Address $address): string {}
 ```
 
+By default, it captures the arguments and the return value, and records exceptions. Turn each off with `arguments: false`, `return: false`, or `exception: false` (a disabled exception still sets the span status to `ERROR`, only its event is omitted).
+
 ### 3. `#[TraceProperties]` — expand an object argument
 
 ```php
@@ -95,20 +97,24 @@ Skip `AttributeScanner` and hand `register()` the method map directly:
 ```php
 ClassInstrumentation::register([
     OrderService::class => [
-        'pay'    => ['orderId' => 0],  // trace, capture orderId only
-        'cancel' => [],                // trace, capture nothing
+        'pay' => [
+            'arguments' => ['orderId' => 0],  // name => position
+            'return'    => true,
+            'exception' => true,
+        ],
+        'cancel' => ['arguments' => []],      // 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.
+Each method maps to its `arguments` (`name => position`) plus the `return` and `exception` flags. Missing keys default to off. Anything not listed is not traced.
 
 ## Traced output
 
 ### Selecting what to trace
 
-`include` and `exclude` behave the same wherever they appear — `#[Trace]`, `#[TraceArguments]`, `#[TraceProperties]`:
+`include` and `exclude` behave the same wherever they appear — `#[Trace]`, `#[TraceMethod]`, `#[TraceProperties]`:
 
 | `include` | `exclude` | Result                                    |
 |-----------|-----------|-------------------------------------------|
@@ -149,12 +155,13 @@ Object expansion via `#[TraceProperties]`:
 
 Each traced call produces an `INTERNAL` span named `ClassName::methodName`, with:
 
-| Attribute            | Value                             |
-|----------------------|-----------------------------------|
-| `code.function.name` | `ClassName::methodName`           |
-| `code.file.path`     | File where the method is defined  |
-| `code.line.number`   | Line number of the method         |
-| Method arguments     | Parameter name → serialized value |
+| Attribute            | Value                                                                      |
+|----------------------|----------------------------------------------------------------------------|
+| `code.function.name` | `ClassName::methodName`                                                    |
+| `code.file.path`     | File where the method is defined                                           |
+| `code.line.number`   | Line number of the method                                                  |
+| `code.return`        | Return value, serialized the same way (on success, unless `return: false`) |
+| Method arguments     | Parameter name → serialized value                                          |
 
 If the method throws, the span records an `exception` event and its status is set to `ERROR`:
 
@@ -164,18 +171,20 @@ If the method throws, the span records an `exception` event and its status is se
 | `exception.message`    | Exception message    |
 | `exception.stacktrace` | Full stack trace     |
 
+With `exception: false` the status still becomes `ERROR`, but the event above is omitted.
+
 ## 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]`.
+3. Collects the public methods allowed by `include` / `exclude`, and for each the arguments, return value, and exception recording configured by `#[TraceMethod]`.
 
-It returns a `class → method → {argument: position}` map. `ClassInstrumentation::register()` then installs an `ext-opentelemetry` hook on every mapped method:
+It returns a `class → method → {arguments, return, exception}` 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.
+- **post** — captures the return value on success, records the exception and sets `ERROR` status on failure, then ends the span.
 
 ## Disabling instrumentation
 

…es/core/src/Attribute/TraceArguments.php …kages/core/src/Attribute/TraceMethod.phppackages/core/src/Attribute/TraceArguments.php renamed to packages/core/src/Attribute/TraceMethod.php packages/core/src/Attribute/TraceArguments.php renamed to packages/core/src/Attribute/TraceMethod.php

@@ -7,15 +7,18 @@
 use Attribute;
 
 #[Attribute(Attribute::TARGET_METHOD)]
-final readonly class TraceArguments
+final readonly class TraceMethod
 {
     /**
      * @param list<string> $include
      * @param list<string> $exclude
      */
     public function __construct(
+        public bool $arguments = true,
         public array $include = [],
         public array $exclude = [],
+        public bool $return = true,
+        public bool $exception = true,
     ) {
     }
 }

packages/core/src/AttributeScanner.php

@@ -5,7 +5,7 @@
 namespace Eerzho\Instrumentation\Class;
 
 use Eerzho\Instrumentation\Class\Attribute\Trace;
-use Eerzho\Instrumentation\Class\Attribute\TraceArguments;
+use Eerzho\Instrumentation\Class\Attribute\TraceMethod;
 use ReflectionClass;
 use ReflectionException;
 use ReflectionMethod;
@@ -20,7 +20,7 @@ final class AttributeScanner
      *
      * @throws ReflectionException
      *
-     * @return array<class-string, array<string, array<string, int>>>
+     * @return array<class-string, array<string, array{arguments: array<string, int>, return: bool, exception: bool}>>
      */
     public static function scan(array $classes): array
     {
@@ -41,7 +41,7 @@ public static function scan(array $classes): array
      *
      * @throws ReflectionException
      *
-     * @return array<string, array<string, int>>
+     * @return array<string, array{arguments: array<string, int>, return: bool, exception: bool}>
      */
     private static function scanClass(string $class): array
     {
@@ -61,7 +61,7 @@ private static function scanClass(string $class): array
     /**
      * @param ReflectionClass<object> $class
      *
-     * @return array<string, array<string, int>>
+     * @return array<string, array{arguments: array<string, int>, return: bool, exception: bool}>
      */
     private static function scanMethods(ReflectionClass $class): array
     {
@@ -73,32 +73,38 @@ private static function scanMethods(ReflectionClass $class): array
         $methodsMap = [];
         foreach ($class->getMethods(ReflectionMethod::IS_PUBLIC) as $method) {
             if (self::isAllowed($method->getName(), $attribute->include, $attribute->exclude)) {
-                $methodsMap[$method->getName()] = self::scanArguments($method);
+                $methodsMap[$method->getName()] = self::scanMethod($method);
             }
         }
 
         return $methodsMap;
     }
 
     /**
-     * @return array<string, int>
+     * @return array{arguments: array<string, int>, return: bool, exception: bool}
      */
-    private static function scanArguments(ReflectionMethod $method): array
+    private static function scanMethod(ReflectionMethod $method): array
     {
-        $attribute = self::findTraceArguments($method);
+        $attribute = self::findTraceMethod($method);
         if ($attribute === null) {
-            return [];
+            return ['arguments' => [], 'return' => false, 'exception' => false];
         }
 
         $arguments = [];
-        foreach ($method->getParameters() as $parameter) {
-            $name = $parameter->getName();
-            if (self::isAllowed($name, $attribute->include, $attribute->exclude)) {
-                $arguments[$name] = $parameter->getPosition();
+        if ($attribute->arguments) {
+            foreach ($method->getParameters() as $parameter) {
+                $name = $parameter->getName();
+                if (self::isAllowed($name, $attribute->include, $attribute->exclude)) {
+                    $arguments[$name] = $parameter->getPosition();
+                }
             }
         }
 
-        return $arguments;
+        return [
+            'arguments' => $arguments,
+            'return' => $attribute->return,
+            'exception' => $attribute->exception,
+        ];
     }
 
     /**
@@ -127,12 +133,12 @@ private static function findTrace(ReflectionClass $class): ?Trace
         return $instance;
     }
 
-    private static function findTraceArguments(ReflectionMethod $method): ?TraceArguments
+    private static function findTraceMethod(ReflectionMethod $method): ?TraceMethod
     {
-        $attributes = $method->getAttributes(TraceArguments::class);
+        $attributes = $method->getAttributes(TraceMethod::class);
         $instance = $attributes !== [] ? $attributes[0]->newInstance() : null;
 
-        assert($instance instanceof TraceArguments || $instance === null);
+        assert($instance instanceof TraceMethod || $instance === null);
 
         return $instance;
     }

packages/core/src/ClassInstrumentation.php

@@ -37,7 +37,7 @@ final class ClassInstrumentation
     public const NAME = 'class';
 
     /**
-     * @param array<class-string, array<string, array<string, int>>> $classesMap
+     * @param array<class-string, array<string, array{arguments?: array<string, int>, return?: bool, exception?: bool}>> $classesMap
      */
     public static function register(array $classesMap): void
     {
@@ -47,22 +47,24 @@ public static function register(array $classesMap): void
         );
 
         foreach ($classesMap as $class => $methods) {
-            foreach ($methods as $method => $arguments) {
-                self::registerHook($instrumentation, $class, $method, $arguments);
+            foreach ($methods as $method => $config) {
+                self::registerHook($instrumentation, $class, $method, $config);
             }
         }
     }
 
     /**
-     * @param array<string, int> $arguments
+     * @param array{arguments?: array<string, int>, return?: bool, exception?: bool} $config
      */
     private static function registerHook(
         CachedInstrumentation $instrumentation,
         string $class,
         string $method,
-        array $arguments,
+        array $config,
     ): void {
-        $positionToName = array_flip($arguments);
+        $positionToName = array_flip($config['arguments'] ?? []);
+        $captureReturn = $config['return'] ?? false;
+        $recordException = $config['exception'] ?? false;
 
         hook(
             $class,
@@ -85,6 +87,7 @@ private static function registerHook(
                 foreach ($positionToName as $position => $name) {
                     if (array_key_exists($position, $params)) {
                         foreach (self::serialize($name, $params[$position]) as $key => $value) {
+                            assert($key !== '');
                             $builder->setAttribute($key, $value);
                         }
                     }
@@ -98,7 +101,7 @@ private static function registerHook(
                 array $params,
                 mixed $returnValue,
                 ?Throwable $exception,
-            ): void {
+            ) use ($captureReturn, $recordException): void {
                 $scope = Context::storage()->scope();
                 if ($scope === null) {
                     return;
@@ -108,8 +111,17 @@ private static function registerHook(
                 $span = Span::fromContext($scope->context());
 
                 if ($exception !== null) {
-                    $span->recordException($exception);
-                    $span->setStatus(StatusCode::STATUS_ERROR, $exception->getMessage());
+                    if ($recordException) {
+                        $span->recordException($exception);
+                        $span->setStatus(StatusCode::STATUS_ERROR, $exception->getMessage());
+                    } else {
+                        $span->setStatus(StatusCode::STATUS_ERROR);
+                    }
+                } elseif ($captureReturn) {
+                    foreach (self::serialize('code.return', $returnValue) as $key => $value) {
+                        assert($key !== '');
+                        $span->setAttribute($key, $value);
+                    }
                 }
 
                 $span->end();

packages/laravel/README.md

@@ -49,14 +49,14 @@ Add `#[Trace]` to any class in a scanned namespace:
 namespace App\Services;
 
 use Eerzho\Instrumentation\Class\Attribute\Trace;
-use Eerzho\Instrumentation\Class\Attribute\TraceArguments;
+use Eerzho\Instrumentation\Class\Attribute\TraceMethod;
 use Eerzho\Instrumentation\Class\Attribute\TraceProperties;
 
 #[Trace(exclude: ['healthCheck'])]         // trace public methods, but hide "healthCheck"
 class OrderService
 {
     // span "App\Services\OrderService::pay"
-    #[TraceArguments(exclude: ['card'])]   // hide "card" from the span
+    #[TraceMethod(exclude: ['card'])]   // hide "card" from the span
     public function pay(int $orderId, string $card, Address $address): void {}
 
     public function healthCheck(): bool {}

packages/laravel/composer.json

@@ -30,7 +30,7 @@
     "php": ">=8.2",
     "ext-opentelemetry": "*",
     "open-telemetry/api": "^1.0",
-    "eerzho/opentelemetry-auto-class": "^0.3",
+    "eerzho/opentelemetry-auto-class": "self.version",
     "illuminate/support": "^11.0 || ^12.0 || ^13.0"
   },
   "autoload": {

packages/symfony/README.md

@@ -40,14 +40,14 @@ Add `#[Trace]` to any class registered as a service:
 namespace App\Service;
 
 use Eerzho\Instrumentation\Class\Attribute\Trace;
-use Eerzho\Instrumentation\Class\Attribute\TraceArguments;
+use Eerzho\Instrumentation\Class\Attribute\TraceMethod;
 use Eerzho\Instrumentation\Class\Attribute\TraceProperties;
 
 #[Trace(exclude: ['healthCheck'])]         // trace public methods, but hide "healthCheck"
 class OrderService
 {
     // span "App\Service\OrderService::pay"
-    #[TraceArguments(exclude: ['card'])]   // hide "card" from the span
+    #[TraceMethod(exclude: ['card'])]   // hide "card" from the span
     public function pay(int $orderId, string $card, Address $address): void {}
 
     public function healthCheck(): bool {}

packages/symfony/composer.json

@@ -30,7 +30,7 @@
     "php": ">=8.2",
     "ext-opentelemetry": "*",
     "open-telemetry/api": "^1.0",
-    "eerzho/opentelemetry-auto-class": "^0.3",
+    "eerzho/opentelemetry-auto-class": "self.version",
     "symfony/http-kernel": "^6.0 || ^7.0 || ^8.0",
     "symfony/dependency-injection": "^6.0 || ^7.0 || ^8.0"
   },

packages/symfony/src/AutoClassBundle.php

@@ -61,7 +61,7 @@ public function boot(): void
             return;
         }
 
-        /** @var array<class-string, array<string, array<string, int>>> $classesMap */
+        /** @var array<class-string, array<string, array{arguments?: array<string, int>, return?: bool, exception?: bool}>> $classesMap */
         $classesMap = $this->container->getParameter('otel.trace.classes_map');
         ClassInstrumentation::register($classesMap);
     }