コンテキスト・メタデータ API

コンテキスト・メタデータを使用してカウンターベースのメトリックを収集し、次のようなハードウェア・トポロジーに関連付けます。

PCIe デバイス
ブロックデバイス
CPU コア
スレッド

コンテキスト・メタデータ API を使用すると、特殊属性を使用することでコード内にカスタムカウンターを定義できます。インテル® VTune™ プロファイラーでは、収集されたデータのメトリックセットを、従来のデータ表現形式で取得することもできます。

可用性:

デフォルトでは、データ収集と視覚化を行うコンテキスト・メタデータ API は入出力解析でのみ使用できます。

他の解析タイプを実行する際にこのデータを表示するには、

注目する定義済みの解析タイプに基づいてカスタム解析を作成します。
カスタム解析オプションで、[すべての ITT API ユーザーデータを分析] チェックボックスを有効にします。

カウンター・オブジェクトを定義および作成

コンテキスト・メタデータを保存するには、次の構造体を使用します。

__itt_context_metadata 
{ 
     __itt_context_type type; /*!< コンテキスト・メタデータ値のタイプ */ 
     void* value; /*!< コンテキスト・メタデータ値自体へのポインター */ 
}

この構造体は、次のタイプのコンテキスト・メタデータを受け入れます。

__itt_context_type	値	説明
__itt_context_name	ASCII 文字列 char/ Unicode 文字列 wchar_t タイプ	カウンターベースのメトリックの名前。これは必須値です。
__itt_context_device	ASCII 文字列 char/ Unicode 文字列 wchar_t タイプ	カウンターサンプルを分類する統計サブドメイン (ネットワーク・ポート ID、ディスク・パーティションなど)
__itt_context_units	ASCII 文字列 char/ Unicode 文字列 wchar_t タイプ	測定単位。時間の測定には、ns/us/ms/s 単位を使用して、インテル® VTune™ プロファイラーのデータ表現を変更します。
__itt_context_pci_addr	ASCII 文字列 char/ Unicode 文字列 wchar_t タイプ	カウンターに関連付けるデバイスの PCI アドレス。
__itt_context_tid	符号なし 64 ビット整数タイプ	カウンターに関連付けるスレッド ID。
__itt_context_bandwidth_flag	符号なし 64 ビット整数タイプ (0、1)	このフラグが 1 に設定されている場合、レイテンシー分布図とカウンター/秒のタイムライン分布を計算します。
__itt_context_latency_flag	符号なし 64 ビット整数タイプ (0、1)	このフラグが 1 に設定されている場合、スループット分布図とカウンター/秒のタイムライン分布を計算します。
__itt_context_on_thread_flag	符号なし 64 ビット整数タイプ (0、1)	このフラグが 1 に設定されている場合、スレッドグラフの上部に CPU 時間分布のパーセンテージを示すカウンターが表示されます。

コンテキスト・メタデータをカウンターに関連付ける前に、ITT API ドメインと ITT API カウンター・インスタンスを作成する必要があります。

ドメイン名は、インテル® VTune™ プロファイラーの結果にあるカウンターのメトリック・セクションの見出しを提供します。単一のドメインで、任意の数のカウンターのデータを組み合わせることができます。ただし、カウンターの名前は同一ドメインで同じである必要があります。

コンテキスト・メタデータの単一のメトリックで、さまざまなカウンターを組み合わせることができます。

コンテキスト情報を追加

すべてのオブジェクトを作成したら、選択したカウンターのコンテキスト情報を追加できます。使用するプリミティブ:

__itt_bind_context_metadata_to_counter(__itt_counter counter, size_t length, __itt_context_metadata* metadata);

プリミティブのパラメーター:

タイプ	パラメーター	説明
[in]	`__itt_counter counter`	コンテキスト・メタデータに関連付けられたカウンター・インスタンスへのポインター
[in]	`size_t length`	コンテキスト・メタデータの配列内の要素数
[in]	`__itt_context_metadata* metadata`	コンテキスト・メタデータの配列へのポインター

カウンター・インスタンスを作成し、カウンターデータを送信するには、以下を使用します。

__itt_counter_create_v3(__itt_domain* domain, const char* name, __itt_metadata_type type); 
__itt_counter_set_value_v3(__itt_counter counter, void *value_ptr);

使用例

この例では、SSD NVMe デバイスのランダム読み取り操作メトリックを測定するコンテキスト・メタデータを含むカウンターを作成します。


    #include "ittnotify.h"
    #include "ittnotify_types.h"

    // Create domain and counters:
    __itt_domain* domain = __itt_domain_create("ITT API collected data");
    __itt_counter counter_read_op = __itt_counter_create_v3(domain, "Read Operations", __itt_metadata_u64);
    __itt_counter counter_read_mb = __itt_counter_create_v3(domain, "Read Megabytes", __itt_metadata_u64);
    __itt_counter counter_spin_time = __itt_counter_create_v3(domain, "Spin Time", __itt_metadata_u64);

    // Create context metadata:
    __itt_context_metadata metadata_read_op[] = {
         { __itt_context_name, "Reads"},
         { __itt_context_device, "NVMe SSD Intel DC 660p"},
         { __itt_context_units, "Operations"},
         {__itt_context_pci_addr, "0001:10:00.1"},
         {__itt_context_latency_flag, &true_flag}
    };

    __itt_context_metadata metadata_read_mb[] = {
         {__itt_context_name, "Read"},
         {__itt_context_device, "NVMe SSD Intel DC 660p"},
         {__itt_context_units, "MB"},
         {__itt_context_pci_addr, "0001:10:00.1"},
         {__itt_context_bandwidth_flag, &true_flag}
    };

    __itt_context_metadata metadata_spin_time[] = {
         {__itt_context_name, "Spin Time"},
         {__itt_context_device, "NVMe SSD Intel DC 660p"},
         {__itt_context_units, "ms"}, {__itt_context_tid, &thread_id}
    };

    // Bind context metadata to counters:
    __itt_bind_context_metadata_to_counter(counter_read_op, n, metadata_read_op);
    __itt_bind_context_metadata_to_counter(counter_read_mb, n, metadata_read_mb);
    __itt_bind_context_metadata_to_counter(counter_spin_time, n, metadata_spin_time);

    while(1) {
         // Get collected data:
         uint64_t read_op = get_user_read_operation_num();
         uint64_t read_mb = get_user_read_megabytes_num();
         uint64_t spin_time = get_user_spin_time();

         // Dump collected data:
         __itt_counter_set_value_v3(counter_read_op, &read_op);
         __itt_counter_set_value_v3(counter_read_mb, &read_mb);
         __itt_counter_set_value_v3(counter_spin_time, &spin_time);
    }

コンテキスト・メタデータ API

使用例

関連情報