ヒストグラム API を使用して、インテル® VTune™ プロファイラーで任意のデータをヒストグラム (分布図) 形式で表示するヒストグラムを定義します。
ヒストグラム API を使用すると、コードからカスタム・ヒストグラム・グラフを定義して、インテル® VTune™ プロファイラーで任意のデータを表示できます。
ヒストグラムは、相互比較のため個々のユニットで分割可能な統計を表示する場合に有効です。
例えば、この API では次が可能になります。
- 負荷分散の追跡
- リソース利用率の追跡
- ワーカーノードのオーバーサブスクリプションと未使用を特定
ヒストグラムを作成したスレッドに関係なく、プロセス内のスレッドはすべてのヒストグラム・インスタンスにアクセスできます。ヒストグラム API 呼び出しはスレッドセーフです。
注
デフォルトでは、ヒストグラム API データの収集と視覚化は、入出力解析でのみ使用できます。ほかの解析タイプの結果から分布図 (ヒストグラム) を表示するには、注目する事前定義された解析タイプに基づいてカスタム解析を作成し、カスタム解析オプションのユーザー分布図を解析するチェックボックスを有効にします。
ヒストグラムを定義して作成
ヒストグラムを作成する前に、ITT API ドメインを作成する必要があります。このドメインへのポインターがプリミティブに渡されます。
ドメイン名は、インテル® VTune™ プロファイラーの結果の [サマリー] タブにある分布図の見出しに表示されます。
1 つのドメインで、複数の分布図を組み合わせることができます。ただし、分布図の名称は同一ドメインでは同じである必要があります。
プリミティブのパラメーター:
| [in] | domain | 呼び出しを制御するドメイン |
| [in] | name | ヒストグラム名 |
| [in] | x_axis_type | X 軸データのタイプ |
| [in] | y_axis_type | Y 軸データのタイプ |
プリミティブ:
| 使用するプリミティブ | 説明 |
|---|---|
| __itt_histogram* _itt_histogram_create(__itt_domain* domain, const char* name, __itt_metadata_type x_axis_type, __itt_metadata_type y_axis_type); | Linux* および Android* で、指定されたドメイン、名前、データタイプの分布図を作成します。 |
| __itt_histogram* _itt_histogram_createA(__itt_domain* domain, const char* name, __itt_metadata_type x_axis_type, __itt_metadata_type y_axis_type); | Windows* で、ASCII 文字列 (char) に対し、指定されたドメイン、名前、データタイプの分布図を作成します。 |
| __itt_histogram* _itt_histogram_createW(__itt_domain* domain, const wchar_t* name, __itt_metadata_type x_axis_type, __itt_metadata_type y_axis_type); | Windows* で UNICODE 文字列 (wchar_t) に対し、指定されたドメイン、名前、データタイプの分布図を作成します。 |
分布図にデータを送信
プリミティブのパラメーター:
| [in] | histogram | データを送信する分布図のインスタンス |
| [in] | length | 送信された軸データ配列の要素数 |
| [in] | x_axis_data | X 軸のデータを含む配列 (NULL でも可)。 x_axis_data が NULL の場合、インテル® VTune™ プロファイラーは y_axis_data 配列のインデックスを使用します。 |
| [in] | y_axis_data | Y 軸のデータを含む配列 |
プリミティブ:
| 使用するプリミティブ | 説明 |
|---|---|
| void _itt_histogram_submit(__itt_histogram* histogram, size_t length, void* x_axis_data, void* y_axis_data); | 選択されたヒストグラム・インスタンスのユーザー統計情報を送信します。 Y 軸の配列データは、2 次元の平面上に点座標として、X 軸の配列データにマッピングされます。 ワークロードの実行中に送信されたデータは、このプリミティブのすべての呼び出しで 1 つの共通の分布図に集約されます。 データ送信の間隔を効率良く定義し、収集のオーバーヘッドを軽減することを推奨します。 |
使用例
次の例では、ワーカースレッドの統計情報を保存する分布図を作成しています。
#include "ittnotify.h"
#include "ittnotify_types.h"
void submit_stats()
{
// ドメインを作成
__itt_domain* domain = __itt_domain_create("Histogram statistics domain");
// ヒストグラムを作成
__itt_histogram* histogram = __itt_histogram_create(domain, "Worker TID 13454", __itt_metadata_u64, __itt_metadata_u64);
// 統計配列にプロファイル・データを入力
uint64_t* x_stats, y_stats;
size_t array_size;
get_worker_stats(x_stats, y_stats, array_size);
// ヒストグラム特性を送信
__itt_histogram_submit(histogram, array_size, x_stats, y_stats);
}