Debug Realtime with Logger and Log Levels

logger 和 log_level 参数是什么？ #

🌐 What are logger and log_level parameters?

实时客户端提供内置日志功能，帮助你调试连接问题、跟踪消息，并了解实时连接的情况。有两个参数可以控制日志记录：

🌐 The Realtime client provides built-in logging to help you debug connection issues, track messages, and understand what's happening with your real-time connections. Two parameters control logging:

logger：一个处理日志消息的自定义函数
logLevel: 控制服务器记录哪些消息（info、warn 或 error）

默认情况下，日志记录是禁用的。启用后，你可以看到：

🌐 By default, logging is disabled. When enabled, you can see:

发送和接收的消息
连接事件（连接、断开、错误）
心跳状态
通道订阅
员工活动

如何在你的实时客户端启用日志记录 #

🌐 How to enable logging in your Realtime client

基本控制台日志 #

🌐 Basic logging to console

1
import { createClient } from '@supabase/supabase-js'
2
3
const supabase = createClient(SUPABASE_URL, SUPABASE_KEY, {
4
  realtime: {
5
    logger: (kind, msg, data) => {
6
      console.log(`${kind}: ${msg}`, data)
7
    },
8
  },
9
})

带有服务器端过滤的日志级别 #

🌐 With log levels for server-side filtering

1
const supabase = createClient(SUPABASE_URL, SUPABASE_KEY, {
2
  realtime: {
3
    logLevel: 'info', // 'info' | 'warn' | 'error'
4
    logger: (kind, msg, data) => {
5
      console.log(`[${kind}] ${msg}`, data)
6
    },
7
  },
8
})

理解日志信息 #

🌐 Understanding log messages

记录器接收三个参数：kind、msg 和 data。

🌐 The logger receives three parameters: kind, msg, and data.

你会看到的日志类型：

push - 发送到服务器的消息

1
push: realtime:chat heartbeat (42) {}
2
push: realtime:chat phx_join (1) { config: {...} }

receive - 从服务器接收到的消息

1
receive: ok realtime:chat phx_reply (1) { response: {...} }
2
receive: realtime:chat broadcast { event: 'message', payload: {...} }

transport - 连接事件

1
transport: connected to wss://project.supabase.co/realtime/v1
2
transport: heartbeat timeout. Attempting to re-establish connection
3
transport: close CloseEvent {...}
4
transport: leaving duplicate topic "realtime:chat"

error - 错误事件

1
error: error in heartbeat callback Error: ...
2
error: error waiting for auth on connect Error: ...

worker - Web Worker 事件

1
worker: starting default worker
2
worker: starting worker for from /worker.js
3
worker: worker error message

常见调试场景

调试通道无法订阅的原因：

1
import { createClient } from '@supabase/supabase-js'
2
3
const supabase = createClient(SUPABASE_URL, SUPABASE_KEY, {
4
  realtime: {
5
    logger: (kind, msg, data) => {
6
      console.log(`[${kind}] ${msg}`, data)
7
    },
8
  },
9
})
10
11
const channel = supabase
12
  .channel('debug-channel')
13
  .on('broadcast', { event: 'test' }, (payload) => {
14
    console.log('Received:', payload)
15
  })
16
  .subscribe((status, err) => {
17
    console.log('Subscribe status:', status, err)
18
  })
19
20
// Check logs for:
21
// push: realtime:debug-channel phx_join - subscription attempt
22
// receive: ok realtime:debug-channel phx_reply - successful subscription
23
// Or error messages if subscription failed

调试消息投递问题 #

🌐 Debug message delivery issues

1
const supabase = createClient(SUPABASE_URL, SUPABASE_KEY, {
2
  realtime: {
3
    logger: (kind, msg, data) => {
4
      if (kind === 'push' || kind === 'receive') {
5
        console.log(`[${kind}] ${msg}`, data)
6
      }
7
    },
8
  },
9
})
10
11
const channel = supabase.channel('chat', { config: { broadcast: { self: true } } })
12
13
channel.on('broadcast', { event: 'message' }, (payload) => {
14
  console.log('Message received:', payload)
15
})
16
// Send message after subscribing
17
channel.subscribe((status, err) => {
18
  if (status == 'SUBSCRIBED') {
19
    channel.send({
20
      type: 'broadcast',
21
      event: 'message',
22
      payload: { text: 'Hello' },
23
    })
24
  } else {
25
    console.error({ status, err })
26
  }
27
})
28
29
// Check logs:
30
// push: realtime:chat broadcast - message sent
31
// receive: realtime:chat broadcast - message received (if self: true)