诊断与日志

问题排查通常从证据收集开始。

这页说明在提交排查信息前应先准备哪些内容，以及客户端和设备端分别如何获取 TiRTC 相关日志。目标不是一次性解释所有故障，而是先把排查所需的证据收集完整。

提交排查信息前先准备这些内容

• 问题发生在哪一侧：设备端、客户端，还是双端同时出现。
• 技术栈与平台：例如 Flutter、Android、iOS、Linux 设备端。
• SDK 版本，以及你的应用版本或设备固件版本。
• 问题发生的准确时间，最好带上时区，并说明是否可以稳定复现。
• 复现步骤：从启动、初始化、建连到出现异常的最短步骤链。
• 现象描述：你期望发生什么，实际看到了什么。
• 关键标识：例如 remote_id、stream_id、cmdw、错误码。
• 可提供的日志凭据：客户端 logId，或设备端原始日志文件。

如果问题涉及双端互通，例如设备端推流但客户端无画面，尽量同时提供两侧日志和同一时间段的复现信息。

客户端

客户端优先使用 SDK 的日志上传能力。建议在问题刚复现后尽快上传，并记录返回的 logId。

Flutter

final ({int code, String? logId}) result = await TiRtcLogging.upload();

if (result.logId != null) {
  debugPrint('TiRTC logId: ${result.logId}');
} else {
  debugPrint('TiRTC log upload failed, code=${result.code}');
}

Android

val accepted = TiRtcLogging.upload { code, logId ->
  if (logId != null) {
    Log.i("TiRTC", "logId=$logId")
  } else {
    Log.w("TiRTC", "upload failed, code=$code")
  }
}

if (accepted != 0) {
  Log.w("TiRTC", "upload request not accepted, code=$accepted")
}

iOS

let accepted = TiRtcDebugging.uploadLogs { code, logId in
    if let logId {
        print("TiRTC logId: \(logId)")
    } else {
        print("TiRTC log upload failed, code=\(code)")
    }
}

if accepted != 0 {
    print("TiRTC log upload request not accepted, code=\(accepted)")
}

• 上传成功时，记录并提交 logId。
• 上传失败时，记录错误码和失败发生时的操作。

设备端

设备端排查的重点是尽早开启日志，并把日志范围覆盖到初始化、鉴权、建连、收发消息和异常发生时刻。对于集成 C SDK 的设备端，通常有两种获取方式：使用 SDK 内置文件日志，或通过回调接管日志输出。

设备端文件日志

TiRtcLogConfig(...) 用于配置 SDK 内置文件日志，这个能力当前仅 Linux 平台有效。建议在 SDK 初始化后、开始实际建连或收发数据前完成配置。以下以 Linux 为例：

TiRtcInit();
TiRtcLogConfig(0, "/tmp/tirtc/device.log", 4 * 1024 * 1024);
TiRtcLogSetLevel(4);

这组配置的含义是：

• TiRtcInit() 先完成 SDK 初始化。
• 第一个参数为 0，表示不额外镜像到控制台；如果你需要同时输出到 stdout，把它改为非 0。
• 日志文件写到 /tmp/tirtc/device.log。
• 单个日志文件最大为 4 * 1024 * 1024 字节，超出后滚动覆盖。

如果设备使用 Flash 存储，优先把日志目录放在临时文件系统，例如 tmpfs，避免持续写盘。

设备端回调日志

TiRtcLogSetCallback(...) 设置后，SDK 会把日志内容通过回调交给应用，不再自行输出到文件或控制台。

#include <stdint.h>
#include <stdio.h>

static void on_tirtc_log(const char *log, uint32_t length) {
  fwrite(log, 1, length, stdout);
}

TiRtcLogSetCallback(on_tirtc_log);
TiRtcLogSetLevel(4);

使用回调模式时请注意：

• 回调拿到的是一段原始日志字节，是否以 NUL 结尾不应假设，处理时以 length 为准。
• 一旦启用回调，日志落盘与控制台输出由你的应用负责。
• 如果你会把日志再写入自己的文件或上报系统，注意脱敏，不要暴露 token、secret_key、device_secret_key 等敏感信息。

提交排查信息时请一并提供

• 客户端 logId，或设备端对应时间段的原始日志文件。
• 最短复现步骤，以及问题是否稳定复现。
• 日志里如果不能直接看出来，再补充异常发生时间、涉及的 remote_id、stream_id、cmdw 或错误码。
• 如果问题涉及双端互通，提供两侧日志，并标明哪一侧先出现异常。

相关文档

• 客户端 API 参考
• 设备端 API 参考
• 客户端错误码
• 设备端错误码