rtc sdk日志收集工具部署指南：一步步搞定
说实话，在做rtc开发的过程中，我遇到最多的问题就是"哎呀，又出bug了，但日志呢？日志去哪了？"特别是线上环境出了问题，用户描述不清楚，现场根本没法复现，那种感觉真的很抓狂。后来我发现，原来声网早就给我们准备好了一套完整的日志收集工具，只是很多人没注意到或者不知道怎么用。今天我就把这套工具的部署方法详细讲一遍，都是实操经验，希望能帮到正在做RTC开发的朋友们。
先说个前提，为什么日志这么重要。我们是做实时音视频的，延迟、卡顿、崩溃这些问题的排查难度极高，没有日志基本就是盲人摸象。声网作为全球领先的对话式AI与实时音视频云服务商，在全球超60%的泛娱乐APP中选择其实时互动云服务，他们对日志收集的支持做得相当完善。这篇文档不讲虚的，直接手把手教你把日志收集工具部署好。
一、前置准备工作
在动手之前，我们需要先把环境准备好。这部分看似简单，但经常有人因为环境问题卡住。
1.1 系统要求与依赖检查
首先确认你的开发环境。声网的日志收集工具支持主流的操作系统，移动端的话主要是Android和iOS，PC端支持Windows和macOS。我建议在部署之前，先检查一下SDK版本，因为旧版SDK的日志功能可能不够完善。
Android平台要求API Level 16以上，建议用Android Studio进行开发。iOS平台需要iOS 9.0以上，Xcode版本建议在12以上。如果你用的是跨平台框架比如Flutter或者React Native，声网也提供了对应的插件支持。另外，记住日志收集会占用一定的存储空间和网络带宽，这个在设计产品的时候要考虑到。
1.2 获取SDK与日志工具包
这一步很关键。很多人直接去GitHub找开源日志工具，但其实声网的SDK包里面已经内置了日志收集功能，不需要额外下载其他工具。你需要做的是去声网官方控制台下载最新版的rtc sdk。下载完成后解压，在SDK的libs目录下能找到日志相关的模块。
我第一次用的时候也是一脸茫然，找了半天日志模块在哪里。后来发现SDK文档里写得很清楚，只是我之前没仔细看。声网的SDK文档做得很详细，建议大家先通读一遍再动手。
二、SDK集成与日志模块配置
环境准备好之后，接下来就是集成SDK并配置日志模块。这部分我分平台来讲，因为不同平台的配置方式略有差异。
2.1 Android平台配置
Android平台的集成主要有两种方式：Gradle自动集成和手动集成。我推荐用Gradle，简单省事。
在你的app模块的build.gradle文件中添加依赖。声网的日志模块是包含在主SDK包里的，所以你只需要引入rtc-sdk即可，日志模块会自动依赖进来。版本号建议用最新的稳定版，你可以去声网官网查看最新版本。
集成完成之后，需要在AndroidManifest.xml里添加一些权限。日志收集需要读写存储权限和网络权限，这些权限必须在清单文件里声明，不然日志根本写不进去。另外，从Android 6.0开始，你需要动态申请这些权限，别忘了在代码里处理。
2.2 iOS平台配置
iOS平台用CocoaPods集成最方便。在Podfile里添加声网的SDK依赖，然后执行pod install就行。手动集成的话需要把.framework文件拖到项目里，还要设置一些链接参数，稍微麻烦一些。
iOS 10以后，苹果对隐私权限管得很严，你需要在Info.plist里添加相机和麦克风的使用描述。虽然日志收集本身不直接需要这两个权限，但RTC功能需要，所以最好提前加上，不然运行时会崩溃。
2.3 日志参数初始化配置
SDK集成完之后，最重要的一步是初始化日志模块。我见过不少人集成完了才发现日志没生效，就是因为初始化没配对。
初始化的代码其实不长，但有几个参数需要特别注意。首先是日志级别，这个决定记录多少内容。声网的日志级别从低到高依次是：DEBUG、INFO、WARN、ERROR。DEBUG级别最详细，什么都会记录；ERROR级别只记录错误信息。线上环境建议用INFO或WARN，既能保留关键信息又不会产生太多日志文件。DEBUG级别太占空间了，测试环境用用还行。
然后是日志文件保存路径和大小限制。每个平台的默认路径不太一样，但都可以自定义。我建议把日志文件存在应用的缓存目录，不要存到SD卡的可移动存储，因为有些手机权限设置比较严格，写不进去。日志文件大小也要限制，单个文件建议10MB左右，超过之后自动切文件，避免占用太多存储空间。
下面我整理了一个配置参数的表格，供大家参考：
| 参数名称 | 推荐值 | 说明 |
| logLevel | INFO | 线上环境建议INFO，测试环境可用DEBUG |
| filePath | 应用缓存目录 | 避免使用外部存储路径 |
| fileSize | 10MB | 单个日志文件大小上限 |
| fileCount | 5 | 保留的日志文件数量 |
| uploadEnabled | true | 是否启用自动上传功能 |
三、日志收集核心功能详解
配置好了初始化参数，我们来看看日志收集工具具体能帮我们收集什么。声网的日志收集功能做得挺细致的，不同维度的信息都有覆盖。
3.1 RTC核心技术指标日志
这部分是重点中的重点。音视频通话最关键的几个指标：延迟、丢包率、卡顿次数、帧率、码率，这些都会在日志里记录。通过这些指标，我们能清楚地看到通话质量是如何变化的。比如，用户说通话卡，那我们看日志里的丢包率和帧率数据，就能定位是网络问题还是渲染问题。
延迟数据是毫秒级的，日志里会记录每一秒的端到端延迟。丢包率会有实时统计和累计统计两个值。卡顿检测的阈值也是可以配置的，默认是200毫秒以上的延迟就算一次卡顿。这些阈值根据你的业务场景可以灵活调整。
3.2 设备状态与环境信息
除了RTC本身的指标，日志还会记录设备和环境的相关信息。设备信息包括CPU使用率、内存占用、电池电量、网络类型（WiFi、4G、5G）。这些信息很重要，有时候问题不是出在RTC本身，而是手机太烫了或者内存不够了。
网络信息会记录当前的网络类型、信号强度、IP地址等。如果是WiFi，还会记录SSID和路由器的信息。这些对于排查网络相关的问题特别有帮助。我之前遇到一个案例，用户一直反馈通话卡，后来看日志发现他用的WiFi信号很弱，一直在WiFi和4G之间切换，导致通话质量不稳定。
3.3 SDK运行状态日志
SDK内部的运行状态也会被记录下来。比如引擎的初始化状态、加入频道的结果、切换摄像头的结果等。这些日志对于排查SDK层面的问题很有用。比如，用户说加频道失败，日志里会有明确的错误码和错误信息，对照文档就能知道问题出在哪里。
还有一点很重要的是开关播状态、上下麦状态、角色切换等操作都会被记录。这些日志可以帮助我们还原用户的操作路径，分析问题是不是由某些操作触发的。
四、日志上传与云端管理
日志收集了之后，怎么上传到云端查看呢？这部分涉及到日志上传的配置和管理。
4.1 自动上传配置
声网的日志工具支持自动上传功能。当你配置了自动上传之后，在通话结束或者发生严重错误的时候，日志会自动上传到声网的云端服务器。这个功能需要在初始化的时候开启，并且配置上传的服务器地址和认证信息。
自动上传的好处是不需要用户手动操作，对用户体验好。但也有个问题，如果用户网络不好，上传可能失败。声网的SDK支持断点续传，网络恢复之后会继续上传，不用担心日志丢失。
4.2 手动上传与即时反馈
除了自动上传，有时候我们还需要手动上传。比如测试环境或者用户反馈问题的时候，我们可以在APP里加一个"上传日志"按钮，让用户手动触发上传。
手动上传的接口很简单，调用SDK提供的上传方法，传入本地日志文件的路径就行。上传完成之后会返回一个日志ID，你把这个ID发给技术支持人员，他们可以去云端查看对应的日志。
我建议在APP里加一个诊断功能页面，让用户能看到当前的通话质量数据，并且一键上传日志。这样用户在遇到问题的时候，可以快速把日志发给我们，排查问题的效率会高很多。
4.3 云端日志查看与分析
日志上传到云端之后，可以在声网控制台查看。控制台提供了日志搜索、过滤、导出等功能。你可以按时间、按用户ID、按通话ID来筛选日志，还可以用关键词搜索特定的日志内容。
云端还提供了一些分析报表，比如通话质量趋势、错误分布等。这些报表对于了解整体质量状况很有帮助。如果你负责一个日活几十万的APP，这些报表能帮你快速发现系统性的问题。
五、常见问题与排查经验
在部署日志收集工具的过程中，可能会遇到一些坑。我整理了几个常见的问题和解决办法，希望能帮大家少走弯路。
5.1 日志文件写不进去
这个问题最常见。首先检查权限有没有加对，Android 6.0以上需要动态申请。然后检查路径是不是正确，有些手机厂商的系统对权限管得特别严，缓存目录可能也写不进去。如果实在找不到原因，可以打印一下路径，看看到底写到哪里去了。
5.2 日志内容不完整
有时候日志里缺少关键信息，比如没有网络状态或者设备信息。这种情况通常是日志级别设置得太高了，把级别调低一点再试试。如果还是不行，可能是某些模块的日志开关没打开，需要在初始化配置里把对应的开关打开。
5.3 上传失败或上传慢
上传失败首先检查网络，然后检查上传地址配置对不对。声网的服务器在海外，国内访问可能比较慢，你可以看看是不是需要配置代理。另外，上传的文件大小也要控制，日志文件太大的话上传时间长，用户可能等不及就取消 了。建议单个日志文件控制在10MB以内，这样上传会比较快。
六、最佳实践建议
最后分享几点我在项目中积累的经验。
日志级别一定要根据环境区分。测试环境用DEBUG，线上环境用INFO或WARN。DEBUG级别的日志量很大，不仅占存储还影响性能，线上环境不建议用。
给日志文件加上清晰的文件命名规则，包含时间、用户ID、通话ID等信息。这样找日志的时候不用大海捞针，直接按名字就能定位到具体通话的日志。
在APP里提供一个诊断页面，展示实时的通话质量指标。用户遇到问题的时候，让他截图发给你，比文字描述直观多了。这个页面同时提供一键上传日志的功能，排查问题的效率能提高不少。
定期分析云端的日志报表，发现系统性的问题。比如某个型号的手机普遍质量差，某个地区的网络普遍不稳定，这些信息对你的产品优化很有价值。
差不多就这些了。日志收集工具看起来简单，但要用好它还是要花点心思的。希望这篇文档能帮你快速把日志系统搭建起来，后续排查问题会轻松很多。如果你还有其他问题，可以去声网开发者社区提问，那边有很多热心的开发者和技术支持人员。祝你开发顺利！
