ネイティブ・イメージ・ビルド・レポート

ビルド・レポートは、GraalVMネイティブ・イメージ用に特に調整された単一のHTMLページ・レポートです。このレポートには、各ビルド・ステージおよび生成されたバイナリの内容に関する幅広い情報が表示されます。ここでは、ビルド・レポートの生成方法と各レポート・セクションの使用方法について学習します。

ノート: ビルド・レポートは、GraalVM Community Editionでは使用できません。

目次

• レポートの生成
• レポートの構成
  • サマリー
  • コード領域
    • メソッドベースの内訳
    • パッケージとクラスのリスト
  • イメージ・ヒープ
  • リソース
  • ソフトウェア部品表(SBOM)
  • PGOサンプリング・プロファイル
• 関連ドキュメント

レポートの生成

単純なHelloWorld Micronautアプリケーション(GraalVMデモ・リポジトリで使用可能)は、ビルド・レポートの生成とその構成を示すために使用されます。

ビルド・レポートは、native-imageコマンドの実行時に--emitオプションを使用して簡単に生成できます:

native-image --emit build-report -cp . Application

ネイティブ・イメージ用のMavenプラグインを使用するMicronautの例の場合、プラグインの構成にオプション--emit build-reportを追加するだけです:

<plugin>
  <groupId>org.graalvm.buildtools</groupId>
  <artifactId>native-maven-plugin</artifactId>
  <configuration>
    ...
    <buildArgs combine.children="append">
      <buildArg>--emit build-report</buildArg>
      ...
    </buildArgs>
  </configuration>
</plugin>

レポートは、ビルドの成功後に生成されるバイナリとともに自動的に作成されます。HTMLページへのリンク(デフォルトでは<binary-name>-build-report.htmlという名前)は、ビルド出力の最後にあるBuild artifactsセクションにリストされます:

========================================================================================================================
GraalVM Native Image: Generating 'MnHelloRest' (executable)...
========================================================================================================================

...

Build artifacts:
 .../graalvm-demos/micronaut-hello-rest-maven/target/MnHelloRest (executable)
 .../graalvm-demos/micronaut-hello-rest-maven/target/MnHelloRest-build-report.html (build_info) <----- generated report
========================================================================================================================
Finished generating 'MnHelloRest' in 36.0s.

また、レポートのファイル名またはパスは、build-report引数にそれを追加することでカスタマイズできます。これは、たとえば、異なる構成を使用して同じアプリケーションの複数のバイナリを作成する場合に非常に役立ちます:

native-image -0b --emit build-report=/tmp/application-build-report-default.html -cp . Application
native-image -0s --emit build-report=/tmp/application-build-report-size-optimized.html -cp . Application

レポートの構成

すべてのレポート・ページは、複数のセクション(タブ)で構成され、そのそれぞれにタイトルに対応するデータが表示されます。「Summary」セクションが最初に表示され、「Code Area」、「Image Heap」、「Resources」、「Software Bill of Materials (SBOM)」および「PGO Sampling Profile」(PGOビルドのみ)セクションもあります。各セクションの詳細は、次のそれぞれの項を参照してください。

サマリー

「Summary」セクションには、ビルドの概要が表示されます。このセクションは、4つのサブセクションで構成されており、それぞれビルド・プロセスのステージに対応するか、追加の有益な情報を提供します:

• 「Environment」には、ビルドで使用された環境に関する情報(Javaバージョン、GraalVMバージョン、Graalコンパイラ構成など)が表示されます。
• 「Analysis Results」には、ポイントツー分析の結果(タイプ、フィールドおよびメソッド)がカテゴリ(到達可能、リフレクション、JNIおよびロード済)ごとにグループ化されて表示されます。
• 「Image Details」には、バイナリの内容の概要が表示されます。このチャートでは、バイナリの様々な部分(コード領域、イメージ・ヒープ、デバッグ情報およびその他のデータ)が、そのサイズに関して相互にどのように関連しているかがビジュアル化されます。
• 「Security Report」では、ビルドに関する様々な種類のセキュリティ関連情報(デシリアライズ、埋込みSBOMおよびバックワードエッジ制御フロー整合性(CFI))がレポートされます。
• 「Resource Usage」には、ビルドに使用されたリソースに関する追加情報(ガベージ・コレクション、ピークRSSおよびCPU負荷)に加え、バイナリの生成にかかった合計時間が表示されます。

ノート: 「Image Details」の各バーにマウス・ポインタを重ねると、詳細情報を確認できます。また、「Code Area」および「Image Heap」のバーをクリックすると、リンクするそれぞれのセクションに移動できます。

このすべての情報はJSON形式でも入手でき、ページの右上にある「Download as JSON」をクリックしてダウンロードできます。

コード領域

「Code Area」セクションには、静的分析後に到達可能であることがわかったコードの詳細ビューが表示されます。これは、内訳チャートおよびパッケージとクラスのリストという2つの相互接続された部分で構成されます。

メソッドベースの内訳

バイナリのコード領域は、詳細なメソッド・レベルでパッケージ別に分類されます。この内訳では、ポイントツー分析で見つけられた到達可能なメソッドのみが考慮されます。これは、サンバースト・チャート(階層的な複数レベルの円グラフ)の形式でビジュアル化されます。

チャートには、異なるパッケージ(およびクラス)が相互にどのように関連しているかが表示されます。比率は、累積メソッドのバイトコード・サイズ(デフォルト)またはメソッドの合計数に基づいて計算されます。これは、ページの右上にある「Breakdown type」ドロップダウン・リストを使用して選択できます。

ノート: 固定しきい値は、チャートに表示されるデータの量を制限するために使用されます(現在のルート・パッケージを基準とする合計パーセンテージの0.1)。しきい値は内訳チャートのみに適用され、下の表には(現在のレベルの)パッケージとクラスの完全なリストが含まれます。

パーセンテージ(すべてのパッケージ円弧に表示)は、兄弟パッケージ間の関係を表します。すべてのパーセンテージは、ルート・パッケージ(トップレベル・ビューでは抽象的なTotalパッケージ、任意のパッケージにドリルダウンするときはそのパッケージ)を基準として計算されます。さらに、特定のパッケージの具体的な値(メソッドのバイトコード・サイズまたはメソッドの合計数)は、そのパッケージ円弧にマウス・ポインタを重ねると確認できます。

この内訳の最も重要な機能は、任意のパッケージの関係を詳細に調査する機能です。これは、(子のパッケージまたはクラスを少なくとも1つ含む)目的のパッケージをクリックするだけで実行できます。親パッケージに1レベル戻す逆の操作も同様に、(チャートの中央にある)「ルート」パッケージをクリックすることで実行します。

(Totalから現在のパッケージまでの)ドリルダウン・チェーン内にある任意のパッケージに戻ることもできます。これは、チャートのすぐ上に表示されているドリルダウン・チェーン内の特定のパッケージをクリックするだけで実行できます。

また、内訳チャートおよびパッケージとクラスのリストは同期されており、すべてのドリルダウンで同時に下の表が更新されます(逆の操作でも同様です)。

パッケージとクラスのリスト

パッケージとクラスのリストは、メインの内訳の展開として機能します。ここには、選択したパッケージ(最初はTotal)に含まれるすべてのパッケージとクラスがリストされます。表には、それぞれのパッケージとクラスに関するすべての情報(メソッドのバイトコード・サイズ(またはメソッドの合計数)および相対的パーセンテージ)も表示されます。

子(少なくとも1つのパッケージまたはクラス)を含むパッケージは、リンクとして表示されます。リンクをクリックすると、内訳チャートがドリルダウンされます(これらは同期されます)。同様に、1レベル(親パッケージに)戻る「↑」(最初の行に表示)をクリックすることで、逆の操作も可能です。

ノート: 選択したパッケージの直接の子のみがリストされます(ドリルダウンごとに更新されます)。

イメージ・ヒープ

バイナリのオブジェクト・ヒープは、オブジェクト型別に分類およびグループ化されます(CLIビルド出力のイメージ・ヒープ表と同様)。主な違いは、ビルド・レポートには、オブジェクト型の完全なリストと、その数、サイズ、相対的パーセンテージ(進捗バーの形式でビジュアル化)などのより詳細な情報が表示されることです。

完全なリストの一般的なユース・ケースの1つは、特定のクラスのインスタンスがイメージ・ヒープの一部であるかどうかを判断することです(「ページ内で検索」を使用)。

リソース

「Resources」タブを使用して、ネイティブ・イメージに含まれるJavaリソース、そのオリジン、およびそのサイズがイメージ・サイズ全体に占める容量を調査できます。これは、たとえば、不適切な到達可能性メタデータが原因で誤って含まれているリソースや欠落しているリソースを検出する場合に便利です。

すべてのリソースがメインの表にリストされます。デフォルトでは、構成ファイルを介して明示的にリクエストされたリソースが表示されます。さらに、次の3種類のリソースが提供されます:

• 欠落リソースは、構成ファイルを介してリクエストされましたが、システムに存在しませんでした。
• 注入リソースは、GraalVM SDKを介してプログラムで登録されました(通常は、ネイティブ・イメージのコンパイルを支援するためにフレームワークによって使用されます)。
• ディレクトリ・リソースは、ディレクトリを表す特殊なタイプのリソースです(通常は、そのディレクトリ内のファイルおよびディレクトリの名前のみが含まれるため、小さくなります)。各種のリソースは、対応するチェック・ボックスを使用して表に表示できます。

表のリソースは、左上にある検索ボックスを使用して名前でフィルタできます。さらに、リストは任意のリソース属性でソートできます(表ヘッダーの専用の上下矢印ソート・ボタンを使用)。

ソフトウェア部品表(SBOM)

ソフトウェア部品表は、最終バイナリのビルドに含まれるすべてのアーティファクトのインベントリを表します。各アーティファクトは、完全修飾名(組織名+アーティファクト名)とその特定のバージョンによって一意に識別されます。ビルドで使用されたすべてのアーティファクトが表にリストされます。

このすべての情報はCycloneDX形式のJSONとしても入手でき、「Download as JSON」をクリックしてダウンロードできます。

PGOサンプリング・プロファイル

「PGO Sampling Profile」は、PGO最適化バイナリのビルド時に生成されるレポートにのみ存在するセクションです。このセクションの詳細は、専用のPGOガイドの「ビルド・レポートでのプロファイルの検査」を参照してください。

関連ドキュメント

• ネイティブ・イメージ・ビルド出力
• ビルド・レポートでのプロファイルの検査
• ネイティブ・イメージ・ビルドの概要
• デバッグおよび診断