此页面由 Cloud Translation API 翻译。

ProtoLog

Android 日志记录系统旨在实现普遍可访问性和易用性，前提是所有日志数据都可以表示为字符序列。这个前提适用于大多数用例，尤其是在没有专用工具的情况下，日志可读性至关重要时。不过，在对日志记录性能要求很高且日志大小受限的环境中，基于文本的日志记录可能不是最佳选择。WindowManager 就是这样的一个场景，它需要一个强大的日志记录系统，能够处理实时窗口转换日志且对系统影响最小。

ProtoLog 是满足 WindowManager 和类似服务的日志记录需求的替代方案。ProtoLog 相对于 logcat 的主要优势包括：

用于记录日志的资源量更少。
从开发者角度来看，这与使用默认的 Android 日志记录框架相同。
支持在运行时启用或停用日志语句。
仍可根据需要将日志记录到 logcat。

为了优化内存用量，ProtoLog 采用了字符串驻留机制，其中涉及计算和保存消息的已编译哈希值。为了提高性能，ProtoLog 会在编译期间（针对系统服务）执行字符串驻留，仅在运行时记录消息标识符和参数。此外，在生成 ProtoLog 跟踪记录或获取 bug 报告时，ProtoLog 会自动合并在编译时创建的消息字典，从而支持从任何 build 中解码消息。

使用 ProtoLog 时，消息会以二进制格式 (proto) 存储在 Perfetto 跟踪记录中。消息解码发生在 Perfetto 的 trace_processor 内。该过程包括解码二进制 proto 消息、使用嵌入的消息字典将消息标识符转换为字符串，以及使用动态参数设置字符串格式。

ProtoLog 支持与 android.utils.Log 相同的日志级别，即：d、v、i、w、e、wtf。

客户端 ProtoLog

最初，ProtoLog 仅适用于 WindowManager 的服务器端，在单个进程和组件中运行。随后，它被扩展到包含系统界面进程中的 WindowManager shell 代码，但使用 ProtoLog 需要复杂的样板设置代码。此外，Proto 日志记录仅限于系统服务器和系统界面进程，因此很难集成到其他进程中，并且需要为每个进程单独设置内存缓冲区。不过，ProtoLog 现在已可用于客户端代码，且无需额外的样板代码。

与系统服务代码不同，客户端代码通常会跳过编译时字符串驻留。字符串驻留则会在后台线程中动态发生。因此，虽然客户端上的 ProtoLog 在内存使用方面与系统服务伤的 ProtoLog 具有相当的优势，但它的性能开销略高，并且不具备其服务器端对应部分的固定内存带来的内存缩减优势。

ProtoLog 组

ProtoLog 消息会分成名为 ProtoLogGroups 的组，类似于 Logcat 消息按 TAG 进行整理的方式。这些 ProtoLogGroups 用作消息集群，可在运行时集体启用或停用。此外，它们还控制着是否应在编译期间去除消息，以及应在何处记录消息（proto、logcat 或两者兼有）。每个 ProtoLogGroup 都包含以下属性：

enabled：如果设置为 false，则会在编译期间排除此组中的消息，并且在运行时无法使用这些消息。
logToProto：定义此组是否使用二进制格式记录日志。
logToLogcat：定义此组是否会将日志记录到 logcat。
tag：已记录消息的来源名称。

使用 ProtoLog 的每个进程都必须配置一个 ProtoLogGroup 实例。

支持的参数类型

在内部，ProtoLog 使用 android.text.TextUtils#formatSimple(String, Object...) 格式化字符串，因此其语法相同。

ProtoLog 支持以下参数类型：

%b - 布尔值
%d、%x - 整数类型（short、integer 或 long）
%f - 浮点类型（float 或 double）
%s - 字符串
%% - 字面量百分号

系统支持宽度和精度修饰符，例如 %04d 和 %10b，但不支持 argument_index 和 flags。

在新服务中使用 ProtoLog

如需在新进程中使用 ProtoLog，请执行以下操作：

为此服务创建 ProtoLogGroup 定义。
在首次使用之前初始化定义（例如，在进程创建时）：

Protolog.init(ProtologGroup.values());
使用 Protolog 的方式与使用 android.util.Log 的方式相同：

ProtoLog.v(WM_SHELL_STARTING_WINDOW, "create taskSnapshot surface for task: %d", taskId);

启用编译时优化

如需在进程中启用编译时 ProtoLog，您必须更改其构建规则并调用 protologtool 二进制文件。

ProtoLogTool 是一种代码转换二进制文件，用于执行字符串驻留并更新 ProtoLog 调用。此二进制文件会转换每个 ProtoLog 日志记录调用，如以下示例所示：

ProtoLog.x(ProtoLogGroup.GROUP_NAME, "Format string %d %s", value1, value2);

转换为：

if (ProtoLogImpl.isEnabled(GROUP_NAME)) {
    int protoLogParam0 = value1;
    String protoLogParam1 = String.valueOf(value2);
    ProtoLogImpl.x(ProtoLogGroup.GROUP_NAME, 1234560b0100, protoLogParam0, protoLogParam1);
}

在此示例中，ProtoLog、ProtoLogImpl 和 ProtoLogGroup 是作为参数提供的类（可以导入、静态导入或完整路径，不允许通配符导入），x 是日志记录方法。

转换是在源代码级别完成的。系统会根据格式字符串、日志级别和日志组名称生成哈希，并将其插入 ProtoLogGroup 参数后面。实际生成的代码是内嵌的，并添加一些新的换行符以保持文件中的行号不变。

示例：

genrule {
    name: "wm_shell_protolog_src",
    srcs: [
        ":protolog-impl", // protolog lib
        ":wm_shell_protolog-groups", // protolog groups declaration
        ":wm_shell-sources", // source code
    ],
    tools: ["protologtool"],
    cmd: "$(location protologtool) transform-protolog-calls " +
        "--protolog-class com.android.internal.protolog.ProtoLog " +
        "--loggroups-class com.android.wm.shell.protolog.ShellProtoLogGroup " +
        "--loggroups-jar $(location :wm_shell_protolog-groups) " +
        "--viewer-config-file-path /system_ext/etc/wmshell.protolog.pb " +
        "--legacy-viewer-config-file-path /system_ext/etc/wmshell.protolog.json.gz " +
        "--legacy-output-file-path /data/misc/wmtrace/shell_log.winscope " +
        "--output-srcjar $(out) " +
        "$(locations :wm_shell-sources)",
    out: ["wm_shell_protolog.srcjar"],
}

命令行选项

ProtoLog 的一个主要优势是，您可以在运行时启用或停用它。例如，您可以在 build 中启用详细日志记录（默认处于停用状态），并在本地开发期间启用它，以便调试特定问题。例如，在 WindowManager 中使用此模式，其中 WM_DEBUG_WINDOW_TRANSITIONS 和 WM_DEBUG_WINDOW_TRANSITIONS_MIN 组用于启用不同类型的转换日志记录，前者默认处于启用状态。

在启动跟踪记录时，您可以使用 Perfetto 配置 ProtoLog。您还可以使用 adb 命令行在本地配置 ProtoLog。

命令 adb shell cmd protolog_configuration 支持以下参数：

help
  Print this help text.

groups (list | status)
  list - lists all ProtoLog groups registered with ProtoLog service"
  status <group> - print the status of a ProtoLog group"

logcat (enable | disable) <group>"
  enable or disable ProtoLog to logcat

有效使用提示

ProtoLog 会对消息和传递的任何字符串参数使用字符串驻留。这意味着，为了从 ProtoLog 中获得更多优势，消息应将重复值隔离到变量中。

例如，请参考以下语句：

Protolog.v(MY_GROUP, "%s", "The argument value is " + argument);

在编译时优化后，它会转换为以下代码：

ProtologImpl.v(MY_GROUP, 0x123, "The argument value is " + argument);

如果在代码中使用 ProtoLog 并带有参数 A,B,C：

Protolog.v(MY_GROUP, "%s", "The argument value is A");
Protolog.v(MY_GROUP, "%s", "The argument value is B");
Protolog.v(MY_GROUP, "%s", "The argument value is C");
Protolog.v(MY_GROUP, "%s", "The argument value is A");

这会导致内存中出现以下消息：

Dict:
  0x123: "%s"
  0x111: "The argument value is A"
  0x222: "The argument value is B"
  0x333: "The argument value is C"

Message1 (Hash: 0x123, Arg1: 0x111)
Message2 (Hash: 0x123, Arg2: 0x222)
Message3 (Hash: 0x123, Arg3: 0x333)
Message4 (Hash: 0x123, Arg1: 0x111)

如果改为将 ProtoLog 语句写成如下形式：

Protolog.v(MY_GROUP, "The argument value is %s", argument);

内存缓冲区最终将变为：

Dict:
  0x123: "The argument value is %s" (24 b)
  0x111: "A" (1 b)
  0x222: "B" (1 b)
  0x333: "C" (1 b)

Message1 (Hash: 0x123, Arg1: 0x111)
Message2 (Hash: 0x123, Arg2: 0x222)
Message3 (Hash: 0x123, Arg3: 0x333)
Message4 (Hash: 0x123, Arg1: 0x111)

此序列可使内存占用量减少 35%。

Winscope 查看器

Winscope 的 ProtoLog 查看器标签页会以表格式显示 ProtoLog 跟踪记录。您可以按日志级别、标记、源文件（存在 ProtoLog 语句）和消息内容过滤跟踪记录。所有列均可过滤。点击第一列中的时间戳会将时间轴移动到消息时间戳。此外，点击 Go to Current Time 可将 ProtoLog 表格滚动回时间轴中所选的时间戳：

ProtoLog 查看器

图 1. ProtoLog 查看器