アプリのKPIの測定

• KPI Visualizerの使用
• アプリの主要業績評価指標の測定と理解
• 測定のセットアップ
• 結果の解釈

​

前提条件

1. VegaパフォーマンスAPIモジュールをインストールします。
   npm install @amazon-devices/kepler-performance-api
   
2. 次のセクションに目を通してください。
   • 各KPIが測定する内容とそのターゲットのガイドライン。アプリのKPI指標とガイドラインを参照してください。
   • さまざまなシナリオでのアプリの起動方法。起動シナリオを参照してください。
   • パフォーマンスマーカーを設定するタイミング。描画完了マーカーを参照してください。
3. フォアグラウンドメモリ、ビデオの滑らかさ、またはUIの滑らかさを測定するには、滑らかさとフォアグラウンドメモリの測定の手順に従ってください。
4. 測定方法を選択します。
   • Visual Studio（VS）CodeでのKPIの測定
   • コマンドラインインターフェイス（CLI）でのKPIの測定

​

アプリのKPI指標とガイドライン

​

起動シナリオ

• クールスタート - ユーザーが初めてアプリを起動し、システムがすべてのリソースと依存関係をメモリに読み込むとき。
• ウォームスタート - 一部のリソースと依存関係がすでにメモリにある状態で、ユーザーがアプリをバックグラウンド（非アクティブ状態）からフォアグラウンド（アクティブ状態）に移行するとき。

​

描画完了マーカー

• アプリの必須コンポーネントの読み込みが完了したことを示す。
• ユーザーがアプリの操作を開始できるタイミングを示す。
• TTFDパフォーマンスの測定に役立つ。

1. useReportFullyDrawnフックをアプリに追加します。
2. 次のキーポイントにマーカーを配置します。
   • クールスタート - 初期データを読み込んでメイン画面をレンダリングした後。
   • ウォームスタート - フォアグラウンド移行後にアプリが応答可能になったとき。

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」と入力してEnterを押す

​

手順3：ユースケースを選択する

• メモリテスト用 - ビデオ再生または画像読み込みを含めます。
• ストリーミング用 - 一般的なビデオ視聴パターンを含めます。

​

クールスタートKPI

• デバイス上でテストアプリを起動します。
• テストアプリが完全に読み込まれるまで10秒間待ちます。
• テストアプリを閉じます。
• KPIを処理します。

​

ウォームスタートKPI

• デバイス上でテストアプリを起動します。
• デバイス上で別のアプリを起動して、テストアプリをバックグラウンドに移行させます。
• テストアプリを起動して、フォアグラウンドに移動します。
• テストアプリが完全に読み込まれるまで15秒間待ちます。
• テストアプリを閉じます。
• KPIを処理します。

​

フォアグラウンドメモリKPI

• デバイス上でテストアプリを起動します。
• テストシナリオに指定されている手順を実行し、分析とレポートのためにKPIをキャプチャします。
• テストアプリを閉じます。
• KPIを処理します。

​

バックグラウンドメモリKPI

• デバイス上でテストアプリを起動します。
• デバイス上で別のアプリを起動して、テストアプリをバックグラウンドに移行させます。
• テストアプリのKPIが収集されるまで15秒間待ちます。
• テストアプリを閉じます。
• KPIを処理します。

​

UIの滑らかさKPI

• デバイス上でテストアプリを起動します。
• テスト方法を選択します。
  • カスタムテスト - 独自のUI操作シナリオを使用する
  • デフォルトテスト - 標準のスクロールパターンを使用する
    • 横スクロール2セット（左5回、右5回）
    • 縦スクロール2セット（下5回、上5回）
    • アクション間隔900ミリ秒
• [Cancel] ボタンをクリックするか、Escキーを押してテストを終了します。
• 分析とレポートのためにKPIをキャプチャします。
• テストアプリを閉じます。
• KPIを処理します。

​

ビデオ再生の滑らかさKPI

• デバイス上でテストアプリを起動します。
• ビデオ再生テストシナリオに指定されている手順を実行し、分析とレポートのためにKPIをキャプチャします。
• テストアプリを閉じます。
• KPIを処理します。

​

手順4：テスト中のトレースロスを無視するかどうかを選択する

​

手順5：VisualizerのウィンドウでKPIスコアを確認する

​

手順6：結果を評価する

​

CLIコマンドによるKPIの測定

1. コマンドプロンプトでvega exec perf doctorコマンドを実行して、ホストとターゲットデバイスの準備が整っているかどうかを確認します。
   vega exec perf doctor [--app-name]
   
   --app-nameには、manifest.tomlファイルから取得したパッケージIDを指定します。複数のデバイス（Vega仮想デバイスを含む）が実行されている場合は、perfコマンドで--device-serial-numberパラメーターを使用して、デバイスのシリアル番号を指定します。 1つのデバイスのみが接続されている場合の例：
   # 単一のデバイス
   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 App KPI Visualizerを起動します。
   vega exec perf kpi-visualizer --app-name=[app-name]
   
   kpi-visualizerでは、app-nameが唯一の必須パラメーターです。[app-name]をmanifest.tomlファイルにあるデフォルトの対話型コンポーネントのIDに置き換えます。
3. （任意）デフォルトの反復回数を指定します。デフォルトの反復回数は –certificationを使用する場合は3または30。
   --iteration [number]
   
4. （任意）測定するKPIを指定します。
   --kpi [kpi name]
   
   このパラメーターがない場合、Visualizerはクールスタートの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の名前と単位。
3. Test Name - テストまたは実行されたユースケースの名前。
4. KPI Health - 各KPIの健全性を示す色分け表示。
   • 🟢（緑）- 推奨ガイドラインを満たしている
   • 🟡（黄色）- ガイドラインの10%以内
   • 🔴（赤）- ガイドラインを10%超過
5. KPI Score - KPIの数値。KPI名に指定されている単位で表されます。VisualizerでKPIを計算できない場合、KPIスコアは「N/A」と表示され、KPIの健全性は「Unknown」と表示されます。
6. Guideline - 推奨されるKPIスコアの値または範囲。業界標準または業績目標に基づきます。

​

結果の例

​

ユースケース：クールスタート時のTTFFとTTFD

​

ユースケース：ウォームスタート時のTTFFとTTFD

​

ユースケース：フォアグラウンドメモリ

​

ユースケース：バックグラウンドメモリ

​

ユースケース：UIの滑らかさ

​

ユースケース：ビデオ再生の滑らかさ

​

KPIレポートを開く

• aggregated-kpi-report-<タイムスタンプ>.json - すべてのテストシナリオのKPIデータを統合する。
• <テスト名>-kpi-report-<タイムスタンプ>.json - 個々のテストシナリオごとに1つのファイルを作成する。<テスト名> は特定のシナリオを表します。

​

オプション1（推奨）：クイックオープンを使用する

​

VS Codeの場合

1. KPIレポートファイル（例：app-launch-kpi-report-[timestamp].json）を、VS Codeクイックオープンを使用して、またはプロジェクトのgeneratedディレクトリで見つけます。
2. ファイルを1回クリックしてプレビューするか、2回クリックしてアクティブモードで開きます。

​

CLIの場合

1. ターミナルウィンドウを開き、次のように入力します。
   code <<記録ファイルのパス>>
   
   ターミナルでcodeコマンドが認識されない場合は、VS Codeコマンドパレットを開きます。
   • Mac：Cmd+Shift+P
   • Linux：Ctrl+Shift+P
2. 「Shell Command: Install code command in PATH」を実行します。
3. コマンドを再試行します。

​

オプション2：VS Codeコマンドパレットを使用する

1. VS Codeを開きます。
2. コマンドパレットを開きます。
   • Mac：Cmd+Shift+P
   • Linux：Ctrl+Shift+P
3. 「Vega: Open Recording View」と入力します。
4. app-launch-kpi-report-[timestamp].jsonなど、開くファイルを選択します。

​

関連トピック

• ▶️ Vegaアプリのパフォーマンスの向上
• 滑らかさとフォアグラウンドメモリの測定
• UIレンダリングの問題の特定
• CPU使用率のモニタリング
• メモリのモニタリングと記録
• オーバードローの検出