カスタムのイベントとメトリックのための Application Insights API

アプリケーションに数行のコードを挿入して、ユーザーの行動を調べたり、問題の診断に役立つ情報を取得したりすることができます。 デバイスとデスクトップ アプリケーション、Web クライアント、Web サーバーからテレメトリを送信できます。 Azure Application Insights コア テレメトリ API を使用すると、カスタムのイベントやメトリック、独自バージョンの標準テレメトリを送信できます。 この API は、Application Insights の標準のデータ コレクターで使用される API と同じものです。

API の概要

コア API は、GetMetric (.NET のみ) のようないくつかの違いは別として、すべてのプラットフォームにわたって同一です。

Method 使用目的
TrackPageView ページ、画面、ブレード、フォーム
TrackEvent ユーザー アクションとその他のイベント。 ユーザーの行動を追跡するために、またはパフォーマンスを監視するために使用されます。
GetMetric 0 と多次元メトリックは、は、C# の場合のみ、一元的に構成された集計です。
TrackMetric キューの長さなど、特定のイベントに関連しないパフォーマンスを測定します。
TrackException 診断用に例外を記録します。 他のイベントとの関連で例外の発生箇所を追跡し、スタック トレースを調べます。
TrackRequest パフォーマンス分析用にサーバー要求の頻度と期間を記録します。
TrackTrace リソース診断ログ メッセージ。 サードパーティのログをキャプチャすることもできます。
TrackDependency アプリが依存する外部コンポーネントへの呼び出しの実行時間と頻度を記録します。

これらのテレメトリの呼び出しのほとんどに プロパティとメトリックをアタッチ できます。

開始する前に

Application Insights SDK の参照がまだない場合:

TelemetryClient インスタンスの取得

TelemetryClient インスタンスを取得します (Web ページの JavaScript を除く)。

ASP.NET Core アプリと .NET/.NET Core 向けの非 HTTP/ワーカー アプリの場合、それぞれのドキュメントに説明されているとおり、依存関係インジェクション コンテナーから TelemetryClient のインスタンスを取得することが推奨されます。

AzureFunctions v2 以降または Azure WebJobs v3 以降を使用する場合は、このドキュメントに従ってください。

C#

private TelemetryClient telemetry = new TelemetryClient();

このメソッドが現在不使用のメッセージであることがわかっている場合は、microsoft/ApplicationInsights-dotnet # 1152 にアクセスして詳細を確認してください。

Visual Basic

Private Dim telemetry As New TelemetryClient

Java

private TelemetryClient telemetry = new TelemetryClient();

Node.js

var telemetry = applicationInsights.defaultClient;

TelemetryClient はスレッド セーフです。

ASP.NET および Java プロジェクトの場合は、受信 HTTP 要求が自動的にキャプチャされます。 アプリの他のモジュールのために TelemetryClient の追加のインスタンスを作成することもできます。 たとえば、ミドルウェア クラスでビジネス ロジック イベントを報告する 1 つの TelemetryClient インスタンスを使用できます。 マシンを識別するために UserId や DeviceId などのプロパティを設定できます。 こうした情報は、インスタンスから送信されるすべてのイベントに付属します。

C#

TelemetryClient.Context.User.Id = "...";
TelemetryClient.Context.Device.Id = "...";

Java

telemetry.getContext().getUser().setId("...");
telemetry.getContext().getDevice().setId("...");

Node.js のプロジェクトでは、new applicationInsights.TelemetryClient(instrumentationKey?) を使用して新しいインスタンスを作成できますが、シングルトン defaultClient から分離された構成を必要とするシナリオにのみ推奨されます。

TrackEvent

Application Insights の カスタム イベント はデータ ポイントであり、メトリックス エクスプローラーでは集計カウントとして、診断検索では個々の発生として表示できます。 (これは MVC にも他のフレームワークの "イベント" にも関連していません)。

さまざまなイベントをカウントするために、TrackEvent 呼び出しを挿入します。 これによって、ユーザーが特定の機能を使用する頻度や、特定の目標を達成する頻度、特定の種類の間違いを起こす頻度をカウントできます。

たとえば、ゲーム アプリで、ユーザーが勝利したときにイベントを送信します。

JavaScript

appInsights.trackEvent({name:"WinGame"});

C#

telemetry.TrackEvent("WinGame");

Visual Basic

telemetry.TrackEvent("WinGame")

Java

telemetry.trackEvent("WinGame");

Node.js

telemetry.trackEvent({name: "WinGame"});

Analytics でのカスタム イベント

テレメトリは、Application Insights ログのタブまたは使用エクスペリエンスcustomEvents テーブルにあります。 イベントは、trackEvent(..) またはクリック分析自動収集プラグインから取得できます。

サンプリングが実行中の場合は、itemCount プロパティは 1 より大きい値を示します。 たとえば itemCount==10 は trackEvent() への 10 回の呼び出しで、サンプリング プロセスはそれらのうちの 1 つだけを転送したことを意味します。 カスタム イベントの正しい数を取得するには、したがって customEvents | summarize sum(itemCount) などのコードを使用する必要があります。

GetMetric

GetMetric() 呼び出しを効果的に使用し、.NET および .NET Core アプリケーション用にローカルで事前集計されたメトリックをキャプチャする方法については、GetMetric のドキュメントにアクセスしてください。

TrackMetric

注意

Microsoft.ApplicationInsights.TelemetryClient.TrackMetric は、メトリックを送信するための推奨されるメソッドではありません。 メトリックは送信される前に必ず、ある期間にわたって事前に集計される必要があります。 GetMetric(..) オーバーロードのいずれかを使用して、SDK の事前集計機能にアクセスするためのメトリック オブジェクトを取得します。 独自の事前集計ロジックを実装する場合は、TrackMetric() メソッドを使用して集計結果を送信できます。 アプリケーションで、一定時間にわたる集計を行わず、すべての機会に個別のテレメトリ項目を送信する必要がある場合は、おそらくイベント テレメトリのユース ケースに該当します。TelemetryClient.TrackEvent (Microsoft.ApplicationInsights.DataContracts.EventTelemetry) を参照してください。

Application Insights では、特定のイベントに関連付けられていないメトリックをグラフ化できます。 たとえば、一定の間隔でキューの長さを監視できます。 メトリックでは、個々の測定値は変化と傾向よりも関心が薄いため、統計グラフが役に立ちます。

Application Insights にメトリックを送信するために、TrackMetric(..) API を使用できます。 メトリックを送信するには、次の 2 つの方法があります。

  • 単一の値。 アプリケーションで、測定を実行するたびに、対応する値を Application Insights に送信します。 たとえば、コンテナー内の項目数を記述するメトリックがあるとします。 特定の期間に、まずコンテナーに 3 つの項目を配置し、次に 2 つの項目を削除します。 したがって、TrackMetric を 2 回呼び出します。最初に値 3 を渡して、次に値 -2 を渡します。 Application Insights は、両方の値を自動的に格納します。

  • 集計。 メトリックを使用する場合、個々の測定値はあまり重要ではありません。 代わりに特定の期間に、発生したことの概要が重要です。 このような概要は 集計 と呼ばれます。 上記の例で、その期間の集計メトリックの合計は 1 で、メトリック値のカウントは 2 です。 集計アプローチを使用する場合、期間ごとに TrackMetric を 1 回だけ呼び出し、集計値を送信します。 これは、すべての関連情報を収集しながら、Application Insights に送信するデータ ポイントを少なくすることによって、コストとパフォーマンスのオーバーヘッドを大幅に削減できるため、推奨される方法です。

単一の値

1 つのメトリック値を送信するには:

JavaScript

appInsights.trackMetric({name: "queueLength", average: 42});

C#

var sample = new MetricTelemetry();
sample.Name = "queueLength";
sample.Value = 42.3;
telemetryClient.TrackMetric(sample);

Java

telemetry.trackMetric("queueLength", 42.0);

Node.js

telemetry.trackMetric({name: "queueLength", value: 42.0});

Analytics でのカスタム メトリック

テレメトリは、Application Insights AnalyticscustomMetrics テーブルにあります。 各行は、アプリでの trackMetric(..) に対する呼び出しを表します。

  • valueSum: これは測定値の合計です。 平均値を取得するには、valueCount で除算します。
  • valueCount: この trackMetric(..) 呼び出しで集計された測定値の数。

ページ ビュー

デバイスまたは Web ページ アプリケーションでは、各画面または各ページが読み込まれた場合既定でページ ビュー テレメトリが送信されます。 ただし、これを変更し、ページ ビューを追跡する回数を増やしたり、変えたりできます。 たとえば、タブまたはブレードを表示するアプリケーションで、ユーザーが新しいブレードを開いたときに常にページを追跡できます。

ユーザーとセッションのデータはページ ビューとともにプロパティとして送信されます。そのため、ページ ビューのテレメトリがあれば、ユーザーとセッションのグラフがアクティブになります。

カスタム ページ ビュー

JavaScript

appInsights.trackPageView("tab1");

C#

telemetry.TrackPageView("GameReviewPage");

Visual Basic

telemetry.TrackPageView("GameReviewPage")

Java

telemetry.trackPageView("GameReviewPage");

別々の HTML ページ内で複数のタブを使用している場合、URL を指定することもできます。

appInsights.trackPageView("tab1", "http://fabrikam.com/page1.htm");

ページ ビューのタイミング

既定では、ページ ビューの読み込み時間 として報告される時間は、ブラウザーが要求を送信した時点からブラウザーのページ読み込みイベントが呼び出されるまで測定されます。

代わりに、次のいずれかを行うことができます。

  • trackPageView の呼び出し appInsights.trackPageView("tab1", null, null, null, durationInMilliseconds); で明示的な時間を設定する。
  • ページ ビューのタイミングの呼び出し (startTrackPagestopTrackPage) を使用する。

JavaScript

// To start timing a page:
appInsights.startTrackPage("Page1");

...

// To stop timing and log the page:
appInsights.stopTrackPage("Page1", url, properties, measurements);

1 番目のパラメーターとして使用する名前により、開始呼び出しと停止呼び出しを関連付けます。 既定値は現在のページ名です。

メトリックス エクスプローラーに結果として表示されるページ読み込み時間は、開始呼び出しと停止呼び出しの時間間隔から求められます。 実際の時間間隔はユーザーが決定します。

Analytics でのページ テレメトリ

Analytics では、2 つのテーブルに、ブラウザー操作からのデータが表示されます。

  • pageViews テーブルには、URL とページ タイトルに関するデータが含まれます。
  • browserTimings テーブルには、受信データの処理にかかった時間などのクライアントのパフォーマンスに関するデータが含まれます。

ブラウザーでさまざまなページの処理にかかる時間を知るには、次のようにします。

browserTimings
| summarize avg(networkDuration), avg(processingDuration), avg(totalDuration) by name

さまざまなブラウザーの人気度を検出するには、次のようにします。

pageViews
| summarize count() by client_Browser

AJAX 呼び出しにページ ビューを関連付けるには、依存関係によって結合します。

pageViews
| join (dependencies) on operation_Id 

TrackRequest

サーバー SDK では、TrackRequest を使用して HTTP 要求が記録されます。

Web サービス モジュールが実行されていない状況で要求をシミュレーションする場合に、これを自分で呼び出すこともできます。

ただし、要求テレメトリを送信するための推奨される方法は、要求が操作コンテキストとして機能しているところです。

操作コンテキスト

テレメトリ項目を操作コンテキストと関連付けることで、それらの項目を互いに相関させることができます。 標準の要求追跡モジュールでは、HTTP 要求の処理中に送信される例外や他のイベントに対してこの関連付けが行われます。 検索分析では、操作 ID を使用して、要求に関連付けられたイベントを簡単に見つけることができます。

相関の詳細については、「Application Insights におけるテレメトリの相関付け」を参照してください。

手動でテレメトリを追跡している場合、テレメトリの相関付けを確実に行うための最も簡単な方法として、次のパターンを使用できます。

C#

// Establish an operation context and associated telemetry item:
using (var operation = telemetryClient.StartOperation<RequestTelemetry>("operationName"))
{
    // Telemetry sent in here will use the same operation ID.
    ...
    telemetryClient.TrackTrace(...); // or other Track* calls
    ...

    // Set properties of containing telemetry item--for example:
    operation.Telemetry.ResponseCode = "200";

    // Optional: explicitly send telemetry item:
    telemetryClient.StopOperation(operation);

} // When operation is disposed, telemetry item is sent.

操作コンテキストの設定に合わせて、指定した種類のテレメトリ項目を StartOperation で作成します。 テレメトリ項目は、操作を破棄するか StopOperation を明示的に呼び出すと送信されます。 テレメトリの種類として RequestTelemetry を使用する場合、その継続時間は開始から停止までの間の一定の間隔に設定されます。

操作のスコープ内にあるテレメトリ項目は、その操作の「子」になります。 操作コンテキストは入れ子にできます。

検索では、操作コンテキストを使用して 関連項目 の一覧が作成されます。

関連項目

カスタム操作の追跡の詳細については、「Application Insights .NET SDK でカスタム操作を追跡する」をご覧ください。

Analytics での要求

Application Insights Analytics で、要求は requests テーブルに表示されます。

サンプリング を操作中の場合は、itemCount プロパティに 1 より大きい値が表示されます。 たとえば itemCount==10 は trackRequest() への 10 回の呼び出しで、サンプリング プロセスはそれらのうちの 1 つだけを転送したことを意味します。 要求の正しい数と要求名別にセグメント化された平均所要時間を取得するには、次のようなコードを使用します。

requests
| summarize count = sum(itemCount), avgduration = avg(duration) by name

TrackException

次の目的で例外を Application Insights に送信します。

レポートにはスタック トレースが含まれます。

C#

try
{
    ...
}
catch (Exception ex)
{
    telemetry.TrackException(ex);
}

Java

try {
    ...
} catch (Exception ex) {
    telemetry.trackException(ex);
}

JavaScript

try
{
    ...
}
catch (ex)
{
    appInsights.trackException({exception: ex});
}

Node.js

try
{
    ...
}
catch (ex)
{
    telemetry.trackException({exception: ex});
}

SDK が多数の例外を自動的にキャッチするため、常に TrackException を明示的に呼び出す必要はありません。

({
    instrumentationKey: "your key",
    disableExceptionTracking: true
})

Analyticsでの例外

Application Insights Analytics で、例外は exceptions テーブルに表示されます。

サンプリングが実行中の場合は、itemCount プロパティは 1 より大きい値を示します。 たとえば itemCount==10 は trackException() への 10 回の呼び出しで、サンプリング プロセスはそれらのうちの 1 つだけを転送したことを意味します。 例外の種類別にセグメント化された例外の正しい数を取得するには、次のようなコードを使用します。

exceptions
| summarize sum(itemCount) by type

重要なスタック情報の大部分は既に個別の変数に抽出されていますが、details 構造を分析してさらに詳細な情報を取得できます。 この構造は動的なので、期待する型に結果をキャストする必要があります。 次に例を示します。

exceptions
| extend method2 = tostring(details[0].parsedStack[1].method)

例外を関連する要求に関連付けるには、結合を使用します。

exceptions
| join (requests) on operation_Id

TrackTrace

TrackTrace を使用すると、Application Insights に "階層リンクの追跡" を送信して問題を診断できます。 診断データのチャンクを送信し、診断検索で検査できます。

.NET ログ アダプターでは、この API を使用してポータルにサードパーティのログを送信します。

Java では、Application Insights Java エージェントによってログが自動収集され、ポータルに送信されます。

C#

telemetry.TrackTrace(message, SeverityLevel.Warning, properties);

Java

telemetry.trackTrace(message, SeverityLevel.Warning, properties);

Node.js

telemetry.trackTrace({
    message: message,
    severity: applicationInsights.Contracts.SeverityLevel.Warning,
    properties: properties
});

クライアント/ブラウザー側の JavaScript

trackTrace({
    message: string, 
    properties?: {[string]:string}, 
    severityLevel?: SeverityLevel
})

メソッドの出入りなどの診断イベントをログに記録します。

パラメーター 説明
message 診断データ。 名前よりはるかに長くなることがあります。
properties 文字列と文字列のマップ:ポータルで、例外のフィルターに使用される追加のデータ。 既定値は空です。
severityLevel サポートされる値:SeverityLevel.ts

メッセージ コンテンツで検索できますが、(プロパティ値とは異なり) フィルター処理はできません。

message のサイズ制限は、プロパティの制限よりも非常に高くなっています。 TrackTrace の利点は、比較的長いデータをメッセージの中に配置できることです。 たとえば、メッセージ中で POST データをエンコードできます。

加えて、メッセージに重大度レベルを追加することができます。 また他のテレメトリと同様、プロパティ値を追加することで、さまざまなトレースの組み合わせをフィルタリングしたり検索したりすることができます。 次に例を示します。

C#

var telemetry = new Microsoft.ApplicationInsights.TelemetryClient();
telemetry.TrackTrace("Slow database response",
                SeverityLevel.Warning,
                new Dictionary<string,string> { {"database", db.ID} });

Java

Map<String, Integer> properties = new HashMap<>();
properties.put("Database", db.ID);
telemetry.trackTrace("Slow Database response", SeverityLevel.Warning, properties);

この後に Search で、特定のデータベースに関連し特定の重大度レベルを持つすべてのメッセージを簡単に抽出することができます。

Analytics でのトレース

Application Insights Analytics で、TrackTrace への呼び出しは traces テーブルに表示されます。

サンプリングが実行中の場合は、itemCount プロパティは 1 より大きい値を示します。 たとえば、itemCount==10 は、サンプリング プロセスで転送されたのは trackTrace() への 10 回の呼び出しのうち 1 回だけであることを意味します。 トレース呼び出しの正確な数を取得するには、traces | summarize sum(itemCount) などのコードを使用する必要があります。

TrackDependency

応答時間と外部コードの呼び出しの成功率を追跡するには、TrackDependency 呼び出しを使用します。 結果は、ポータルの依存関係グラフに表示されます。 依存関係呼び出しが行われるたびに、以下のコード スニペットを追加する必要があります。

注意

.NET および .NET Core の場合は、関連付けに必要な DependencyTelemetry プロパティと、開始時刻や期間などの他のプロパティを設定する TelemetryClient.StartOperation (拡張機能) メソッドを代わりに使用できるため、下の例のようにカスタム タイマーを作成する必要はありません。 詳細については、こちらの記事の出力方向の依存関係の追跡に関するセクションを参照してください。

C#

var success = false;
var startTime = DateTime.UtcNow;
var timer = System.Diagnostics.Stopwatch.StartNew();
try
{
    success = dependency.Call();
}
catch(Exception ex) 
{
    success = false;
    telemetry.TrackException(ex);
    throw new Exception("Operation went wrong", ex);
}
finally
{
    timer.Stop();
    telemetry.TrackDependency("DependencyType", "myDependency", "myCall", startTime, timer.Elapsed, success);
}

Java

boolean success = false;
Instant startTime = Instant.now();
try {
    success = dependency.call();
}
finally {
    Instant endTime = Instant.now();
    Duration delta = Duration.between(startTime, endTime);
    RemoteDependencyTelemetry dependencyTelemetry = new RemoteDependencyTelemetry("My Dependency", "myCall", delta, success);
    dependencyTelemetry.setTimeStamp(startTime);
    telemetry.trackDependency(dependencyTelemetry);
}

Node.js

var success = false;
var startTime = new Date().getTime();
try
{
    success = dependency.Call();
}
finally
{
    var elapsed = new Date() - startTime;
    telemetry.trackDependency({
        dependencyTypeName: "myDependency",
        name: "myCall",
        duration: elapsed,
        success: success
    });
}

サーバー SDK には、データベースや REST API などに対する依存関係の呼び出しを自動的に検出して追跡する依存関係モジュールが含まれています。 このモジュールを機能させるには、サーバーにエージェントをインストールする必要があります。

Java では、Application Insights Java エージェントを使用して、多くの依存関係呼び出しを自動的に追跡することができます。

この呼び出しは、自動追跡ではキャッチされない呼び出しを追跡する場合に使用します。

C# の標準の依存関係追跡モジュールを無効にするには、ApplicationInsights.config を編集し、DependencyCollector.DependencyTrackingTelemetryModule への参照を削除します。 Java の場合は、「特定の自動収集テレメトリの抑制」を参照してください。

Analytics での依存関係

Application Insights Analytics で、trackDependency 呼び出しは dependencies テーブルに表示されます。

サンプリングが実行中の場合は、itemCount プロパティは 1 より大きい値を示します。 たとえば itemCount==10 は trackDependency() への 10 回の呼び出しで、サンプリング プロセスはそれらのうちの 1 つだけを転送したことを意味します。 ターゲット コンポーネント別にセグメント化された依存関係の正しい数を取得するには、次のようなコードを使用します。

dependencies
| summarize sum(itemCount) by target

依存関係を関連する要求に関連付けるには、結合を使用します。

dependencies
| join (requests) on operation_Id

データのフラッシュ

通常、SDK からは一定の間隔 (通常 30 秒) で、またはバッファがいっぱいになったとき (通常 500 項目) にデータが送信されます。 ただし、終了するアプリケーションで SDK を使用する場合などには、バッファーのフラッシュが必要になることがあります。

C#

telemetry.Flush();
// Allow some time for flushing before shutdown.
System.Threading.Thread.Sleep(5000);

Java

telemetry.flush();
//Allow some time for flushing before shutting down
Thread.sleep(5000);

Node.js

telemetry.flush();

サーバー テレメトリ チャネルの場合、この関数は非同期です。

理想的には、アプリケーションのシャットダウン アクティビティで flush() メソッドを使用する必要があります。

認証されたユーザー

Web アプリでは、ユーザーは (既定では) Cookie により識別されます。 ユーザーは、別のコンピューターまたはブラウザーからアプリにアクセスしたり、Cookie を削除した場合、複数回カウントされることがあります。

ユーザーがアプリにサインインしていれば、認証されたユーザーの ID をブラウザー コードに設定して、より正確な数値を取得できます。

JavaScript

// Called when my app has identified the user.
function Authenticated(signInId) {
    var validatedId = signInId.replace(/[,;=| ]+/g, "_");
    appInsights.setAuthenticatedUserContext(validatedId);
    ...
}

ASP.NET Web MVC アプリケーションでの例:

Razor

@if (Request.IsAuthenticated)
{
    <script>
        appInsights.setAuthenticatedUserContext("@User.Identity.Name
            .Replace("\\", "\\\\")"
            .replace(/[,;=| ]+/g, "_"));
    </script>
}

ユーザーの実際のサインイン名を使用する必要はありません。 必要なのは、そのユーザーに一意の ID であるということだけです。 ID には、スペースや ,;=| を含めることはできません。

ユーザー ID はセッション Cookie にも設定され、サーバーに送信されます。 サーバー SDK がインストールされている場合、認証されたユーザー ID は、クライアントおよびサーバー テレメトリの両方のコンテキスト プロパティの一部として送信されます。 送信後、フィルター処理や検索を行うことができます。

アカウントにアプリのグループ ユーザーがある場合、アカウントの識別子も渡すことができます (同じ文字制約が適用されます)。

appInsights.setAuthenticatedUserContext(validatedId, accountId);

メトリックス エクスプローラーで、ユーザー、認証アカウントユーザー アカウント をカウントするグラフを作成できます。

また、特定のユーザー名とアカウントを持つクライアント データ ポイントを検索することもできます。

注意

.NET Core SDK の ApplicationInsightsServiceOptions クラスの EnableAuthenticationTrackingJavaScript プロパティを使用すると、Application Insights JavaScript SDK によって送信される各トレースの認証 ID としてユーザー名を挿入するために必要な JavaScript 構成が簡略化されます。 このプロパティが true に設定されている場合、ASP.NET Core のユーザーのユーザー名がクライアント側のテレメトリと共に出力されます。そのため、appInsights.setAuthenticatedUserContext を手動で追加する必要はなくなります。ASP.NET CORE の SDK によって既に挿入されているためです。 認証 ID は、JavaScript API リファレンスで説明されているように、サーバーにも送信され、そこで、.NET CORE の SDK によって識別され、サーバー側のテレメトリに使用されます。 ただし、ASP.NET Core MVC と同じ方法で動作しない JavaScript アプリケーション (SPA Web アプリなど) の場合は、やはり、appInsights.setAuthenticatedUserContext を手動で追加する必要があります。

プロパティを使用したデータのフィルタリング、検索、セグメント化

プロパティと測定値をイベント (およびメトリック、ページ ビュー、その他のテレメトリ データ) に結び付けることができます。

プロパティ は、利用状況レポートでテレメトリをフィルター処理するのに使用できる文字列値です。 たとえば、アプリケーションで複数のゲームを提供する場合、各イベントにゲームの名前を結び付けることで人気のあるゲームを確認できます。

文字列の長さには 8,192 の制限があります。 (データの大きなチャンクを送信する場合は、TrackTrace のメッセージ パラメーターを使用します。)

メトリックス はグラフィカルに表示できる数値です。 たとえば、ゲーマーが達成するスコアに漸増があるかどうかを確認できます。 イベントともに送信されるプロパティ別にグラフをセグメント化し、ゲームごとの個別のグラフや積み重ねグラフを表示できます。

メトリック値は、0 以上でないと正しく表示されません。

使用できる プロパティ、プロパティ値、およびメトリックの数には制限 があります。

JavaScript

appInsights.trackEvent({
  name: 'some event',
  properties: { // accepts any type
    prop1: 'string',
    prop2: 123.45,
    prop3: { nested: 'objects are okay too' }
  }
});

appInsights.trackPageView({
  name: 'some page',
  properties: { // accepts any type
    prop1: 'string',
    prop2: 123.45,
    prop3: { nested: 'objects are okay too' }
  }
});

C#

// Set up some properties and metrics:
var properties = new Dictionary <string, string>
    {{"game", currentGame.Name}, {"difficulty", currentGame.Difficulty}};
var metrics = new Dictionary <string, double>
    {{"Score", currentGame.Score}, {"Opponents", currentGame.OpponentCount}};

// Send the event:
telemetry.TrackEvent("WinGame", properties, metrics);

Node.js

// Set up some properties and metrics:
var properties = {"game": currentGame.Name, "difficulty": currentGame.Difficulty};
var metrics = {"Score": currentGame.Score, "Opponents": currentGame.OpponentCount};

// Send the event:
telemetry.trackEvent({name: "WinGame", properties: properties, measurements: metrics});

Visual Basic

' Set up some properties:
Dim properties = New Dictionary (Of String, String)
properties.Add("game", currentGame.Name)
properties.Add("difficulty", currentGame.Difficulty)

Dim metrics = New Dictionary (Of String, Double)
metrics.Add("Score", currentGame.Score)
metrics.Add("Opponents", currentGame.OpponentCount)

' Send the event:
telemetry.TrackEvent("WinGame", properties, metrics)

Java

Map<String, String> properties = new HashMap<String, String>();
properties.put("game", currentGame.getName());
properties.put("difficulty", currentGame.getDifficulty());

Map<String, Double> metrics = new HashMap<String, Double>();
metrics.put("Score", currentGame.getScore());
metrics.put("Opponents", currentGame.getOpponentCount());

telemetry.trackEvent("WinGame", properties, metrics);

注意

プロパティで個人を特定できる情報を記録しないように注意します。

プロパティとメトリックを設定する別の方法

個別のオブジェクトでイベントのパラメーターを集めたほうが便利であれば、そのようにできます。

var event = new EventTelemetry();

event.Name = "WinGame";
event.Metrics["processingTime"] = stopwatch.Elapsed.TotalMilliseconds;
event.Properties["game"] = currentGame.Name;
event.Properties["difficulty"] = currentGame.Difficulty;
event.Metrics["Score"] = currentGame.Score;
event.Metrics["Opponents"] = currentGame.Opponents.Length;

telemetry.TrackEvent(event);

警告

Track*() を複数回呼び出すために、同じテレメトリ項目インスタンス (この例では event) を再利用しないでください。 再利用すると、正しくない構成でテレメトリが送信される場合があります。

Analytics でのカスタム測定とプロパティ

Analytics で、カスタム メトリックとプロパティは、各テレメトリ レコードの customMeasurements および customDimensions 属性に表示されます。

たとえば、要求テレメトリに "game" というプロパティを追加した場合、このクエリは "game" のさまざまな値の出現数をカウントし、カスタム メトリック "score" の平均を表示します。

requests
| summarize sum(itemCount), avg(todouble(customMeasurements.score)) by tostring(customDimensions.game)

次のことに注意してください。

  • customDimensions または customMeasurements JSON から値を抽出する場合、これは動的な型を持つため、tostring または todouble にキャストする必要があります。
  • サンプリングの可能性について考慮するには、count() ではなく、sum(itemCount) を使用する必要があります。

タイミング イベント

アクションの実行にかかる時間をグラフで示す必要が生じることがあります。 たとえば、ユーザーがゲームで選択肢について考える時間について調べるとします。 測定パラメーターを使用することでこの調査を行うことができます。

C#

var stopwatch = System.Diagnostics.Stopwatch.StartNew();

// ... perform the timed action ...

stopwatch.Stop();

var metrics = new Dictionary <string, double>
    {{"processingTime", stopwatch.Elapsed.TotalMilliseconds}};

// Set up some properties:
var properties = new Dictionary <string, string>
    {{"signalSource", currentSignalSource.Name}};

// Send the event:
telemetry.TrackEvent("SignalProcessed", properties, metrics);

Java

long startTime = System.currentTimeMillis();

// Perform timed action

long endTime = System.currentTimeMillis();
Map<String, Double> metrics = new HashMap<>();
metrics.put("ProcessingTime", (double)endTime-startTime);

// Setup some properties
Map<String, String> properties = new HashMap<>();
properties.put("signalSource", currentSignalSource.getName());

// Send the event
telemetry.trackEvent("SignalProcessed", properties, metrics);

カスタム テレメトリの既定のプロパティ

記述するカスタム イベントのいくつかに既定のプロパティ値を設定する必要がある場合、TelemetryClient インスタンスで設定できます。 既定値は、そのクライアントから送信されたすべてのテレメトリ項目に追加されます。

C#

using Microsoft.ApplicationInsights.DataContracts;

var gameTelemetry = new TelemetryClient();
gameTelemetry.Context.GlobalProperties["Game"] = currentGame.Name;
// Now all telemetry will automatically be sent with the context property:
gameTelemetry.TrackEvent("WinGame");

Visual Basic

Dim gameTelemetry = New TelemetryClient()
gameTelemetry.Context.GlobalProperties("Game") = currentGame.Name
' Now all telemetry will automatically be sent with the context property:
gameTelemetry.TrackEvent("WinGame")

Java

import com.microsoft.applicationinsights.TelemetryClient;
import com.microsoft.applicationinsights.TelemetryContext;
...

TelemetryClient gameTelemetry = new TelemetryClient();
TelemetryContext context = gameTelemetry.getContext();
context.getProperties().put("Game", currentGame.Name);

gameTelemetry.TrackEvent("WinGame");

Node.js

var gameTelemetry = new applicationInsights.TelemetryClient();
gameTelemetry.commonProperties["Game"] = currentGame.Name;

gameTelemetry.TrackEvent({name: "WinGame"});

個別のテレメトリの呼び出しはプロパティ ディクショナリの既定値をオーバーライドできます。

JavaScript Web クライアントの場合、JavaScript テレメトリ初期化子を使用します。

標準コレクション モジュールのデータなど、すべてのテレメトリにプロパティを追加する には、ITelemetryInitializer を実装します

テレメトリのサンプリング、フィルタリング、および処理

テレメトリを SDK からの送信前に処理するコードを記述することができます。 この処理では、HTTP 要求のコレクションや依存関係のコレクションなど、標準的なテレメトリ モジュールから送信されるデータも対象となります。

テレメトリにプロパティを追加するには、ITelemetryInitializer を実装します。 たとえば、バージョン番号や、他のプロパティから算出された値を追加できます。

ITelemetryProcessor を実装すると、テレメトリが SDK から送信される前にフィルタリングによってテレメトリを変更または破棄することができます。 送信対象や破棄対象を指定できますが、メトリックへの影響を考慮する必要があります。 項目を破棄する方法によっては、関連する項目間を移動する機能が失われる可能性があります。

サンプリングは、アプリからポータルに送信されるデータの量を減らすためのパッケージ化ソリューションです。 これにより、表示されるメトリックに影響をあたえることなくデータ量を削減できます。 また、サンプリングを行った場合でも、変わらずに例外、要求、ページ ビューなどの関連する項目間を移動して問題を診断できます。

詳細については、こちらを参照してください

テレメトリの無効化

テレメトリの収集と送信を 動的に停止および開始 するには

C#

using  Microsoft.ApplicationInsights.Extensibility;

TelemetryConfiguration.Active.DisableTelemetry = true;

Java

telemetry.getConfiguration().setTrackingDisabled(true);

選択されている標準のコレクターを無効にする には (たとえば、パフォーマンス カウンター、HTTP 要求、依存関係)、ApplicationInsights.config 内の該当する行を削除するか、コメントアウトします。たとえば、独自の TrackRequest データを送信する場合にこれを行います。

Node.js

telemetry.config.disableAppInsights = true;

初期化時にパフォーマンス カウンター、HTTP 要求、依存関係などの 選択されている標準コレクターを無効にする には、構成メソッドを次のように SDK の初期化コードに追加します。

applicationInsights.setup()
    .setAutoCollectRequests(false)
    .setAutoCollectPerformance(false)
    .setAutoCollectExceptions(false)
    .setAutoCollectDependencies(false)
    .setAutoCollectConsole(false)
    .start();

初期化後にこれらのコレクターを無効にするには、構成オブジェクト applicationInsights.Configuration.setAutoCollectRequests(false) を使用します。

開発者モード

デバッグ中、結果をすぐに確認できるように、テレメトリをパイプラインから送信すると便利です。 テレメトリで問題を追跡する際に役立つ付加的なメッセージも取得できます。 アプリケーションの速度を低下させる可能性があるため、本稼働ではオフにしてください。

C#

TelemetryConfiguration.Active.TelemetryChannel.DeveloperMode = true;

Visual Basic

TelemetryConfiguration.Active.TelemetryChannel.DeveloperMode = True

Node.js

Node.js の場合は、setInternalLogging 経由で内部ログを有効にし、maxBatchSize を 0 に設定することによって開発者モードを有効にすることができます。これにより、テレメトリは、収集されるとすぐに送信されます。

applicationInsights.setup("ikey")
  .setInternalLogging(true, true)
  .start()
applicationInsights.defaultClient.config.maxBatchSize = 0;

選択したカスタム テレメトリにインストルメンテーション キーを設定する

C#

var telemetry = new TelemetryClient();
telemetry.InstrumentationKey = "---my key---";
// ...

動的なインストルメンテーション キー

開発、テスト、運用の各環境のテレメトリが混じらないようにするために、環境に応じて個別の Application Insights リソースを作成し、それぞれのキーを変更できます。

インストルメンテーション キーは構成ファイルから取得する代わりにコードで設定できます。 ASP.NET サービスの global.aspx.cs など、初期化メソッドでキーを設定します。

C#

protected void Application_Start()
{
    Microsoft.ApplicationInsights.Extensibility.
    TelemetryConfiguration.Active.InstrumentationKey =
        // - for example -
        WebConfigurationManager.Settings["ikey"];
    ...
}

JavaScript

appInsights.config.instrumentationKey = myKey;

Web ページでは、スクリプトに一語一語コーディングするのではなく、Web サーバーの状態から設定することもできます。 たとえば、ASP.NET アプリで生成される Web ページでは次のように設定します。

Razor の JavaScript

<script type="text/javascript">
// Standard Application Insights webpage script:
var appInsights = window.appInsights || function(config){ ...
// Modify this part:
}({instrumentationKey:  
    // Generate from server property:
    @Microsoft.ApplicationInsights.Extensibility.
        TelemetryConfiguration.Active.InstrumentationKey;
}) // ...
    String instrumentationKey = "00000000-0000-0000-0000-000000000000";

    if (instrumentationKey != null)
    {
        TelemetryConfiguration.getActive().setInstrumentationKey(instrumentationKey);
    }

TelemetryContext

TelemetryClient には、すべてのテレメトリ データとともに送信される値が含まれる Context プロパティが備わっています。 通常、標準のテレメトリ モジュールによって設定されますが、自分で設定することもできます。 次に例を示します。

telemetry.Context.Operation.Name = "MyOperationName";

いずれかの値を自分で設定した場合は、その値と標準の値が混同されないように、ApplicationInsights.config から該当する行を削除することを検討します。

  • Component:アプリそのバージョン。
  • Device:アプリが実行されているデバイスに関するデータ (Web アプリでは、テレメトリを送信するサーバーまたはクライアント デバイスのデータ)。
  • InstrumentationKey:テレメトリが表示される Azure 内の Application Insights リソース。 通常、ApplicationInsights.config から取得されます。
  • [場所] :デバイスの地理的な場所。
  • Operation:Web アプリでは現在の HTTP 要求。 他の種類のアプリケーションでは、イベントをグループ化するために、これを設定できます。
    • [ID] :診断検索でイベントを調べるときに関連項目を見つけることができるように、さまざまなイベントを関連付けるために生成される値。
    • Name:識別子。通常は HTTP 要求の URL です。
    • SyntheticSource:null 値または空ではない場合に、要求元がロボットまたは Web テストとして識別されたことを示す文字列。 既定で、メトリックス エクスプローラーの計算から除外されます。
  • セッション:ユーザーのセッション。 ID は生成された値に設定されますが、ユーザーがしばらくの間アクティブでない場合には変更されます。
  • [ユーザー] :ユーザー情報。

制限

アプリケーションごと (インストルメンテーション キーごと) のメトリックとイベントの数には制限があります。 制限は、選択する料金プランによって異なります。

リソース 既定の制限 Note
1 日あたりの合計データ量 100 GB 上限を設定することでデータを削減できます。 さらにデータが必要な場合は、ポータルで上限を最大 1,000 GB まで引き上げることができます。 1,000 GB を超える容量については、AIDataCap@microsoft.com までメールでご連絡ください。
Throttling 32,000 イベント/秒 制限は 1 分以上にわたって測定されます。
データ保持 (ログ) 30 日から 730 日 このリソースはログ用です。
データ保持 (メトリック) 90 日間 このリソースはメトリックス エクスプローラー用です。
可用性の複数手順のテストの詳細な結果の保持 90 日間 このリソースは、各手順の詳細な結果を提供します。
テレメトリ項目の最大サイズ 64 KB
バッチあたりの最大テレメトリ項目数 64 K
プロパティとメトリック名の長さ 150 型スキーマに関するページを参照してください。
プロパティ値の文字列の長さ 8,192 型スキーマに関するページを参照してください。
トレースおよび例外のメッセージ長 32,768 型スキーマに関するページを参照してください。
アプリあたりの可用性テストの数 100
プロファイラーのデータ保持期間 5 日
プロファイラーの 1 日あたりの送信データ 10 GB

詳細については、Application Insights の価格とクォータに関するページを参照してください。

データ速度の上限に達するのを回避するには、サンプリングを使用します。

データの保持期間を確認する方法については、データの保持とプライバシーに関するページを参照してください。

リファレンス ドキュメント

SDK コード

疑問がある場合

  • Track_() の呼び出しでは、どのような例外がスローされることがありますか。

    [なし] : try catch 句で例外をラップする必要はありません。 SDK で問題が発生すると、デバッグ コンソール出力のメッセージが記録されます。メッセージがスルーされる場合は、診断検索にも記録されます。

  • ポータルからデータを取得する REST API はありますか。

    はい、データ アクセス API があります。 データを抽出する別の方法としては、Analytics から Power BI へのエクスポート連続エクスポートなどがあります。

次のステップ