衡量应用KPI

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

​

先决条件

1. 安装Vega性能API模块：
   npm install @amazon-devices/kepler-performance-api
   
2. 阅读以下部分：
   • 每个KPI衡量的内容及其目标指南。参阅应用KPI指标和指南。
   • 应用在不同场景中如何启动。请参阅启动场景。
   • 何时设置性能标记。请参阅完全绘制的标记。
3. 要衡量前台内存、视频流畅度或用户界面流畅度，请按照衡量流畅度和前台内存中的说明进行操作。
4. 选择您的衡量方法：
   • 在VS Code中衡量KPI
   • 使用CLI衡量KPI

​

应用KPI指标和指南

​

启动场景

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

​

完全绘制的标记

• 表示您的应用何时完成其主要组件的加载。
• 标记用户何时可以开始与您的应用进行交互。
• 帮助衡量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

​

步骤3： 选择用例

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

​

冷启动KPI

• 在设备上启动测试应用
• 等待10秒钟让测试应用加载。
• 关闭测试应用
• 处理KPI

​

热启动KPI

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

​

前台内存KPI

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

​

后台内存KPI

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

​

用户界面流畅度KPI

• 在设备上启动测试应用
• 选择测试方法：
  • 自定义测试 - 使用您自己的用户界面交互场景
  • 默认测试 - 使用标准滚动模式
    • 两组水平滚动（向左五个，向右五个）
    • 两组垂直滚动（向下五个，向上五个）
    • 操作间隔900毫秒
• 选择Cancel（取消）或按Esc结束测试。
• 捕获KPI以进行分析和报告。
• 关闭测试应用
• 处理KPI

​

视频播放流畅度KPI

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

​

步骤5：选择在测试期间是否忽略跟踪丢失问题

​

步骤6：在可视化工具窗口中查看KPI分数

​

步骤7：评估结果

​

使用CLI命令衡量KPI

1. 在命令提示符下，运行vega exec perf doctor命令以检查主机和目标设备是否已准备就绪。
   vega exec perf doctor [--app-name]
   
   将--app-name替换为manifest.toml文件中的程序包ID。如有多台设备同时运行（包括Vega虚拟设备），则使用--device-serial-number参数在性能命令中指定设备序列号。 单台设备连接示例：
   # 单台设备
   vega 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.
   
   多台设备连接示例：
   # 多台设备
   vega exec perf doctor --app-name=com.amazondeveloper.keplervideoapp.main --device-serial-number=G000XX1234567890
   
2. 启动Vega应用KPI可视化工具：
   vega exec perf kpi-visualizer --app-name=[应用名称]
   
   对于kpi-visualizer，只有app-name是必填参数。将 [应用名称] 替换为manifest.toml文件中默认交互组件的ID。
3. （可选）指定默认迭代次数。默认迭代数：如果使用了认证，则为3或30。
   --iteration [次数]
   
4. （可选）指定要衡量的KPI：
   --kpi [KPI名称]
   
   如果没有此参数，可视化工具会默认衡量冷启动TTFF和TTFD KPI。
5. 查看所有可用选项：
   kpi-visualizer --help
   
   示例：
   vega exec perf kpi-visualizer --help
   
   NAME:
   
   KPI Visualizer Tool
   
   DESCRIPTION:
   
   Measures key performance metrics like app launch times, memory usage, and UI responsiveness to optimize your app's user experience.
   
   SYNOPSIS:
   
   vega exec perf kpi-visualizer [parameters]
   
   Use 'vega exec perf command --help' to retrieve information for a specific command.
   
   PARAMETERS:
   
   --iterations ITERATIONS
         Sets the number of times to run the test. This overrides .conf setting.
   --record-cpu-profiling
         Enables CPU profile recording during test execution.
   --sourcemap-file-path SOURCEMAP_FILE_PATH
         Specifies the path to the source map file.
   --grpc-port port
         Specifies the port number for the gRPC server.
   --certification
         Runs tests in certification mode using 30 iterations and 90th percentile aggregation.
   --expected-video-fps EXPECTED_VIDEO_FPS
         Specifies the target FPS for the app under test.
   --kpi KPI
         (Optional) Specifies the performance metric to measure.
   
         Supported scenarios:
         1. cool-start-latency -  Measures app launch latency from cool start. Includes both TTFF and TTFD by default.
         2. ui-fluidity - Measures smoothness of UI interactions.
         3. warm-start-latency - Measures first frame display latency when resuming an app from background to foreground.
         4. foreground-memory -  Measures app memory usage while in foreground state.
         5. background-memory -  Measures app memory usage while in background state.
         6. video-fluidity - Measures smoothness of video playback. Requires a test scenario (--test-scenario) that initiates video playback.
   
   --test-scenario TEST_SCENARIO
         Specifies the Python script that defines the UI test scenario. Use the generate-test-template command to create a test scenario template.
   
   --monitor-processes MONITOR_PROCESSES [MONITOR_PROCESSES ...]
         Specifies additional services to monitor during testing.
   
         Example:
         --monitor-processes webview.renderer_service
   
   --ignore-trace-loss
         Skips trace data loss verification during test.
   
   --help
         Shows this help message.
   
   --version, -v
         Shows current version of this perf tool.
   %
   

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 √

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

​

了解性能报告

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分数建议值或范围。

​

结果示例

​

用例：冷启动TTFF和TTFD

​

用例：热启动TTFF和TTFD

​

用例：前台内存

​

用例：后台内存

​

用例：用户界面流畅度

​

用例：视频播放流畅度

​

打开KPI报告

• aggregated-kpi-report-[时间戳].json - 整合来自所有测试场景的KPI数据
• [测试名称]-kpi-report-[时间戳].json - 为每个单独的测试场景创建一个文件[测试名称] 用于标识特定场景

​

选项1（首选）：使用快速打开

​

在VS Code中

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

​

在CLI中

1. 打开终端窗口并输入：
   code <<记录文件路径>>
   
   如果您的终端无法识别代码命令，请打开VS Code命令面板：
   • 输入Vega: Open Recording View（Vega：打开记录视图）。
   • 如果您的终端无法识别code命令，请打开VS Code命令面板（使用Mac时按Cmd+Shift+P，使用Linux时按Ctrl+Shift+P）。
2. 选择Shell Command: Install code command in PATH（Shell命令：在PATH中安装code命令）。
3. 重试该命令。

​

选项2：使用VS Code命令面板

1. 打开VS Code。
2. 打开命令面板（使用Mac时按Cmd+Shift+P，使用Linux时按Ctrl+Shift+P）。
   • 输入Vega: Open Recording View（Vega：打开记录视图）。
   • 如果您的终端无法识别code命令，请打开VS Code命令面板（使用Mac时按Cmd+Shift+P，使用Linux时按Ctrl+Shift+P）。
3. 输入Vega: Open Recording View（Vega：打开记录视图）。
4. 选择要打开的文件，例如app-launch-kpi-report-[时间戳].json。

​

相关主题

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