实时消息 SDK 故障排查工具使用指南
做开发这些年，我遇到过太多次这样的场景：凌晨三点，手机突然响起，产品经理在电话那头急得跳脚，说用户反馈消息发不出去、收不到、或者延迟得离谱。作为声网的开发者支持团队成员，我太理解这种压力了。实时消息 SDK 看似简单，背后却涉及网络连接、协议握手、消息队列、服务端推送等一堆复杂的环节，一个小问题就可能导致整个链路挂掉。
这篇文章，我想和大家聊聊声网实时消息 SDK 的故障排查工具怎么用。我不会照搬官方文档，那玩意儿太"技术"了，读起来跟看天书似的。我会用最接地气的方式，结合我平时处理工单时积累的经验，把排查思路和方法捋清楚。你可能正在为一个偶发的消息丢失问题焦头烂额，也可能对着日志里一串错误码发呆，不管怎样，希望这篇文章能帮到你。
工欲善其事：认识故障排查的"十八般武器"
在开始排查之前，我们得先搞清楚手里有哪些工具能用。声网为实时消息 SDK 提供了一套完整的诊断体系，我把这些工具分成三类：日志系统、监控面板、以及调试工具。它们各有侧重，配合使用才能快速定位问题。
日志系统：真相都藏在细节里
日志是排查问题的第一手资料，这个不用多说。但很多开发者只看错误级别的日志warn和error，这是不够的。很多时候，问题出在info甚至debug级别，只是表象到error阶段才显现出来。
声网实时消息 SDK 的日志系统做得挺细分的。我建议你在开发阶段把日志级别调到debug，这样能看到完整的连接建立过程、心跳包交互、消息收发每一个环节的详细信息。比如，连接断开这件事，表面上看只是一个"disconnected"的日志，但往前翻，你可能会发现是因为心跳超时、认证失败、还是网络切换导致的。日志级别设置的代码大概是这样的：
如果是 Android 平台，你可以在初始化的时候调用这个方法，把日志级别设成 DEBUG。日志会输出到 logcat，tag 一般是 RtmClient 或者类似的标识，你可以用这个 tag 做过滤。iOS 端也是类似的，Objective-C 或者 Swift 的 API 设计得很直观，初始化配置里直接指定日志级别就行。
日志里有一些关键信息你一定要敏感。比如 connectionStateChanged 这个状态变化，从 CONNECTING 到 CONNECTED 再到 DISCONNECTED，每一次状态跳转都有原因码。声网的 SDK 会把断开原因编码成数字，不同的数字代表不同的问题：网络超时、服务器主动断开、认证token过期、被其他端踢掉、等等。遇到状态跳转异常时，把前后的日志上下文一起保存下来，发给技术支持同事，他们能快速判断问题所在。
监控面板：把问题可视化
日志是事后复盘用的，监控面板则能帮你实时看系统的健康状况。声网控制台有一个"质量监控"入口，里面能看到实时消息通道的各项指标。这里我要重点说几个我觉得最有用的指标。
第一个是消息送达率。这个指标直接反映消息有没有成功到达。正常情况下应该接近 100%，如果看到有明显的下降趋势或者波动，说明链路存在问题。监控面板会按小时、按天给你展示历史数据，你可以对比问题出现前后的数据变化，找到时间窗口。
第二个是端到端延迟。声网对实时消息的延迟有比较高的承诺，但如果网络质量不好，延迟会明显上升。面板里会展示 P50、P90、P99 这几个分位数，P90 特别值得关注，它反映了 90% 的消息的延迟水平。如果 P90 突然从几百毫秒跳到几秒，那肯定有问题。
第三个是连接质量分布。面板会把连接的 quality 分成 excellent、good、fair、poor 四个等级，实时展示每种等级的占比。如果 poor 的比例突然升高，说明客户端到声网边缘节点之间的网络质量恶化了，可能是运营商侧的问题，也可能是客户端网络环境本身不好。
我一般建议客户把监控面板的数据和业务日志对照着看。假设面板显示下午三点消息送达率下降了，你就在日志里搜索那个时间段前后的 error 日志，往往能发现问题线索。这种交叉验证的方法比单一依赖日志或监控都高效。
调试工具：主动测试与复现
除了被动的日志和监控，声网还提供了一些主动调试的工具，帮助你在问题复现时快速定位。
网络诊断工具是其中一个。这个工具可以测试客户端到声网服务器之间的网络连通性、延迟、丢包率。你让它跑一下，它会依次 ping 几个边缘节点的地址，测量 RTT，返回丢包统计。如果某个节点丢包率特别高，你可能需要考虑切换到其他节点，或者排查客户端网络出口的问题。
SDK 内部一般都有一个质量报告开关，打开之后，SDK 会在通话或消息过程中定期上报质量数据到服务器。这些数据你可以在控制台看到，也可以在本地保存一份自己做分析。质量报告里包含每帧的发送接收情况、码率、帧率、丢包率这些详细信息，对于排查音视频相关的问题特别有帮助。
常见故障场景及排查思路
聊完了工具，我们来看看几类最常见的故障场景。这些都是我在实际工作中遇到的，排查思路和方法有一定通用性，你可以参考。
消息发送失败
这是最常见的问题之一。用户反馈消息发不出去，或者转圈好久最终失败。排查这个问题，我一般从以下几个方面入手。
首先确认网络状态。如果客户端本身网络不通，那肯定发不出去。你可以用前面的网络诊断工具跑一下，或者简单点，让用户换个网络试试，比如从 WiFi 切到 4G。如果换网络就好了，那问题可能出在原来的网络出口上。
然后看 SDK 的连接状态。消息发送的前提是 SDK 已经成功连接到声网的服务器。如果状态是 CONNECTING 或者 DISCONNECTED，消息会进入队列等待发送，这时候不一定是失败，只是延迟。如果状态是 CONNECTED 但消息还是发不出去，那就需要看 SDK 返回的错误码了。
声网的 SDK 对消息发送失败有比较细的错误码分类。常见的比如 1004 是网络不可达，1006 是服务器返回错误，1011 是对方不在线、消息无法送达。每个错误码背后都有对应的原因，你需要对照文档来解读。最有效的方法是把错误码和当时的时间戳、用户 ID、频道信息一起记录下来，然后联系声网的技术支持，让他们帮你查服务端的日志。
还有一个容易忽略的点：消息体大小。声网对单条消息的最大长度有限制，如果你的消息内容超出了限制，SDK 会直接返回错误。你可以检查一下消息的内容，特别是那种带图、带附件的消息，有没有超限。
消息丢失或延迟
消息丢失比发送失败更难排查，因为用户可能只是觉得"好像少了几条"，很难精确定位是哪一条没了。我处理这类问题的时候，通常会建议客户从几个角度入手。
首先是确认消息是否真的丢失。有时候是发送方以为发出去了，实际没发成功，或者接收方收到了但没正确渲染。这种情况在弱网环境下特别常见。你可以做一个简单的测试：让发送方在发送消息后查看发送状态回调，确认消息已经进入已发送状态；让接收方在收到消息后打印日志，确认回调被触发。如果双方状态都对得上，那可能是业务层的渲染逻辑有问题，不在 SDK 层面。
如果确认是 SDK 层的问题，那就需要看服务端的消息漫游记录了。声网的服务端会保存消息的历史，你可以用控制台的消息漫游功能查询某个用户在某个时间段内的消息收发记录。如果发送方显示消息已送达服务端，但接收方没有收到回调，那问题可能出在推送环节；如果发送方根本没有送达服务端的记录，那就是客户端发送环节的问题。这种二分法能帮你快速缩小范围。
消息延迟的问题排查思路类似。正常情况下，实时消息的端到端延迟应该在毫秒级别。如果用户反馈延迟特别明显，你可以先在控制台看监控数据，确认延迟的量级和分布。然后在问题复现时抓取客户端日志，看消息从业务层进入 SDK、到 SDK 发送到服务端、再到服务端推送给接收方的每个环节的时间戳，对比分析哪个环节耗时最长。
频道内消息不同步
还有一类问题是频道内的消息不同步：群聊里有人能看到消息，有人看不到。这类问题往往和频道的订阅机制或者用户的在线状态有关。
首先确认问题用户是否成功加入了频道。SDK 加入频道会有成功或失败的回调，你应该确保业务逻辑正确处理了这些回调。如果加入频道本身就失败了，后面的消息同步自然无从谈起。
然后看用户的订阅状态。声网实时消息 SDK 用的是发布订阅模式，发送方发布消息，接收方需要订阅相应的频道才能收到。如果某个用户没有订阅频道，他就收不到消息。你可以在日志里搜索 subscribe 相关的日志，确认用户的订阅关系是否正确建立。
还有一种可能是用户短暂掉线后又重连，但重连过程中错过了消息。声网的 SDK 有消息漫游机制，用户重新上线后会拉取离线期间的消息，但这个机制有前提条件：用户必须开启了消息漫游功能，而且离线时间不能超过服务端的保存期限。你可以检查一下 SDK 的初始化配置，确保消息漫游开关是打开的。
SDK Crash 或 ANR
最后说说比较严重的问题：SDK 本身崩溃或者导致应用 ANR。这类问题必须重视，因为它直接影响用户体验。
如果是 Android 端的 ANR，你首先要看主线程是否被阻塞了。声网的 SDK 在设计上已经尽量避免在主线程做重操作，但有些场景比如网络切换、弱网重试，可能会在主线程执行一些逻辑。如果你的应用在 SDK 回调里有耗时操作，就会雪上加霜。你可以用 Android Studio 的 CPU Profiler 抓一下 ANR 发生时的线程堆栈，看看主线程到底在等什么。
如果是 Crash，崩溃日志是最直接的线索。Android 会输出 tombstone 文件，iOS 会生成 crash log。你需要把这些日志和 SDK 的版本号、手机的型号、系统版本一起提供给声网的技术支持。崩溃日志里会有崩溃时的堆栈信息，SDK 的开发团队可以根据这个快速定位是 SDK 本身的 bug，还是和业务代码交互时产生的问题。
排查问题的一些个人心得
说了这么多工具和方法，我想分享几点个人的心得体会。
第一，问题描述比想象中重要。我收到过很多工单，只有一句话"消息发不出去"，这种工单处理起来效率很低。如果你能把问题复现的时间、影响的用户范围、是否必现、手机型号和系统版本、网络环境（日志里能看到）、以及已经尝试过的排查步骤都写清楚，我可以少走很多弯路，帮你更快定位问题。
第二，日志要抓全。有时候一个问题需要看客户端日志和服务端日志才能判断责任归属。你在给我提工单的时候，最好把问题发生时间段内的客户端日志全部打包发给我，不要自己先过滤，因为你不知道哪个日志条目是关键的，可能你觉着没用的信息恰恰是破案的关键。
第三，注意问题的时间窗口。很多问题不是一直存在的，而是和特定的时间点相关。比如某个运营商网络在某个时段有故障，或者某个客户端版本有 bug，后面修复了。你如果能提供准确的问题开始结束时间，我可以去做关联分析，查出是不是某个系统变更导致的。
第四，弱网环境是问题的照妖镜。很多问题在正常网络环境下不会复现，但一到弱网、丢包、延迟高的环境下就会暴露出来。如果你有条件，可以在测试环境模拟弱网条件，用 Network Link Conditioner 或者抓包工具来制造丢包和延迟，观察 SDK 的表现。很多隐藏的问题会在这种条件下现出原形。
写在最后
排查实时消息 SDK 的问题，说难不难，说简单也不简单。关键是得知道从哪儿入手、该看什么数据、怎么把分散的信息串起来变成线索。这篇文章里提到的工具和方法，希望能成为你工具箱里的一件家伙事儿。下次遇到问题的时候，不要慌，按部就班地搜集信息、分析日志、确认范围、定位根因，大部分问题都能解决。
如果你在排查过程中遇到任何困惑，或者需要我帮你看日志，直接联系声网的技术支持团队就行。我们处理过各种奇奇怪怪的问题，经验还是有一些的。
