新【北极星】工具概述

wangyutong · 2025 年10 月 31 日 03:42

本文将介绍融云的开发者工具箱 北极星 的基础用法，和进阶用法，学习如何自助查询连接信息、消息流转、通话明细、数据监控以及调试 Server API。

IM 问题排查工具概述

IM 北极星主要为开发者提供了终端用户连接状态、消息流转状态、回调服务查询功能：

通过查看用户的连接日志，判断用户某时间段内是否可以正常使用融云服务，如：用户反馈消息发送不成功，可能是因为该用户在此时间段内没有成功连接融云。
通过查看消息的整个发送过程状态，分析出收不到消息的原因，帮助开发者定位问题，提高问题解决效率。
支持查询 IM 消息路由、在线状态订阅、用户注销与激活状态三个回调服务，可查看每次回调的时间、URL、响应状态码及相应内容详情，当应用服务器没有收到相关回调时，可通过北极星回调查询回溯回调数据。

登录融云开发者后台北极星页面，即可查看应用内，用户最近 7 天的连接及消息发送情况。

连接状态监控

支持查看用户 7 天内连接融云状态情况及消息发送情况，消息需要在发送 5 分钟后才能查看完整状态数据。

输入用户 ID 查询该用户的连接情况，用户 ID 为获取过融云 Token 用户唯一标识。

连接状态内容

显示内容包括：连接时间范围、使用的 SDK 版本、平台、手机型号、系统（Android API 级别；iOS 系统版本号）、终端用户连接时的 IP 地址
消息监控：点击“查看”后，显示该连接时间段内的该用户的消息发送情况

消息记录查询

查看指定用户的消息发送状态，目前支持查看单聊、群聊、聊天室、系统会话类型，默认为查看单聊会话类型消息。

查询条件

支持根据以下查询条件，查询已发送的消息：

发送用户 ID：融云获取过 Token 的 UserID，查看此 ID 发送的所有消息，必填项
消息 ID：为融云全局消息唯一标识 msgUID，可通过融云消息路由服务或服务端消息历史日志服务获取，非必填项
目标 ID：根据不同的会话类型，对应为单聊用户 ID、群组 ID、聊天室 ChatRoomID
会话类型：支持查看单聊、群聊、聊天室、系统消息会话
消息类型：支持融云所有内置消息及用户自定义消息，用户在消息类型中选择自定义消息时，需要手动输入自定义消息的 ObjectName 进行查询，自定义消息一次只能查询一个。
消息来源：包括：Android、iOS、Web、PC、小程序、Server API。默认查询全部平台的消息。
时间范围：消息发送时间范围，默认显示当天零点到当前时间

消息发送列表

消息 ID：融云消息的全局唯一标识 msgUID
发送用户 ID：该消息的发送用户 ID
目标会话 ID：根据不同的会话类型，对应为单聊用户 Id、群组 Id、系统消息 Id
发送时间：消息在融云服务端的发送时间
会话类型：单聊、群聊、系统消息会话
消息类型：当前消息的消息类型，包括客户自定义消息（ObjectName）
消息来源：包括：Android、iOS、Web、PC、小程序
接收状态：点击查看该条消息的目标用户接收状态

单聊、群聊消息接收状态

查看一条消息目标用户的接收情况，消息是否发送成功、敏感词、黑名单过滤情况及目标用户未在线时（单群聊）的消息 Push 状态。

用户在线接收消息，消息发送成功显示

消息状态包括：发送成功、消息未下发

发送成功：目标用户在线情况下接收到该消息，显示为发送成功
消息未下发：目标用户有大量消息需要接收时，融云服务端通知目标客户端有新消息需要接收，目标用户在获取新消息前因网络问题断开连接或用户主动退出登录，显示为消息未下发，此状态的消息在用户下次登录时会重新获取到

用户未在线情况下，转为 Push 推送

Push 通道：发送 Push 时使用的通道类型，包括：融云 Android Push、APNs、小米、华为、魅族、vivo、OPPO
Push 发送时间：该消息转为发送 Push 时的融云服务器时间
Push 是否成功：成功/不成功，在使用第三方 Push 通道时，调用第三方 Push 通道接口，第三方 Push 服务返回成功后，融云默认 Push 成功
错误描述：Push 失败后，将返回错识码，开发者可根据错误描述修复错误或提交工单联系融云处理

消息回调处理
当消息回调服务返回不下发或未通过审核服务的审核时，消息会提示发送失败，提示如下：

黑名单、白名单过滤提示

在使用融云黑名单服务状态下，如发送消息用户在目标用户的黑名单中时，消息发送失败，此时消息 ID 为空，提示如下：

白名单服务与黑名单服务相反，如使用的是白名单服务，发送消息用户未在目标用户的白名单中时，消息发送失败消息 ID 为空

用户被禁言提示

当用户被禁言时，包括群禁言（群整体禁言、群成员禁言）及聊天室成员禁言，该用户无法在群组或聊天室中发送消息，此时消息 ID 为空，提示如下：

消息命中敏感词提示

发送有文本消息中含有敏感信息审核不通过时，消息被融云服务端屏蔽发送失败，此时消息 ID 为空，提示如下：

如消息含有替换敏感词时，消息可正常下发，提示“含有替换敏感词，已完成替换操作”

聊天室消息接收状态

在查询聊天室消息接收状态时，可查询指定用户的接收情况。

进入发送消息信息页面后，进行查询

选择时间范围: 该消息发送后的时间范围。
输入要查询的用户id。
点击查询按钮后会将符合条件的用户连接信息显示在后面
选择用户连接信息后，将查询用户在此次连接的消息拉取结果。

用户连接会根据设备进行进行分组，相同设备的连接将在同一个分组进行展示，在显示连接信息的同时也会展示此次连接是否有加入此聊天室的行为。

指定用户消息接收说明

消息接收查询结果分为 3 个区域，分别为:

用户本次连接的设备信息（系统、型号、SDK版本）。
查询范围内加入、退出聊天室的时间（如果只有一次加入聊天室的行为，则不显示）和消息接收的最终结果，最终结果包括: 接收成功, 消息未接收。如果用户有多次加入、退出聊天室的行为将会分为多组进行展示。
用户在聊天室内与接收消息相关的行为动作，行为动作包括: 消息发送, 拉取成功, 未拉取到数据, 首次拉取消息, 消息被淘汰, 消息已撤回,未拉取消息 ,加入聊天室 ,退出聊天室等…

结果示例与说明：

拉取动作只显示此聊天室消息发送后的第一次拉取动作。
某些情况下没有退出聊天室的行为动作（例如: 用户被封禁）。

接收成功

消息接收成功时，最终结果和行为动作列表中的拉取动作会有高亮提醒（绿色）。

消息未接收

未接收到消息时，最终结果和行为动作列表中的拉取动作会有高亮提醒（黄色）。

未接收到消息可能原因包括但不限于:

消息已撤回
消息已淘汰
消息发送前已退出聊天室
拉取消息的开始、结束时间范围没覆盖到此消息
拉取消息的类型不匹配
拉取消息的级别不匹配

回调查询

支持查看近7天的 IM 各服务回调数据，包含：

消息路由
在线状态订阅
用户注销与激活状态回调
聊天室状态同步及聊天室属性同步即将上线，敬请期待。

查询条件

支持根据以下查询条件，查询对应的回调事件：

查询时段：发生回调时间的时段，时间精确到秒
响应状态码：可通过回调的响应状态码筛选回调事件

回调数据列表

基于对应的检索条件，可查询到该时段所有的回调事件，内容展示包含：

回调时间，实际回调给应用服务器时间，精确到毫秒
回调URL ，数据回调实际使用URL 地址
响应状态码，应用服务器的响应状态码

查看回调详情

点击查看按钮，可查看具体的回调内容。

消息路由详情

用户可以在消息状态监控里查看消息路由详情，点击查看详情，弹窗展示消息路由状态。

数据监控概述（仅限北极星专业版使用）

北极星-数据监控是为开发者提供的包含业务数据监控、API监控的数据监控平台，可查看近 7 天的消息量、同时在线、Sever API 请求量、QPS、请求成功率、错误码占比等相关数据。后续会陆续上线指定会话的消息量、指定聊天室活跃程度等更丰富的数据统计维度，致力于帮助开发者提前感知业务潜在风险，协助客户提前发现问题，降低因各类问题对客户业务产生的影响。

使用限制

客户开通【 北极星专业版】后才可以使用“数据监控”相关功能，客户登录开发者后台-北极星，即可看到“数据监控”相关菜单并查看相关功能看板。

业务数据

消息数据

可查看近 7 天的单聊、群聊、聊天室、聊天室KV、超级群的消息相关数据，同时支持根据消息类型筛选，包含：

总消息量：上行总消息量、分发总消息量、下行总消息量
消息峰值：上行消息峰值、分发消息峰值、下行消息峰值
消息量变化趋势：数据统计为 5 分钟粒度，每 5 分钟 1 个点，可查看上行、分发、消息量趋势；每个五分钟的消息量为该 5 分钟产生的消息总量。

消息数据为实时统计，数据延迟 5 分钟左右。

同时在线

“同时在线类型”选择“全部”可查看近 7 天的全部用户的同时在线峰值趋势。
“同时在线类型”选择“仅聊天室”可查看近 7 天的聊天室用户的同时在线峰值趋势。
数据统计为 1 分钟粒度，每 5 分钟 1 个点，图表展示该 5 分钟内的 1 分钟粒度峰值。

同时在线为实时统计，数据延迟 5 分钟左右。

需要注意的是，全部用户同时在线统计依赖客户连接，当用户数量较少时，可能存在某个时段没有新客户连接的情况，因此服务端没有触发数据统计，会存在一定程度的误差。

API监控

实时统计

API 实时统计页面可查看近 7 天的有实际调用的 API 的 QPS 情况。

左侧展示该 Appkey 在当前检索的时间段内有实际调用的所有 Server API 及该接口的请求成功率。
点击某个对应 API ，展示该接口在当前查询时段的QPS及错误码分布。
图表中会标注接口当前在融云开发者后台设定的频率值，当 QPS 有频繁超过设定频率的情况时，您可以在开发者后台调整对应接口的调用频率。详情请见 [频率限制] (融云开发者文档)

Server API 实时统计数据延迟 5 分钟左右。