Application Insights (クラシック API) を使用して Node.js アプリケーションとサービスを監視する

Application Insights は、デプロイ後のコンポーネントを監視して、パフォーマンスや他の問題を検出します。 Application Insights は、自社のデータセンターや、Azure VM、Web アプリ、さらには他のパブリック クラウドにホストされた Node.js サービスに対しても使用できます。

監視データを受信、保存、探索するためには、ご使用のコードに SDK を追加します。 次に、Azure で対応する Application Insights リソースを設定します。 そのリソースに対して SDK からデータが送信され、詳細な分析と探索が行えるようになります。

Node.js クライアント ライブラリでは、着信と発信の HTTP 要求、例外、システムのいくつかのメトリックを自動的に監視できます。 さらに、バージョン 0.20 以降のクライアント ライブラリでは、MongoDB、MySQL、Redis など、一般的なサードパーティ製パッケージを監視することもできます。

受信 HTTP 要求に関連するすべてのイベントは、トラブルシューティングを迅速に行えるように関連付けられます。

TelemetryClient API を使用して手動でインストルメント化すれば、ご使用のアプリとシステムのその他の側面も監視できます。 TelemetryClient API については、この記事の後半でさらに詳しく説明します。

概要

アプリまたはサービスの監視を設定するには、次の作業を完了します。

前提条件

開始する前に、Azure サブスクリプションがあることを確認するか、無償で新しい Azure サブスクリプションを取得してください。 組織に Azure サブスクリプションが既にある場合は、管理者にこちらの手順に従ってもらうことで、追加してもらうことができます。

Application Insights リソースを設定する

1. Azure portal にサインインします。
2. Application Insights のリソースを作成します。

Node.js クライアント ライブラリを設定する

アプリでデータを収集できるように、アプリに SDK を追加します。

1. 新しいリソースからリソースの接続文字列をコピーします。 Application Insights は、この接続文字列を使って、対象の Azure リソースにデータをマッピングします。 SDK で接続文字列を使うには、その接続文字列を環境変数またはコードの中で指定する必要があります。

   

2. package.json を使って、Node.js クライアント ライブラリをアプリの依存関係に追加します。 アプリのルート フォルダーから次を実行します。

   npm install applicationinsights --save
   

   注

   TypeScript を使用している場合は、個別の "typings" パッケージをインストールしないでください。 この NPM パッケージには、組み込みの型指定が含まれています。

3. コードでライブラリを明示的に読み込みます。 インストルメンテーションは、SDK によって他の多数のライブラリに挿入されます。そのため、ライブラリはできる限り早く (require ステートメントよりも前に) 読み込むようにしてください。

   let appInsights = require('applicationinsights');
   

4. また、APPLICATIONINSIGHTS_CONNECTION_STRING または setup() に手動で渡すのではなく、環境変数 new appInsights.TelemetryClient() を使って接続文字列を指定することもできます。 この方法では、コミットされたソース コードに接続文字列を含めず、異なる環境に合わせて異なる接続文字列を指定できます。 手動で構成するには、appInsights.setup('[your connection string]'); を呼び出します。

   その他の構成オプションについては、以降のセクションを参照してください。

   appInsights.defaultClient.config.disableAppInsights = true を設定すると、テレメトリを送信することなく SDK を試すことができます。

5. appInsights.start(); を呼び出して、データの収集と送信を自動的に開始します。

アプリを監視する

SDK は、Node.js ランタイムおよび一般的なサード パーティ モジュールに関するテレメトリを自動的に収集します。 アプリケーションを使用して、そうしたデータを生成します。

次に、Azure portal で、先ほど作成した Application Insights リソースに移動します。 [概要のタイムライン]で、最初のデータ ポイントを探してください。 さらに詳しいデータを表示するには、グラフ内の別のコンポーネントを選択してください。

対象のアプリに関して検出されたトポロジを表示するには、[アプリケーション マップ] を使用できます。

データなし

SDK では送信するデータをバッチ処理するため、ポータルに項目が表示されるまでに遅延が発生する場合があります。 リソースのデータが表示されない場合は、次の対処方法を試してください。

• 引き続きアプリケーションを使用します。 操作を実行して、テレメトリをさらに生成します。
• ポータルのリソース ビューで [最新の情報に更新] を選びます。 グラフは定期的に自動で更新されますが、手動で更新を強制することで最新の情報が直ちに表示されます。
• 必要な送信ポートが開いていることを確認します。
• [検索] を使用して特定のイベントを探します。
• よく寄せられる質問を確認します。

基本的な使用方法

すぐに利用できる HTTP 要求のコレクション、一般的なサードパーティ ライブラリ イベント、未処理の例外、およびシステム メトリックの場合は、次のとおりです。

let appInsights = require("applicationinsights");
appInsights.setup("[your connection string]").start();

他のパッケージを読み込む前に、スクリプトのできるだけ早い段階で Application Insights ライブラリ require("applicationinsights") を読み込みます。 このステップは、Application Insights ライブラリが追跡のために後でパッケージを準備できるようにするために必要です。 同様の準備を行った他のライブラリとの競合が発生した場合は、後で Application Insights ライブラリを読み込んでみてください。

JavaScript がコールバックを処理する方法が原因で、外部依存関係および後のコールバックで要求を追跡するために追加の作業が必要になります。 既定では、この追加の追跡が有効になっています。 「setAutoDependencyCorrelation(false)」セクションの説明に従って を呼び出して無効にします。

0.22 より前のバージョンからの移行

バージョン 0.22 より前のリリースと、それ以降のリリースの間には、破壊的変更があります。 これらの変更は、他の Application Insights SDK との一貫性を保ち、将来の拡張を可能にするように設計されています。

一般に、次の操作を行うことで移行できます。

• appInsights.client への参照を appInsights.defaultClient に置き換えます。
• appInsights.getClient() への参照を new appInsights.TelemetryClient() に置き換えます。
• client.track* メソッドのすべての引数を、名前付きプロパティを引数として含む 1 つのオブジェクトに置き換えます。 それぞれの型のテレメトリに対して除外されるオブジェクトについては、IDE の組み込みの型ヒントまたは TelemetryTypes を参照してください。

appInsights.setup() にチェーンせずに SDK 構成関数にアクセスすると、これらの関数を appInsights.Configurations で見つけることができるようになります。 たとえば appInsights.Configuration.setAutoCollectDependencies(true) です。 次のセクションで、既定の構成に対する変更を確認してください。

SDK の構成

appInsights オブジェクトには、多くの構成メソッドがあります。 これらを既定値と共に、次のスニペットに一覧表示します。

let appInsights = require("applicationinsights");
appInsights.setup("<connection_string>")
    .setAutoDependencyCorrelation(true)
    .setAutoCollectRequests(true)
    .setAutoCollectPerformance(true, true)
    .setAutoCollectExceptions(true)
    .setAutoCollectDependencies(true)
    .setAutoCollectConsole(true)
    .setUseDiskRetryCaching(true)
    .setSendLiveMetrics(false)
    .setDistributedTracingMode(appInsights.DistributedTracingModes.AI)
    .start();

サービスのイベントを完全に関連付けるには、必ず .setAutoDependencyCorrelation(true) を設定します。 このオプションを設定することにより、Node.js の非同期コールバック全体のコンテキストを SDK で追跡できます。

IDE の組み込みの型ヒントで説明を確認するか、applicationinsights.ts で詳細な情報と省略可能なセカンダリ引数を確認してください。

分散トレース

最新のクラウドおよび マイクロサービス アーキテクチャでは、可用性とスループットを向上させながらコストを削減する、シンプルで個別にデプロイ可能なサービスが実現されています。 ただし、システム全体の推論とデバッグが難しくなっています。 分散トレースでは、クラウドおよびマイクロサービス アーキテクチャの呼び出し履歴と同様に動作するパフォーマンス プロファイラーを提供することで、この問題を解決します。

Azure Monitor には、分散トレース データを使用するための 2 つのエクスペリエンスが用意されています。1 つのトランザクション/要求の トランザクション診断 ビューと、システムの対話方法を示す アプリケーション マップ ビューです。

Application Insights では、分散テレメトリの相関関係を使用して、各コンポーネントを個別に監視し、障害やパフォーマンスの低下を担当するコンポーネントを検出できます。 この記事では、Application Insights で使用されるさまざまな言語とプラットフォームでのデータ モデル、コンテキスト伝達手法、プロトコル、相関戦術の実装について説明します。

Application Insights の自動インストルメンテーションまたは SDK を使用して、分散トレースを有効にする。

.NET、.NET Core、Java、Node.js、JavaScript 用の Application Insights エージェントと SDK はすべて、分散トレースをネイティブにサポートします。

適切な Application Insights SDK がインストールされ、構成されると、一般的なフレームワーク、ライブラリ、テクノロジのトレース情報が SDK 依存関係オートコレクタによって自動的に収集されます。 サポートされているテクノロジの完全な一覧は、 Dependency autocollection ドキュメントで入手できます。

TelemetryClient で TrackDependency を呼び出して、任意のテクノロジを手動で追跡することもできます。

テレメトリの相関関係のデータ モデル

Application Insights では、分散テレメトリの相関関係のための データ モデル を定義します。 テレメトリを論理操作に関連付けるために、すべてのテレメトリ項目には operation_Id というコンテキスト フィールドがあります。 分散トレース内のすべてのテレメトリ項目は、この識別子を共有します。 そのため、1 つのレイヤーからテレメトリを失った場合でも、他のコンポーネントから報告されたテレメトリを関連付けることができます。

分散論理操作は、通常、コンポーネントの 1 つによって処理される要求である一連の小規模な操作で構成されます。 要求テレメトリは、 これらの操作を定義します。 すべての要求テレメトリ項目には、一意かつグローバルに識別する独自の id があります。 要求に関連付けられているすべてのテレメトリ項目 (トレースや例外など) は、要求operation_parentIdの値にidを設定する必要があります。

依存関係テレメトリ は、別のコンポーネントへの HTTP 呼び出しなど、すべての送信操作を表します。 また、グローバルに一意の独自の id も定義します。 この依存関係呼び出しによって開始された要求テレメトリは、この id を operation_parentIdとして使用します。

operation_Idでoperation_parentId、request.id、およびdependency.idを使用して、分散論理操作のビューを構築できます。 これらのフィールドは、テレメトリ呼び出しの因果関係の順序も定義します。

マイクロサービス環境では、コンポーネントからのトレースはさまざまなストレージ項目に移動できます。 Application Insights では、すべてのコンポーネントに独自の接続文字列を含めることができます。 Application Insights は、論理操作のテレメトリを取得するために、すべてのストレージ項目からデータを照会します。

ストレージ項目の数が多い場合は、次の場所に関するヒントが必要です。 Application Insights データ モデルでは、この問題を解決するために、 request.source と dependency.targetという 2 つのフィールドが定義されています。 最初のフィールドは、依存関係要求を開始したコンポーネントを識別します。 2 番目のフィールドは、依存関係呼び出しの応答を返したコンポーネントを識別します。

複数の異なるインスタンスからのクエリの詳細については、 Azure Monitor の Log Analytics ワークスペース、アプリケーション、およびリソース全体のデータのクエリを参照してください。

Example

例を見てみましょう。 株価と呼ばれるアプリケーションは、Stock と呼ばれる外部 API を使用して、株式の現在の市場価格を示します。 株価アプリケーションには、 GET /Home/Stockを使用してクライアント Web ブラウザーが開く Stock ページというページがあります。 アプリケーションは、HTTP 呼び出し GET /api/stock/valueを使用して Stock API に対してクエリを実行します。

クエリを実行することで、結果のテレメトリを分析できます。

(requests | union dependencies | union pageViews)
| where operation_Id == "STYz"
| project timestamp, itemType, name, id, operation_ParentId, operation_Id

結果では、すべてのテレメトリ項目がルート operation_Idを共有します。 ページから Ajax 呼び出しが行われると、依存関係テレメトリに新しい一意の ID (qJSXU) が割り当てられ、pageView の ID が operation_ParentIdとして使用されます。 その後、サーバー要求は Ajax ID を operation_ParentIdとして使用します。

呼び出し GET /api/stock/value が外部サービスに対して行われる場合は、 dependency.target フィールドを適切に設定できるように、そのサーバーの ID を把握する必要があります。 外部サービスが監視をサポートしていない場合、 target はサービスのホスト名に設定されます。 たとえば stock-prices-api.com です。 ただし、定義済みの HTTP ヘッダーを返すことによってサービス自体が識別される場合、 target には、Application Insights がそのサービスからのテレメトリに対してクエリを実行して分散トレースを構築できるようにするサービス ID が含まれます。

W3C TraceContext を使用した関連付けヘッダー

Application Insights は、次を定義する W3C トレース コンテキストに移行しています。

• traceparent: 呼び出しのグローバルに一意の操作 ID と一意識別子を格納します。
• tracestate: システム固有のトレース コンテキストを実行します。

Application Insights SDK の最新バージョンでは、Trace-Context プロトコルがサポートされていますが、オプトインが必要な場合があります。 (Application Insights SDK でサポートされていた以前の関連付けプロトコルとの下位互換性は維持されます)。

関連付け HTTP プロトコル (Request-Id とも呼ばれます) は非推奨になっています。 このプロトコルは、次の 2 つのヘッダーを定義します。

• Request-Id: 呼び出しのグローバルに一意の ID を伝送します。
• Correlation-Context: 分散トレース プロパティの名前と値のペアのコレクションを保持します。

Application Insights では、関連付け HTTP プロトコルの 拡張機能 も定義されます。 Request-Context名前と値のペアを使用して、直前の呼び出し元または呼び出し先が使用するプロパティのコレクションを伝達します。 Application Insights SDK では、このヘッダーを使用して、 dependency.target フィールドと request.source フィールドを設定します。

W3C トレース コンテキストおよび Application Insights データ モデルは、次のようにマップされます。

詳細については、「 Application Insights テレメトリ データ モデル」を参照してください。

サンプリング

既定では、SDK は収集されたすべてのデータを Application Insights サービスに送信します。 サンプリングを有効にしてデータの量を減らす場合は、クライアントの samplingPercentage オブジェクトで config フィールドを設定します。 samplingPercentage を 100 (既定値) に設定すると、すべてのデータが送信され、0 にした場合は何も送信されません。

自動関連付けを使っている場合は、1 つの要求に関連付けられているすべてのデータが 1 つの単位として、追加または除外されます。

次のようなコードを追加して、サンプリングを有効にします。

const appInsights = require("applicationinsights");
appInsights.setup("<connection_string>");
appInsights.defaultClient.config.samplingPercentage = 33; // 33% of all telemetry will be sent to Application Insights
appInsights.start();

マルチコンポーネントアプリケーションにおける複数の役割

一部のシナリオでは、アプリケーションは、同じ接続文字列ですべてをインストルメント化する複数のコンポーネントで構成される場合があります。 これらのコンポーネントは、個別の接続文字列を使用しているかのように、ポータルで個別の単位として引き続き表示される必要があります。 例として、アプリケーション マップ上の個別のノードがあります。 あるコンポーネントのテレメトリと Application Insights リソースにデータを送信する他のコンポーネントを区別するには、RoleName フィールドを手動で構成する必要があります。

次のコードを使用して RoleName フィールドを設定します。

const appInsights = require("applicationinsights");
appInsights.setup("<connection_string>");
appInsights.defaultClient.context.tags[appInsights.defaultClient.context.keys.cloudRole] = "MyRoleName";
appInsights.start();

ブラウザー SDK ローダー

構成によって、JavaScript (Web) SDK ローダー スクリプトの挿入を使用して、自動 Web インストルメンテーションをノード サーバーに対して有効にすることができます。

let appInsights = require("applicationinsights");
appInsights.setup("<connection_string>")
    .enableWebInstrumentation(true)
    .start();

または、環境変数 APPLICATIONINSIGHTS_WEB_INSTRUMENTATION_ENABLED = true を設定します。

Web インストルメンテーションは、次のすべての要件が満たされている場合、ノード サーバーの応答で有効になります。

• 応答に状態コード 200 が含まれている。
• 応答メソッドが GET である。
• サーバーの応答に Content-Type html が含まれている。
• サーバー応答に <head> と </head> の両方のタグが含まれている。
• 応答が圧縮されている場合は、Content-Encoding の種類が 1 つしか存在せず、エンコードの種類は gzip、br、deflate のいずれかである必要がある。
• 応答に現在およびバックアップの Web インストルメンテーション CDN エンドポイントが含まれていない。 (現在およびバックアップの Web インストルメンテーション CDN エンドポイントはここにあります)

Web インストルメンテーション CDN エンドポイントは、環境変数を APPLICATIONINSIGHTS_WEB_INSTRUMENTATION_SOURCE = "web Instrumentation CDN endpoints"設定することで変更できます。 Web インストルメンテーション接続文字列は、環境変数を設定することで変更できます APPLICATIONINSIGHTS_WEB_INSTRUMENTATION_CONNECTION_STRING = "web Instrumentation connection string"

自動サードパーティ インストルメンテーション

非同期呼び出し間でコンテキストを追跡するには、MongoDB や Redis などのサードパーティ製のライブラリでいくつかの変更が必要になります。 既定では、Application Insights は diagnostic-channel-publishers を使用して、これらのライブラリの一部をモンキーパッチにより修正します。 この機能は、APPLICATION_INSIGHTS_NO_DIAGNOSTIC_CHANNEL 環境変数を設定することによって無効にできます。

個々のモンキーパッチを無効にするには、APPLICATION_INSIGHTS_NO_PATCH_MODULES 環境変数に、無効にするパッケージをコンマ区切りリストで設定します。 たとえば、APPLICATION_INSIGHTS_NO_PATCH_MODULES=console,redis および console パッケージの修正プログラムの適用を回避するために redis を使用します。

現時点では、bunyan、console、mongodb、mongodb-core、mysql、redis、winston、pg、pg-pool の 9 つのパッケージがインストルメント化されています。 これらのパッケージのどのバージョンにパッチが適用されているかについては、「diagnostic-channel-publishers の README」を参照してください。

bunyan、winston、console のパッチにより、setAutoCollectConsole が有効になっているかどうかに基づいて Application Insights トレース イベントが生成されます。 残りにより、setAutoCollectDependencies が有効になっているかどうかに基づいて Application Insights 依存関係イベントが生成されます。

リアルタイムの指標

アプリから Azure へのライブ メトリックの送信を有効にするには、setSendLiveMetrics(true) を使用します。 現在、ポータルでのライブ メトリックのフィルター処理はサポートされていません。

拡張メトリック

アプリから Azure に拡張ネイティブ メトリックを送信できるようにするには、個別のネイティブ メトリック パッケージをインストールします。 SDK はインストールされると自動的に読み込まれ、Node.js ネイティブ メトリックの収集を開始します。

npm install applicationinsights-native-metrics

現在、ネイティブ メトリック パッケージでは、ガベージ コレクションの CPU 時間、イベント ループのティック、およびヒープの使用率の自動収集が実行されます。

• ガベージ コレクション:各種類のガベージコレクションに費やされた CPU 時間と、それぞれの種類の発生回数。
• イベント ループ:発生したティックの数と、合計で費やされた CPU 時間。
• ヒープと非ヒープ: アプリのメモリ使用量がヒープと非ヒープのどちらにあるか。

分散トレース モード

既定では、SDK は、Application Insights SDK でインストルメント化された他のアプリケーションやサービスによって認識されるヘッダーを送信します。 既存の AI ヘッダーに加えて、W3C トレース コンテキスト ヘッダーの送受信を有効にすることができます。 この方法では、既存のレガシ サービスとの相関関係を損ないません。 W3C ヘッダーを有効にすると、アプリは Application Insights でインストルメント化されていない他のサービスと関連付けることが可能になりますが、この W3C 標準が採用されます。

const appInsights = require("applicationinsights");
appInsights
  .setup("<your connection string>")
  .setDistributedTracingMode(appInsights.DistributedTracingModes.AI_AND_W3C)
  .start()

TelemetryClient API

TelemetryClient API の詳細な説明については、「カスタムのイベントとメトリックのための Application Insights API」を参照してください。

Node.js 用の Application Insights クライアント ライブラリを使って、任意の要求、イベント、メトリック、または例外を追跡できます。 次のコード サンプルで、使用できるいくつかの API を紹介します。

let appInsights = require("applicationinsights");
appInsights.setup().start(); // assuming connection string in env var. start() can be omitted to disable any non-custom data
let client = appInsights.defaultClient;
client.trackEvent({name: "my custom event", properties: {customProperty: "custom property value"}});
client.trackException({exception: new Error("handled exceptions can be logged with this method")});
client.trackMetric({name: "custom metric", value: 3});
client.trackTrace({message: "trace message"});
client.trackDependency({target:"http://dbname", name:"select customers proc", data:"SELECT * FROM Customers", duration:231, resultCode:0, success: true, dependencyTypeName: "ZSQL"});
client.trackRequest({name:"GET /customers", url:"http://myserver/customers", duration:309, resultCode:200, success:true});

let http = require("http");
http.createServer( (req, res) => {
  client.trackNodeHttpRequest({request: req, response: res}); // Place at the beginning of your request handler
});

依存関係を追跡する

依存関係を追跡するには、次のコードを使用します。

let appInsights = require("applicationinsights");
let client = new appInsights.TelemetryClient();

var success = false;
let startTime = Date.now();
// execute dependency call here....
let duration = Date.now() - startTime;
success = true;

client.trackDependency({target:"http://dbname", name:"select customers proc", data:"SELECT * FROM Customers", duration:duration, resultCode:0, success: true, dependencyTypeName: "ZSQL"});;

trackMetric を使用して、イベント ループのスケジュール設定にかかる時間を測定するユーティリティの例を次に示します。

function startMeasuringEventLoop() {
  var startTime = process.hrtime();
  var sampleSum = 0;
  var sampleCount = 0;

  // Measure event loop scheduling delay
  setInterval(() => {
    var elapsed = process.hrtime(startTime);
    startTime = process.hrtime();
    sampleSum += elapsed[0] * 1e9 + elapsed[1];
    sampleCount++;
  }, 0);

  // Report custom metric every second
  setInterval(() => {
    var samples = sampleSum;
    var count = sampleCount;
    sampleSum = 0;
    sampleCount = 0;

    if (count > 0) {
      var avgNs = samples / count;
      var avgMs = Math.round(avgNs / 1e6);
      client.trackMetric({name: "Event Loop Delay", value: avgMs});
    }
  }, 1000);
}

すべてのイベントにカスタム プロパティを追加する

すべてのイベントにカスタム プロパティを追加するには、次のコードを使用します。

appInsights.defaultClient.commonProperties = {
  environment: process.env.SOME_ENV_VARIABLE
};

HTTP GET 要求を追跡する

HTTP GET 要求を手動で追跡するには、次のコードを使用します。

appInsights.defaultClient.trackRequest({name:"GET /customers", url:"http://myserver/customers", duration:309, resultCode:200, success:true});

または、trackNodeHttpRequest メソッドを使用して要求を追跡することもできます。

var server = http.createServer((req, res) => {
  if ( req.method === "GET" ) {
      appInsights.defaultClient.trackNodeHttpRequest({request:req, response:res});
  }
  // other work here....
  res.end();
});

サーバーの起動時間を追跡する

サーバーの起動時間を追跡するには、次のコードを使用します。

let start = Date.now();
server.on("listening", () => {
  let duration = Date.now() - start;
  appInsights.defaultClient.trackMetric({name: "server startup time", value: duration});
});

フラッシュする

既定では、テレメトリは 15 秒間バッファリングされた後、インジェスト サーバーへ送信されます。 存続期間の短いアプリケーション (CLI ツールなど) の場合は、アプリケーションの終了時に、appInsights.defaultClient.flush() を使ってバッファリングされたテレメトリを手動でフラッシュすることが必要になる場合があります。

SDK はアプリケーションがクラッシュしたことを検知すると、appInsights.defaultClient.flush({ isAppCrashing: true }) を使ってフラッシュを呼び出します。 フラッシュ オプション (isAppCrashing) によって、アプリケーションが異常な状態であり、テレメトリ送信に適していないと見なされます。 代わりに、SDK はバッファリングしたすべてのテレメトリを永続ストレージに保存して、アプリケーションを終了させます。 アプリケーションは、再起動すると、永続ストレージに保存されたテレメトリを送信しようと試みます。

テレメトリのフィルター処理と前処理

SDK から送信される前に、テレメトリをフィルター処理、変更、または強化するコードを記述できます。 この処理には、HTTP 要求の収集や依存関係の収集など、標準のテレメトリ モジュールから送信されるデータが含まれます。

• フィルター処理 では、 ITelemetryProcessorを実装することで、SDK から送信される前にテレメトリを変更または破棄できます。 たとえば、ロボットからの要求を除外することで、テレメトリの量を減らすことができます。 サンプリングとは異なり、送信または破棄される内容を完全に制御できますが、集計されたログに基づくメトリックに影響します。 項目を破棄する方法によっては、関連する項目間を移動する機能が失われる場合もあります。

• ITelemetryInitializerを実装して、アプリから送信されたテレメトリにプロパティを追加または変更します。 たとえば、計算値やバージョン番号を追加して、ポータルでデータをフィルター処理できます。

• サンプリング により、統計情報に影響を与えずにテレメトリの量が減ります。 関連するデータ ポイントがまとめて保持されるため、問題を診断するときにそれらの間を移動できます。 ポータルでは、サンプリングを補正するために合計カウントが乗算されます。

フィルタリング

この手法を使用すると、テレメトリ ストリームに含まれるもの、またはテレメトリ ストリームから除外される内容を直接制御できます。 フィルター処理を使用して、テレメトリ項目が Application Insights に送信されないようにすることができます。 サンプリングでフィルター処理を使用することも、個別に使用することもできます。

テレメトリをフィルター処理するには、テレメトリ プロセッサを記述し、 TelemetryConfigurationに登録します。 すべてのテレメトリはプロセッサを通過します。 ストリームから削除するか、チェーン内の次のプロセッサに渡すかを選択できます。 HTTP 要求コレクターや依存関係コレクターなどの標準モジュールからのテレメトリと、自分で追跡したテレメトリが含まれます。 たとえば、ロボットからの要求や成功した依存関係呼び出しに関するテレメトリを除外できます。

ITelemetryProcessor と ITelemetryInitializer

テレメトリ プロセッサとテレメトリ初期化子の違いは何ですか?

• 実行できる操作には、いくつかの重複があります。 どちらもテレメトリのプロパティを追加または変更するために使用できますが、その目的には初期化子を使用することをお勧めします。
• テレメトリ初期化子は、テレメトリ プロセッサの前に常に実行されます。
• テレメトリ初期化子は、複数回呼び出される場合があります。 慣例により、既に設定されているプロパティは設定されません。
• テレメトリ プロセッサを使用すると、テレメトリ項目を完全に置き換えたり破棄したりすることができます。
• 登録されているすべてのテレメトリ初期化子は、すべてのテレメトリ項目に対して呼び出されます。 テレメトリ プロセッサの場合、SDK は最初のテレメトリ プロセッサの呼び出しを保証します。 残りのプロセッサが呼び出されるかどうかは、前述のテレメトリ プロセッサによって決定されます。
• テレメトリ初期化子を使用して、より多くのプロパティでテレメトリを強化するか、既存のプロパティをオーバーライドします。 テレメトリ プロセッサを使用してテレメトリを除外します。

プロパティの追加/変更

テレメトリ初期化子を使用して、テレメトリを追加情報で強化したり、標準のテレメトリ モジュールによって設定されたテレメトリ プロパティをオーバーライドしたりします。

たとえば、Web パッケージの Application Insights は、HTTP 要求に関するテレメトリを収集します。 既定では、応答コード > =400 で要求に失敗としてフラグを設定します。 代わりに 400 を成功として扱う場合は、成功プロパティを設定するテレメトリ初期化子を指定できます。

テレメトリ初期化子を指定すると、Track*() メソッドのいずれかが呼び出されるたびに呼び出されます。 この初期化子には、標準のテレメトリ モジュールによって呼び出される Track() メソッドが含まれています。 慣例により、これらのモジュールは初期化子によって既に設定されたプロパティを設定しません。 テレメトリ初期化子は、テレメトリ プロセッサを呼び出す前に呼び出されるため、初期化子によって実行されるエンリッチメントはプロセッサに表示されます。

テレメトリ プロセッサを使用したデータの前処理

"テレメトリ プロセッサ" を使って、収集されたデータを保持のために送信する前に、データ処理とフィルター処理を行うことができます。 テレメトリ プロセッサは、テレメトリ項目がクラウドに送信される前に、追加された順序で、1 つずつ呼び出されます。

public addTelemetryProcessor(telemetryProcessor: (envelope: Contracts.Envelope, context: { http.RequestOptions, http.ClientRequest, http.ClientResponse, correlationContext }) => boolean)

テレメトリ プロセッサが false を返した場合、そのテレメトリ項目は送信されません。

すべてのテレメトリ プロセッサは、検査と変更のために、テレメトリ データとそのエンベロープを受け取ります。 また、コンテキスト オブジェクトも受け取ります。 このオブジェクトの内容は、手動で追跡されたテレメトリの追跡メソッド呼び出し時に、contextObjects パラメーターによって定義されます。 自動収集されたテレメトリについては、このオブジェクトには、appInsights.getCorrelationContext() によって提供される、使用可能な要求情報と永続的な要求コンテンツが格納されます (依存関係の自動関連付けが有効になっている場合)。

テレメトリ プロセッサの TypeScript の種類は次のとおりです。

telemetryProcessor: (envelope: ContractsModule.Contracts.Envelope, context: { http.RequestOptions, http.ClientRequest, http.ClientResponse, correlationContext }) => boolean;

たとえば、スタック トレースのデータを例外から削除するプロセッサは、次のように記述、および追加できます。

function removeStackTraces ( envelope, context ) {
  if (envelope.data.baseType === "Microsoft.ApplicationInsights.ExceptionData") {
    var data = envelope.data.baseData;
    if (data.exceptions && data.exceptions.length > 0) {
      for (var i = 0; i < data.exceptions.length; i++) {
        var exception = data.exceptions[i];
        exception.parsedStack = null;
        exception.hasFullStack = false;
      }
    }
  }
  return true;
}

appInsights.defaultClient.addTelemetryProcessor(removeStackTraces);

クラウド ロール名とクラウド ロール インスタンスを追加する

直接コンテキスト タグを使用してクラウド ロール名を設定します。

var appInsights = require("applicationinsights");
appInsights.setup('INSTRUMENTATION_KEY').start();
appInsights.defaultClient.context.tags["ai.cloud.role"] = "your role name";
appInsights.defaultClient.context.tags["ai.cloud.roleInstance"] = "your role instance";

テレメトリ プロセッサを使用してクラウド ロール名を設定します。

var appInsights = require("applicationinsights");
appInsights.setup('INSTRUMENTATION_KEY').start();

appInsights.defaultClient.addTelemetryProcessor(envelope => {
    envelope.tags["ai.cloud.role"] = "your role name";
    envelope.tags["ai.cloud.roleInstance"] = "your role instance"
});

複数の接続文字列を使用する

複数の Application Insights リソースを作成し、それぞれの接続文字列を使って異なるデータを送信することができます。

次に例を示します。

let appInsights = require("applicationinsights");

// configure auto-collection under one connection string
appInsights.setup("Connection String A").start();

// track some events manually under another connection string
let otherClient = new appInsights.TelemetryClient("Connection String B");
otherClient.trackEvent({name: "my custom event"});

高度な構成オプション

クライアント オブジェクトには、高度なシナリオ用の多くのオプション設定を持つ config プロパティが含まれています。 これらを設定するには、次を使用します。

client.config.PROPERTYNAME = VALUE;

これらのプロパティはクライアント固有であるため、appInsights.defaultClient で作成されたクライアントとは別に new appInsights.TelemetryClient() を構成することができます。

カスタム イベントとメトリックのコア API

アプリケーションに数行のコードを挿入して、ユーザーが何をしているのかを調べるか、問題の診断に役立ちます。 デバイス アプリ、デスクトップ アプリ、Web クライアント、Web サーバーからテレメトリを送信できます。 Application Insights コア テレメトリ API を使用して、カスタム イベントとメトリック、および独自のバージョンの標準テレメトリを送信します。 この API は、標準の Application Insights データ コレクターが使用するのと同じ API です。

API の概要

コア API は、 GetMetric (.NET のみ) などのいくつかのバリエーションとは別に、すべてのプラットフォームで統一されています。

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

前提条件

Application Insights SDK に関する参照がまだない場合:

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

2. デバイスまたは Web サーバーのコードには、次のものが含まれます。

   • .NET
   • Node.js

   using Microsoft.ApplicationInsights;
   

TelemetryClient インスタンスを取得する

TelemetryClientのインスタンスを取得します。

private TelemetryClient telemetry = new TelemetryClient();

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

var telemetry = applicationInsights.defaultClient;

TrackEvent

Application Insights では、 カスタム イベント は 、メトリックス エクスプローラー で集計されたカウントとして、 および診断検索 で個別の出現回数として表示できるデータ ポイントです。 (MVC やその他のフレームワークの "イベント" には関連しません)。

コード TrackEvent 呼び出しを挿入して、さまざまなイベントをカウントします。 たとえば、ユーザーが特定の機能を選択する頻度を追跡できます。 または、特定の目標を達成する頻度や、特定の種類の間違いを犯す頻度を知りたい場合があります。

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

telemetry.TrackEvent("WinGame");

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

Log Analytics のカスタム イベント

テレメトリは、customEventsまたは使用状況エクスペリエンスの テーブルにあります。 イベントは、 trackEvent(..) または Click Analytics Autocollection プラグインから発生する可能性があります。

サンプリングが処理中の場合、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 回の測定に対する関心はほとんどありません。 代わりに、特定の期間中に発生した内容の概要が重要です。 このような概要は 、集計と呼ばれます。

  前の例では、その期間の集計メトリックの合計が 1 され、メトリック値の数が 2されています。 集計方法を使用する場合は、期間ごとに 1 回だけ TrackMetric を呼び出し、集計値を送信します。 この方法をお勧めします。Application Insights に送信するデータ ポイントの数を減らしてコストとパフォーマンスのオーバーヘッドを大幅に削減しながら、すべての関連情報を収集できるためです。

単一値の例

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

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

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

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

テレメトリは、customMetrics の テーブルで使用できます。 各行は、アプリ内の trackMetric(..) の呼び出しを表します。

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

ページ ビュー

デバイスまたは Web ページ アプリでは、各画面またはページが読み込まれると、ページ ビューテレメトリが既定で送信されます。 ただし、既定の設定を変更して、ページ ビューを追跡する時間を増やしたり、異なる時間に変更したりできます。 たとえば、タブまたはペインを表示するアプリでは、ユーザーが新しいウィンドウを開くたびにページを追跡できます。

ユーザーとセッションのデータは、ページ ビューと共にプロパティとして送信されるため、ページ ビューテレメトリがある場合は、ユーザーグラフとセッション グラフが有効になります。

カスタム ページ ビュー

telemetry.TrackPageView("GameReviewPage");

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

サーバー SDK では TrackRequest を使用して HTTP 要求をログに記録します。

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

要求テレメトリを送信する推奨される方法は、要求が 操作コンテキストとして機能する場所です。

操作コンテキスト

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

テレメトリを手動で追跡する場合、テレメトリの相関関係を確認する最も簡単な方法は、次のパターンを使用することです。

// Establish an operation context and associated telemetry item:
using (var operation = telemetryClient.StartOperation<RequestTelemetry>("operationName"))
{
    // Telemetry sent in here uses 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.

// Establish an operation context and associated telemetry item:
const operation = appInsights.startOperation(client, { name: "operationName" });

appInsights.wrapWithCorrelationContext(() => {
    // Telemetry sent in here uses the same operation ID.
    ...
    client.trackTrace({ message: "..." }); // or other track* calls
    ...

    // Set properties of containing telemetry item—for example:
    operation.telemetry.responseCode = "200";

    // Optional: explicitly send telemetry item:
    client.stopOperation(operation);

}, operation.context)(); // When callback completes, 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 に例外を送信する:

• それらをカウントすることは、問題の頻度を示す指標です。
• 個々の出現箇所を調べる。

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

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

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

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

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 に送信し、問題を診断します。 診断データのチャンクを送信し、 診断検索で検査できます。

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

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

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

メッセージの内容は検索できますが、プロパティ値とは異なり、フィルター処理することはできません。

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

メッセージに重大度レベルを追加することもできます。 また、他のテレメトリと同様に、プロパティ値を追加して、さまざまなトレース セットのフィルター処理や検索に役立ちます。 次に例を示します。

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

検索では、特定のデータベースに関連する特定の重大度レベルのすべてのメッセージを簡単に除外できます。

Log Analytics のトレース

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

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

TrackDependency

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

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

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 など、特定の依存関係呼び出しを自動的に検出して追跡する 依存関係モジュール が含まれています。 モジュールを動作させるには、サーバーにエージェントをインストールする必要があります。

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

C# で標準の依存関係追跡モジュールを無効にするには、 ApplicationInsights.config を編集し、 DependencyCollector.DependencyTrackingTelemetryModuleへの参照を削除します。

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

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

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

telemetry.flush();

認証済みユーザー

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

ユーザーがアプリにサインインした場合は、ブラウザー コードで認証されたユーザー ID を設定することで、より正確な数を取得できます。 ユーザーの実際のサインイン名を使用する必要はありません。 必要なのは、そのユーザーに固有の ID のみです。 スペースや ,;=|文字を含めることはできません。

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

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

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

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

プロパティを使用してデータをフィルター処理、検索、セグメント化する

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

プロパティ は、使用状況レポートでテレメトリをフィルター処理するために使用できる文字列値です。 たとえば、アプリで複数のゲームが提供されている場合は、各イベントにゲームの名前を添付して、どのゲームがより人気のあるかを確認できます。

文字列の長さには 8,192 という制限があります。 大量のデータを送信する場合は、 TrackTraceのメッセージ パラメーターを使用します。

メトリック は、グラフィカルに表示できる数値です。 たとえば、ゲーマーが達成するスコアが徐々に増加しているかどうかを確認できます。 グラフは、イベントと共に送信されるプロパティでセグメント化できるため、ゲームごとに個別のグラフまたは積み上げグラフを取得できます。

正しく表示するには、メトリック値が 0 以上である必要があります。

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

// 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);

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

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

より便利な場合は、別のオブジェクトでイベントのパラメーターを収集できます。

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キャストする必要があります。
• サンプリングの可能性を考慮するには、sum(itemCount)しないcount()使用します。

タイミングイベント

アクションの実行にかかる時間をグラフに表示したい場合があります。 たとえば、ユーザーがゲーム内の選択肢を検討するのにかかる時間を知りたい場合があります。 この情報を取得するには、測定パラメーターを使用します。

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

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

書き込む一部のカスタム イベントの既定のプロパティ値を設定する場合は、 TelemetryClient インスタンスで設定します。 これらは、そのクライアントから送信されるすべてのテレメトリ項目にアタッチされます。

using Microsoft.ApplicationInsights.DataContracts;

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

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

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

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

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

遠隔測定を無効にする

テレメトリの収集と送信を 動的に停止して開始 するには:

using  Microsoft.ApplicationInsights.Extensibility;

TelemetryConfiguration.Active.DisableTelemetry = true;

telemetry.config.disableAppInsights = true;

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

開発者モード

デバッグ中に、結果をすぐに確認できるように、パイプラインを通じてテレメトリを迅速化すると便利です。 また、テレメトリに関する問題を追跡するのに役立つ他のメッセージも表示されます。 アプリの速度が低下する可能性があるため、運用環境でオフにします。

TelemetryConfiguration.Active.TelemetryChannel.DeveloperMode = true;

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

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

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

動的接続文字列

開発、テスト、運用環境からのテレメトリの混在を回避するために、環境に応じて 個別の Application Insights リソースを作成 し、そのキーを変更できます。

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

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

TelemetryContext

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

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

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

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

Limits

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

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

データ レート制限に達しないようにするには、サンプリングを使用 します。

データの保持期間を確認するには、「 データの保持とプライバシー」を参照してください。

トラブルシューティング

"データなし" のシナリオやログのカスタマイズなどのトラブルシューティング情報については、「Node.js アプリとサービスの Application Insights の監視のトラブルシューティング」を参照してください。

次のステップ

• よく寄せられる質問 (FAQ) を確認するには、次を参照してください。
  • Node.js FAQ
  • カスタム イベントとメトリックの Application Insights API に関する FAQ
• ポータルでテレメトリを監視します。
• Log Analytics を使用し、テレメトリに対して分析クエリを記述する方法について説明します。