diff --git a/AGENTS.md b/AGENTS.md index b84bc89c3b..edaeff9ea5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -117,7 +117,7 @@ Common injections: `$response`, `$request`, `$dbForProject`, `$dbForPlatform`, ` ## Tracing with Utopia Span -In handlers, only call `Span::add($key, $value)`. **Never** call `Span::init`, `Span::error`, or `Span::finish` -- lifecycle is owned by the entry-point harness (`app/http.php`, `app/worker.php`, `app/realtime.php`, `Bus::dispatch`). For selective export, filter in the sampler in `app/init/span.php`. +In handlers, only call `Span::add($key, $value)`. **Never** call `Span::init`, `setError`, or `Span::finish` -- lifecycle is owned by the entry-point harness (`app/http.php`, `app/worker.php`, `app/realtime.php`, `Bus::dispatch`). For selective export, filter in the sampler in `app/init/span.php`. Keys are `snake_case` with dots only for child relationships: `project.id` (id of project), `storage.bucket.id`. No dot otherwise: `inbound_bytes`, not `inbound.bytes`. No camelCase, no bare top-level keys (`function.id`, not `functionId`). diff --git a/app/controllers/general.php b/app/controllers/general.php index 219c14774f..cb25803b4c 100644 --- a/app/controllers/general.php +++ b/app/controllers/general.php @@ -1198,7 +1198,7 @@ Http::error() $line = $error->getLine(); $trace = $error->getTrace(); - Span::error($error); + Span::current()?->setError($error); switch ($class) { case Utopia\Http\Exception::class: diff --git a/app/http.php b/app/http.php index 6226026a16..a6fc6df13b 100644 --- a/app/http.php +++ b/app/http.php @@ -529,6 +529,7 @@ $swoole->onRequest(function ($utopiaRequest, $utopiaResponse) use ($files, $swoo $app->setCompression(System::getEnv('_APP_COMPRESSION_ENABLED', 'enabled') === 'enabled'); $app->setCompressionMinSize(intval(System::getEnv('_APP_COMPRESSION_MIN_SIZE_BYTES', '1024'))); // 1KB + $error = null; try { $authorization = $app->context()->get('authorization'); @@ -542,7 +543,7 @@ $swoole->onRequest(function ($utopiaRequest, $utopiaResponse) use ($files, $swoo $route = $app->match($request)?->route; Span::add('http.path', $route?->getPath() ?? 'unknown'); } catch (\Throwable $th) { - Span::error($th); + $error = $th; $version = System::getEnv('_APP_VERSION', 'UNKNOWN'); @@ -631,7 +632,7 @@ $swoole->onRequest(function ($utopiaRequest, $utopiaResponse) use ($files, $swoo $swooleResponse->end(\json_encode($output)); } finally { Span::add('http.response.code', $response->getStatusCode()); - Span::current()?->finish(); + Span::current()?->finish(error: $error); } }); diff --git a/app/init/span.php b/app/init/span.php index f6871badfa..4249daa2ac 100644 --- a/app/init/span.php +++ b/app/init/span.php @@ -12,7 +12,7 @@ $traceProjectId = System::getEnv('_APP_TRACE_PROJECT_ID', ''); $traceFunctionId = System::getEnv('_APP_TRACE_FUNCTION_ID', ''); $traceEnabled = $traceProjectId !== '' || $traceFunctionId !== ''; -Span::addExporter(new Exporter\Pretty(), function (Span $span) use ($traceEnabled, $traceProjectId, $traceFunctionId): bool { +Span::setExporters(new Exporter\Pretty(sampler: function (Span $span) use ($traceEnabled, $traceProjectId, $traceFunctionId): bool { if (\str_starts_with($span->getAction(), 'listener.')) { return $span->getError() !== null; } @@ -29,4 +29,4 @@ Span::addExporter(new Exporter\Pretty(), function (Span $span) use ($traceEnable } return true; -}); +})); diff --git a/app/realtime.php b/app/realtime.php index c99e4c0857..4d638818f5 100644 --- a/app/realtime.php +++ b/app/realtime.php @@ -845,6 +845,7 @@ $server->onOpen(function (int $connection, SwooleRequest $request) use ($server, Span::add('realtime.origin', $request->getOrigin()); } + $error = null; try { /** @var Document $project */ $project = $connectionContainer->get('project'); @@ -1009,7 +1010,7 @@ $server->onOpen(function (int $connection, SwooleRequest $request) use ($server, $success = true; } catch (Throwable $th) { - Span::error($th); + $error = $th; // Convert known Utopia DB exceptions to AppwriteException so isPublishable() // suppresses expected client errors (permission denied, query timeout) from Sentry. @@ -1067,7 +1068,7 @@ $server->onOpen(function (int $connection, SwooleRequest $request) use ($server, if (!empty($logUser?->getId())) { Span::add('user.id', $logUser->getId()); } - Span::current()?->finish(); + Span::current()?->finish(error: $error); } }); @@ -1086,6 +1087,7 @@ $server->onMessage(function (int $connection, string $message) use ($container, Span::add('realtime.inbound_bytes', $rawSize); Span::add('realtime.container.id', $containerId); + $error = null; try { $response = new Response(new SwooleResponse()); @@ -1213,7 +1215,7 @@ $server->onMessage(function (int $connection, string $message) use ($container, $success = true; } catch (Throwable $th) { - Span::error($th); + $error = $th; // Convert known Utopia DB exceptions to AppwriteException so isPublishable() // suppresses expected client errors (permission denied, query timeout) from Sentry. @@ -1259,7 +1261,7 @@ $server->onMessage(function (int $connection, string $message) use ($container, Span::add('project.id', $project?->getId() ?? $projectId); Span::add('user.id', $realtime->connections[$connection]['userId'] ?? null); Span::add('realtime.message_type', $messageType); - Span::current()?->finish(); + Span::current()?->finish(error: $error); } }); @@ -1346,7 +1348,7 @@ $server->onClose(function (int $connection) use ($realtime, $stats, $register, $ ); $presenceState->triggerUsage($publisherForUsage, $project, -$deletionCount); } catch (Throwable $th) { - Span::error($th); + Span::current()?->setError($th); logError($th, 'realtimeOnClosePresenceDeletion', tags: [ 'projectId' => $projectId, 'presences' => \count($presences) @@ -1373,7 +1375,7 @@ $server->onClose(function (int $connection) use ($realtime, $stats, $register, $ } } } catch (Throwable $th) { - Span::error($th); + Span::current()?->setError($th); logError($th, 'realtimeOnClosePresenceCleanup', tags: [ 'projectId' => $projectId, ]); @@ -1392,13 +1394,13 @@ $server->onClose(function (int $connection) use ($realtime, $stats, $register, $ // Log only; do not rethrow. If we let this bubble, Swoole dumps full coroutine // backtraces and unsubscribe() below would never run (connection cleanup would fail). Console::error('Realtime onClose error: ' . $th->getMessage()); - Span::error($th); + Span::current()?->setError($th); } finally { try { $realtime->unsubscribe($connection); } catch (\Throwable $th) { Console::error('Realtime onClose unsubscribe error: ' . $th->getMessage()); - Span::error($th); + Span::current()?->setError($th); } Span::add('realtime.success', $success); diff --git a/app/worker.php b/app/worker.php index a7a1f7633d..999bcbc9c6 100644 --- a/app/worker.php +++ b/app/worker.php @@ -118,7 +118,7 @@ $worker ->action(function (Throwable $error, ?Logger $logger, Log $log, Document $project, Authorization $authorization) use ($queueName) { $version = System::getEnv('_APP_VERSION', 'UNKNOWN'); - Span::error($error); + Span::current()?->setError($error); if ($logger) { $log->setNamespace('appwrite-worker'); diff --git a/composer.json b/composer.json index 431a175515..e1ab3c62ab 100644 --- a/composer.json +++ b/composer.json @@ -80,7 +80,7 @@ "utopia-php/migration": "1.*", "utopia-php/platform": "1.0.0-rc5", "utopia-php/pools": "1.*", - "utopia-php/span": "1.1.*", + "utopia-php/span": "3.0.*", "utopia-php/preloader": "0.2.*", "utopia-php/queue": "0.20.*", "utopia-php/servers": "0.4.*", diff --git a/composer.lock b/composer.lock index 1c01b85ed8..af1527d3cd 100644 --- a/composer.lock +++ b/composer.lock @@ -4,7 +4,7 @@ "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies", "This file is @generated automatically" ], - "content-hash": "182aa10ce3b77b8cf38eefc25944e939", + "content-hash": "e922d0ba4d0c7d12cc24cff52b552803", "packages": [ { "name": "adhocore/jwt", @@ -3839,22 +3839,22 @@ }, { "name": "utopia-php/dns", - "version": "1.7.2", + "version": "1.7.3", "source": { "type": "git", "url": "https://github.com/utopia-php/dns.git", - "reference": "5225f52a82d4128e69ad17c2a81fcfea6aa00ae1" + "reference": "5ee1c165b381c05fea1ad9dd62263a5a854786f8" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/utopia-php/dns/zipball/5225f52a82d4128e69ad17c2a81fcfea6aa00ae1", - "reference": "5225f52a82d4128e69ad17c2a81fcfea6aa00ae1", + "url": "https://api.github.com/repos/utopia-php/dns/zipball/5ee1c165b381c05fea1ad9dd62263a5a854786f8", + "reference": "5ee1c165b381c05fea1ad9dd62263a5a854786f8", "shasum": "" }, "require": { "php": ">=8.3", "utopia-php/domains": "^2.0", - "utopia-php/span": "1.1.*", + "utopia-php/span": "3.0.*", "utopia-php/telemetry": "*", "utopia-php/validators": "0.*" }, @@ -3890,9 +3890,9 @@ ], "support": { "issues": "https://github.com/utopia-php/dns/issues", - "source": "https://github.com/utopia-php/dns/tree/1.7.2" + "source": "https://github.com/utopia-php/dns/tree/1.7.3" }, - "time": "2026-05-20T04:49:11+00:00" + "time": "2026-06-07T14:02:16+00:00" }, { "name": "utopia-php/domains", @@ -4908,16 +4908,16 @@ }, { "name": "utopia-php/span", - "version": "1.1.5", + "version": "3.0.1", "source": { "type": "git", "url": "https://github.com/utopia-php/span.git", - "reference": "028406940ca92bdc88099f0b1a123a3b2cbdd4e5" + "reference": "97f0ab6e9125c000262f8b5b007423d11fd1a9b3" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/utopia-php/span/zipball/028406940ca92bdc88099f0b1a123a3b2cbdd4e5", - "reference": "028406940ca92bdc88099f0b1a123a3b2cbdd4e5", + "url": "https://api.github.com/repos/utopia-php/span/zipball/97f0ab6e9125c000262f8b5b007423d11fd1a9b3", + "reference": "97f0ab6e9125c000262f8b5b007423d11fd1a9b3", "shasum": "" }, "require": { @@ -4946,9 +4946,9 @@ "description": "Simple span tracing library for PHP with coroutine support", "support": { "issues": "https://github.com/utopia-php/span/issues", - "source": "https://github.com/utopia-php/span/tree/1.1.5" + "source": "https://github.com/utopia-php/span/tree/3.0.1" }, - "time": "2026-02-13T18:00:11+00:00" + "time": "2026-05-13T11:53:06+00:00" }, { "name": "utopia-php/storage", diff --git a/src/Appwrite/Platform/Tasks/Interval.php b/src/Appwrite/Platform/Tasks/Interval.php index 836508c73d..aaf09c494e 100644 --- a/src/Appwrite/Platform/Tasks/Interval.php +++ b/src/Appwrite/Platform/Tasks/Interval.php @@ -60,12 +60,13 @@ class Interval extends Action $timers[] = Timer::tick($task['interval'], function () use ($task, $dbForPlatform, $getProjectDB, $publisherForCertificates) { $taskName = $task['name']; Span::init("interval.{$taskName}"); + $error = null; try { $task['callback']($dbForPlatform, $getProjectDB, $publisherForCertificates); } catch (\Exception $e) { - Span::error($e); + $error = $e; } finally { - Span::current()?->finish(); + Span::current()?->finish(error: $error); } }); }