C++Build Insights SDK

C++ Build Insights SDK は、Visual Studio 2017 以降と互換性があります。 これらのバージョンのドキュメントを表示するには、この記事の Visual Studio バージョン セレクター コントロールを Visual Studio 2017 以降に設定します。 このページの目次の一番上にあります。

C++ Build Insights SDK は、C++ Build Insights プラットフォーム上でパーソナライズされたツールを作成できる API のコレクションです。 このページでは、作業を開始するために役立つ概要を説明します。

SDK の取得

次の手順に従って、C++ Build Insights SDK を NuGet パッケージとしてダウンロードできます。

1. Visual Studio 2017 以降で、新しい C++ プロジェクトを作成します。
2. [ソリューション エクスプローラー] ウィンドウで、プロジェクトを右クリックします。
3. コンテキスト メニューから [NuGet パッケージの管理] を選択します。
4. 右上で、[nuget.org] パッケージ ソースを選択します。
5. Microsoft.Cpp.BuildInsights パッケージの最新バージョンを検索します。
6. [インストール] を選択します。
7. ライセンスに同意します。

SDK の一般的な概念に関する情報を参照してください。 公式の C++ Build Insights サンプルの GitHub リポジトリにアクセスして、SDK を使用する C++ アプリケーションの実例を参照することもできます。

トレースの収集

C++ Build Insights SDK を使用して、MSVC ツールチェーンから発生するイベントを分析するには、最初にトレースを収集する必要があります。 この SDK では、基になるトレース テクノロジとして Event Tracing for Windows (ETW) が使用されます。 トレースを収集するには、次の 2 つの方法があります。

方法 1: Visual Studio 2019 以降の vcperf を使用する

1. VS 2019 用の x64 Native Tools コマンド プロンプトを管理者特権で開きます。

2. 次のコマンドを実行します。vcperf /start MySessionName

3. プロジェクトをビルドする。

4. 次のコマンドを実行します。vcperf /stopnoanalyze MySessionName outputTraceFile.etl

   重要

   vcperf を使用してトレースを停止する場合は、/stopnoanalyze コマンドを使用します。 通常の /stop コマンドによって停止されたトレースの分析に、C++ Build Insights SDK を使用することはできません。

方法 2: プログラムを使用する

プログラムでトレースを開始および停止するには、C++ Build Insights SDK の次のトレース収集関数のいずれかを使用します。 これらの関数呼び出しを実行するプログラムには、管理特権が必要です。 管理特権を必要とするのは、トレースの開始および停止関数のみです。 C++ Build Insights SDK 内のその他のすべての関数は、管理特権がなくても実行できます。

トレースの収集に関連する SDK 関数

以降のセクションでは、分析または再ログ セッションを構成する方法について説明します。 これは、機能を結合した関数 (StopAndAnalyzeTracingSession など) に必要です。

トレースの使用

ETW トレースを収集したら、C++ Build Insights SDK を使用してアンパックします。 SDK によって、ツールをすばやく開発できる形式でイベントが提供されます。 SDK を使用せずに未処理の ETW トレースを使用することはお勧めしません。 MSVC で使用されるイベント形式はドキュメント化されておらず、非常に大規模なビルドにスケーリングできるように最適化されており、理解するのは困難です。 さらに、C++ Build Insights SDK API は安定していますが、未処理の ETW トレースは予告なしに変更される可能性があります。

トレースの使用に関連する SDK の種類と関数

分析と再ログ

トレースの使用は、分析セッションまたは再ログ セッションのいずれかを介して行われます。

ほとんどのシナリオでは、通常の分析の使用が適しています。 この方法を使用すると、出力形式 (printf テキスト、xml、JSON、データベース、REST 呼び出しなど) を柔軟に選択できます。

再ログは、ETW 出力ファイルを生成する必要がある特定用途の分析に使用されます。 再ログを使用すると、C++ Build Insights イベントを独自の ETW イベント形式に変換できます。 再ログの使用が適切なのは、C ++ Build Insights データを既存の ETW ツールとインフラストラクチャにフックする場合です。 たとえば、vcperf では、再ログ インターフェイスが使用されます。 これは、ETW ツールである Windows Performance Analyzer で理解できるデータを生成する必要があるためです。 再ログ インターフェイスの使用を計画する場合は、ETW の動作方法について事前の知識が多少必要です。

アナライザー グループの作成

グループの作成方法を理解することが重要です。 アクティビティ開始イベントを受け取るごとに Hello, world! を出力するアナライザー グループの作成方法の例を次に示します。

using namespace Microsoft::Cpp::BuildInsights;

class Hello : public IAnalyzer
{
public:
    AnalysisControl OnStartActivity(
        const EventStack& eventStack) override
    {
        std::cout << "Hello, " << std::endl;
        return AnalysisControl::CONTINUE;
    }
};

class World : public IAnalyzer
{
public:
    AnalysisControl OnStartActivity(
        const EventStack& eventStack) override
    {
        std::cout << "world!" << std::endl;
        return AnalysisControl::CONTINUE;
    }
};

int main()
{
    Hello hello;
    World world;

    // Let's make Hello the first analyzer in the group
    // so that it receives events and prints "Hello, "
    // first.
    auto group = MakeStaticAnalyzerGroup(&hello, &world);

    unsigned numberOfAnalysisPasses = 1;

    // Calling this function initiates the analysis and
    // forwards all events from "inputTrace.etl" to my analyzer
    // group.
    Analyze("inputTrace.etl", numberOfAnalysisPasses, group);

    return 0;
}

イベントの使用

イベントに関連する SDK の種類と関数

アクティビティと簡易イベント

発生するイベントには、"アクティビティ" と "簡易イベント" の 2 つのカテゴリがあります。 アクティビティは継続的なプロセスであり、時間に始まりと終わりがあります。 簡易イベントは時間どおりに発生し、継続時間はありません。 C++ Build Insights SDK を使用して MSVC トレースを分析する場合、アクティビティが開始したときと停止したときに個別のイベントを受け取ります。 簡易イベントの場合、発生時に 1 つのイベントのみを受け取ります。

親子関係

アクティビティおよび簡易イベントは、親子関係を介して相互に関連付けられます。 アクティビティまたは簡易イベントの親は包括的なアクティビティであり、アクティビティまたは簡易イベントはその中で発生します。 たとえば、ソース ファイルをコンパイルする場合、コンパイラでは、ファイルを解析し、その後コードを生成する必要があります。 解析とコード生成のアクティビティは両方とも、コンパイラ アクティビティの子です。

簡易イベントに継続時間はないので、その中で他のイベントは発生しません。 したがって、それらに子はありません。

各アクティビティおよび簡易イベントの親子関係は、イベント テーブル に示されます。 C++ Build Insights イベントを使用する場合、これらの関係を把握することが重要です。 多くの場合、イベントの完全なコンテキストを理解するには、それらに依存する必要があります。

Properties

すべてのイベントには次のプロパティがあります。

簡易イベント以外のすべてのアクティビティには、次のプロパティもあります。

一部のイベントには、前述以外の独自のプロパティがあります。 この場合、これらの追加プロパティは、イベント テーブルに一覧表示されます。

C++ Build Insights SDK で提供されるイベントの使用

イベント スタック

C++ Build Insights SDK では、イベントを提供する場合、必ずスタックの形式で提供します。 スタック内の最後のエントリは現在のイベントであり、それより前のエントリは、その親階層です。 たとえば、LTCG の開始および停止イベントは、リンカーのパス 1 で発生するとします。 この場合、受け取るスタックには、[LINKER, PASS1, LTCG] が含まれます。 親階層は、イベントをそのルートまでトレースできるので便利です。 前述の LTCG アクティビティの速度が遅い場合、どのリンカー呼び出しが関係していたかをすぐに知ることができます。

イベントとイベント スタックの照合

C++ Build Insights SDK では、トレース内のすべてのイベントが提供されますが、ほとんどの場合、注意を要するのはそれらのサブセットのみです。 場合によっては、注意を要するのは、"イベント スタック" のサブセットのみであることもあります。 SDK では、必要なイベントまたはイベント スタックをすばやく抽出して、不要なイベントを拒否するのに役立つ機能が提供されます。 これは、次の照合関数を使用して実行されます。

MatchEventStack などのイベント スタック照合関数では、親階層を照合するときにギャップを許容します。 たとえば、[LINKER, LTCG] スタックに関心があるとします。 これは、[LINKER, PASS1, LTCG] スタックとも一致します。 最後に指定する種類は、照合するイベントの種類である必要があり、親階層には含まれません。

キャプチャ クラス

Match* 関数を使用するには、照合する種類を指定する必要があります。 これらの種類は、"キャプチャ クラス" の一覧から選択されます。 キャプチャ クラスには、次に示す複数のカテゴリがあります。

各イベントの照合に使用できるキャプチャ クラスについては、「イベント テーブル」を参照してください。

照合後: キャプチャされたイベントの使用

照合が正常に完了すると、Match* 関数によって、キャプチャ クラス オブジェクトが構築され、指定された関数に転送されます。 これらのキャプチャ クラス オブジェクトを使用して、イベントのプロパティにアクセスします。

例

AnalysisControl MyAnalyzer::OnStartActivity(const EventStack& eventStack)
{
    // The event types to match are specified in the PrintIncludes function
    // signature.  
    MatchEventStackInMemberFunction(eventStack, this, &MyAnalyzer::PrintIncludes);
}

// We want to capture event stacks where:
// 1. The current event is a FrontEndFile activity.
// 2. The current FrontEndFile activity has at least one parent FrontEndFile activity
//    and possibly many.
void PrintIncludes(FrontEndFileGroup parentIncludes, FrontEndFile currentFile)
{
    // Once we reach this point, the event stack we are interested in has been matched.
    // The current FrontEndFile activity has been captured into 'currentFile', and
    // its entire inclusion hierarchy has been captured in 'parentIncludes'.

    cout << "The current file being parsed is: " << currentFile.Path() << endl;
    cout << "This file was reached through the following inclusions:" << endl;

    for (auto& f : parentIncludes)
    {
        cout << f.Path() << endl;
    }
}