supabase-js теперь передает контекст трассировки W3C в 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 в активный интервал (span), чтобы появилась трассировка для передачи:
_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. Для локальных конфигураций (self-hosted), использующих коллектор 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 молча не отправляли заголовки трассировки в упакованных приложениях, поэтому проблему решает именно обновление, а не просто добавление импорта.
Полная инструкция по настройке, включая параметры семплирования, приведена в руководстве по клиентской трассировке.
