Библиотека supabase-js теперь передает W3C Trace Context в Supabase. Включите эту функцию, и trace_id из клиентских запросов будет передаваться через API Gateway и логи Edge Function в Supabase, что позволит отслеживать единый запрос из браузера вплоть до логов бэкенда.
Представьте, что фронтенд-трейс показывает медленный запрос, уходящий из браузера, а лог Supabase показывает соответствующий запрос на сервере. До сих пор ничто их не связывало: SDK выполнял вызов, Supabase фиксировал его в логах, и эти две записи существовали в разных системах без общего идентификатора. Отладка через эту границу требовала ручного сопоставления временных меток.
Теперь, когда включен параметр tracePropagation, SDK добавляет три стандартных заголовка к запросам, направленным на домены Supabase:
- traceparent
- tracestate
- baggage
Supabase считывает входящий контекст трассировки и проставляет тот же trace_id в генерируемых им логах. Любой трейсер, совместимый со спецификацией W3C (OpenTelemetry, Sentry, Datadog, Honeycomb, Grafana), подхватывает трассировку на стороне сервера.
В этом руководстве рассматривается supabase-js. Передача трассировок также доступна в Swift, Flutter и Python; ознакомьтесь с документацией для настройки под конкретный язык и актуальным списком.
SDK не настраивает OpenTelemetry за вас. Вы используете собственный трейсер, а затем сообщаете клиенту о необходимости передачи контекста.
Сначала настройте OpenTelemetry обычным образом: установите SDK (@opentelemetry/sdk-trace-node для Node, @opentelemetry/sdk-trace-web для браузера), добавьте экспортер и глобально зарегистрируйте TracerProvider. Среда выполнения трассировки должна иметь доступ к @opentelemetry/api в вашем приложении; установите его напрямую, если ваш менеджер пакетов не подтягивает его вместе с SDK.
Затем загрузите среду выполнения трассировки один раз в точке входа вашего приложения и включите передачу на клиенте:
_10
import '@supabase/supabase-js/tracing'
_10
import { createClient } from '@supabase/supabase-js'
_10
_10
const supabase = createClient(SUPABASE_URL, SUPABASE_KEY, {
_10
tracePropagation: true,
_10
Основной бандл не содержит кода OpenTelemetry, именно этот первый импорт связывает их воедино.
Оберните вызовы Supabase в активный спан, чтобы появился трейс для передачи:
_10
await tracer.startActiveSpan('load-dashboard', async (span) => {
_10
const { data } = await supabase.from('profiles').select('*')
_10
span.end()
_10
Если ваш семплер отбрасывает большинство трейсов, но вы все равно хотите передавать запросы Supabase, переопределите решение семплирования:
_10
import '@supabase/supabase-js/tracing'
_10
_10
const supabase = createClient(SUPABASE_URL, SUPABASE_KEY, {
_10
tracePropagation: { enabled: true, respectSamplingDecision: false },
_10
Функция Log Drains перенаправляет ваши логи Supabase во внешний бэкенд. При включенной передаче трассировок каждый перенаправленный лог содержит тот же trace_id, что и трейсы вашего клиента и сервера, поэтому вы можете объединить их в уже используемом интерфейсе трассировки.
В этом случае спан браузера в Sentry и соответствующий лог API Gateway, перенаправленный в Datadog, выстраиваются под одним trace_id. Для локальных инсталляций, использующих коллектор OpenTelemetry, это то же объединение в контролируемой вами инфраструктуре.
Интеграция с OpenTelemetry находится за собственной точкой входа, поэтому основной бандл supabase-js содержит ноль кода OpenTelemetry. В ваш бандл ничего не добавляется и ничего не разрешается на этапе сборки, пока вы сами не подключите эту функцию. Это позволяет не затрагивать React Native/Hermes, Metro и сборщики для Edge-среды, а также означает, что при подключении функции ваш сборщик сможет увидеть зависимость и включить ее.
- Поддержка CDN/UMD отсутствует. Среда выполнения трассировки не может быть загружена с тегом script, поэтому передача трассировок недоступна в сборке для CDN.
- Доступно в supabase-js, Swift, Flutter и Python.
- Только для доменов Supabase. Заголовки прикрепляются к хосту вашего проекта (*.supabase.co, *.supabase.in) и локальным хостам разработки (localhost, 127.0.0.1, [::1]), но никогда к сторонним хостам, даже при использовании кастомного метода fetch.
- Логи API Gateway и Edge Function. На данный момент это источники логов, которые подхватывают trace_id.
- Требуется реальный спан. Если на момент запроса нет активного спана или зарегистрированного TracerProvider (по умолчанию API использует фиктивный провайдер), передавать нечего, и SDK молча выполняет операцию-заглушку (no-op).
- Решения семплирования учитываются по умолчанию. Неотсемплированные трейсы не отправляют заголовки, если вы не установите параметр respectSamplingDecision: false.
Передача трассировок уже доступна в supabase-js. Добавьте import '@supabase/supabase-js/tracing' в точке входа, включите tracePropagation, укажите на него ваш существующий трейсер, и ваши клиентские трейсы совпадут с логами Supabase.
Уже используете tracePropagation из более ранней версии? Обновитесь до supabase-js версии 2.112.0 или выше и добавьте строку import '@supabase/supabase-js/tracing'. Версии с 2.106.0 по 2.111.x молча не отправляли заголовки трассировки в бандл-приложениях, поэтому именно обновление исправляет передачу, а не только добавление импорта.
Полная инструкция по установке, включая параметры семплирования, находится в руководстве по клиентской трассировке.
