アプリのKPIの測定

Vega App KPI Visualizerは、ユーザーエクスペリエンスに影響を与える重要な指標を測定することにより、アプリのパフォーマンスのモニタリングと最適化をサポートします。このツールは、アプリの起動時間、メモリ使用量、ユーザーインターフェイス（UI）の応答性に関するデータを提供します。これらのKPIを定期的にトラッキングすると、アプリはユーザーの期待に応えるスムーズで応答性の高いエクスペリエンスを提供できます。App Storeにアプリを公開する前に、リリースバリアントのパフォーマンスを測定して、ユーザーエクスペリエンスの応答性が高いことを確認してください。

このページでは、次の方法について説明します。

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

前提条件

Vega App 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指標とガイドライン

次の表は、主なKPIとそれに関連するマイクロKPIの両方を示しています。メインKPIは全体的なパフォーマンス指標を測定し、マイクロKPIはメインKPIに寄与する特定の測定可能なコンポーネントを表します。

たとえば、Application JavaScript bundle load timeは、最初に描画されるまでの時間（TTFD）のKPI全体に影響するマイクロKPIです。空のマイクロKPIセルは、そのメインKPIについて現在特定のサブコンポーネントが測定されていないことを示しています。

起動シナリオ

KPI Visualizerは、TTFFとTTFDのパフォーマンスを評価するために、次の2種類のアプリ起動シナリオを測定します。

• クールスタート - ユーザーが初めてアプリを起動し、システムがすべてのリソースと依存関係をメモリに読み込むとき。

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

描画完了マーカー

描画完了マーカーは、アプリがユーザー操作を受け付けられる状態になったことを知らせます。マーカーは以下の役割を果たします。

• アプリの必須コンポーネントの読み込みが完了したことを示す。
• ユーザーがアプリの操作を開始できるタイミングを示す。
• 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キーを押します。

   

   [Kepler Studio] パネルから [App KPI Visualizer] をクリックすることもできます。

3. ユースケースを選択します。

   

   注： 複数のケースを選択して実行できます。

   フォアグラウンドメモリとビデオストリーミングの滑らかさを測定するには、ユーザーによるアプリの操作方法に合わせたカスタムテストシナリオを作成します。

   以下に例を示します。

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

   UIの滑らかさを測定するには、アプリで特に多く実行されるユーザー操作を再現するテストシナリオを開発してください。カスタムシナリオがない場合、デフォルトのテストではアプリのフロントページを縦横にスクロールする操作が使用されますが、これはユーザーの行動を正確に反映していない可能性があります。

   テストシナリオの生成に関するガイダンスについては、アプリのUIの滑らかさの測定を参照してください。

   ユースケースを選択すると、Visualizerが起動し、次のKPI測定を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を処理します。
   重要： UIの滑らかさテストシナリオの考慮事項
   
   事前定義されたテストではアプリのホームページがスクロールされますが、これはアプリの使用パターンと一致しない場合があります。アプリ固有のUI操作を反映したカスタムテストシナリオを作成してください。

   • ビデオ再生の滑らかさKPI

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

   視覚化プロセスを停止するには、[Cancel] をクリックします。

   

4. テスト中のトレースロスを無視するかどうかを選択します。

   

   アプリにパフォーマンス上の問題があると、トレースが大幅に失われる可能性があります。Vega App KPI Visualizerはトレースを読み込まず、レポートにKPIを表示しなくなります（N/Aと表示）。

   KPIレポートを生成して指標を表示するときに、トレースロスを無視するかどうかを選択できます。ただし、トレースロスを無視すると、実際のパフォーマンスよりも優れたKPI値が生成されます。

5. VisualizerウィンドウでKPIスコアを確認します。

   ウィンドウには、3回のテストから計算された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 App KPI Visualizerを起動します。

   kpi-visualizer --app-name=<アプリ名>
   

   kpi-visualizerでは、app-nameが唯一の必須パラメーターです。<アプリ名>をmanifest.tomlファイルにあるデフォルトの対話型コンポーネントのIDに置き換えます。

3. （任意）デフォルトの反復回数を指定します。デフォルトの反復回数： –certificationを使用する場合は3または30。

   --iteration <回数> 
   

4. （任意）測定するKPIを指定します。

   --kpi <KPI名>
   

   このパラメーターがない場合、VisualizerはクールスタートのTTFFとTTFD KPIをデフォルトで測定します。

5. 利用可能なすべてのオプションを表示します。

   コードをコピー クリップボードにコピーしました。

    kpi-visualizer --help
   

   例（注：画面の出力に関する日本語表記は説明のために提供しています。実際には英語で表示されます。）：

    kepler exec perf kpi-visualizer --help
   
    名前：
   
    KPI Visualizerツール
   
    説明：
   
    アプリのユーザーエクスペリエンスを最適化するために、アプリの起動時間、メモリ使用量、UIの応答性などの主要業績評価指標を測定します。
   
    書式：
   
    kepler exec perf kpi-visualizer [パラメーター]
   
    特定のコマンドの情報を取得するには、'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. cool-start-latency - コールドスタートからのアプリの起動レイテンシを測定します。TTFFとTTFDの両方がデフォルトで含まれます。
          2. ui-fluidity - UI操作の滑らかさを測定します。
          3. warm-start-latency - アプリがバックグラウンドからフォアグラウンドに復帰するときの、最初のフレームの表示レイテンシを測定します。
          4. foreground-memory - アプリがフォアグラウンド状態にあるときのメモリ使用量を測定します。
          5. background-memory - アプリがバックグラウンド状態にあるときのメモリ使用量を測定します。
          6. video-fluidity - ビデオ再生の滑らかさを測定します。ビデオ再生を開始するテストシナリオ（--test-scenario）が必要です。
   
    --test-scenario TEST_SCENARIO
          UIのテストシナリオを定義する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 Visualizerはトレースを読み込まず、KPIも表示されません。トレースが失われた場合でもKPIを表示するには、以下を実行します。

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

パフォーマンスレポートの理解

Vega App KPI Visualizerには、以下を含むパフォーマンスレポートが表示されます。

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スコアの値または範囲。業界標準または業績目標に基づきます。

結果の例

以下の画像は、各ユースケースの結果のサンプルを示しています。ガイドラインに関連するKPIの健全性指標とスコアに注目してください。

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

以下の結果は起動パフォーマンス指標を示しています。緑色のインジケーターは、アプリが起動時間のガイドラインを満たしていることを示します。

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

以下の結果は、アプリがバックグラウンド状態から再開する際の状況を示しています。TTFFとTTFDの時間を比較して、最適化の必要性を評価してください。

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

アクティブに使用中のアプリのメモリ使用量を表示します。この指標をモニタリングして、メモリを過剰に消費することによるパフォーマンスの問題を回避してください。

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

バックグラウンド状態でのアプリのメモリ使用量を表示します。非アクティブ状態のアプリがシステムリソースに与える影響を理解するうえで重要です。

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

アプリがユーザー操作をどの程度スムーズに処理できるかを示します。パーセンテージは、スクロールおよびナビゲーション中に正常にレンダリングされたフレームを示します。

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

アプリがビデオコンテンツをどれだけスムーズに再生するかを示します。パーセンテージは、意図した再生レートでのフレーム配信が成功したことを示します。

KPIレポートを開く

Vega App KPI Visualizerがテストシナリオを完了すると、以下のレポートファイルが生成されます。

• aggregated-kpi-report-<タイムスタンプ>.json - すべてのテストシナリオのKPIデータを統合する。

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

<タイムスタンプ> は、Vega App KPI Visualizerがレポートを生成した日時を示します。

KPIレポートを開くには、以前の記録を開きます。次に、次のいずれかの方法を使用します。

オプション1（推奨）： クイックオープンを使用するこの方法では、VS CodeのインターフェイスまたはCLIから記録にアクセスできます。

VS Codeから：

1. KPIレポートファイル（例：app-launch-kpi-report-[timestamp].json）を、VS Codeクイックオープンを使用して、またはプロジェクトのgeneratedディレクトリで見つけます。
2. ファイルを1回クリックしてプレビューするか、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など、開くファイルを選択します。

関連トピック

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

Last updated: 2025年10月13日