问题排查指南

全面了解 Flashduty RUM 的问题排查方法，确保监控数据的准确性和完整性

​

概述

本指南帮助您解决 Flashduty RUM 使用过程中可能遇到的常见问题，包括数据采集异常、SDK 配置问题和性能优化等方面。

​

数据采集验证

如果您在 RUM 平台上看不到数据，请按以下步骤进行检查。

​

SDK 安装检查

1. 检查脚本引入

   确认 RUM SDK 是否正确引入：

   CDN 引入

   <script
     src="https://static.flashcat.cloud/browser-sdk/v0/flashcat-rum.js"
     type="text/javascript"
   ></script>
   <script>
     window.FC_RUM &&
       window.FC_RUM.init({
         applicationId: "您的应用ID",
         clientToken: "您的客户端令牌",
         service: "<SERVICE_NAME>",
         env: "<ENV_NAME>",
         version: "1.0.0",
         sessionSampleRate: 10
       });
   </script>
   
2. 检查控制台

   打开浏览器开发者工具（F12），查看 Console 面板是否有 JavaScript 报错。

3. 验证配置

   确认应用 ID 和客户端令牌是否与 RUM 控制台中的配置一致。

​

网络请求检查

1. 打开浏览器开发者工具的 Network 面板
2. 筛选 browser.flashcat.cloud 的请求
3. 确认请求状态码为 200
4. 如果请求失败，查看具体错误信息

如果看到 CORS 错误，请检查您的 CSP 配置是否正确。

​

浏览器兼容性

确认您使用的浏览器版本是否受支持：

浏览器	最低版本
Chrome	60+
Firefox	60+
Safari	12+
Edge	15+
Internet Explorer	11（部分功能受限）

​

广告拦截器影响

部分广告拦截插件可能会阻止 RUM SDK 的运行。建议将您的域名和 browser.flashcat.cloud 加入白名单。

​

常见问题解决

数据未显示

问题：已完成 SDK 配置，但平台上没有数据。

解决方案：

1. 等待数据同步：数据一般在 2-5 分钟内显示

2. 检查初始化时机：确保 SDK 在页面加载时就完成初始化

3. 检查采样率：确认采样率设置合理

flashcatRum.init({
  // ... 其他配置
  sessionSampleRate: 100  // 设为 100 表示采集所有会话
});

4. 检查用户授权：确认用户跟踪授权状态

flashcatRum.setTrackingConsent("granted");

行为数据缺失

问题：用户行为数据不完整。

解决方案：

1. 启用行为跟踪：

flashcatRum.init({
  // ... 其他配置
  trackUserInteractions: true
});

2. 为自定义元素添加标记：

<button data-action-name="提交表单">提交</button>

3. 手动记录复杂交互：

flashcatRum.addAction("click", "自定义按钮点击");

异常数据缺失

问题：JavaScript 异常未被记录。

解决方案：

1. 启用异常跟踪：

flashcatRum.init({
  // ... 其他配置
  trackErrors: true
});

2. 手动上报 try-catch 中的异常：

try {
  // 可能出错的代码
} catch (error) {
  console.error(error);
  flashcatRum.addError(error);
}

3. 配置 Source Map：便于定位生产环境的问题，详见 Source Mapping

性能影响担忧

问题：担心 RUM SDK 影响网站性能。

解决方案：

1. 只启用必要的功能：

flashcatRum.init({
  // ... 其他配置
  trackResources: true,
  trackLongTasks: false,  // 关闭不需要的功能
  trackErrors: true,
  trackUserInteractions: true
});

2. 调整采样率：

flashcatRum.init({
  // ... 其他配置
  sessionSampleRate: 50  // 只采集 50% 的会话
});

3. 过滤非关键资源：

flashcatRum.init({
  // ... 其他配置
  beforeSend: (event) => {
    // 过滤掉非关键资源
    if (event.type === 'resource' && event.resource.url.includes('/static/')) {
      return false;
    }
    return true;
  }
});

CSP 配置问题

问题：CSP 策略阻止 RUM SDK 运行。

解决方案：

在您的 CSP 配置中添加以下规则：

script-src 'self' https://static.flashcat.cloud;
connect-src 'self' https://browser.flashcat.cloud;

单页应用页面访问未记录

问题：SPA 应用的路由切换未被记录。

解决方案：

React Router

import { useEffect } from "react";
import { useLocation } from "react-router-dom";

function RumRouteTracker() {
  const location = useLocation();

  useEffect(() => {
    flashcatRum.startView({
      name: location.pathname,
      url: location.pathname + location.search
    });
  }, [location]);

  return null;
}

// 在 App 组件中使用
function App() {
  return (
    <Router>
      <RumRouteTracker />
      {/* 其他路由 */}
    </Router>
  );
}

Vue Router

router.afterEach((to) => {
  flashcatRum.startView({
    name: to.name || to.path,
    url: to.fullPath
  });
});

手动记录

// 路由变化时调用
flashcatRum.startView({
  name: "商品详情页",
  url: "/products/123"
});

​

高级调试

​

启用调试模式

开启调试模式可在控制台获取详细日志：

flashcatRum.init({
  // ... 其他配置
  debug: true
});

​

强制数据采集

测试时可强制开启全量数据采集：

flashcatRum.init({
  // ... 其他配置
  sessionSampleRate: 100,
  sessionReplaySampleRate: 100
});

请勿在生产环境使用 100% 采样率，以避免产生过多数据和费用。

​

控制台调试命令

在浏览器控制台中可使用以下命令：

// 获取 RUM 内部上下文
window.FC_RUM.getInternalContext();

// 获取当前会话 ID
window.FC_RUM.getSessionId();

// 获取当前页面 ID  
window.FC_RUM.getViewId();

// 手动发送测试事件
window.FC_RUM.addAction('test', 'debug_action');

​

网络请求分析

1. 打开开发者工具 Network 面板
2. 筛选 browser.flashcat.cloud 请求
3. 查看请求 Payload 确认数据内容
4. 检查 Response 确认上报成功

​

常见问题解答

数据多久能在平台显示？

一般在 2-5 分钟内显示，高峰期可能稍有延迟。

移动端浏览器是否支持？

支持 iOS Safari 和 Android Chrome 等主流移动端浏览器，但部分高级功能（如 Long Tasks 监控）可能受限。

如何排除特定页面的监控？

可以根据 URL 条件判断是否初始化：

// 排除管理后台页面
if (!window.location.pathname.startsWith("/admin")) {
  flashcatRum.init({
    // ... 配置
  });
}

如何跟踪多个子域名的用户？

需要以下配置：

1. 使用相同的应用 ID 和客户端令牌
2. 设置一致的用户标识
3. 启用跨域跟踪：

flashcatRum.init({
  // ... 其他配置
  allowedTracingUrls: [
    "https://example.com",
    "https://app.example.com",
    "https://shop.example.com"
  ]
});

如何减少数据量和费用？

可以通过以下方式：

1. 降低采样率：设置 sessionSampleRate 为 10-50
2. 关闭不必要的功能：如 trackLongTasks: false
3. 排除特定页面：不在管理后台等内部页面初始化
4. 配置数据过滤：使用 beforeSend 过滤非关键数据

​

联系技术支持

如果按上述步骤排查后仍有问题，请联系我们的技术支持团队。

1. 准备诊断信息

   请收集以下信息：

   • 应用 ID
   • 浏览器类型和版本
   • SDK 版本
   • 控制台错误截图
   • Network 面板请求截图
   • 问题复现步骤
2. 联系支持

   • 邮箱：[e-mail]
   • 在线咨询：点击平台右下角「帮助」按钮