カスタムのイベントとメトリックのための Application Insights APIApplication Insights API for custom events and metrics

アプリケーションに数行のコードを挿入して、ユーザーの行動を調べたり、問題の診断に役立つ情報を取得したりすることができます。Insert a few lines of code in your application to find out what users are doing with it, or to help diagnose issues. デバイスとデスクトップ アプリケーション、Web クライアント、Web サーバーからテレメトリを送信できます。You can send telemetry from device and desktop apps, web clients, and web servers. Azure Application Insights コア テレメトリ API を使用すると、カスタムのイベントやメトリック、独自バージョンの標準テレメトリを送信できます。Use the Azure Application Insights core telemetry API to send custom events and metrics, and your own versions of standard telemetry. この API は、Application Insights の標準のデータ コレクターで使用される API と同じものです。This API is the same API that the standard Application Insights data collectors use.

注意

TrackMetric() は、.NET ベースのアプリケーションのためにカスタム メトリックを送信する場合に推奨される方法ではなくなりました。TrackMetric() is no longer the preferred method of sending custom metrics for your .NET based applications. Application Insights .NET SDK のバージョン 2.60 beta 3 で、新しいメソッドの TelemetryClient.GetMetric() が導入されました。In version 2.60-beta 3 of the Application Insights .NET SDK a new method, TelemetryClient.GetMetric() was introduced. Application Insights .NET SDK バージョン 2.72 の時点で、この機能は安定したリリースの一部になりました。As of the Application Insights .NET SDK version 2.72 this functionality is now part of the stable release.

API の概要API summary

コア API は、GetMetric (.NET のみ) のようないくつかの違いは別として、すべてのプラットフォームにわたって同一です。The core API is uniform across all platforms, apart from a few variations like GetMetric(.NET only).

方法Method 使用対象Used for
TrackPageView ページ、画面、ブレード、フォームPages, screens, blades, or forms.
TrackEvent ユーザー アクションとその他のイベント。User actions and other events. ユーザーの行動を追跡するために、またはパフォーマンスを監視するために使用されます。Used to track user behavior or to monitor performance.
GetMetric 0 と多次元メトリックは、は、C# の場合のみ、一元的に構成された集計です。Zero and multi-dimensional metrics, centrally configured aggregation, C# only.
TrackMetric キューの長さなど、特定のイベントに関連しないパフォーマンスを測定します。Performance measurements such as queue lengths not related to specific events.
TrackException 診断用に例外を記録します。Logging exceptions for diagnosis. 他のイベントとの関連で例外の発生箇所を追跡し、スタック トレースを調べます。Trace where they occur in relation to other events and examine stack traces.
TrackRequest パフォーマンス分析用にサーバー要求の頻度と期間を記録します。Logging the frequency and duration of server requests for performance analysis.
TrackTrace メッセージを記録し、診断に利用します。Diagnostic log messages. サードパーティのログをキャプチャすることもできます。You can also capture third-party logs.
TrackDependency アプリが依存する外部コンポーネントへの呼び出しの実行時間と頻度を記録します。Logging the duration and frequency of calls to external components that your app depends on.

これらのテレメトリの呼び出しのほとんどに プロパティとメトリックをアタッチ できます。You can attach properties and metrics to most of these telemetry calls.

開始する前にBefore you start

Application Insights SDK の参照がまだない場合:If you don't have a reference on Application Insights SDK yet:

TelemetryClient インスタンスの取得Get a TelemetryClient instance

TelemetryClient インスタンスを取得します (Web ページの JavaScript を除く)。Get an instance of TelemetryClient (except in JavaScript in webpages):

C#C#

private TelemetryClient telemetry = new TelemetryClient();

Visual BasicVisual Basic

Private Dim telemetry As New TelemetryClient

JavaJava

private TelemetryClient telemetry = new TelemetryClient();

Node.jsNode.js

var telemetry = applicationInsights.defaultClient;

TelemetryClient はスレッド セーフです。TelemetryClient is thread-safe.

ASP.NET および Java プロジェクトの場合は、受信 HTTP 要求が自動的にキャプチャされます。For ASP.NET and Java projects, incoming HTTP Requests are automatically captured. アプリの他のモジュールのために TelemetryClient の追加のインスタンスを作成することもできます。You might want to create additional instances of TelemetryClient for other module of your app. たとえば、ミドルウェア クラスでビジネス ロジック イベントを報告する 1 つの TelemetryClient インスタンスを使用できます。For instance, you may have one TelemetryClient instance in your middleware class to report business logic events. マシンを識別するために UserId や DeviceId などのプロパティを設定できます。You can set properties such as UserId and DeviceId to identify the machine. こうした情報は、インスタンスから送信されるすべてのイベントに付属します。This information is attached to all events that the instance sends.

C#C#

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

JavaJava

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

Node.js のプロジェクトでは、new applicationInsights.TelemetryClient(instrumentationKey?) を使用して新しいインスタンスを作成できますが、シングルトン defaultClient から分離された構成を必要とするシナリオにのみ推奨されます。In Node.js projects, you can use new applicationInsights.TelemetryClient(instrumentationKey?) to create a new instance, but this is recommended only for scenarios that require isolated configuration from the singleton defaultClient.

TrackEventTrackEvent

Application Insights のカスタム イベントはデータ ポイントであり、メトリックス エクスプローラーでは集計カウントとして、診断検索では個々の発生として表示できます。In Application Insights, a custom event is a data point that you can display in Metrics Explorer as an aggregated count, and in Diagnostic Search as individual occurrences. (これは MVC にも他のフレームワークの "イベント" にも関連していません)。(It isn't related to MVC or other framework "events.")

さまざまなイベントをカウントするために、TrackEvent 呼び出しを挿入します。Insert TrackEvent calls in your code to count various events. これによって、ユーザーが特定の機能を使用する頻度や、特定の目標を達成する頻度、特定の種類の間違いを起こす頻度をカウントできます。How often users choose a particular feature, how often they achieve particular goals, or maybe how often they make particular types of mistakes.

たとえば、ゲーム アプリで、ユーザーが勝利したときにイベントを送信します。For example, in a game app, send an event whenever a user wins the game:

JavaScriptJavaScript

appInsights.trackEvent("WinGame");

C#C#

telemetry.TrackEvent("WinGame");

Visual BasicVisual Basic

telemetry.TrackEvent("WinGame")

JavaJava

telemetry.trackEvent("WinGame");

Node.jsNode.js

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

Analytics でのカスタム イベントCustom events in Analytics

テレメトリは、Application Insights AnalyticscustomEvents テーブルにあります。The telemetry is available in the customEvents table in Application Insights Analytics. 各行は、アプリでの trackEvent(..) に対する呼び出しを表します。Each row represents a call to trackEvent(..) in your app.

サンプリングが実行中の場合は、itemCount プロパティは 1 より大きい値を示します。If sampling is in operation, the itemCount property shows a value greater than 1. たとえば itemCount==10 は trackEvent() への 10 回の呼び出しで、サンプリング プロセスはそれらのうちの 1 つだけを転送したことを意味します。For example itemCount==10 means that of 10 calls to trackEvent(), the sampling process only transmitted one of them. カスタム イベントの正しい数を取得するには、customEvent | summarize sum(itemCount) などのコードを使用する必要があります。To get a correct count of custom events, you should use therefore use code such as customEvent | summarize sum(itemCount).

GetMetricGetMetric

Examples

C#C#

#pragma warning disable CA1716  // Namespace naming

namespace User.Namespace.Example01
{
    using System;
    using Microsoft.ApplicationInsights;
    using TraceSeveretyLevel = Microsoft.ApplicationInsights.DataContracts.SeverityLevel;

    /// <summary>
    /// Most simple cases are one-liners.
    /// This is all possible without even importing an additional namespace.
    /// </summary>

    public class Sample01
    {
        /// <summary />
        public static void Exec()
        {
            // *** SENDING METRICS ***

            // Recall how you send custom telemetry with Application Insights in other cases, e.g. Events.
            // The following will result in an EventTelemetry object to be sent to the cloud right away.
            TelemetryClient client = new TelemetryClient();
            client.TrackEvent("SomethingInterestingHappened");

            // Metrics work very similar. However, the value is not sent right away.
            // It is aggregated with other values for the same metric, and the resulting summary (aka "aggregate" is sent automatically every minute.
            // To mark this difference, we use a pattern that is similar, but different from the established TrackXxx(..) pattern that sends telemetry right away:

            client.GetMetric("CowsSold").TrackValue(42);

            // *** MULTI-DIMENSIONAL METRICS ***

            // The above example shows a zero-dimensional metric.
            // Metrics can also be multi-dimensional.
            // In the initial version we are supporting up to 2 dimensions, and we will add support for more in the future as needed.
            // Here is an example for a one-dimensional metric:

            Metric animalsSold = client.GetMetric("AnimalsSold", "Species");

            animalsSold.TrackValue(42, "Pigs");
            animalsSold.TrackValue(24, "Horses");

            // The values for Pigs and Horses will be aggregated separately from each other and will result in two distinct aggregates.
            // You can control the maximum number of number data series per metric (and thus your resource usage and cost).
            // The default limits are no more than 1000 total data series per metric, and no more than 100 different values per dimension.
            // We discuss elsewhere how to change them.
            // We use a common .Net pattern: TryXxx(..) to make sure that the limits are observed.
            // If the limits are already reached, Metric.TrackValue(..) will return False and the value will not be tracked. Otherwise it will return True.
            // This is particularly useful if the data for a metric originates from user input, e.g. a file:

            Tuple<int, string> countAndSpecies = ReadSpeciesFromUserInput();
            int count = countAndSpecies.Item1;
            string species = countAndSpecies.Item2;

            if (!animalsSold.TrackValue(count, species))

            {
                client.TrackTrace($"Data series or dimension cap was reached for metric {animalsSold.Identifier.MetricId}.", TraceSeveretyLevel.Error);
            }

            // You can inspect a metric object to reason about its current state. For example:
            int currentNumberOfSpecies = animalsSold.GetDimensionValues(1).Count;
        }

        private static void ResetDataStructure()
        {
            // Do stuff
        }

        private static Tuple<int, string> ReadSpeciesFromUserInput()
        {
            return Tuple.Create(18, "Cows");
        }

        private static int AddItemsToDataStructure()
        {
            // Do stuff
            return 5;
        }
    }
}

TrackMetricTrackMetric

注意

Microsoft.ApplicationInsights.TelemetryClient.TrackMetric は、.NET SDK では非推奨です。Microsoft.ApplicationInsights.TelemetryClient.TrackMetric is deprecated in the .NET SDK. メトリックは送信される前に必ず、ある期間にわたって事前に集計される必要があります。Metrics should always be pre-aggregated across a time period before being sent. GetMetric(..) オーバーロードのいずれかを使用して、SDK の事前集計機能にアクセスするためのメトリック オブジェクトを取得します。Use one of the GetMetric(..) overloads to get a metric object for accessing SDK pre-aggregation capabilities. 独自の事前集計ロジックを実装する場合は、Track(ITelemetry metricTelemetry) メソッドを使用して集計結果を送信できます。If you are implementing your own pre-aggregation logic, you can use the Track(ITelemetry metricTelemetry) method to send the resulting aggregates. アプリケーションで、一定時間にわたる集計を行わず、すべての機会に個別のテレメトリ項目を送信する必要がある場合は、おそらくイベント テレメトリのユース ケースに該当します。TelemetryClient.TrackEvent (Microsoft.Applicationlnsights.DataContracts.EventTelemetry) を参照してください。If your application requires sending a separate telemetry item at every occasion without aggregation across time, you likely have a use case for event telemetry; see TelemetryClient.TrackEvent (Microsoft.Applicationlnsights.DataContracts.EventTelemetry).

Application Insights では、特定のイベントに関連付けられていないメトリックをグラフ化できます。Application Insights can chart metrics that are not attached to particular events. たとえば、一定の間隔でキューの長さを監視できます。For example, you could monitor a queue length at regular intervals. メトリックでは、個々の測定値は変化と傾向よりも関心が薄いため、統計グラフが役に立ちます。With metrics, the individual measurements are of less interest than the variations and trends, and so statistical charts are useful.

Application Insights にメトリックを送信するために、TrackMetric(..) API を使用できます。In order to send metrics to Application Insights, you can use the TrackMetric(..) API. メトリックを送信するには、次の 2 つの方法があります。There are two ways to send a metric:

  • 単一の値。Single value. アプリケーションで、測定を実行するたびに、対応する値を Application Insights に送信します。Every time you perform a measurement in your application, you send the corresponding value to Application Insights. たとえば、コンテナー内の項目数を記述するメトリックがあるとします。For example, assume that you have a metric describing the number of items in a container. 特定の期間に、まずコンテナーに 3 つの項目を配置し、次に 2 つの項目を削除します。During a particular time period, you first put three items into the container and then you remove two items. したがって、TrackMetric を 2 回呼び出します。最初に値 3 を渡して、次に値 -2 を渡します。Accordingly, you would call TrackMetric twice: first passing the value 3 and then the value -2. Application Insights は、両方の値を自動的に格納します。Application Insights stores both values on your behalf.

  • 集計。Aggregation. メトリックを使用する場合、個々の測定値はあまり重要ではありません。When working with metrics, every single measurement is rarely of interest. 代わりに特定の期間に、発生したことの概要が重要です。Instead a summary of what happened during a particular time period is important. このような概要は_集計_と呼ばれます。Such a summary is called aggregation. 上記の例で、その期間の集計メトリックの合計は 1 で、メトリック値のカウントは 2 です。In the above example, the aggregate metric sum for that time period is 1 and the count of the metric values is 2. 集計アプローチを使用する場合、期間ごとに TrackMetric を 1 回だけ呼び出し、集計値を送信します。When using the aggregation approach, you only invoke TrackMetric once per time period and send the aggregate values. これは、すべての関連情報を収集しながら、Application Insights に送信するデータ ポイントを少なくすることによって、コストとパフォーマンスのオーバーヘッドを大幅に削減できるため、推奨される方法です。This is the recommended approach since it can significantly reduce the cost and performance overhead by sending fewer data points to Application Insights, while still collecting all relevant information.

Examples

単一の値Single values

1 つのメトリック値を送信するには:To send a single metric value:

JavaScriptJavaScript

appInsights.trackMetric("queueLength", 42.0);

C#C#

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

JavaJava

telemetry.trackMetric("queueLength", 42.0);

Node.jsNode.js

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

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

テレメトリは、Application Insights AnalyticscustomMetrics テーブルにあります。The telemetry is available in the customMetrics table in Application Insights Analytics. 各行は、アプリでの trackMetric(..) に対する呼び出しを表します。Each row represents a call to trackMetric(..) in your app.

  • valueSum: これは測定値の合計です。valueSum - This is the sum of the measurements. 平均値を取得するには、valueCount で除算します。To get the mean value, divide by valueCount.
  • valueCount: この trackMetric(..) 呼び出しで集計された測定値の数。valueCount - The number of measurements that were aggregated into this trackMetric(..) call.

ページ ビューPage views

デバイスまたは Web ページ アプリケーションでは、各画面または各ページが読み込まれた場合既定でページ ビュー テレメトリが送信されます。In a device or webpage app, page view telemetry is sent by default when each screen or page is loaded. ただし、これを変更し、ページ ビューを追跡する回数を増やしたり、変えたりできます。But you can change that to track page views at additional or different times. たとえば、タブまたはブレードを表示するアプリケーションで、ユーザーが新しいブレードを開いたときに常にページを追跡できます。For example, in an app that displays tabs or blades, you might want to track a page whenever the user opens a new blade.

ユーザーとセッションのデータはページ ビューとともにプロパティとして送信されます。そのため、ページ ビューのテレメトリがあれば、ユーザーとセッションのグラフがアクティブになります。User and session data is sent as properties along with page views, so the user and session charts come alive when there is page view telemetry.

カスタム ページ ビューCustom page views

JavaScriptJavaScript

appInsights.trackPageView("tab1");

C#C#

telemetry.TrackPageView("GameReviewPage");

Visual BasicVisual Basic

telemetry.TrackPageView("GameReviewPage")

JavaJava

telemetry.trackPageView("GameReviewPage");

別々の HTML ページ内で複数のタブを使用している場合、URL を指定することもできます。If you have several tabs within different HTML pages, you can specify the URL too:

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

ページ ビューのタイミングTiming page views

既定では、ページ ビューの読み込み時間として報告される時間は、ブラウザーが要求を送信した時点からブラウザーのページ読み込みイベントが呼び出されるまで測定されます。By default, the times reported as Page view load time are measured from when the browser sends the request, until the browser's page load event is called.

代わりに、次のいずれかを行うことができます。Instead, you can either:

  • trackPageView の呼び出し appInsights.trackPageView("tab1", null, null, null, durationInMilliseconds); で明示的な時間を設定する。Set an explicit duration in the trackPageView call: appInsights.trackPageView("tab1", null, null, null, durationInMilliseconds);.
  • ページ ビューのタイミングの呼び出し (startTrackPagestopTrackPage) を使用する。Use the page view timing calls startTrackPage and stopTrackPage.

JavaScriptJavaScript

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

...

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

1 番目のパラメーターとして使用する名前により、開始呼び出しと停止呼び出しを関連付けます。The name that you use as the first parameter associates the start and stop calls. 既定値は現在のページ名です。It defaults to the current page name.

メトリックス エクスプローラーに結果として表示されるページ読み込み時間は、開始呼び出しと停止呼び出しの時間間隔から求められます。The resulting page load durations displayed in Metrics Explorer are derived from the interval between the start and stop calls. 実際の時間間隔はユーザーが決定します。It's up to you what interval you actually time.

Analytics でのページ テレメトリPage telemetry in Analytics

Analytics では、2 つのテーブルに、ブラウザー操作からのデータが表示されます。In Analytics two tables show data from browser operations:

  • pageViews テーブルには、URL とページ タイトルに関するデータが含まれます。The pageViews table contains data about the URL and page title
  • browserTimings テーブルには、受信データの処理にかかった時間などのクライアントのパフォーマンスに関するデータが含まれます。The browserTimings table contains data about client performance, such as the time taken to process the incoming data

ブラウザーでさまざまなページの処理にかかる時間を知るには、次のようにします。To find how long the browser takes to process different pages:

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

さまざまなブラウザーの人気度を検出するには、次のようにします。To discover the popularities of different browsers:

pageViews
| summarize count() by client_Browser

AJAX 呼び出しにページ ビューを関連付けるには、依存関係によって結合します。To associate page views to AJAX calls, join with dependencies:

pageViews
| join (dependencies) on operation_Id 

TrackRequestTrackRequest

サーバー SDK では、TrackRequest を使用して HTTP 要求が記録されます。The server SDK uses TrackRequest to log HTTP requests.

Web サービス モジュールが実行されていない状況で要求をシミュレーションする場合に、これを自分で呼び出すこともできます。You can also call it yourself if you want to simulate requests in a context where you don't have the web service module running.

ただし、要求テレメトリを送信するための推奨される方法は、要求が操作コンテキストとして機能しているところです。However, the recommended way to send request telemetry is where the request acts as an operation context.

操作コンテキストOperation context

テレメトリ項目を操作コンテキストと関連付けることで、それらの項目を互いに相関させることができます。You can correlate telemetry items together by associating them with operation context. 標準の要求追跡モジュールでは、HTTP 要求の処理中に送信される例外や他のイベントに対してこの関連付けが行われます。The standard request-tracking module does this for exceptions and other events that are sent while an HTTP request is being processed. Search および Analytics では、操作 ID を使用して、要求に関連付けられたイベントを簡単に見つけることができます。In Search and Analytics, you can easily find any events associated with the request using its operation Id.

相関の詳細については、「Application Insights におけるテレメトリの相関付け」を参照してください。See Telemetry correlation in Application Insights for more details on correlation.

手動でテレメトリを追跡している場合、テレメトリの相関付けを確実に行うための最も簡単な方法として、次のパターンを使用できます。When tracking telemetry manually, the easiest way to ensure telemetry correlation by using this pattern:

C#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 で作成します。Along with setting an operation context, StartOperation creates a telemetry item of the type that you specify. テレメトリ項目は、操作を破棄するか StopOperation を明示的に呼び出すと送信されます。It sends the telemetry item when you dispose the operation, or if you explicitly call StopOperation. テレメトリの種類として RequestTelemetry を使用する場合、その継続時間は開始から停止までの間の一定の間隔に設定されます。If you use RequestTelemetry as the telemetry type, its duration is set to the timed interval between start and stop.

操作のスコープ内にあるテレメトリ項目は、その操作の「子」になります。Telemetry items reported within a scope of operation become 'children' of such operation. 操作コンテキストは入れ子にできます。Operation contexts could be nested.

検索では、操作コンテキストを使用して関連項目の一覧が作成されます。In Search, the operation context is used to create the Related Items list:

関連項目

カスタム操作の追跡の詳細については、「Application Insights .NET SDK でカスタム操作を追跡する」をご覧ください。See Track custom operations with Application Insights .NET SDK for more information on custom operations tracking.

Analytics での要求Requests in Analytics

Application Insights Analytics で、要求は requests テーブルに表示されます。In Application Insights Analytics, requests show up in the requests table.

サンプリング を操作中の場合は、itemCount プロパティに 1 より大きい値が表示されます。If sampling is in operation, the itemCount property will show a value greater than 1. たとえば itemCount==10 は trackRequest() への 10 回の呼び出しで、サンプリング プロセスはそれらのうちの 1 つだけを転送したことを意味します。For example itemCount==10 means that of 10 calls to trackRequest(), the sampling process only transmitted one of them. 要求の正しい数と要求名別にセグメント化された平均所要時間を取得するには、次のようなコードを使用します。To get a correct count of requests and average duration segmented by request names, use code such as:

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

TrackExceptionTrackException

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

レポートにはスタック トレースが含まれます。The reports include the stack traces.

C#C#

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

JavaJava

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

JavaScriptJavaScript

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

Node.jsNode.js

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

SDK が多数の例外を自動的にキャッチするため、常に TrackException を明示的に呼び出す必要はありません。The SDKs catch many exceptions automatically, so you don't always have to call TrackException explicitly.

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

Analyticsでの例外Exceptions in Analytics

Application Insights Analytics で、例外は exceptions テーブルに表示されます。In Application Insights Analytics, exceptions show up in the exceptions table.

サンプリングが実行中の場合は、itemCount プロパティは 1 より大きい値を示します。If sampling is in operation, the itemCount property shows a value greater than 1. たとえば itemCount==10 は trackException() への 10 回の呼び出しで、サンプリング プロセスはそれらのうちの 1 つだけを転送したことを意味します。For example itemCount==10 means that of 10 calls to trackException(), the sampling process only transmitted one of them. 例外の種類別にセグメント化された例外の正しい数を取得するには、次のようなコードを使用します。To get a correct count of exceptions segmented by type of exception, use code such as:

exceptions
| summarize sum(itemCount) by type

重要なスタック情報の大部分は既に個別の変数に抽出されていますが、details 構造を分析してさらに詳細な情報を取得できます。Most of the important stack information is already extracted into separate variables, but you can pull apart the details structure to get more. この構造は動的なので、期待する型に結果をキャストする必要があります。Since this structure is dynamic, you should cast the result to the type you expect. 例: For example:

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

例外を関連する要求に関連付けるには、結合を使用します。To associate exceptions with their related requests, use a join:

exceptions
| join (requests) on operation_Id

TrackTraceTrackTrace

TrackTrace を使用すると、Application Insights に "階層リンクの追跡" を送信して問題を診断できます。Use TrackTrace to help diagnose problems by sending a "breadcrumb trail" to Application Insights. 診断データのチャンクを送信し、診断検索で検査できます。You can send chunks of diagnostic data and inspect them in Diagnostic Search.

.NET ログ アダプターでは、この API を使用してポータルにサードパーティのログを送信します。In .NET Log adapters use this API to send third-party logs to the portal.

Java の Log4J や Logback などの標準ロガーでは、Application Insights Log4j または Logback アペンダーを使用してポータルにサードパーティのログを送信します。In Java for Standard loggers like Log4J, Logback use Application Insights Log4j or Logback Appenders to send third-party logs to the portal.

C#C#

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

JavaJava

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

Node.jsNode.js

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

メッセージ コンテンツで検索できますが、(プロパティ値とは異なり) フィルター処理はできません。You can search on message content, but (unlike property values) you can't filter on it.

message のサイズ制限は、プロパティの制限よりも非常に高くなっています。The size limit on message is much higher than the limit on properties. TrackTrace の利点は、比較的長いデータをメッセージの中に配置できることです。An advantage of TrackTrace is that you can put relatively long data in the message. たとえば、メッセージ中で POST データをエンコードできます。For example, you can encode POST data there.

加えて、メッセージに重大度レベルを追加することができます。In addition, you can add a severity level to your message. また他のテレメトリと同様、プロパティ値を追加することで、さまざまなトレースの組み合わせをフィルタリングしたり検索したりすることができます。And, like other telemetry, you can add property values to help you filter or search for different sets of traces. 例: For example:

C#C#

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

JavaJava

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

この後に Search で、特定のデータベースに関連し特定の重大度レベルを持つすべてのメッセージを簡単に抽出することができます。In Search, you can then easily filter out all the messages of a particular severity level that relate to a particular database.

Analytics でのトレースTraces in Analytics

Application Insights Analytics で、TrackTrace への呼び出しは traces テーブルに表示されます。In Application Insights Analytics, calls to TrackTrace show up in the traces table.

サンプリングが実行中の場合は、itemCount プロパティは 1 より大きい値を示します。If sampling is in operation, the itemCount property shows a value greater than 1. たとえば、itemCount==10 は、サンプリング プロセスで転送されたのは trackTrace() への 10 回の呼び出しのうち 1 回だけであることを意味します。For example itemCount==10 means that of 10 calls to trackTrace(), the sampling process only transmitted one of them. トレース呼び出しの正確な数を取得するには、traces | summarize sum(itemCount) などのコードを使用する必要があります。To get a correct count of trace calls, you should use therefore code such as traces | summarize sum(itemCount).

TrackDependencyTrackDependency

応答時間と外部コードの呼び出しの成功率を追跡するには、TrackDependency 呼び出しを使用します。Use the TrackDependency call to track the response times and success rates of calls to an external piece of code. 結果は、ポータルの依存関係グラフに表示されます。The results appear in the dependency charts in the portal.

C#C#

var success = false;
var startTime = DateTime.UtcNow;
var timer = System.Diagnostics.Stopwatch.StartNew();
try
{
    success = dependency.Call();
}
finally
{
    timer.Stop();
    telemetry.TrackDependency("myDependency", "myCall", startTime, timer.Elapsed, success);
     // The call above has been made obsolete in the latest SDK. The updated call follows this format:
     // TrackDependency (string dependencyTypeName, string dependencyName, string data, DateTimeOffset startTime, TimeSpan duration, bool success);
}

JavaJava

boolean success = false;
long startTime = System.currentTimeMillis();
try {
    success = dependency.call();
}
finally {
    long endTime = System.currentTimeMillis();
    long delta = endTime - startTime;
    RemoteDependencyTelemetry dependencyTelemetry = new RemoteDependencyTelemetry("My Dependency", "myCall", delta, success);
    telemetry.setTimeStamp(startTime);
    telemetry.trackDependency(dependencyTelemetry);
}

JavaScriptJavaScript

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 などに対する依存関係の呼び出しを自動的に検出して追跡する依存関係モジュールが含まれています。Remember that the server SDKs include a dependency module that discovers and tracks certain dependency calls automatically--for example, to databases and REST APIs. このモジュールを機能させるには、サーバーにエージェントをインストールする必要があります。You have to install an agent on your server to make the module work.

Java では、Java エージェントを使用して、特定の依存関係呼び出しを自動的に追跡できます。In Java, certain dependency calls can be automatically tracked using Java Agent.

この呼び出しは、自動追跡ではキャッチされない呼び出しを追跡する場合、またはエージェントをインストールしない場合に使用します。You use this call if you want to track calls that the automated tracking doesn't catch, or if you don't want to install the agent.

C# の標準の依存関係追跡モジュールを無効にするには、ApplicationInsights.config を編集し、DependencyCollector.DependencyTrackingTelemetryModule への参照を削除します。To turn off the standard dependency-tracking module in C#, edit ApplicationInsights.config and delete the reference to DependencyCollector.DependencyTrackingTelemetryModule. Java では、標準の依存関係を自動的に収集したくない場合は Java エージェントをインストールしないでください。In Java, please do not install java agent if you do not want to collect standard dependencies automatically.

Analytics での依存関係Dependencies in Analytics

Application Insights Analytics で、trackDependency 呼び出しは dependencies テーブルに表示されます。In Application Insights Analytics, trackDependency calls show up in the dependencies table.

サンプリングが実行中の場合は、itemCount プロパティは 1 より大きい値を示します。If sampling is in operation, the itemCount property shows a value greater than 1. たとえば itemCount==10 は trackDependency() への 10 回の呼び出しで、サンプリング プロセスはそれらのうちの 1 つだけを転送したことを意味します。For example itemCount==10 means that of 10 calls to trackDependency(), the sampling process only transmitted one of them. ターゲット コンポーネント別にセグメント化された依存関係の正しい数を取得するには、次のようなコードを使用します。To get a correct count of dependencies segmented by target component, use code such as:

dependencies
| summarize sum(itemCount) by target

依存関係を関連する要求に関連付けるには、結合を使用します。To associate dependencies with their related requests, use a join:

dependencies
| join (requests) on operation_Id

データのフラッシュFlushing data

通常、SDK は、ユーザーへの影響を最小限に抑えるために選択した時間帯にデータを送信します。Normally, the SDK sends data at times chosen to minimize the impact on the user. ただし、終了するアプリケーションで SDK を使用する場合などには、バッファーのフラッシュが必要になることがあります。However, in some cases, you might want to flush the buffer--for example, if you are using the SDK in an application that shuts down.

C#C#

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

JavaJava

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

Node.jsNode.js

telemetry.flush();

サーバー テレメトリ チャネルの場合、この関数は非同期であることに注意してください。Note that the function is asynchronous for the server telemetry channel.

理想的には、アプリケーションのシャットダウン アクティビティで flush() メソッドを使用する必要があります。Ideally, flush() method should be used in the shutdown activity of the Application.

認証されたユーザーAuthenticated users

Web アプリでは、ユーザーは (既定では) Cookie により識別されます。In a web app, users are (by default) identified by cookies. ユーザーは、別のコンピューターまたはブラウザーからアプリにアクセスしたり、Cookie を削除した場合、複数回カウントされることがあります。A user might be counted more than once if they access your app from a different machine or browser, or if they delete cookies.

ユーザーがアプリにサインインしていれば、認証されたユーザーの ID をブラウザー コードに設定して、より正確な数値を取得できます。If users sign in to your app, you can get a more accurate count by setting the authenticated user ID in the browser code:

JavaScriptJavaScript

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

ASP.NET Web MVC アプリケーションでの例:In an ASP.NET web MVC application, for example:

RazorRazor

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

ユーザーの実際のサインイン名を使用する必要はありません。It isn't necessary to use the user's actual sign-in name. 必要なのは、そのユーザーに一意の ID であるということだけです。It only has to be an ID that is unique to that user. ID には、スペースや ,;=| を含めることはできません。It must not include spaces or any of the characters ,;=|.

ユーザー ID はセッション Cookie にも設定され、サーバーに送信されます。The user ID is also set in a session cookie and sent to the server. サーバー SDK がインストールされている場合、認証されたユーザー ID は、クライアントおよびサーバー テレメトリの両方のコンテキスト プロパティの一部として送信されます。If the server SDK is installed, the authenticated user ID is sent as part of the context properties of both client and server telemetry. 送信後、フィルター処理や検索を行うことができます。You can then filter and search on it.

アカウントにアプリのグループ ユーザーがある場合、アカウントの識別子も渡すことができます (同じ文字制約が適用されます)。If your app groups users into accounts, you can also pass an identifier for the account (with the same character restrictions).

appInsights.setAuthenticatedUserContext(validatedId, accountId);

メトリックス エクスプローラーで、ユーザー、認証アカウントユーザー アカウントをカウントするグラフを作成できます。In Metrics Explorer, you can create a chart that counts Users, Authenticated, and User accounts.

また、特定のユーザー名とアカウントを持つクライアント データ ポイントを検索することもできます。You can also search for client data points with specific user names and accounts.

プロパティを使用したデータのフィルタリング、検索、セグメント化Filtering, searching, and segmenting your data by using properties

プロパティと測定値をイベント (およびメトリック、ページ ビュー、その他のテレメトリ データ) に結び付けることができます。You can attach properties and measurements to your events (and also to metrics, page views, exceptions, and other telemetry data).

プロパティ は、利用状況レポートでテレメトリをフィルター処理するのに使用できる文字列値です。Properties are string values that you can use to filter your telemetry in the usage reports. たとえば、アプリケーションで複数のゲームを提供する場合、各イベントにゲームの名前を結び付けることで人気のあるゲームを確認できます。For example, if your app provides several games, you can attach the name of the game to each event so that you can see which games are more popular.

文字列の長さには 8,192 の制限があります。There's a limit of 8192 on the string length. (データの大きなチャンクを送信する場合は、TrackTrace のメッセージ パラメーターを使用します。)(If you want to send large chunks of data, use the message parameter of TrackTrace.)

メトリックスはグラフィカルに表示できる数値です。Metrics are numeric values that can be presented graphically. たとえば、ゲーマーが達成するスコアに漸増があるかどうかを確認できます。For example, you might want to see if there's a gradual increase in the scores that your gamers achieve. イベントともに送信されるプロパティ別にグラフをセグメント化し、ゲームごとの個別のグラフや積み重ねグラフを表示できます。The graphs can be segmented by the properties that are sent with the event, so that you can get separate or stacked graphs for different games.

メトリック値は、0 以上でないと正しく表示されません。For metric values to be correctly displayed, they should be greater than or equal to 0.

使用できる プロパティ、プロパティ値、およびメトリックの数には制限 があります。There are some limits on the number of properties, property values, and metrics that you can use.

JavaScriptJavaScript

appInsights.trackEvent
    ("WinGame",
        // String properties:
        {Game: currentGame.name, Difficulty: currentGame.difficulty},
        // Numeric metrics:
        {Score: currentGame.score, Opponents: currentGame.opponentCount}
        );

appInsights.trackPageView
    ("page name", "http://fabrikam.com/pageurl.html",
        // String properties:
        {Game: currentGame.name, Difficulty: currentGame.difficulty},
        // Numeric metrics:
        {Score: currentGame.score, Opponents: currentGame.opponentCount}
        );

C#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.jsNode.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 BasicVisual 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)

JavaJava

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

注意

プロパティで個人を特定できる情報を記録しないように注意します。Take care not to log personally identifiable information in properties.

プロパティとメトリックを設定する別の方法Alternative way to set properties and metrics

個別のオブジェクトでイベントのパラメーターを集めたほうが便利であれば、そのようにできます。If it's more convenient, you can collect the parameters of an event in a separate object:

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) を再利用しないでください。Don't reuse the same telemetry item instance (event in this example) to call Track*() multiple times. 再利用すると、正しくない構成でテレメトリが送信される場合があります。This may cause telemetry to be sent with incorrect configuration.

Analytics でのカスタム測定とプロパティCustom measurements and properties in Analytics

Analytics で、カスタム メトリックとプロパティは、各テレメトリ レコードの customMeasurements および customDimensions 属性に表示されます。In Analytics, custom metrics and properties show in the customMeasurements and customDimensions attributes of each telemetry record.

たとえば、要求テレメトリに "game" というプロパティを追加した場合、このクエリは "game" のさまざまな値の出現数をカウントし、カスタム メトリック "score" の平均を表示します。For example, if you have added a property named "game" to your request telemetry, this query counts the occurrences of different values of "game", and show the average of the custom metric "score":

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

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

  • customDimensions または customMeasurements JSON から値を抽出する場合、これは動的な型を持つため、tostring または todouble にキャストする必要があります。When you extract a value from the customDimensions or customMeasurements JSON, it has dynamic type, and so you must cast it tostring or todouble.
  • サンプリングの可能性について考慮するには、count() ではなく、sum(itemCount) を使用する必要があります。To take account of the possibility of sampling, you should use sum(itemCount), not count().

タイミング イベントTiming events

アクションの実行にかかる時間をグラフで示す必要が生じることがあります。Sometimes you want to chart how long it takes to perform an action. たとえば、ユーザーがゲームで選択肢について考える時間について調べるとします。For example, you might want to know how long users take to consider choices in a game. 測定パラメーターを使用することでこの調査を行うことができます。You can use the measurement parameter for this.

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

JavaJava

long startTime = System.currentTimeMillis();

// Perform timed action

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

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

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

カスタム テレメトリの既定のプロパティDefault properties for custom telemetry

記述するカスタム イベントのいくつかに既定のプロパティ値を設定する必要がある場合、TelemetryClient インスタンスで設定できます。If you want to set default property values for some of the custom events that you write, you can set them in a TelemetryClient instance. 既定値は、そのクライアントから送信されたすべてのテレメトリ項目に追加されます。They are attached to every telemetry item that's sent from that client.

C#C#

using Microsoft.ApplicationInsights.DataContracts;

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

Visual BasicVisual Basic

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

JavaJava

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.jsNode.js

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

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

個別のテレメトリの呼び出しはプロパティ ディクショナリの既定値をオーバーライドできます。Individual telemetry calls can override the default values in their property dictionaries.

JavaScript Web クライアントの場合、 JavaScript テレメトリ初期化子を使用します。For JavaScript web clients, use JavaScript telemetry initializers.

標準コレクション モジュールのデータなど、すべてのテレメトリにプロパティを追加するには、ITelemetryInitializer を実装しますTo add properties to all telemetry, including the data from standard collection modules, implement ITelemetryInitializer.

テレメトリのサンプリング、フィルタリング、および処理Sampling, filtering, and processing telemetry

テレメトリを SDK からの送信前に処理するコードを記述することができます。You can write code to process your telemetry before it's sent from the SDK. この処理では、HTTP 要求のコレクションや依存関係のコレクションなど、標準的なテレメトリ モジュールから送信されるデータも対象となります。The processing includes data that's sent from the standard telemetry modules, such as HTTP request collection and dependency collection.

テレメトリにプロパティを追加するには、ITelemetryInitializer を実装します。Add properties to telemetry by implementing ITelemetryInitializer. たとえば、バージョン番号や、他のプロパティから算出された値を追加できます。For example, you can add version numbers or values that are calculated from other properties.

ITelemetryProcesor を実装すると、テレメトリが SDK から送信される前にフィルタリングによってテレメトリを変更または破棄することができます。Filtering can modify or discard telemetry before it's sent from the SDK by implementing ITelemetryProcesor. 送信対象や破棄対象を指定できますが、メトリックへの影響を考慮する必要があります。You control what is sent or discarded, but you have to account for the effect on your metrics. 項目を破棄する方法によっては、関連する項目間を移動する機能が失われる可能性があります。Depending on how you discard items, you might lose the ability to navigate between related items.

サンプリングは、アプリからポータルに送信されるデータの量を減らすためのパッケージ化ソリューションです。Sampling is a packaged solution to reduce the volume of data that's sent from your app to the portal. これにより、表示されるメトリックに影響をあたえることなくデータ量を削減できます。It does so without affecting the displayed metrics. また、サンプリングを行った場合でも、変わらずに例外、要求、ページ ビューなどの関連する項目間を移動して問題を診断できます。And it does so without affecting your ability to diagnose problems by navigating between related items such as exceptions, requests, and page views.

詳細情報Learn more.

テレメトリの無効化Disabling telemetry

テレメトリの収集と送信を 動的に停止および開始 するにはTo dynamically stop and start the collection and transmission of telemetry:

C#C#

using  Microsoft.ApplicationInsights.Extensibility;

TelemetryConfiguration.Active.DisableTelemetry = true;

JavaJava

telemetry.getConfiguration().setTrackingDisabled(true);

選択されている標準のコレクターを無効にするには (たとえば、パフォーマンス カウンター、HTTP 要求、依存関係)、ApplicationInsights.config 内の該当する行を削除するか、コメントアウトします。たとえば、独自の TrackRequest データを送信する場合にこれを行います。To disable selected standard collectors--for example, performance counters, HTTP requests, or dependencies--delete or comment out the relevant lines in ApplicationInsights.config. You can do this, for example, if you want to send your own TrackRequest data.

Node.jsNode.js

telemetry.config.disableAppInsights = true;

初期化時にパフォーマンス カウンター、HTTP 要求、依存関係などの選択されている標準コレクターを無効にするには、構成メソッドを次のように SDK の初期化コードに追加します。To disable selected standard collectors--for example, performance counters, HTTP requests, or dependencies--at initialization time, chain configuration methods to your SDK initialization code:

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

初期化後にこれらのコレクターを無効にするには、構成オブジェクト applicationInsights.Configuration.setAutoCollectRequests(false) を使用します。To disable these collectors after initialization, use the Configuration object: applicationInsights.Configuration.setAutoCollectRequests(false)

開発者モードDeveloper mode

デバッグ中、結果をすぐに確認できるように、テレメトリをパイプラインから送信すると便利です。During debugging, it's useful to have your telemetry expedited through the pipeline so that you can see results immediately. テレメトリで問題を追跡する際に役立つ付加的なメッセージも取得できます。You also get additional messages that help you trace any problems with the telemetry. アプリケーションの速度を低下させる可能性があるため、本稼働ではオフにしてください。Switch it off in production, because it may slow down your app.

C#C#

TelemetryConfiguration.Active.TelemetryChannel.DeveloperMode = true;

Visual BasicVisual Basic

TelemetryConfiguration.Active.TelemetryChannel.DeveloperMode = True

選択したカスタム テレメトリにインストルメンテーション キーを設定するSetting the instrumentation key for selected custom telemetry

C#C#

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

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

開発、テスト、運用の各環境のテレメトリが混じらないようにするために、環境に応じて個別の Application Insights リソースを作成し、それぞれのキーを変更できます。To avoid mixing up telemetry from development, test, and production environments, you can create separate Application Insights resources and change their keys, depending on the environment.

インストルメンテーション キーは構成ファイルから取得する代わりにコードで設定できます。Instead of getting the instrumentation key from the configuration file, you can set it in your code. ASP.NET サービスの global.aspx.cs など、初期化メソッドでキーを設定します。Set the key in an initialization method, such as global.aspx.cs in an ASP.NET service:

C#C#

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

JavaScriptJavaScript

appInsights.config.instrumentationKey = myKey;

Web ページでは、スクリプトに一語一語コーディングするのではなく、Web サーバーの状態から設定することもできます。In webpages, you might want to set it from the web server's state, rather than coding it literally into the script. たとえば、ASP.NET アプリで生成される Web ページでは次のように設定します。For example, in a webpage generated in an ASP.NET app:

Razor の JavaScriptJavaScript in Razor

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

TelemetryContextTelemetryContext

TelemetryClient には、すべてのテレメトリ データとともに送信される値が含まれる Context プロパティが備わっています。TelemetryClient has a Context property, which contains values that are sent along with all telemetry data. 通常、標準のテレメトリ モジュールによって設定されますが、自分で設定することもできます。They are normally set by the standard telemetry modules, but you can also set them yourself. 例: For example:

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

いずれかの値を自分で設定した場合は、その値と標準の値が混同されないように、ApplicationInsights.config から該当する行を削除することを検討します。If you set any of these values yourself, consider removing the relevant line from ApplicationInsights.config, so that your values and the standard values don't get confused.

  • Component: アプリそのバージョン。Component: The app and its version.
  • Device: アプリが実行されているデバイスに関するデータ Device: Data about the device where the app is running. (Web アプリでは、テレメトリを送信するサーバーまたはクライアント デバイスのデータ)。(In web apps, this is the server or client device that the telemetry is sent from.)
  • InstrumentationKey: テレメトリが表示される Azure 内の Application Insights リソース。InstrumentationKey: The Application Insights resource in Azure where the telemetry appear. 通常、ApplicationInsights.config から取得されます。It's usually picked up from ApplicationInsights.config.
  • Location: デバイスの地理的な場所。Location: The geographic location of the device.
  • Operation: Web アプリでは現在の HTTP 要求。Operation: In web apps, the current HTTP request. 他の種類のアプリケーションでは、イベントをグループ化するために、これを設定できます。In other app types, you can set this to group events together.
    • Id: 診断検索でイベントを調べるときに関連項目を見つけることができるように、さまざまなイベントを関連付けるために生成される値。Id: A generated value that correlates different events, so that when you inspect any event in Diagnostic Search, you can find related items.
    • 名前: 識別子。通常は HTTP 要求の URL です。Name: An identifier, usually the URL of the HTTP request.
    • SyntheticSource: null 値または空ではない場合に、要求元がロボットまたは Web テストとして識別されたことを示す文字列。SyntheticSource: If not null or empty, a string that indicates that the source of the request has been identified as a robot or web test. 既定で、メトリックス エクスプローラーの計算から除外されます。By default, it is excluded from calculations in Metrics Explorer.
  • Properties: すべてのテレメトリ データとともに送信されるプロパティ。Properties: Properties that are sent with all telemetry data. 個々 の Track* 呼び出しでオーバーライドできます。It can be overridden in individual Track* calls.
  • Session: ユーザーのセッション。Session: The user's session. ID は生成された値に設定されますが、ユーザーがしばらくの間アクティブでない場合には変更されます。The ID is set to a generated value, which is changed when the user has not been active for a while.
  • User: ユーザー情報。User: User information.

制限Limits

アプリケーションごと (インストルメンテーション キーごと) のメトリックとイベントの数には制限があります。There are some limits on the number of metrics and events per application (that is, per instrumentation key). 制限は、選択する料金プランによって異なります。Limits depend on the pricing plan that you choose.

リソースResource 既定の制限Default limit Note
1 日あたりの合計データ量Total data per day 100 GB100 GB 上限を設定することでデータを削減できます。You can reduce data by setting a cap. さらにデータが必要な場合は、ポータルで上限を最大 1,000 GB まで引き上げることができます。If you need more data, you can increase the limit in the portal, up to 1,000 GB. 1,000 GB を超える容量については、AIDataCap@microsoft.com までメールでご連絡ください。For capacities greater than 1,000 GB, send mail to AIDataCap@microsoft.com.
調整Throttling 32K イベント/秒32 K events/second 制限は 1 分以上にわたって測定されます。The limit is measured over a minute.
データの保持Data retention 90 日間90 days このリソースは、SearchAnalytics、およびメトリックス エクスプローラー用です。This resource is for Search, Analytics, and Metrics Explorer.
可用性の複数手順のテストの詳細な結果の保持Availability multi-step test detailed results retention 90 日間90 days このリソースは、各手順の詳細な結果を提供します。This resource provides detailed results of each step.
イベントの最大サイズMaximum event size 64 K64 K
プロパティとメトリック名の長さProperty and metric name length 150150 型スキーマに関するページを参照してください。See type schemas.
プロパティ値の文字列の長さProperty value string length 8,1928,192 型スキーマに関するページを参照してください。See type schemas.
トレースおよび例外のメッセージ長Trace and exception message length 10K10 K 型スキーマに関するページを参照してください。See type schemas.
アプリあたりの可用性テストの数Availability tests count per app 100100
プロファイラーのデータ保持期間Profiler data retention 5 日5 days
プロファイラーの 1 日あたりの送信データProfiler data sent per day 10 GB10 GB

詳細については、Application Insights の価格とクォータに関するページを参照してください。For more information, see About pricing and quotas in Application Insights.

データ速度の上限に達するのを回避するには、サンプリングを使用します。To avoid hitting the data rate limit, use sampling.

データの保持期間を確認する方法については、データの保持とプライバシーに関するページを参照してください。To determine how long data is kept, see Data retention and privacy.

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

SDK コードSDK code

疑問がある場合Questions

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

    なし。None. try catch 句で例外をラップする必要はありません。You don't need to wrap them in try-catch clauses. SDK で問題が発生すると、デバッグ コンソール出力のメッセージが記録されます。メッセージがスルーされる場合は、診断検索にも記録されます。If the SDK encounters problems, it will log messages in the debug console output and--if the messages get through--in Diagnostic Search.

  • ポータルからデータを取得する REST API はありますか。Is there a REST API to get data from the portal?

    はい、データ アクセス API があります。Yes, the data access API. データを抽出する別の方法としては、Analytics から Power BI へのエクスポート連続エクスポートなどがあります。Other ways to extract data include export from Analytics to Power BI and continuous export.

次のステップNext steps