iStats 埋点统计 · 控制台

iStats 使用说明

这份说明覆盖从零到看到数据的过程:注册账号、建应用拿 app_id、三端任选其一接入、 然后在六个视图里读数据。最后两节是告警配置和指标口径——口径先看,能省掉大部分「数字对不上」的疑惑。

适用版本 v1.0.0 Web / Flutter / Java 服务端 阅读约 12 分钟

01 快速开始

整个流程只有四步,后面每端接入的细节在各自的章节里。

  1. 登录或注册:登录页支持自助注册(服务端允许时),注册出来默认是可创建应用的账号。
  2. 新建应用:顶栏右侧「新建应用」,填个名字即可,系统会给一个 app_id。
  3. 接入 SDK:进控制台的「应用管理」页复制 app_id,再按应用端看 03–05 节对应的步骤。
  4. 回来看数据:「实时数据」页通常几秒内就能看到自己刚触发的页面浏览。
一个 app_id 可以同时接三端。控制台不区分「端」——事件按应用聚合,同一用户的 Web 与 App 行为会算在同一个应用里, 用 platform 属性区分来源即可。

02 账号与权限

账号不再区分角色:能看哪些应用、能不能写,全部由应用授权决定。

注册后即可在「应用管理」里创建自己的应用,创建时自动获得该应用的可写授权,不用等管理员分配。

首次引导创建的超级管理员默认可见全部应用,并负责账号管理与授权;普通成员只看得到自己创建的、以及被授权的应用。

授权粒度是按应用。一个应用都没有时会落到「先建一个应用」引导页,自己建一个就能开始用,不是登录失败。

没有写权限时所有写按钮都会隐藏——界面隐藏只是避免点到必然失败的入口,真正的拦截在接口层,绕过前端也写不进去。

03 Web 端接入

一行式接入(推荐)

把 app_id 写进 id 属性,SDK 加载后会读标签自己初始化,不需要额外写 JS:

<script id="你的 app_id"
        src="//istats.denghb.com/istats.js" async></script>

加载即开始采集,默认全开:页面浏览、点击、性能、离开、JS 错误。

手动初始化(需要自定义配置时)

不带 id 属性即不自动初始化,由业务自己调:

<script src="https://istats.denghb.com/istats.js"></script>
<script>
  Istats.init({
    appId: 'app_xxx',
    // host 不写默认 https://istats.denghb.com;换域名才需要显式传
    autoPageView: true,   // 含 SPA 的 pushState / hashchange
    autoClick: true,      // 只采集带 data-istats 的元素
    autoError: true       // 自动捕获 JS 错误 / Promise 异常 / 资源加载失败
  });

  Istats.identify('user_10086');                        // 登录后绑定,UV 按此去重
  Istats.track('pay_success', { amount: 199 });         // 自定义事件
  Istats.captureException(err, { biz: 'checkout' });    // 手动上报异常
</script>
应用版本 SDK 会自己找:页面里有 <meta name="app-version" content="1.2.3"> 就自动带上,没有就留空;也可以显式传 appVersion。
登录后调 identify(userId) 会把登录前设备 id 的历史事件归并到该用户; Web / Flutter / 服务端用同一个 userId,就能串成同一个人。

自动采集的事件

事件名触发时机关键属性
$page_view页面加载与 SPA 路由切换页面路径、来源、UTM
$click点击带 data-istats 的元素元素选择器、坐标、滚动位置
$page_leave离开页面(停留 < 300ms 不报)dwell_ms、scroll_pct
$perf页面加载完成TTFB、DCL、LCP、CLS、FID、DOM 节点数
$exceptionJS 错误 / Promise 异常 / 资源失败类型、消息、堆栈
点击埋点默认只采带 data-istats 的元素,避免把页面上的每个按钮都染成一条事件。 给按钮加上 data-istats="checkout_click" 就会以该名字上报。

04 Flutter 端接入

在 runApp 之前 init 一次,页面切换交给 NavigatorObserver:

void main() {
  WidgetsFlutterBinding.ensureInitialized();
  Istats.init(
    appId: 'demo_app',
    // host 默认 https://istats.denghb.com,换域名才要写
    // appVersion 可选:传 PackageInfo.version(package_info_plus)就能按版本切开
  );
  runApp(const MyApp());
}

MaterialApp(
  navigatorObservers: [IstatsNavigatorObserver()],   // 自动上报页面切换
  ...
)

Flutter 端会自动带上设备信息:平台、系统版本、设备型号与类型、屏幕尺寸、时区、CPU 核数。

Flutter 运行时拿不到自身版本号,所以 appVersion 要业务自己传: appVersion: (await PackageInfo.fromPlatform()).version(package_info_plus)。 不传就留空,不影响其它指标。

05 Java 服务端接入

agent 方式(零代码)

下载 istats-agent.jar 由当前 iStats 服务直接提供;也可以按下方 Maven 命令自行构建。

把 agent jar 挂到启动参数上,业务代码一行都不用改:

java -javaagent:istats-agent.jar=app_id=demo_app \
     -jar your-app.jar

也认环境变量(ISTATS_APP_ID / ISTATS_AGENT_HOST / ISTATS_APP_VERSION)。host 默认 https://istats.denghb.com, 换域名部署时才需要 host=...。 启动日志会有一行 [istats-agent] 已启动(premain) 确认接管成功。

自动采集织入点
HTTP 请求与耗时HttpServlet#service
慢 SQL 与耗时JDBC execute*
外部调用耗时RestTemplate / OkHttp / AsyncHttpClient
未捕获异常全局异常处理器
注解方法@IstatsTrack
agent 初始化失败只打一行错误,绝不阻断宿主启动。观测工具把业务带走,比不观测糟得多。

注解埋点

@IstatsTrack("order_submit")
public void submit(Order order) { ... }

侵入式 API

IstatsServer.init(new IstatsServer.Config().appId("demo_app"));
IstatsServer.track("pay_success", Props.of("amount", 199));

host 默认 https://istats.denghb.com;应用版本不传时,SDK 会从 jar 的 MANIFEST(Implementation-Version)里自己取。 两种方式可以共存;agent 已接管时,代码里的 init 会被忽略并打一行提示。

06 六个视图怎么用

左边的菜单会跟着当前应用的「平台服务」走:Java 服务端应用不显示「会话分析」, 因为它没有页面,入口页 / 出口页 / 页数这几列永远是空的。

数据概览

五个 KPI 看整体水位:事件量、活跃用户、会话数、页面浏览、新增用户;右边那张卡是跳出率、 人均事件数、平均会话时长。下面是趋势图、Top 事件与热门页面。时间范围切 1 / 7 / 30 天。

应用是 Java 服务端时,这页自动换成请求视角:请求数(http_request 事件数)、 错误率(只算 5xx,4xx 是调用方问题不计入)、人均事件数;「页面浏览」标签与「热门页面」卡不再出现。

事件分析

左边是事件清单(带自动/自定义标记、触发次数、影响用户数、最近触发时间),点一条看右侧详情: 趋势、页面分布、属性分布。属性分布能直接回答「哪个版本、哪个城市、哪个渠道」这类问题。

异常监控

按「类型 + 消息」聚合成指纹,一行一个错误种类:出现次数、影响用户数、首次与最近时间, 点开看最新一条堆栈样本。同一个错误只占一行,不会被刷屏。

实时数据

最近 30 分钟的事件流,5 秒刷新一次,每行可以展开看完整属性(含设备、系统、浏览器、IP、时区)。 排查「上报到底有没有到」时看这里最快。

会话分析

一分钟内多个事件会归到同一个会话。列表给每个会话的进出页面、事件数、页面数、时长、是否跳出; 点一行展开时间线,能看到每次跳转的间隔。跳出率高的时候,先看这里是从哪一步走的。

漏斗分析

最多 8 步,按同一会话内的先后顺序判定,给出每步人数、相对首步与上一步的转化率、流失量。 步骤可以按事件名加属性条件,比如「$page_view 且 page=/checkout」。

留存分析

以首次触发某个事件的那天为分组,看之后第 1 / 3 / 7 / 14 / 30 天的回访比例。 选一个能代表「真正用起来」的事件(比如 pay_success),比拿登录当留存更有意义。

07 阈值告警

一条规则 = 应用 + 事件 + 字段条件 + 阈值 + 通知渠道。命中就把当时的实际值发出去。

  1. 选事件与字段(字段来自该应用上报过的属性,没数据时字段列表是空的)。
  2. 选比较符(大于 / 小于 / 等于),填阈值。
  3. 选通知渠道:邮件或群机器人。渠道没配置时规则可以保存,但发送会落到 dry_run。
  4. 保存后可以「测试发送」,只发一次不落业务数据,用来验证渠道通不通。
状态含义
sent已发送成功
dry_run渠道未配置,只记录未发送
failed发送失败(凭据、网络或接收方拒收)
告警是「越过阈值就发」的即时判断,不做抑制窗口。阈值调得太低会反复触发,建议先用 dry_run 观察几轮再开渠道。

08 指标口径

数字对不上时,先对照这四条:

指标口径
「日」按 Asia/Shanghai 切分,跨时区访客归到同一天。
PV只统计 $page_view 与 $screen_view,自定义事件不计入 PV。
UVCOUNT(DISTINCT distinct_id);调过 identify 是用户 ID,否则是设备 ID。
会话30 分钟静默即切新会话;跳出率 = 只有 1 个页面的会话占比。
设备 ID 存在浏览器本地。同一个用户换浏览器、清缓存、用隐私模式,会被算成新的 UV——这是所有客户端埋点的共性, 不是统计错误。要精确到人,就在登录后调 identify。

09 常见问题

接入后实时数据里看不到事件

  • 确认标签上是 id="app_id",值就是控制台里那串 app_id,不是应用名。
  • 上报是加密的,服务端拒收明文。如果自己改过 SDK 或中间层改写了请求体,会被直接拒掉。
  • 用浏览器 Network 面板看 /collect 的状态码:2xx 说明到了,4xx 看响应里的原因。

登录提示验证码错误

验证码是一次性的,提交失败后那张就作废了,必须点图换一张再提交。验证码校验在密码校验之前,所以「账号不存在」和「密码错误」的提示是一样的——这是为了避免账号被枚举。

UV 比预期高很多

大概率是没调 identify。未登录用户按设备 ID 去重,换设备、清缓存都会产生新的 UV。

会话数比事件数还多

会话按 30 分钟静默切分。低频上报(比如只在关键操作时上报)会导致每次上报都开一个新会话。这类场景建议直接看事件量,不要看会话指标。

看不到「账号与授权」

这个入口只对超级管理员显示;普通成员不需要它,也能创建并管理自己的应用。