Application Insights のテレメトリ チャネル

テレメトリ チャネルは、Application Insights SDK の不可欠な要素です。 これにより、テレメトリのバッファー処理と Application Insights サービスへの送信が管理されます。 この SDK の .NET バージョンと .NET Core バージョンには、InMemoryChannel と ServerTelemetryChannel の 2 つのテレメトリ チャネルが組み込まれています。 この記事では、各チャネルについて説明し、チャネルの動作をカスタマイズする方法を示しています。

テレメトリ チャネルとは

テレメトリ チャネルは、テレメトリ項目をバッファー処理し、Application Insights サービスに送信する役割を担うものです (テレメトリ項目は、クエリと解析のために Application Insights サービスに保存されます)。 Microsoft.ApplicationInsights.ITelemetryChannel インターフェイスを実装するクラスはいずれも、テレメトリ チャネルです。

テレメトリ チャネルの Send(ITelemetry item) メソッドは、テレメトリ初期化子とテレメトリ プロセッサがすべて呼び出された後に呼び出されます。 つまり、テレメトリ プロセッサによって削除された項目はチャネルに到達しません。 通常、Send() メソッドが項目をすぐにバックエンドに送信することはありません。 通常はメモリ内でバッファー処理されてから、バッチ単位で効率的に送信されます。

このほか Live Metrics Stream にも、テレメトリのライブ ストリーミングに役立つカスタム チャネルがあります。 このチャネルは通常のテレメトリ チャネルからは独立しているので、このドキュメントの内容が該当しません。

あらかじめ組み込まれているテレメトリ チャネル

Application Insights の .NET SDK と .NET Core SDK には、2 つのチャネルがあらかじめ組み込まれています。

• InMemoryChannel:項目が送信されるまでの間、項目をメモリ内でバッファー処理する軽量のチャネルです。 項目はメモリ内でバッファー処理され、30 秒ごとまたは 500 項目がバッファー処理されるごとにフラッシュされます。 このチャネルは、障害の後にテレメトリの送信を再試行しないので、保証される信頼性は最小限です。 また、このチャネルでは、ディスク上にある項目は保持されません。 そのため、正常かどうかに関係なく、アプリケーションのシャットダウン時には未承認の項目は完全に失われます。 このチャネルには、メモリ内のすべてのテレメトリ項目を同期的に強制フラッシュできる Flush() メソッドが実装されています。 このチャネルは、同期的にフラッシュすることが理想的な実行時間の短いアプリケーションに適しています。

  このチャネルは、これよりも大きな Microsoft.ApplicationInsights NuGet パッケージの一部であり、他に何も構成されていないときに SDK が使用する既定のチャネルです。

• ServerTelemetryChannel:再試行ポリシーとローカル ディスクへのデータ保存機能を備えたより高度なチャネルです。 このチャネルでは、一時的なエラーが発生すると、テレメトリの送信が再試行されます。 また、このチャネルは、ネットワーク障害時またはテレメトリが大量にある場合に、ローカル ディスク ストレージを使用してディスク上に項目を保持します。 このように再試行メカニズムとローカル ディスクへの保存機能を備えているため、このチャネルは信頼性が高いと考えられています。 すべての運用シナリオに適しています。 公式ドキュメントに従って構成した ASP.NET および ASP.NET Core アプリケーションでは、このチャネルが既定となっています。 このチャネルは、実行時間の長いプロセスがあるサーバーのシナリオに最適です。 このチャネルによって実装される Flush() メソッドは同期的ではありません。

  このチャネルは、Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel NuGet パッケージとして提供されるものであり、Microsoft.ApplicationInsights.Web または Microsoft.ApplicationInsights.AspNetCore NuGet パッケージを使用している場合には自動的に取得されます。

テレメトリ チャネルの構成

テレメトリ チャネルを構成するには、テレメトリ チャネルをアクティブなテレメトリ構成に設定します。 ASP.NET アプリケーションの構成では、テレメトリ チャネル インスタンスを TelemetryConfiguration.Active に設定するか、ApplicationInsights.config を変更します。 ASP.NET Core アプリケーションの構成では、依存関係挿入コンテナーにチャネルを追加します。

以降のセクションでは、さまざまな種類のアプリケーションに存在するチャネルの StorageFolder 設定の構成例を示します。 StorageFolder は構成可能な設定の 1 つです。 構成設定の完全な一覧については、この記事の後の方にある「チャネル内の構成設定に関するセクション」を参照してください。

ApplicationInsights.config を使用した ASP.NET アプリケーションの構成

ApplicationInsights.config の以下のセクションは、StorageFolder にカスタムの場所が構成された ServerTelemetryChannel チャネルを示しています。

    <TelemetrySinks>
        <Add Name="default">
            <TelemetryProcessors>
                <!-- Telemetry processors omitted for brevity  -->
            </TelemetryProcessors>
            <TelemetryChannel Type="Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.ServerTelemetryChannel, Microsoft.AI.ServerTelemetryChannel">
                <StorageFolder>d:\temp\applicationinsights</StorageFolder>
            </TelemetryChannel>
        </Add>
    </TelemetrySinks>

コードによる ASP.NET アプリケーションの構成

次のコードでは、ServerTelemetryChannel にカスタムの場所を設定した StorageFolder インスタンスを設定しています。 このコードはアプリケーションの最初の方、通常は Global.aspx.cs の Application_Start() メソッドの中に追加します。

using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel;
protected void Application_Start()
{
    var serverTelemetryChannel = new ServerTelemetryChannel();
    serverTelemetryChannel.StorageFolder = @"d:\temp\applicationinsights";
    serverTelemetryChannel.Initialize(TelemetryConfiguration.Active);
    TelemetryConfiguration.Active.TelemetryChannel = serverTelemetryChannel;
}

コードによる ASP.NET Core アプリケーションの構成

Startup.cs クラスの ConfigureServices メソッドを次のように変更します。

using Microsoft.ApplicationInsights.Channel;
using Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel;

public void ConfigureServices(IServiceCollection services)
{
    // This sets up ServerTelemetryChannel with StorageFolder set to a custom location.
    services.AddSingleton(typeof(ITelemetryChannel), new ServerTelemetryChannel() {StorageFolder = @"d:\temp\applicationinsights" });

    services.AddApplicationInsightsTelemetry();
}

コードによる .NET および .NET Core コンソール アプリケーションの構成

コンソール アプリについては、.NET、.NET Core ともコードが同じです。

var serverTelemetryChannel = new ServerTelemetryChannel();
serverTelemetryChannel.StorageFolder = @"d:\temp\applicationinsights";
serverTelemetryChannel.Initialize(TelemetryConfiguration.Active);
TelemetryConfiguration.Active.TelemetryChannel = serverTelemetryChannel;

ServerTelemetryChannel の操作の詳細

ServerTelemetryChannel では、到着した項目がメモリ内バッファーに保存されます。 項目は、シリアル化と圧縮処理の後、30 秒ごとまたは 500 項目がバッファー処理されるごとに Transmission インスタンスに格納されます。 1 つの Transmission インスタンスは最大 500 個の項目を保持することができ、Application Insights サービスに対する 1 回の HTTPS 呼び出しにより送信されるテレメトリのバッチを表しています。

既定では、最大 10 件の Transmission インスタンスを並列で送信できます。 これよりも早いペースでテレメトリが到着する場合や、ネットワークまたは Application Insights のバックエンドが低速な場合は、Transmission インスタンスがメモリ内に保存されます。 このメモリ内 Transmission バッファーの既定の容量は 5 MB です。 メモリ内の容量を超過した場合には、50 MB を上限としてローカル ディスクに Transmission インスタンスが保存されます。

このほか、ネットワークの問題がある場合にも、Transmission インスタンスがローカル ディスクに保存されます。 アプリケーションがクラッシュした場合に消えずに残るのは、ローカル ディスクに保存されている項目のみです。 これらは、アプリケーションを再起動した時点で送信されます。 ネットワークの問題が解決しない場合、ServerTelemetryChannel では、テレメトリの送信を再試行する前に、10 秒から 1 時間の範囲でエクスポネンシャル バックオフ ロジックが使用されます。

チャネルの構成可能な設定

各チャネルの構成可能な設定の完全な一覧については、次を参照してください。

• InMemoryChannel
• ServerTelemetryChannel

ここでは、ServerTelemetryChannel も設定のなかでも特によく使用するものを紹介します。

• MaxTransmissionBufferCapacity:転送項目をメモリ内でバッファー処理するためにチャネルが使用するメモリ量の最大値 (バイト単位) です。 この容量に達すると、新しい項目がローカル ディスクに直接保存されます。 既定値は 5 MB です。 これよりも高い値を設定するとディスクの使用量を抑えられますが、アプリケーションがクラッシュした場合にメモリ内の項目が失われるという点には注意してください。
• MaxTransmissionSenderCapacity:Application Insights に一括送信される Transmission インスタンスの最大数です。 既定値は 10 です。 生成されるテレメトリが膨大な量に及ぶ場合には、これよりも高い数値を設定することをお勧めします。 量が多くなるのは通常、ロード テストの最中や、サンプリングがオフになっている場合です。
• StorageFolder:必要に応じてディスクに項目を保存するためにチャネルが使用するフォルダーです。 Windows では、他のパスが明示的に指定されない限り、%LOCALAPPDATA% または %TEMP% が使用されます。 Windows 以外の環境では、必ず有効な場所を指定する必要があります。そうしないと、テレメトリがローカル ディスクに保存されません。

どのチャネルを使用すればよいですか?

実行時間の長いアプリケーションが絡む運用シナリオのほとんどでは、ServerTelemetryChannel をお勧めします。 ServerTelemetryChannel によって実装された Flush() メソッドは同期しません。 また、保留中のすべてのアイテムがメモリまたはディスクから送信されることも保証されません。

アプリケーションがシャットダウンされそうな状況のシナリオでこのチャネルを使用する場合には、Flush() を呼び出した後に多少の遅延を発生させます。 正確にどの程度の遅延が必要になるかは、予測ができません。 項目または Transmission インスタンスがメモリ内にある数、ディスク上にある数、バックエンドに送信される数、チャネルがエクスポネンシャル バックオフ シナリオの途中であるかどうかなどの要素に左右されます。

同期フラッシュの実行が必要な場合には、InMemoryChannel を使用します。

よく寄せられる質問

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

Application Insights のチャネルでは、テレメトリの配信が保証されるのでしょうか? そうでない場合には、テレメトリが失われる可能性があるシナリオはどのようなものでしょうか?

簡潔に言うと、組み込みチャネルのいずれにおいても、バックエンドへのテレメトリ配信に関して、トランザクションのような保証はありません。 ServerTelemetryChannel は配信の信頼性という点で InMemoryChannel よりも優れていますが、こちらもテレメトリの送信はベストエフォートにすぎません。 次のような一般的なシナリオを含め、いくつかの状況ではテレメトリが失われることがあります。

• アプリケーションがクラッシュすると、メモリ内の項目が失われます。
• ネットワークの問題が長期間に及んだ場合には、テレメトリが失われます。 ネットワークの停止中や Application Insights バックエンドでの問題発生時には、テレメトリがローカル ディスクに保存されます。 ただし、48 時間が経過した項目は破棄されます。
• Windows でテレメトリが保存される既定のディスクの場所は、%LOCALAPPDATA% または %TEMP% です。 これらは通常、マシンのローカルの場所です。 アプリケーションがある場所から別の場所に物理的に移行した場合、元の場所に保存されているテレメトリが失われます。
• Windows 上の Azure Web Apps では、既定のディスク ストレージの場所は D:\local\LocalAppData です。 この場所は、永続的なものではありません。 アプリの再起動やスケールアウトなどの操作によりワイプされるので、そこに保存されているテレメトリが失われます。 既定値をオーバーライドして、ストレージに D:\home のような永続的な場所を指定することもできます。 ただし、このような永続的な場所はリモート ストレージによって提供されるので、速度が遅いことがあります。

あまりないことですが、チャネルによってテレメトリ項目が重複する可能性があります。 この動作は、ServerTelemetryChannel がネットワーク障害またはタイムアウトによる再試行、テレメトリがバックエンドに配信されたものの、ネットワークの問題が原因で応答が失われた場合、またはタイムアウトが発生した場合に発生します。

ServerTelemetryChannel は Windows 以外のシステムでも動作しますか?

このチャネルは、パッケージと名前空間の名前に "WindowsServer" という文言が含まれてこそいるものの、次の例外を除き、Windows 以外のシステムでもサポートされます。 Windows 以外のシステムでは、チャネルにより既定でローカル ストレージ フォルダーが作成されることはありません。 ローカル ストレージ フォルダーをご自身で作成したうえで、それを使用するようにチャネルを構成する必要があります。 ローカル ストレージの構成が済んだ後は、チャネルがすべてのシステムで同じように動作します。

SDK では一時的なローカル ストレージが作成されますか? データはストレージで暗号化されますか?

ネットワークの問題の発生中またはスロットリング中は、SDK によりテレメトリの項目がローカル ストレージに保存されます。 このデータがローカルで暗号化されることはありません。

Windows システムの場合、SDK により自動で %TEMP% または %LOCALAPPDATA% ディレクトリに一時的なローカル フォルダーが作成され、アクセスが管理者と現在のユーザーのみに制限されます。

Windows 以外のシステムの場合、SDK によりローカル ストレージが自動で作成されることはないので、既定ではデータがローカルに保存されません。

ストレージ ディレクトリを作成し、それを使用するようにチャネルを構成できます。 この場合、そのディレクトリのセキュリティ保護については、ご自身の責任となります。 データ保護とプライバシーの詳細をご確認ください。

オープンソース SDK

Application Insights の他の SDK と同じく、チャネルもオープン ソースです。 コードの閲覧、投稿、問題のレポートは公式の GitHub リポジトリで行ってください。

次のステップ

• サンプリング
• SDK のトラブルシューティング