.NETのApplication Insights Classic API SDKをAzure Monitor OpenTelemetryへ移行するポイント

.NET アプリで Application Insights Classic API SDK 2.x を使っている場合、対応の要点は「Azure Monitor OpenTelemetry への移行計画を先延ばしにしないこと」です。.NET Application Insights Classic API SDK 2.x は非推奨で、公式情報では 2027年3月31日に廃止予定とされています。新規開発では Azure Monitor OpenTelemetry Distro を使い、既存アプリでは依存関係・接続文字列・カスタムテレメトリ・サンプリング設定を棚卸ししたうえで、OpenTelemetry ベースの構成へ移行するのが現実的です。(Microsoft Learn)

今回の「Migrate Application Insights Classic API Software Development Kits (SDKs) to Azure Monitor OpenTelemetry」は、単なる NuGet パッケージ更新の話ではありません。監視データの送り方、カスタム計測の書き方、Application Map やアラートで見るデータの前提が、Application Insights 独自 SDK から OpenTelemetry 標準へ寄っていく変更です。特に .NET 管理者は、InstrumentationKey、TelemetryProcessor、TelemetryInitializer、ITelemetryChannel、Track* API の使い方を確認し、移行後に「データが出ない」「ログが減った」「カスタムディメンションが想定と違う」とならないように準備する必要があります。(Microsoft Learn)

目次

.NET の更新ポイントは「Application Insights SDK 2.x から OpenTelemetry へ移す」こと

今回の更新で押さえるべき中心は、Application Insights Classic API SDK を使った従来の監視実装を、Azure Monitor OpenTelemetry ベースの実装へ移行する流れが明確になった点です。Microsoft Learn の移行ガイドでは、.NET、Java、Node.js、Python アプリを Application Insights Classic API SDK から Azure Monitor OpenTelemetry へ移行する手順が整理されています。(Microsoft Learn)

.NET では、既存アプリ向けに Application Insights .NET SDK 3.x という移行経路が示されています。SDK 3.x は、多くの TelemetryClient と TelemetryConfiguration API を維持しながら、内部的には Azure Monitor OpenTelemetry Exporter を使って Application Insights にテレメトリを送信します。既存の多くの Track* 呼び出しはアップグレード後も動作しますが、OpenTelemetry シグナルへ変換される内部マッピングを通る点が重要です。(Microsoft Learn)

一方で、新規アプリ、またはすでに Azure Monitor OpenTelemetry Distro を使っているアプリでは、Application Insights .NET SDK 3.x ではなく Azure Monitor OpenTelemetry Distro を使う方針が推奨されています。同じアプリ内で Application Insights .NET SDK 3.x と Azure Monitor OpenTelemetry Distro を併用しない点も、移行設計で必ず確認すべきポイントです。(Microsoft Learn)

影響を受ける環境

影響を受けるのは、Application Insights を使っている .NET アプリのうち、主に Classic API SDK 2.x 系に依存している環境です。特に、古くから Application Insights を導入している ASP.NET Core、ASP.NET on .NET Framework、Worker Service、コンソールアプリ、Windows Service では確認が必要です。

確認対象影響の見方管理者が見るべきポイント
ASP.NET Core アプリMicrosoft.ApplicationInsights.AspNetCore 2.x を使っている可能性AddApplicationInsightsTelemetry() の利用有無、接続文字列、カスタム初期化処理
ASP.NET on .NET FrameworkMicrosoft.ApplicationInsights.Web や ApplicationInsights.config を使っている可能性.NET Framework 4.6.2 以上か、古い TelemetryModule を使っていないか
Worker Service / ConsoleMicrosoft.ApplicationInsights.WorkerService や TelemetryClient を直接使っている可能性DI での TelemetryClient 注入、手動計測、ログ転送の動作
カスタムテレメトリ実装TrackEvent、TrackMetric、TrackException などを使っている可能性メトリック引数付きオーバーロードや命名規則の変更に注意
独自フィルター・加工TelemetryProcessor、TelemetryInitializer、ITelemetryChannel を使っている可能性OpenTelemetry の Processor や Resource 属性への置き換えを検討

ここで注意したいのは、「Application Insights のリソースがクラシックかワークスペースベースか」という話と、「アプリ内で使っている SDK が Classic API か」という話は別物だという点です。今回の移行テーマは、主にアプリケーションに組み込まれた SDK と計測コードの移行です。Azure ポータル上のリソース移行だけで完了するものではありません。

移行期限:.NET SDK 2.x は 2027年3月31日までに対応が必要

公式の Classic API 2.x ドキュメントでは、Node.js Application Insights Classic API SDK 2.x はすでに retired、.NET Application Insights Classic API SDK 2.x は deprecated で 2027年3月31日に retired と示されています。サポート対象であり続けるには、OpenTelemetry ベースの SDK 3.x、できれば OpenTelemetry Distro へ移行する必要があります。(Microsoft Learn)

実務では、2027年3月31日を「本番移行日」ではなく、「移行済みで安定運用できているべき期限」と考えるべきです。監視基盤は障害対応、SLO、アラート、コスト管理に直結するため、アプリ本体よりも変更の見落としが起きやすい領域です。少なくとも本番移行の前に、ステージング環境で以下を確認しておく必要があります。

時期の目安実施内容完了条件
早期Application Insights SDK 2.x の利用箇所を棚卸し対象アプリ、NuGet、設定ファイル、環境変数を一覧化
移行設計時SDK 3.x と Distro / Exporter のどちらを使うか決定アプリ種別ごとの移行方針が決まっている
検証環境パッケージ更新、接続文字列、カスタム計測を修正requests、dependencies、traces、exceptions が取得できる
本番前アラート、KQL、ダッシュボード、コストを再確認旧 SDK 時代と比較して監視抜けがない
本番後しばらく並行監視・差分確認テレメトリ量、サンプリング、Application Map が安定

移行パターンは大きく2つある

.NET アプリの移行では、すべてのアプリを同じ方法で置き換える必要はありません。既存コードへの影響を抑えるか、OpenTelemetry 標準へ寄せるかで選び方が変わります。

移行パターン向いているケースメリット注意点
Application Insights .NET SDK 3.x へアップグレード既存の TelemetryClient や Track* 呼び出しが多いアプリ既存 API を多く残しながら OpenTelemetry ベースへ移れる削除・変更された API や拡張ポイントの確認が必要
Azure Monitor OpenTelemetry Distro / Exporter へ移行新規アプリ、OpenTelemetry 標準に寄せたいアプリ、ASP.NET Core今後の推奨パスに沿いやすく、標準的な計測に移れるClassic API 前提のコードは書き換えが必要

Microsoft の FAQ では、新規の Application Insights プロジェクトでは Azure Monitor OpenTelemetry Distro が推奨されています。また、ASP.NET Core、Java、Node.js、Python では Distro が推奨され、classic ASP.NET、コンソールアプリ、Windows Forms などその他の .NET シナリオでは Azure.Monitor.OpenTelemetry.Exporter が推奨されています。(Microsoft Learn)

判断基準はシンプルです。既存の Classic API 呼び出しが多く、短期的に監視停止リスクを抑えたいなら SDK 3.x が現実的です。新規開発やクラウドネイティブ化を進めるアプリ、複数言語の監視標準をそろえたいグローバル環境では、OpenTelemetry Distro を第一候補にします。

.NET 管理者が確認すべき設定変更

.NET で特に見落としやすいのは、接続文字列、削除されたパッケージ、サンプリング、カスタム拡張ポイントです。移行ガイドでは、SDK 3.x と互換性のないパッケージを削除し、残る Application Insights パッケージを 3.x にそろえることが示されています。2.x と 3.x のパッケージを同じアプリ内で混在させない点も重要です。(Microsoft Learn)

確認項目変更内容実務上の注意点
パッケージ互換性のない 2.x 系パッケージを削除一部だけ 3.x にすると依存関係の不整合が起きやすい
接続先設定InstrumentationKey ではなく ConnectionString を使うSDK 3.x では接続文字列がないと起動時に失敗する可能性がある
TelemetryConfiguration.Active明示的に構成を作成して TelemetryClient に渡す静的な構成前提のテストコードも見直す
TrackPageView.NET 3.x SDK では削除サーバー側でページビューを送っていた場合は代替を検討
メトリック付き TrackEvent などカスタムメトリック引数の扱いが変わるメトリックは TrackMetric() などで分けて送る
TelemetryProcessor / TelemetryInitializerOpenTelemetry ベースの Processor へ移行カスタムディメンション、除外条件、匿名化処理を重点確認
ITelemetryChannelClassic channel 抽象は削除テストでは In-memory exporter など OpenTelemetry 寄りの検証へ変更
サンプリングSamplingRatio または TracesPerSecond を使うrequests と dependencies を別々の設定にできない点に注意

特に InstrumentationKey から ConnectionString への移行は、設定ファイル、Azure App Service のアプリケーション設定、Kubernetes Secret、CI/CD パイプライン、ローカル開発用 Secret まで含めて確認する必要があります。接続文字列がコードに直書きされている場合は、運用環境では環境変数や構成管理に移すのが安全です。(Microsoft Learn)

ASP.NET Core で OpenTelemetry Distro に移行する基本イメージ

ASP.NET Core で新しい推奨パスに寄せる場合は、Azure.Monitor.OpenTelemetry.AspNetCore を使い、AddOpenTelemetry().UseAzureMonitor() で Azure Monitor への送信を有効化します。公式ドキュメントでは、ASP.NET Core 向けに Azure.Monitor.OpenTelemetry.AspNetCore、その他の .NET シナリオ向けに Azure.Monitor.OpenTelemetry.Exporter が示されています。(Microsoft Learn)

従来の典型例は次のような構成です。

builder.Services.AddApplicationInsightsTelemetry();

OpenTelemetry Distro を使う場合の基本形は次のようになります。

using Azure.Monitor.OpenTelemetry.AspNetCore;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenTelemetry().UseAzureMonitor();

var app = builder.Build();

app.Run();

本番環境では、接続文字列をコードではなく APPLICATIONINSIGHTS_CONNECTION_STRING 環境変数に設定するのが基本です。公式ドキュメントでも、接続文字列の設定方法として環境変数、構成ファイル、コードが示されており、本番では環境変数または Java の構成ファイルが推奨されています。(Microsoft Learn)

APPLICATIONINSIGHTS_CONNECTION_STRING="<Application Insights の接続文字列>"

削除・見直しが必要な NuGet パッケージ

SDK 3.x への移行では、単に Microsoft.ApplicationInsights のバージョンを上げるだけでは不十分です。移行ガイドでは、SDK 3.x と互換性のないパッケージとして、Microsoft.ApplicationInsights.DependencyCollector、Microsoft.ApplicationInsights.EventCounterCollector、Microsoft.ApplicationInsights.PerfCounterCollector、Microsoft.ApplicationInsights.WindowsServer、Microsoft.Extensions.Logging.ApplicationInsights などが挙げられています。これらは 3.x 版が提供されないため、サポートされる 3.x パッケージや OpenTelemetry の仕組みに置き換える必要があります。(Microsoft Learn)

実務では、ソリューション全体で次のように検索すると影響範囲を洗い出しやすくなります。

dotnet list package | findstr ApplicationInsights

または、リポジトリ内で以下の文字列を検索します。

Microsoft.ApplicationInsights
TelemetryClient
TelemetryConfiguration
TelemetryProcessor
TelemetryInitializer
InstrumentationKey
ApplicationInsights.config

複数プロジェクトで共通ライブラリに TelemetryClient を隠しているケースもあります。Web アプリだけを見て移行したつもりでも、バックグラウンドジョブやバッチ処理の監視が旧 SDK のまま残ることがあるため、リポジトリ単位ではなくデプロイ単位で確認するのが安全です。

カスタムテレメトリ移行で失敗しやすいポイント

Application Insights Classic API SDK を長く使っている環境ほど、標準の自動収集だけでなく、独自のイベント、メトリック、プロパティ付与、除外処理を入れていることが多くあります。ここが移行時の最大のつまずきどころです。

旧実装でよくある処理移行時の確認ポイント失敗例
TrackEvent で業務イベントを送るイベント名、カスタムプロパティ、メトリック分離を確認Usage 分析のイベント名が変わり、既存レポートが空になる
TrackMetric で数値を送るメトリック名の命名規則を確認スペース入りの名前で想定どおり送れない
TelemetryInitializer で共通プロパティを付与Resource 属性または OpenTelemetry Processor へ置き換えcloud_RoleName や環境名が消え、Application Map が崩れる
TelemetryProcessor で除外・匿名化OpenTelemetry Processor や収集前フィルターを検討個人情報マスキングが移行後に効かない
ITelemetryChannel をモックしたテストIn-memory exporter などに変更単体テストがコンパイルできない

移行ガイドでは、TelemetryModule、TelemetryInitializer、TelemetryProcessor のカスタマイズは OpenTelemetry ベースの Processor に移行する方針が示されています。また、Resource ベースの値は OpenTelemetry の Resource マッピングを通じて扱える一方、すべてのテレメトリにキー値を付けたい場合は GlobalProperties やカスタム Processor を検討する必要があります。(Microsoft Learn)

サンプリング設定は「ログが減った」と誤解されやすい

移行後に問い合わせが起きやすいのが、「以前よりログや依存関係の数が少ない」という現象です。SDK 3.x では、トレース、つまり requests と dependencies に対して SamplingRatio または TracesPerSecond を設定できます。既定では TracesPerSecond が 5 traces per second とされており、requests と dependencies に同じサンプリング設定が適用されます。(Microsoft Learn)

運用上は、サンプリングを「コスト削減設定」とだけ見るのではなく、「障害調査に必要なトレースの完全性をどこまで保つか」という観点で設計する必要があります。Microsoft の FAQ でも、Azure Monitor OpenTelemetry sampler によるソース側サンプリングを推奨し、ingestion sampling はフォールバックとして使う考え方が示されています。SDK 側と取り込み側の両方でサンプリングすると、実効的な保存率が掛け算で下がる点にも注意が必要です。(Microsoft Learn)

例えば、SDK 側で 20% にサンプリングし、さらに取り込み側で 50% にサンプリングすると、保存されるデータは概算で 10% になります。アラート、SLO、失敗率の分析に使うテレメトリでこの設定を無意識に行うと、障害検知や原因調査に影響します。

グローバル環境ではリージョンとデータ所在地を確認する

グローバル向けサービスでは、SDK 移行と同時に「どの Application Insights リソースに送るか」も確認すべきです。公式 FAQ では、地域ごとのデータコンプライアンス要件を満たすにはグローバルエンドポイントではなくリージョン別の Application Insights エンドポイントを使うこと、厳格な要件がある地域ごとに Application Insights リソースを作成し、ユーザーの地域に応じて接続文字列を切り替える構成例が示されています。(Microsoft Learn)

実務では、次のような設計が考えられます。

要件推奨される考え方
EU、米国、日本などでデータ所在地を分けたい地域ごとに Application Insights リソースを分け、接続文字列を切り替える
全世界の運用チームが横断分析したい必要に応じて Log Analytics ワークスペース側で統合的に分析できる設計にする
マルチリージョンで同じアプリを動かすcloud_RoleName、cloud_RoleInstance、環境名、リージョン名を明示的に設計する
国や地域ごとに監査要件が違うテレメトリに含める個人情報、IP、カスタムプロパティを事前レビューする

グローバル環境でありがちな失敗は、移行後にすべてのテレメトリが1つの Application Insights リソースへ集約され、あとから地域分離が難しくなるケースです。OpenTelemetry へ移るタイミングは、監視のデータルーティングを見直す良い機会でもあります。

Application Map と Cloud Role Name の確認は必須

マイクロサービスや複数コンポーネントを同じ Application Insights リソースへ送っている場合、Cloud Role Name の設定を確認してください。公式ドキュメントでは、2つ以上のサービスが同じ Application Insights リソースへテレメトリを送る場合、Application Map 上で正しく表現するために Cloud Role Names を設定する必要があるとされています。(Microsoft Learn)

移行後に Application Map が「1つの大きなサービス」に見える、依存関係が外部依存としてしか見えない、ロール名が想定と違う、といった問題が出る場合は、まず Resource 属性と Cloud Role Name の設定を疑うべきです。特に Kubernetes、Azure App Service、VM、オンプレミスをまたぐ構成では、環境ごとの命名ルールを先に決めておくと運用が安定します。

KQL、アラート、ダッシュボードへの影響

SDK 移行で見落としがちなのが、アプリからテレメトリが送信されるかだけでなく、それを利用する運用資産が壊れないかです。Application Insights のログ、アラートルール、Workbooks、Grafana ダッシュボード、運用手順書は、旧 SDK 時代のテーブル名やプロパティ名を前提にしている場合があります。

OpenTelemetry では用語も変わります。Application Insights の autocollectors は OpenTelemetry では instrumentation libraries、channel は exporter、requests は server spans、dependencies は client/internal などの span、operation ID は trace ID といった対応関係になります。(Microsoft Learn)

確認すべき代表例は次のとおりです。

運用資産確認内容
KQL クエリcustomDimensions、operation_Id、cloud_RoleName、sdkVersion への依存
アラート失敗率、例外数、依存関係失敗、ログ件数のしきい値
Workbooksカスタムイベント名、メトリック名、ロール名の参照
Application Mapサービス分割、依存関係、リージョン別表示
SLO / SLA レポートサンプリング変更による母数の変化
コスト監視ingestion volume、データ保持、サンプリング率

特に ILogger ログは Application Insights Logs の traces テーブルに格納されます。移行後にログの見え方が変わったと感じる場合は、アプリ側のログレベル、OpenTelemetry のログ収集設定、サンプリング、KQL の検索条件を合わせて確認してください。(Microsoft Learn)

実務向けの移行手順

移行は、パッケージ更新から始めるよりも、先に「監視で何を保証しているか」を整理してから進める方が安全です。以下の順序で進めると、監視抜けやコスト増を抑えやすくなります。

まず SDK 2.x の利用状況を棚卸しする

最初に、各アプリがどの SDK、どの設定、どの接続先を使っているかを洗い出します。ASP.NET Core、Worker Service、バッチ、コンソールアプリ、Azure Functions、オンプレミス実行の .NET Framework アプリまで含めて確認してください。

確認する項目は、NuGet パッケージ、ApplicationInsights.config、appsettings.json、環境変数、Key Vault、Kubernetes Secret、CI/CD の変数、TelemetryClient をラップした共通ライブラリです。

移行パターンをアプリごとに決める

次に、SDK 3.x へアップグレードするのか、Azure Monitor OpenTelemetry Distro / Exporter へ移行するのかを決めます。既存の TelemetryClient 呼び出しが多い業務アプリでは SDK 3.x、ASP.NET Core の新規・刷新案件では Distro、classic ASP.NET やコンソールアプリでは Exporter を検討する、という切り分けが現実的です。

互換性のないパッケージを削除する

SDK 3.x を使う場合、互換性のない 2.x 系パッケージを残したままにしないことが重要です。DependencyCollector、PerfCounterCollector、WindowsServer、TelemetryChannel 系のパッケージが残っている場合は、機能の代替を確認してから削除します。(Microsoft Learn)

接続文字列へ切り替える

InstrumentationKey を使っている環境は、Application Insights の接続文字列へ切り替えます。アプリコード、設定ファイル、環境変数、デプロイテンプレートのどこに値があるかを確認し、本番では環境変数や安全な構成管理を使います。(Microsoft Learn)

カスタム計測とフィルターを移植する

TrackEvent、TrackMetric、TrackException、TelemetryInitializer、TelemetryProcessor を使っている場合、移行後も同じデータが取れるかをテストします。特に、業務 KPI、課金、監査、セキュリティ調査に使うカスタムイベントは、単にアプリが動くことではなく、同じ粒度で分析できることを合格条件にしてください。

ステージングでテレメトリ差分を比較する

移行前後で、最低限以下を比較します。

比較項目確認観点
requestsリクエスト数、失敗率、応答時間が大きくずれていないか
dependenciesSQL、HTTP、Storage、外部 API の依存関係が取れているか
exceptions例外の件数、スタックトレース、相関 ID が追えるか
tracesILogger ログが想定レベルで送られているか
customEvents業務イベント名と customDimensions が変わっていないか
customMetricsメトリック名、単位、集計方法が維持されているか
Application Mapサービス名、依存関係、リージョン表示が崩れていないか
コスト取り込み量が急増または急減していないか

本番移行後はアラートを再調整する

移行直後は、サンプリングや自動収集の差でメトリックの母数が変わる場合があります。従来のしきい値をそのまま使うと、アラートが鳴りすぎる、または鳴らなくなる可能性があります。1〜2週間程度の実データを見て、失敗率、例外数、依存関係失敗、ログ件数のしきい値を調整する運用が必要です。

管理者向けチェックリスト

移行前に、次の項目を確認してください。

チェック項目完了の目安
.NET Application Insights SDK 2.x の利用箇所を一覧化した対象アプリとリポジトリが特定済み
2027年3月31日までの移行計画を作成した本番移行日、検証期間、担当者が決まっている
SDK 3.x / Distro / Exporter の採用方針を決めたアプリ種別ごとの判断基準がある
InstrumentationKey を ConnectionString に置き換えた本番設定は環境変数や安全な構成管理を使用
2.x と 3.x パッケージを混在させていないdotnet list package で確認済み
カスタム Processor / Initializer を移行した個人情報マスキング、共通プロパティ、除外条件を確認済み
サンプリング設定を見直したコストとトレース完全性のバランスを確認済み
KQL、アラート、Workbook を修正した監視画面と通知が移行後データで動作
Cloud Role Name を確認したApplication Map でサービスが正しく分割表示
グローバル環境の接続先を確認したリージョン、データ所在地、コンプライアンス要件を満たす

よくある疑問

SDK 3.x に上げればコード変更なしで済むのか

簡単な自動収集と基本的な Track* 呼び出しだけであれば、変更を少なくできる可能性があります。ただし、TrackPageView、メトリック引数付きオーバーロード、TelemetryProcessor、TelemetryInitializer、ITelemetryChannel、古いサンプリング設定を使っている場合は、コードや設定の見直しが必要です。(Microsoft Learn)

Azure Monitor OpenTelemetry Distro と SDK 3.x を同じアプリで使えるのか

同じアプリで併用しないでください。移行ガイドでは、新規アプリまたはすでに Distro を使っているアプリでは Distro を使い、Application Insights .NET SDK 3.x と Azure Monitor OpenTelemetry Distro を同じアプリで使わないよう明記されています。(Microsoft Learn)

Instrumentation Key はまだ使えるのか

移行後の前提は接続文字列です。SDK 3.x では TelemetryConfiguration.ConnectionString を使い、Instrumentation Key ではなく接続文字列を指定します。接続文字列が構成されていない場合、起動時に失敗する可能性がある点に注意してください。(Microsoft Learn)

OpenTelemetry にすると Application Insights の画面は使えなくなるのか

使えなくなるわけではありません。Azure Monitor OpenTelemetry Distro は Application Insights と連携し、traces、metrics、logs、exceptions の自動収集や Live Metrics などをサポートします。ただし、用語や内部モデルは OpenTelemetry に寄るため、Application Map、KQL、カスタムディメンション、サンプリングの見え方は検証が必要です。(Microsoft Learn)

まとめ:まずは「旧 SDK の棚卸し」と「接続文字列・カスタム計測の確認」から始める

.NET の Application Insights Classic API SDK から Azure Monitor OpenTelemetry への移行は、2027年3月31日の .NET SDK 2.x 廃止予定を見据えて計画的に進めるべき変更です。最初にやるべきことは、アプリごとの SDK 2.x 利用状況、InstrumentationKey、TelemetryClient、カスタム Processor / Initializer、サンプリング、KQL、アラートを棚卸しすることです。(Microsoft Learn)

新規アプリや刷新対象の ASP.NET Core では Azure Monitor OpenTelemetry Distro を優先し、既存の Classic API 呼び出しが多いアプリでは SDK 3.x による段階移行を検討します。移行後は、単にアプリが起動するかではなく、障害調査に必要な requests、dependencies、exceptions、traces、customEvents、customMetrics が従来どおり確認できるかを合格条件にしてください。

この記事を書いた人

実務の現場で詰まりがちなポイントを地図にするITブログ「IT trip」を運営。Windows/Office(Teams・Excel)からSQL、サーバ運用、ガジェットまで、再現性のある手順と“なぜそうなるか”を丁寧に解説します。読んだらすぐ試せること、そして迷った人の次の一歩が見えることを大切にしています。

コメント

コメントする

目次