CometChat Analytics 用于为聊天系统建立可见性，覆盖产品分析、运维可观测性和数据管道三类需求。资料将其分为三个可见性层面。
一、聚合指标（REST，服务端） 通过 Metrics REST API 获取聚合数据：用量指标（usage-metrics）提供活跃用户与随时间变化的用量；消息指标（message-metrics）提供消息量与计数；通话指标可通过 get-call 接口获取单次通话详情，包括参与者指标。这些接口应使用 REST API Key 在服务端定时任务中调用，绝不能放在客户端，并将结果送入 BI 工具。构建报表前需从各文档页面获取确切的查询参数与响应字段。
二、实时事件推送到自有技术栈（Webhook） Webhook 会在消息、用户、群组、通话事件发生时向你的服务器 POST 一个 HTTPS 通知，配置入口见管理 API 的 webhooks 概览。这是把聊天数据实时接入 Segment、BigQuery、Snowflake、Datadog 或数据湖的方式。要点包括：搭建返回 200 以确认接收的 HTTPS 端点；用 CometChat 在每次 webhook 请求中发送的 Basic Auth 凭据进行安全校验（文档仅描述 Basic Auth，没有载荷签名方案，因此应校验 Authorization 头而非寻找 HMAC 签名）；只订阅需要的事件，避免全量扇出；对事件做转换并转发到仓库或可观测性接收端，处理程序需幂等且快速，重活放入队列。同一 webhook 流也可作为防篡改的审计日志。
三、客户端错误与性能监控（按技术栈） 指标 API 无法告诉你某个用户的聊天加载失败，因此需要在客户端埋点：捕获组件渲染错误，React 系列可通过错误边界的钩子（React v7 为 CometChatErrorBoundary 的 onError），Angular/RN 有对应机制，iOS/Android/Flutter 没有错误边界构造，则通过 SDK 错误监听器或组件的错误状态视图；将错误带上下文转发到 Sentry/Datadog。对关键路径埋点，把初始化、令牌获取和登录包在 span 或面包屑中，登录失败激增往往是最早的故障信号（常与区域或令牌问题有关）。监听连接状态，SDK 的连接/WebSocket 监听器可告知客户端何时掉线，并统计重连次数。注意不要把密钥或消息正文写入监控，只记录 UID、事件类型和延迟等元数据，兼顾隐私与合规。这些应通过所选技术栈对应的 core/production/troubleshooting 技能接入。
四、投递与通话日志 推送投递日志覆盖 FCM/APNs/邮件/短信的投递情况，保留约 14 天，适合诊断“通知未送达”，应在过期前导出。通话日志通过 Calls REST API 获取单次通话的质量与参与者指标。
五、自托管可观测性 本地部署自带 Prometheus、Grafana、Loki、Promtail，提供服务指标、仪表盘、告警和集中日志，可将告警（P95 延迟、错误率、WS 容量）接入值班流程。SaaS 客户则改用 Metrics API 加 Webhook。
常见陷阱：在客户端调用指标 API（需要 REST API Key，只能服务端）；Webhook 处理程序慢或不幂等导致重试堆积（应快速确认、排队处理、去重）；绘制虚构指标（应从指标页面获取真实字段）；把消息内容写入监控（隐私与合规风险，应记录元数据而非正文）；缺少客户端错误监控（故障只能从用户处得知）；依赖已过期的推送日志（应在保留窗口内导出）。
验证方式：用量/消息指标在仪表盘中返回真实数字；测试消息触发 webhook 并落入仓库或监控；人为制造的初始化/登录失败带上下文出现在错误监控中；需要时能读取推送/通话日志；自托管下 Grafana 能展示服务且告警可触发。