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

アプリケーションに数行のコードを挿入して、ユーザーの行動を調べたり、問題の診断に役立つ情報を取得したりすることができます。 デバイスとデスクトップ アプリケーション、Web クライアント、Web サーバーからテレメトリを送信できます。 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 の参照がまだない場合:

• Application Insights SDK をプロジェクトに追加します。

  • ASP.NET プロジェクト
  • ASP.NET Core プロジェクト
  • Java プロジェクト
  • Node.js プロジェクト
  • 各 Web ページの JavaScript

• デバイスまたは Web サーバー コードに次を追加します。

  C# : using Microsoft.ApplicationInsights;

  Visual Basic: Imports Microsoft.ApplicationInsights

  Java: import com.microsoft.applicationinsights.TelemetryClient;

  Node.js: var applicationInsights = require("applicationinsights");

TelemetryClient インスタンスの取得

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

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

Azure Functions v2 以降または Azure WebJobs v3 以降を使用する場合は、「Azure Functions を監視する」を参照してください。

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"});

Log Analytics でのカスタム イベント

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

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

GetMetric

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

TrackMetric

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.Sum = 42.3;
telemetryClient.TrackMetric(sample);

Java

telemetry.trackMetric("queueLength", 42.0);

Node.js

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

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

テレメトリは、Application Insights Analytics の customMetrics テーブルにあります。 各行は、アプリでの 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); で明示的な時間を設定する。
• ページ ビューのタイミングの呼び出し (startTrackPage と stopTrackPage) を使用する。

JavaScript

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

...

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

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

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

Log Analytics でのページ テレメトリ

Log 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

HTTP 要求を記録するために、サーバー SDK によって TrackRequest が使用されます。

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 でカスタム操作を追跡する」を参照してください。

Log 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 を明示的に呼び出す必要はありません。

• ASP.NET: 例外をキャッチするコードを記述します。
• Java EE: 例外は自動的にキャッチされます。
• JavaScript: 例外は自動的にキャッチされます。 自動コレクションを無効にする場合は、Web ページに挿入する JavaScript (Web) SDK ローダー スクリプトに次の行を追加します。

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

Log 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 で、特定のデータベースに関連し特定の重大度レベルを持つすべてのメッセージを簡単に抽出することができます。

Log Analytics のトレース

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

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

TrackDependency

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

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 の場合は、「特定の自動収集テレメトリの抑制」を参照してください。

Log 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 を使用している場合です。

.NET

Flush() を使用する場合は、このパターンをお勧めします。

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

FlushAsync() を使用する場合は、このパターンをお勧めします。

await telemetryClient.FlushAsync()
// No need to sleep

テレメトリが失われないように、常にアプリケーション シャットダウンの一部としてフラッシュすることをお勧めします。

Java

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

Node.js

telemetry.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);

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

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

プロパティを使用してデータをフィルター処理、検索、分割する

プロパティと測定値をイベント、メトリック、ページ ビュー、例外、その他のテレメトリ データにアタッチすることができます。

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

文字列の長さには 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);

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

Log 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 を実装します。

テレメトリのサンプル、フィルター、処理

「Application Insights 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 は生成された値に設定されますが、ユーザーがしばらくの間アクティブでない場合には変更されます。
• [ユーザー] :ユーザー情報。

制限

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

リソース	既定の制限	上限	Notes
1 日あたりの合計データ量	100 GB	サポートにお問い合わせください。	上限を設定してデータを減らすことができます。 さらにデータが必要な場合は、ポータルで上限を最大 1,000 GB まで引き上げることができます。 1,000 GB を超える容量については、AIDataCap@microsoft.com までメールでご連絡ください。
Throttling	32,000 イベント/秒	サポートにお問い合わせください。	制限は 1 分間にわたって測定されます。
データ保持ログ	30 日 - 730 日	730 日	このリソースはログ用です。
データ保持メトリック	90 日間	90 日間	このリソースはメトリックス エクスプローラー用です。
可用性の複数手順のテストの詳細な結果の保持	90 日間	90 日間	このリソースは、各手順の詳細な結果を提供します。
テレメトリ項目の最大サイズ	64 KB	64 KB
バッチあたりの最大テレメトリ項目数	64,000	64,000
プロパティとメトリック名の長さ	150	150	型スキーマに関するページを参照してください。
プロパティ値の文字列の長さ	8,192	8,192	型スキーマに関するページを参照してください。
トレースおよび例外のメッセージ長	32,768	32,768	型スキーマに関するページを参照してください。
Application Insights リソースあたりの可用性テスト数	100	100
リソース グループあたりの可用性テスト数	800	800	Azure Resource Manager を参照してください
可用性テストのテストあたりの最大リダイレクト数	10	10
可用性テストの最小テスト頻度	300 秒		5 分未満のカスタム テスト周波数または周波数には、カスタム TrackAvailability 実装が必要です。
.NET Profiler とスナップショット デバッガーのデータ保持	2 週間	サポートにお問い合せください。 保持の最大限度は 6 か月です。
.NET Profiler の 1 日あたりの送信データ	制限なし	制限なし。
スナップショット デバッガーの 1 日あたりの送信データ	監視対象アプリごとに 1 日あたり 30 のスナップショット	制限なし。	アプリケーションあたりに収集されるスナップショットの数は、構成することで変更できます。

価格とクォータの詳細については、「Application Insights の課金」を参照してください。

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

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

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

• .NET リファレンス
• Java リファレンス
• JavaScript リファレンス

SDK コード

• .NET
• Windows Server パッケージ
• Java SDK
• Node.js SDK
• JavaScript SDK

よく寄せられる質問

このセクションでは、一般的な質問への回答を示します。

テレメトリ データが見つからないのはなぜですか?

アプリケーションがシャットダウンする前にフラッシュされていない場合、両方のテレメトリ チャネルでバッファリングされたテレメトリが消失します。

データの損失を回避するには、アプリケーションのシャットダウン時に TelemetryClient をフラッシュします。

詳細については、「データのフラッシュ」を参照してください。

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

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

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

はい、データ アクセス API があります。 データを抽出するその他の方法としては、ワークスペース ベースのリソースでの Power BI があります。

カスタム イベントとメトリック API の呼び出しが無視される理由は?

Application Insights SDK は、自動インストルメンテーションと互換性がありません。 自動インストルメンテーションが有効になっている場合、Track() やその他のカスタム イベントとメトリック API への呼び出しは無視されます。

Azure portal の App Service ページの [Application Insights] タブで自動インストルメンテーションをオフにするか、ApplicationInsightsAgent_EXTENSION_VERSION を disabled に設定します。

検索グラフとメトリック グラフで数が等しくないのはなぜですか?

サンプリングにより、アプリからポータルに送信されるテレメトリ項目 (要求、カスタム イベントなど) の数が減少します。 [検索] には、受信した項目の数が表示されます。 イベント数を表示するメトリック グラフには、発生した元のイベントの数が表示されます。

送信される各項目には、itemCount プロパティが含まれます。このプロパティは、項目が表す元のイベントの数を示します。 Log Analytics で次のクエリを実行すると、サンプリング操作を確認できます。

    requests | summarize original_events = sum(itemCount), transmitted_events = count()

イベントにアラートを設定するには、どうすればよいですか?

Azure アラートはメトリックにのみ設定できます。 イベントが発生するたびにしきい値を超える、カスタム メトリックを作成してください。 その後、メトリックにアラートを設定します。 メトリックがどちらの方向であれしきい値を超えると、必ず通知を受け取ります。 初期値が高くても低くても、最初に超えるまでは通知を受け取りません。 常に数分の待ち時間が発生します。

次のステップ

• イベントおよびログを検索する