アプリのKPIの測定

Vega App Key Performance Indicator（KPI）Visualizerは、アプリの主要業績評価指標を測定します。これらの指標には、起動時間、メモリ使用量、UIの滑らかさ、ビデオの滑らかさ、応答性が含まれます。これを使用して、アプリのユーザーエクスペリエンスのモニタリングと最適化を行うことができます。これらのKPIを定期的にトラッキングすると、アプリがスムーズで応答性の高いエクスペリエンスを提供していることを確認できます。Amazonアプリストアにアプリを公開する前に、リリースバリアントのパフォーマンスを測定してください。

滑らかさと応答性について：

• 「応答性」は、ユーザーがアプリを操作したときに、アプリがどのくらいすばやく反応するかを測定します。ユーザーは、ボタンを押してからUIが更新されるまでの間に体感的な遅延がないことを期待しています。
• 「滑らかさ」は、アニメーション、スクロール、ビデオ再生が、途切れやジャンク、ドロップフレームを生じることなく、どのくらいスムーズにレンダリングされるかを測定します。

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

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

前提条件

Vega App KPI Visualizerを使用する前に、以下を完了してください。

1. VegaパフォーマンスAPIモジュールをインストールします。

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

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

2. 次のセクションに目を通してください。

   • 各KPIが測定する内容とそのターゲットのガイドライン。アプリのKPI指標とガイドラインを参照してください。
   • さまざまなシナリオでのアプリの起動方法。起動シナリオを参照してください。
   • パフォーマンスマーカーを設定するタイミング。描画完了マーカーを参照してください。

3. フォアグラウンドメモリ、ビデオの滑らかさ、またはUIの滑らかさを測定するには、滑らかさとフォアグラウンドメモリの測定の手順に従ってください。

4. 測定方法を選択します。

   • 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」と入力する

手順3： Enterキーを押す

[Vega Studio] パネルから [App KPI Visualizer] を選択することもできます。

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

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

以下に例を示します。

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

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

テストシナリオの生成に関するガイダンスについては、滑らかさとフォアグラウンドメモリの測定を参照してください。

ユースケースを選択すると、Visualizerが起動し、次のKPI測定を3回繰り返します。

クールスタートKPI

1. デバイス上でテストアプリを起動します。
2. テストアプリが読み込まれるまで10秒待ちます。
3. テストアプリを閉じます。
4. KPIを処理します。

ウォームスタートKPI

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

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

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

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

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

UIの滑らかさKPI

1. デバイス上でテストアプリを起動します。
2. テスト方法を選択します。
   • カスタムテスト - 独自のUI操作シナリオを使用する
   • デフォルトテスト - 標準のスクロールパターンを使用する
     • 水平スクロール2セット（左5回、右5回）
     • 垂直スクロール2セット（下5回、上5回）
     • アクション間隔900ミリ秒

3. [Cancel] をクリックするか Escキーを押してテストを終了します。

   

4. 分析とレポートのためにKPIをキャプチャします。
5. テストアプリを閉じます。
6. KPIを処理します。

ビデオ再生の滑らかさKPI

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

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

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

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

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

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

ウィンドウには、3回のテストから計算されたp90（90パーセンタイル）値が表示されます。

手順7： 結果を評価する

結果を評価するには、パフォーマンスレポートの理解を参照してください。

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

手順1： デバイスの準備状態を確認する

コマンドプロンプトでvega exec perf doctorコマンドを実行して、ホストとターゲットデバイスの準備が整っているかどうかを確認します。

vega exec perf doctor [--app-name]

--app-nameには、manifest.tomlファイルから取得したパッケージIDを指定します。複数のデバイスが実行されている場合は、デバイスのシリアル番号を指定します。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=<アプリ名>

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

手順3： （任意）イテレーション回数を指定する

デフォルトのイテレーション回数は3回で、--certificationを使用した場合は30回になります。

--iteration <回数> 

手順4： （任意）測定するKPIを指定する

--kpi <KPI名>

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

手順5： 利用可能なすべてのオプションを表示する

kpi-visualizer --help

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

vega exec perf kpi-visualizer --help

    名前：

    KPI Visualizerツール

    説明：

    アプリのユーザーエクスペリエンスを最適化するために、アプリの起動時間、メモリ使用量、UIの応答性などの主要業績評価指標を測定します。

    書式：

    vega exec perf kpi-visualizer <パラメーター>

    特定のコマンドの情報を取得するには、'vega 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には、以下を含むパフォーマンスレポートが表示されます。

• Test information

  • Date - システムがKPIデータをキャプチャした日付。
  • Device Serial ID - アプリを実行しているデバイスの一意の識別子。
  • App - KPIデータが表示されるアプリの名前。
  • Number of iterations - KPI測定プロセスが実行された回数。

• KPI Name - KPIの名前と単位。

• Test Name - テストまたは実行されたユースケースの名前。

• KPI Health - 各KPIの健全性を示す色分け表示。

  • 🟢（緑）- 推奨ガイドラインを満たしている
  • 🟡（黄色）- ガイドラインの10%以内
  • 🔴（赤）- ガイドラインを10%超過

• KPI Score - KPIの数値。KPI名に指定されている単位で表されます。VisualizerでKPIを計算できない場合、KPIスコアは「N/A」と表示され、KPIの健全性は「Unknown」と表示されます。

• Guideline - 推奨されるKPIスコアの値または範囲。業界標準または業績目標に基づきます。

結果の例

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

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

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

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

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

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

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

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

次の結果は、バックグラウンド状態でのアプリのメモリ使用量を示しています。非アクティブ状態のアプリがシステムリソースに与える影響を理解すると、バックグラウンド動作の最適化に役立ちます。

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

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

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

次の結果は、アプリがビデオコンテンツをどの程度スムーズに再生できるかを示しています。パーセンテージは、意図した再生レートでのフレーム配信が成功したことを示します。このシナリオには、メディアプレーヤーと入力イベントのマイクロKPIも含まれます。

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-<タイムスタンプ>.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コマンドパレットを使用する

この方法では、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など、開くファイルを選択します。

関連トピック

• Vegaアプリのパフォーマンスの向上
• 滑らかさとフォアグラウンドメモリの測定
• トレースの検査

Last updated: 2026年3月20日