Spans model per-action operations (open/message/close); they're a poor fit for ad-hoc
events with no operation lifecycle. Split logError to dispatch by whether a span is
active:
- Active span (realtime.open / realtime.message / realtime.close catches) -> attach
the error to the existing span; the Sentry span exporter ships it with full operation
context (attributes, duration, trace_id).
- No active span (pub/sub subscriber, onStart, Swoole error handler, updateWorkerDocument)
-> push a utopia/logger Log via the realtimeLogger registry. Goes to Sentry as an event
via the Sentry logger adapter (or to logOwl / Raygun / AppSignal). Same dedicated
Realtime project either way.
Restores the realtimeLogger registry (dropped in the previous "spans only" pass), inlines
the now-single-caller $createLogger closure into the logger registry, and drops the
recordRealtimeErrorSpan helper — logError is the only function on this path now.
Also registers a Pretty span exporter in app/init/realtime/span.php for non-self-hosted
editions so Realtime spans are visible in the container's stdout (on self-hosted the
existing app/init/span.php already provides it; gating avoids duplicate output).
Collapse the multi-line doc blocks on recordRealtimeErrorSpan / pushRealtimeErrorLog /
$createLogger to one line each, drop the redundant require comment, and tighten the
"keep in sync" notes — keeping the cross-references and the double-report hazard.
Move the Realtime Sentry span exporter registration out of app/realtime.php
into app/init/realtime/span.php (mirrors app/init/span.php / app/init/realtime/
connection.php), and split the now-80-line logError() into recordRealtimeErrorSpan()
(span path) and pushRealtimeErrorLog() (legacy utopia/logger path, non-Sentry
providers only), leaving logError() a small orchestrator. No behavior change.
Realtime errors are now recorded onto a span and shipped to a Sentry
project configured via _APP_LOGGING_CONFIG_REALTIME (falls back to
_APP_LOGGING_CONFIG). The Sentry span exporter is registered in
app/realtime.php so it does not affect the HTTP/worker/CLI span
exporters. logError() attaches the error to the active span, or opens a
short-lived realtime.error span for call sites without one (pub/sub
subscriber, onStart, the Swoole error handler), and keeps the legacy
utopia/logger push only for non-Sentry providers; the realtimeLogger
registry now returns null when the provider is Sentry to avoid
double-reporting. Documents _APP_LOGGING_CONFIG_REALTIME.
- Updated span logging keys to use camelCase for uniformity across connection and message events.
- Added checks to ensure project and user IDs are only logged if they are not empty, enhancing data integrity.
- Improved error handling and logging structure to maintain consistency in telemetry data.
- Introduced new arrays to capture subscribed channels and passed queries during connection and message events.
- Enhanced span logging to include details about channels and queries for better monitoring and analysis.
- Updated telemetry data structure to reflect the new metrics, improving traceability of realtime interactions.
- Introduced span logging for connection open and close events, capturing metrics such as inbound and outbound bytes, subscription counts, and response codes.
- Enhanced error handling with logging of exceptions during connection lifecycle.
- Updated the structure of the telemetry data to include project and user IDs for better traceability.
Realtime was ignoring _APP_WORKERS_NUM and always computing workers as
CPU × _APP_WORKER_PER_CORE, making it impossible to cap the worker count
without also changing the per-core multiplier. Prefer _APP_WORKERS_NUM
when set, falling back to the CPU × per-core calculation.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Prem Palanisamy
fogelito
Jake Barnby
ArnabChatterjee20k
loks0nandClaude Opus 4.7
Chirag Aggarwal
Matej Bačo