chore(span): upgrade utopia-php/span to 3.0

Span 3.0 removes `Span::addExporter()` and the static `Span::error()`,
and lets `finish()` take the triggering error directly.

- composer: span 1.1.* -> 3.0.* (pulls dns 1.7.3, the first dns release
  that allows span 3.0; it was the only package pinning span to 1.1.*)
- app/init/span.php: addExporter(exporter, sampler) -> setExporters with
  the sampler passed as the exporter's constructor argument
- replace removed static Span::error($e) with Span::current()?->setError($e)
- in the self-contained request handlers (http onRequest, realtime onOpen
  and onMessage, interval task) pass the error to finish(error: ...) rather
  than setError; setError stays where finish() runs in a separate harness
  callback (worker error handler, http error handler) or where cleanup work
  runs between the error and finish (realtime onClose)
- AGENTS.md: update tracing note (Span::error -> setError)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
loks0nandClaude Opus 4.8 committed 2026-06-07 16:59:26 +01:00
1 parent e882acb992
commit cd87b9942a
9 files changed
+36 -32

No files matched your search

+1 -1
View File
@@ -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`).
+1 -1
View File
@@ -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:
+3 -2
View File
@@ -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);
}
});
+2 -2
View File
@@ -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;
});
}));
+10 -8
View File
@@ -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);
+1 -1
View File
@@ -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');
+1 -1
View File
@@ -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.*",
Generated
+14 -14
View File
@@ -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",
+3 -2
View File
@@ -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);
}
});
}