Android 系统每天都会产生大量状态变化和运行事件。如何把这些离散信息变成稳定、可查询的系统指标,同时避免每个组件各自实现一套采集和存储机制?AOSP 的 StatsD 正是为此设计的统计服务。本文从 StatsD 的进程职责、事件格式和数据链路讲起,再看它的核心类,以及 OEM 扩展自定义 CUJ 时需要关注的边界。
StatsD 是什么
StatsD(Android Statistics Daemon)是 Android 平台的统计事件收集与指标处理服务。系统组件通过统一的结构化事件描述状态变化或统计数据,StatsD 根据已安装的配置匹配事件、计算指标,并按需输出报告。
StatsD 由原生守护进程和 Framework 侧的 Java 服务协作完成。原生 statsd 独立于 system_server 运行;StatsCompanionService 在 system_server 中承担桥接职责,协助 Java 框架和 StatsD 交互。独立进程的一个重要价值是:Framework 崩溃或重启时,StatsD 仍可能继续运行,从而观测到包括 system_server 崩溃在内的事件。Android 11 起,StatsD 以 com.android.os.statsd APEX 模块形式提供。
官方介绍:AOSP StatsD 模块文档
Atom:StatsD 处理的结构化事件
StatsD 中的一类事件称为 atom。每个 atom 有固定的 ID 和 schema,schema 规定字段的顺序、类型和语义。一次事件可抽象为:
StatsEvent {
elapsed_realtime_timestamp,
atom_id,
fields...
}
字段可以是整数、长整数、字符串、布尔值、浮点数、字节数组或嵌套列表等。发送端通过 Framework 或 native 的 StatsEvent API 按 schema 组装数据,再序列化传给 StatsD。UID 等字段还可以附带语义注解,供 StatsD 做身份映射或维度处理。
因此,atom 不是自由格式的 logcat 文本。它更像一条有类型的记录:消费者可以根据 atom ID 找到 schema,再按字段进行过滤、匹配和统计。
源码参考:AStatsEvent 实现、StatsD 字段表示
两种数据入口:Push 与 Pull
StatsD 支持两种基本的数据采集方式。选择哪种方式,取决于数据代表的是一个瞬时事件,还是某个时刻的状态或累计值。
Push:发生时上报
Push atom 由产生事件的组件在状态变化时主动写入。例如屏幕状态变化、进程状态变化等,适合用事件发生的时间点表达的信息。
典型数据流如下:
Framework / 系统组件
→ StatsLog 或 AStatsEvent 构造 atom
→ statsdw socket
→ StatsSocketListener 接收并解析
→ LogEventQueue 缓冲
→ StatsLogProcessor 分发
→ MetricsManager 匹配配置
→ MetricProducer 更新指标
→ 报告或持久化数据
StatsSocketListener 从 socket 读取序列化事件,解析 atom ID、时间戳和字段,并将事件放入队列。处理阶段由 StatsLogProcessor 验证事件、处理必要的 UID 映射和状态更新,再把事件分发给相应配置的指标管理器。
源码参考:StatsSocketListener.cpp、StatsLogProcessor.cpp
Pull:需要时取样
Pull atom 表示 StatsD 在某个采集时机请求一份数据。这个请求只针对已经定义并注册的 atom,不是 StatsD 任意遍历系统服务。
以读取当前电池电量为例:StatsD 的 pull 管理逻辑触发请求,系统侧注册的 callback 读取 Health 服务提供的电池信息,将结果封装成 StatsEvent 后返回。StatsD 再把返回的数据送入指标处理流程。Pull 适合当前状态、累计计数器或需要按固定周期取样的数据。
指标配置触发取样
→ StatsPullerManager / puller
→ 系统侧已注册的 callback
→ 读取 Health、内核或其他数据源
→ 返回一个或多个 StatsEvent
→ StatsD 更新指标
Pull 可能涉及 Binder 调用和系统资源,因此实现会考虑超时、冷却时间和缓存,避免对同一数据源过度拉取。
源码参考:StatsPullAtomService.java、StatsPuller.h
简单来说,Push 回答“刚才发生了什么”,Pull 回答“现在的值是多少”。
从事件到指标:核心类各司其职
阅读 StatsD 源码时,可以沿着下面这些核心对象建立整体认识:
| 类 | 职责 |
|---|---|
StatsService | 原生 StatsD 的 Binder 服务入口,接收配置、报告读取和 pull callback 注册等请求,并协调主要模块。 |
StatsSocketListener | 监听 statsdw socket,接收 push atom 并解析事件。 |
LogEventQueue | 缓冲待处理事件,让接收和指标处理相互解耦。 |
LogEvent | 表示一条解析后的事件,携带 atom ID、时间戳及类型化字段。 |
StatsLogProcessor | 校验和分发事件、更新状态、协调各配置的指标处理,并负责报告与数据生命周期。 |
ConfigManager | 保存并管理 StatsD 配置。 |
MetricsManager | 执行单份配置,维护 matcher、condition 和各类指标生产者。 |
MetricProducer 及子类 | 实际维护 Count、Duration、Value、Event、Gauge 等指标数据。 |
StatsPullerManager | 管理 pull atom 的请求、回调、超时、冷却和缓存。 |
StatsCompanionService | 运行在 system_server 的 Java 桥接服务,协助 pull 调度、alarm 和系统侧交互。 |
StatsPullAtomService | Framework 侧 pull callback 的集中实现之一,读取数据并组装返回事件。 |
push 处理的主干可以浓缩为:
StatsSocketListener → LogEventQueue → LogEvent → StatsLogProcessor
→ MetricsManager → MetricProducer → 报告
StatsService 管理服务接口和对象关系;StatsLogProcessor 按配置路由事件;MetricsManager 负责把配置翻译成运行时 matcher、condition 和 producer;producer 再维护实际指标。这种分层让事件的定义、采集和指标算法相对独立。
源码参考:StatsService.h、StatsLogProcessor.h、MetricsManager.h
OEM 扩展自定义 CUJ:先复用,再扩展
CUJ(常见展开为 Customer/User Journey,即用户可感知的交互旅程)用于描述诸如展开通知栏、启动应用、返回桌面等交互。AOSP 的 InteractionJankMonitor 在交互生命周期内启动帧跟踪,结束时汇总帧表现,并可记录到对应的 StatsD interaction type;在满足条件时也能触发 Perfetto trace。
OEM 扩展时,建议先确认新交互是否能准确归入已有 CUJ。若语义一致,复用现有类型并在正确的开始、结束和取消位置接入监控,通常能直接利用已有的帧跟踪、统计和 trace 能力。
若确实需要新增类型,则要在 OEM 维护的 Framework 分支中端到端扩展:
- 定义新 CUJ 的名称和编号,并遵循目标分支的编号规则。
- 增加 CUJ 到 StatsD interaction type 的映射。AOSP 的
Cuj实现维护了这组映射;不需要写入 StatsD 的类型会明确标记为不记录。 - 根据目标分支的 atom schema 和生成流程,确保 StatsD 能识别对应 interaction type。
- 在实际交互生命周期的合适位置调用
InteractionJankMonitor,并覆盖正常结束、取消和超时路径。 - 更新使用该类型的 StatsD 配置、分析脚本或仪表盘,并在设备上核对事件字段、帧区间和 trace 触发结果。
只增加一个 CUJ 整数常量并不足够。CUJ 编号、StatsD interaction type、atom schema 和实际调用点必须一致,否则会出现不记录、类型未知或测量区间不符合真实交互的问题。不同 Android 分支的类组织和扩展细节会变化,实施前应以目标分支源码为准。
源码参考:Cuj.java、InteractionJankMonitor.java
结语
理解 StatsD,可以从三个问题入手:事件由谁产生、数据是 push 还是 pull、配置最终由哪个 producer 转成指标。沿着 StatsSocketListener 或 pull callback 进入,再追到 StatsLogProcessor、MetricsManager 和具体 MetricProducer,就能把“系统里报了一个事件”与“报告里出现一个指标”之间的链路串起来。
对 OEM 的 CUJ 工作来说,关键是保证交互生命周期、帧跟踪和 StatsD 类型映射一致。先复用已有 CUJ;确有新语义时,再按目标分支完成完整映射和端侧验证。