衡量应用KPI

Vega应用KPI可视化工具通过衡量影响用户体验的关键指标，帮助您监控和优化应用的性能。此工具提供有关应用启动时间、内存使用情况和用户界面 (UI) 响应能力的数据。通过定期跟踪这些KPI，您可以确保应用提供流畅、响应迅速的体验，从而满足用户的期望。将应用发布到亚马逊应用商店之前，请务必衡量版本变体的性能，以验证您的用户是否可以获得响应迅速的体验。

本页面介绍了如何：

• 使用KPI可视化工具
• 衡量和了解应用的关键性能指标
• 设置衡量方法
• 解释结果

先决条件

在使用Vega应用KPI可视化工具之前，请确保您已完成以下事项：

1. 安装Vega性能API模块：

   复制代码 已复制到剪贴板。

    npm install @amazon-devices/kepler-performance-api
   

2. 阅读以下部分：

   • 每个KPI衡量的内容及其目标指南。参阅应用KPI指标和指南。
   • 应用在不同场景中如何启动。请参阅启动场景。
   • 何时设置性能标记。请参阅完全绘制的标记。

3. 要衡量前台内存、视频流畅度或用户界面流畅度，请按照衡量流畅度和前台内存中的说明进行操作。

4. 选择您的衡量方法：

   • 在Visual Studio (VS) Code中衡量KPI
   • 使用命令行界面 (CLI) 衡量KPI

应用KPI指标和指南

下表列出了主要KPI以及与其关联的微型KPI。主要KPI衡量整体性能指标，而微型KPI代表影响主要KPI的具体可衡量部分。

例如，应用程序JavaScript包加载时间是一个微型KPI，会影响总体首次绘制时间 (TTFD) KPI。空的微型KPI单元格表示针对该主要KPI，目前没有衡量任何具体的子部分。

启动场景

KPI可视化工具可衡量两种类型的应用启动场景，以评估TTFF和TTFD性能：

• 冷启动 - 指用户首次启动应用，并且系统会将所有资源和依赖项加载到内存中。

• 热启动 - 指用户将应用从后台（非活动状态）切换到前台（活动状态），并且内存中已有一些资源和依赖项。

完全绘制的标记

当您的应用变得可用于用户交互时，完全绘制的标记会发出信号。标记：

• 表示您的应用何时完成其主要组件的加载。
• 标记用户何时可以开始与您的应用进行交互。
• 帮助衡量TTFD性能。

要在应用中实现完全绘制的标记，请执行以下操作：

1. 将useReportFullyDrawn挂钩添加到您的应用。
2. 在以下关键点放置标记：
   • Cool start（冷启动）- 在加载初始数据并渲染主屏幕之后。
   • Warm start（热启动）- 当您的应用在前台运行后变得响应迅速时。

以下代码示例显示了如何添加完全绘制的标记：

复制代码 已复制到剪贴板。

import { useReportFullyDrawn } from '@amazon-devices/kepler-performance-api';
import React, { useCallback, useEffect, useState } from 'react';
import { useKeplerAppStateManager } from '@amazon-devices/react-native-kepler';
...
...
export const App = () => {
  const reportFullyDrawnCallback = useReportFullyDrawn();
  const KeplerAppStateManager = useKeplerAppStateManager();
  const [appState, setAppState] = useState(KeplerAppStateManager.getCurrentState());
	 
  // 使用useEffect挂钩，在首次呈现后以及
  // 在冷启动后发布第一次渲染。

  // 如果应用执行额外的异步处理，
  // 并在完全绘制之前需要完成这些处理，
  // 则在依赖项数组中传递完成状态，
  // 并检查挂钩内部的状态。
  useEffect(() => {
    reportFullyDrawnCallback();
  }, [reportFullyDrawnCallback]);

  // 在热启动后的第一次绘制时发出完全绘制标记。
  const handleAppStateChange = useCallback((stateChange: any) => {
    if (

	 appState.match(/^(inactive|background)$/) &&
	 stateChange === 'active'
	) {
	  reportFullyDrawnCallback();
	}
	if (stateChange.match(/^(inactive|background|active|unknown)$/)) {
	  setAppState(stateChange)
	}
  }, [appState, reportFullyDrawnCallback]);
	 
  useEffect(() => {
    const changeSubscription = keplerAppStateManager.addAppStateListener(
	  'change',
	  handleAppStateChange,
    );
    return () => {
	  changeSubscription.remove();
	}
  }, [handleAppStateChange]);
  ...
  ...
  return (
    <View style={styles.container}>
      ...
      ...
    </View>
  );
};

在VS Code中衡量KPI

1. 在VS Code中打开命令面板：

   • 对于Mac，使用shift + command ⌘ + p
   • 对于Linux， 使用Ctrl + Shift + P

   

2. 输入Vega: Launch App KPI Visualizer，然后按回车键。

   

   您也可以单击Vega Studio面板中的App KPI Visualizer。

3. 选择用例：

   

   注意： 您可以选择多个案例来运行。

   要衡量前台内存和视频播放流畅度，请创建与用户与应用交互方式相匹配的自定义测试场景。

   例如：

   • 对于内存测试 - 包括视频播放或图像加载
   • 对于视频播放 - 包括典型的视频观看模式

   要衡量用户界面流畅度，请开发一个测试场景，以重现应用中最常见的用户交互情况。如果没有自定义场景，默认测试会垂直和水平滚动浏览应用的首页，这可能无法准确代表用户的行为。

   有关生成测试场景的指导，请参阅衡量应用的用户界面流畅度。

   选择用例后，可视化工具将启动并针对以下KPI执行三次迭代：

   • 冷启动KPI

     • 在设备上启动测试应用
     • 等待测试应用完全加载，等待时间为10秒
     • 关闭测试应用
     • 处理KPI

   • 热启动KPI

     • 在设备上启动测试应用
     • 在设备上启动另一个应用，将测试应用移至后台
     • 启动测试应用，将其移至前台
     • 等待测试应用完全加载，等待时间为15秒
     • 关闭测试应用
     • 处理KPI

   • 前台内存KPI

     • 在设备上启动测试应用
     • 在测试场景中执行指定的步骤，并捕获KPI以进行分析和报告
     • 关闭测试应用
     • 处理KPI

   • 后台内存KPI

     • 在设备上启动测试应用
     • 在设备上启动另一个应用，将测试应用移至后台
     • 等待15秒，以收集测试应用的KPI
     • 关闭测试应用
     • 处理KPI

   • 用户界面流畅度KPI

     • 在设备上启动测试应用
     • 选择测试方法：
       • 自定义测试 - 使用您自己的用户界面交互场景
       • 默认测试 - 使用标准滚动模式
         • 2组水平滚动（向左5次，向右5次）
         • 2组垂直滚动（向下5次，向上5次）
         • 操作间隔900毫秒
     • 单击Cancel（取消）按钮或Esc（退出）键即可结束测试。

     

     • 捕获KPI以进行分析和报告。
     • 关闭测试应用
     • 处理KPI
   重要须知： 用户界面流畅度测试场景注意事项
   
   预定义的测试会滚动浏览您的应用的主页，这可能不代表应用的使用模式。创建可以反映特定应用用户界面交互情况的自定义测试场景。

   • 视频播放流畅度KPI

     • 在设备上启动测试应用
     • 在视频播放测试场景中执行相关步骤，并捕获KPI以进行分析和报告
     • 关闭测试应用
     • 处理KPI

   要停止可视化进程，请单击Cancel。

   

4. 选择在测试期间是否忽略跟踪丢失问题。

   

   当您的应用出现性能问题时，可能会发生严重的跟踪丢失问题。Vega应用KPI可视化工具既不会加载跟踪，也不会在报告中显示KPI（显示为N/A）。

   在生成KPI报告以查看指标时，您可以选择忽略跟踪丢失问题。但是，忽略跟踪丢失问题会导致生成的KPI值似乎要优于实际性能。

5. 在可视化工具窗口中查看KPI分数。

   该窗口显示通过三次测试迭代计算得出的P90（第90个百分位数）值。

6. 要评估结果，请参阅了解性能报告。

使用CLI命令衡量KPI

1. 在命令提示符下，运行kepler exec perf doctor命令以检查主机和目标设备是否已准备就绪。

   kepler exec perf doctor [--app-name]
   

   将--app-name替换为manifest.toml文件中的程序包ID。

   示例：

   kepler exec perf doctor --app-name=com.amazondeveloper.keplervideoapp.main
   
   Firmware: Stable build (<device-user> OS 1.1 (TV Mainline/1387)).
   ✅ Network: Connected
   ✅ Free disk space: 43.31 GB available.
   ✅ Appium: Installed (version 2.2.2)
   ✅ Appium driver for Vega: Installed - kepler@3.18.0 [installed (linked from /Users/.../AppiumVegaDriver)]
   ✅ com.amazondeveloper.keplervideoapp.main is installed.
   
   Collecting CPU (4 cores) and Memory data...
   ❌ Max User CPU usage at 241.20%.Check for unwanted processes.
   ❌ Max System CPU usage at 222.80%.Check for unwanted processes.
   ✅ Average User CPU usage at 166.16%
   ✅ Average System CPU usage at 101.84%
   ✅ Min memory available at 30.80%
   ✅ Average memory available at 32.16%
   
   ! Device: Not ready for performance testing.Please review lines with X (error) and ! (warnings) symbols.
   

2. 启动Vega应用KPI可视化工具：

   kepler exec perf kpi-visualizer --app-name=[应用名称]
   

   对于kpi-visualizer来说，应用名称是唯一一个必需要有的参数。将[应用名称]替换为manifest.toml文件中默认交互组件的ID。

3. （可选）指定默认迭代次数。默认迭代数： 如果使用了认证，则为3或30。

   --iteration [次数] 
   

4. （可选）指定要衡量的KPI：

   --kpi [KPI名称]
   

   如果没有此参数，可视化工具会默认衡量冷启动TTFF和TTFD KPI。

5. 查看所有可用选项：

   复制代码 已复制到剪贴板。

    kpi-visualizer --help
   

   示例（注意：界面显示内容均为英文。此处中文译文仅供参考。）：

    kepler exec perf kpi-visualizer --help
   
    名称：
   
    KPI可视化工具
   
    描述：
   
    衡量应用启动时间、内存使用量和用户界面响应能力等关键性能指标，以优化应用的用户体验。
   
    概要：
   
    kepler exec perf kpi-visualizer [parameters]
   
    使用'kepler exec perf command --help'检索特定命令的信息。
   
    参数：
   
    --iterations ITERATIONS
          设置运行测试的次数。这会覆盖.conf设置。
    --record-cpu-profiling
          在测试执行期间启用CPU配置文件记录。
    --sourcemap-file-path SOURCEMAP_FILE_PATH
          指定源映射文件的路径。
    --grpc-port port
          指定gRPC服务器的端口号。
    --certification
          使用30次迭代和第90个百分位聚合在认证模式下运行测试。
    --expected-video-fps EXPECTED_VIDEO_FPS
          为受测应用指定目标FPS。
    --kpi KPI       
          （可选）指定要衡量的性能指标。
   
          支持的场景：
          1. 冷启动延迟 - 衡量应用冷启动时的启动延迟。默认情况下包括TTFF和TTFD。
          2. 用户界面流畅度 - 衡量用户界面交互的流畅度。
          3. 热启动延迟 - 衡量将应用程序从后台恢复到前台时的第一帧显示延迟。
          4. 前台内存 - 衡量应用处于前台状态时的内存使用情况。
          5. 后台内存 - 衡量应用处于后台状态时的内存使用情况。
          6. 视频流畅度 - 衡量视频播放的流畅度。需要启动视频播放的测试场景 (--test-scenario)。
   
    --test-scenario TEST_SCENARIO
          指定定义用户界面测试场景的Python脚本。使用generate-test-template命令创建测试场景模板。
   
    --monitor-processes MONITOR_PROCESSES [MONITOR_PROCESSES ...]
          指定测试期间要监控的其他服务。
   
          示例：
          --monitor-processes webview.renderer_service
   
    --ignore-trace-loss
          测试期间跳过跟踪数据丢失验证。
   
    --help  
          显示此帮助消息。
   
    --version, -v
          显示此perf工具的当前版本。
    %
   

可视化完成后，您将在stdout中看到报告摘要。

示例报告：

Performance Analyzer KPI Report

Firmware version: Device OS 1.1 (VegaMainlineTvIntegration/XXXX), serial number: XXXXXXXXXXXXXXXX
Date: 01/09/2025, test: app-background, iterations requested: 3, iterations completed: 3, duration: 15 seconds

Memory Statistics
                            | n   | min    | mean    | max    | stdev  | ci (+/-)
App Resident Memory (kB)    | 104 | 131044 | 132139.0| 133136 | 865.2  | 140.8 √

当KPI显示-1时，表示平均值、最小值和最大值的数据不可用。对于TTFD，当应用未调用“报告完全绘制的API”时，可能会发生这种情况。

如果KPI未显示，则表示在数据收集过程中可能会出现严重的跟踪丢失问题。KPI可视化工具不会加载跟踪，也不会显示KPI。要在出现跟踪丢失问题的情况下查看KPI，请运行：

--ignore-trace-loss <true/false>

了解性能报告

Vega应用KPI可视化工具会显示性能报告，其中包括：

1. Test information（测试信息）

   • Date（日期）- 系统捕获KPI数据的日期
   • Device Serial ID（设备序列号）- 运行应用的设备的唯一标识符
   • App（应用）- 显示KPI数据的应用的名称
   • Number of iterations（迭代次数）- 执行KPI衡量进程的次数

2. KPI Name（KPI名称）- 带单位的KPI的名称

3. Test Name（测试名称）- 测试或已完成用例的名称

4. KPI Health（KPI健康状况）- 代表每个KPI健康状况的颜色编码系统：

   • 🟢（绿色）- 表示在建议值范围内
   • 🟡（黄色）- 表示超过建议值10%以内
   • 🔴（红色）- 表示超过建议值10％以上

5. KPI Score（KPI分数）- KPI的数值，以KPI名称中指定的单位显示。如果可视化工具无法计算KPI，则会显示KPI分数为“N/A”（不适用），并将KPI Health列为“Unknown”（未知）。

6. Guideline（指南）- 基于行业标准或性能目标提供的KPI分数建议值或范围。

结果示例

下图显示了每个用例的结果示例。请注意与指南相关的KPI Health指标和分数。

用例： 冷启动TTFF和TTFD

以下结果显示了启动性能指标。绿色指示灯表示应用符合启动时间指南的要求。

用例： 热启动TTFF和TTFD

以下结果表示应用如何从后台状态恢复。比较TTFF和TTFD时间以评估优化需求。

用例： 前台内存

显示应用在活跃使用期间的内存使用情况。监控此指标，以防因内存消耗过多而导致性能问题。

用例： 后台内存

显示应用在后台状态下的内存占用量。对于了解应用在非活动状态下对系统资源的影响非常重要。

用例： 用户界面流畅度

显示应用处理用户交互的流畅程度。该百分比表示在滚动和导航期间成功渲染的帧。

用例： 视频播放流畅度

显示应用播放视频内容的流畅程度。该百分比表示以预期播放速率成功传输的帧。

打开KPI报告

Vega应用KPI可视化工具在完成测试场景后会生成以下报告文件：

• aggregated-kpi-report-[时间戳].json - 整合来自所有测试场景的KPI数据

• [测试名称]-kpi-report-[时间戳].json - 为每个单独的测试场景创建一个文件[测试名称] 用于标识特定场景

[时间戳] 表示Vega应用KPI可视化工具生成报告的时间

要打开KPI报告，请打开之前的记录。然后使用以下方法之一：

选项1（首选）： 使用快速打开 此方法可通过VS Code的界面或CLI访问您的记录。

在VS Code中：

1. 使用VS Code快速打开或在项目的generated目录中查找KPI报告文件（例如：app-launch-kpi-report-[时间戳].json）。
2. 单击文件一次进行预览，或单击两次以活动模式打开。

在CLI中：

1. 打开终端窗口并输入：

   code <<记录文件路径>>

如果您的终端无法识别Code命令：

1. 打开VS Code。

2. 打开命令面板：

   • Mac： Cmd+Shift+P
   • Linux： Ctrl+Shift+P
3. 运行“Shell Command: Install code command in PATH”。
4. 重试该命令。

选项2： 使用VS Code命令面板 此方法可让您使用VS Code的内置命令界面或在快速打开不可用时访问您的记录。

1. 打开VS Code。

2. 打开命令面板：

   • Mac： Cmd+Shift+P
   • Linux： Ctrl+Shift+P
3. 输入Vega: Open Recording View。
4. 选择要打开的文件，例如app-launch-kpi-report-[时间戳].json。

相关主题

• 衡量流畅度和前台内存
• 确定用户界面渲染问题
• 监控CPU使用情况
• 监控和记录内存
• 检测过度绘制

Last updated: 2025年10月16日