今回の Azure SDK documentation update で最初に確認すべきことは、Azure.AI.AgentServer.Core 1.0.0-beta.24 の変更が AgentServer Core のテレメトリ実装に関する更新であり、Invocations や Responses まで同時に実質更新されたわけではない点です。特に、Azure Monitor、Application Insights、OTLP Collector、独自の OpenTelemetry 設定を使っている .NET アプリでは、パッケージ更新後に「テレメトリが二重送信されないか」「環境変数から意図した exporter が選ばれるか」「ダッシュボードやアラートが従来通り機能するか」を確認する必要があります。
GitHub の PR では、Azure.AI.AgentServer.Core 1.0.0-beta.24 のリリース日を 2026-05-01 に設定し、変更対象は Core のみとされています。主な変更は、従来の Azure.Monitor.OpenTelemetry.AspNetCore から、統合版の Microsoft.OpenTelemetry distro へ移行したことです。(GitHub)
Azure SDK documentation updateの要点
今回の更新は、Azure SDK for .NET の Azure.AI.AgentServer.Core に関する beta リリース更新です。changelog 上では Features Added、Breaking Changes、Bugs Fixed に個別項目はなく、Other Changes として OpenTelemetry 周りの実装変更が記載されています。(GitHub)
| 確認項目 | 内容 |
|---|---|
| 対象パッケージ | Azure.AI.AgentServer.Core |
| バージョン | 1.0.0-beta.24 |
| リリース日として設定された日付 | 2026-05-01 |
| 公開・更新日 | PR 上では 2026-05-02 に更新 |
| 主な変更 | Azure.Monitor.OpenTelemetry.AspNetCore から Microsoft.OpenTelemetry 統合 distro へ移行 |
| 影響が出やすい領域 | Application Insights、Azure Monitor、OTLP、OpenTelemetry の手動設定、監視ダッシュボード |
| すぐ確認すべき人 | AgentServer Core を使い、テレメトリ収集を有効にしている開発者・運用担当者 |
ポイントは、API の大幅な機能追加というよりも、監視・可観測性の土台が変わる更新として見ることです。アプリ本体が動いていても、トレース、メトリック、ログ、アラート、障害調査の流れに影響する可能性があります。
何が変わったのか
OpenTelemetryの利用パッケージが統合distroへ移行
Azure.AI.AgentServer.Core 1.0.0-beta.24 では、テレメトリ用途で使われていた Azure.Monitor.OpenTelemetry.AspNetCore が、統合版の Microsoft.OpenTelemetry distro に置き換えられています。changelog では、新しい distro が Azure Monitor と OTLP exporter を環境変数から自動検出し、重複インストルメンテーションを防ぐためのガードを不要にする、と説明されています。(GitHub)
この変更により、アプリ側で次のような設定をしている場合は確認が必要です。
dotnet list package --include-transitive確認したいパッケージ例は次の通りです。
Azure.AI.AgentServer.Core
Azure.Monitor.OpenTelemetry.AspNetCore
Microsoft.OpenTelemetry
OpenTelemetry.*
Azure.Monitor.OpenTelemetry.ExporterAzure.AI.AgentServer.Core を直接参照していなくても、Responses や Invocations など別パッケージ経由で Core が推移的に入る構成では、依存関係として影響を受ける可能性があります。Directory.Packages.props、.csproj、packages.lock.json、CI/CD の復元ログを確認しておくと安全です。
Azure MonitorとOTLPの exporter 選択が重要になる
Microsoft OpenTelemetry Distro は、エージェント系・非エージェント系アプリケーションのトレース、メトリック、ログ収集を統合的に扱い、Azure Monitor、OTLP 互換バックエンド、Microsoft Agent 365 などへの出力をサポートするものとして説明されています。(Microsoft Learn)
Azure Monitor Application Insights 側では、OpenTelemetry ベースのデータ収集により、トレース、メトリック、ログ、例外などの自動テレメトリを扱えるとされています。(Microsoft Learn)
実務では、次の環境変数を重点的に確認してください。
APPLICATIONINSIGHTS_CONNECTION_STRING=<Application Insights の接続文字列>
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317APPLICATIONINSIGHTS_CONNECTION_STRING が設定されていれば Azure Monitor / Application Insights 側へ送る構成になりやすく、OTEL_EXPORTER_OTLP_ENDPOINT が設定されていれば OTLP Collector や Grafana Tempo、Jaeger、独自バックエンドなどへの送信も関係します。Microsoft Learn でも、Application Insights の接続文字列や OTLP endpoint を使った構成例が示されています。(Microsoft Learn)
対応が必要な人、不要な人
今回の Azure SDK documentation update は、すべての Azure SDK 利用者に一律で影響する更新ではありません。判断基準は「AgentServer Core を使っているか」と「OpenTelemetry / Azure Monitor の設定をアプリ側で持っているか」です。
| 利用状況 | 対応優先度 | 理由 |
|---|---|---|
Azure.AI.AgentServer.Core を使い、Application Insights に送信している | 高 | テレメトリ送信先、接続文字列、計測結果を確認すべき |
| OTLP Collector を使っている | 高 | exporter の自動検出や endpoint 設定の確認が必要 |
Program.cs で OpenTelemetry を手動登録している | 高 | 二重計測や重複 exporter の有無を確認すべき |
Azure.AI.AgentServer.Responses / Invocations を使っている | 中 | Core が推移的に更新される可能性がある |
| AgentServer Core を使っていない | 低 | 直接の影響は限定的 |
| 監視をまだ有効化していない検証環境のみ | 中 | 将来の本番導入前に設定方針を決めるべき |
PR では、Invocations 1.0.0-beta.4 と Responses 1.0.0-beta.5 はソース変更がないため今回リリース対象ではなく、changelog は Unreleased のままとされています。(GitHub)
移行前に確認すべき設定
パッケージ参照を確認する
まず、アプリがどの OpenTelemetry 関連パッケージを参照しているか確認します。
dotnet list package --include-transitive特に次のような状態は注意が必要です。
| 状態 | 確認ポイント |
|---|---|
Azure.Monitor.OpenTelemetry.AspNetCore を明示参照している | Core 側の更新後も必要かを確認する |
Microsoft.OpenTelemetry を別途導入している | バージョン競合や重複初期化がないか確認する |
OpenTelemetry.Exporter.OpenTelemetryProtocol を使っている | OTLP endpoint の設定と送信結果を確認する |
Directory.Packages.props でバージョン固定している | Core 更新時に依存関係が意図通り解決されるか確認する |
packages.lock.json を使っている | CI とローカルで復元結果が一致するか確認する |
Beta パッケージは将来的に仕様や依存関係が変わる可能性があります。Microsoft Learn でも prerelease product に関する情報は正式リリース前に変更される可能性があると注意されています。(Microsoft Learn)
OpenTelemetryの初期化コードを確認する
Program.cs や拡張メソッド内で、次のような OpenTelemetry 設定を自前で書いている場合は、更新後にテレメトリが重複していないか確認してください。
builder.Services.AddOpenTelemetry()
.WithTracing(tracing =>
{
// ASP.NET Core / HttpClient / OTLP / Azure Monitor などの設定
})
.WithMetrics(metrics =>
{
// メトリック設定
});今回の変更では、統合 distro 側が Azure Monitor と OTLP exporter を環境変数から自動検出する方向になっています。そのため、以前は必要だった「すでに登録済みなら追加しない」といったガードコードが不要になる可能性があります。
ただし、いきなり削除するのは危険です。次の順番で確認するのが現実的です。
| 手順 | 作業 | 判断基準 |
|---|---|---|
| 1 | 現行バージョンでテレメトリ件数を記録する | request、dependency、trace、metric の件数を控える |
| 2 | beta.24 をステージングへ適用する | アプリ起動エラーがないか確認 |
| 3 | 同じテストシナリオを実行する | スパン数やメトリック数が倍増していないか確認 |
| 4 | exporter の送信先を確認する | Application Insights と OTLP の両方へ意図せず送っていないか見る |
| 5 | 不要な手動登録を整理する | 重複が解消されるか再テストする |
実務で見るべき影響範囲
Application Insightsのデータが欠落していないか
更新後は、Azure Portal の Application Insights で次の項目を確認します。
requests
| order by timestamp desc
| take 20dependencies
| order by timestamp desc
| take 20traces
| order by timestamp desc
| take 20確認するポイントは、単に「データがあるか」だけではありません。
- リクエスト件数が急に半減または倍増していないか
- dependency の親子関係が切れていないか
cloud_RoleNameが想定通りか- 例外や Warning ログが別テーブルに流れていないか
- サンプリング設定の影響で重要なトレースが消えていないか
Application Insights では、同じリソースに複数サービスがテレメトリを送る場合、クラウドロール名を適切に設定することが重要だと説明されています。(Microsoft Learn)
OTLP Collectorや外部監視基盤への送信
OTLP を使っている場合は、OTEL_EXPORTER_OTLP_ENDPOINT の設定を確認します。ローカル検証では、collector のログや受信メトリックを見て、更新前後でシグナルが変わっていないか比較します。
echo $OTEL_EXPORTER_OTLP_ENDPOINTWindows PowerShell なら次のように確認できます。
$env:OTEL_EXPORTER_OTLP_ENDPOINTよくある失敗は、ステージング環境にだけ古い OTLP endpoint が残っていて、本番移行時に意図しない監視基盤へ送信されるケースです。CI/CD の変数、Azure App Service のアプリケーション設定、Container Apps や Kubernetes の Secret / ConfigMap まで確認してください。
ダッシュボードとアラート
テレメトリの送信方式が変わると、アプリコードの動作は変わらなくても、監視側の見え方が変わることがあります。特に次の設定は見直し対象です。
| 監視項目 | 確認内容 |
|---|---|
| 可用性ダッシュボード | リクエスト数、失敗率、応答時間が従来通り表示されるか |
| アラート | 失敗率、例外数、メトリック名、ディメンション条件が有効か |
| 分散トレース | 親子スパンが途切れず、外部 HTTP 呼び出しも追跡できるか |
| SLO / SLA レポート | 更新後も同じ条件で集計できるか |
| コスト | ログやメトリックの重複送信で取り込み量が増えていないか |
監視コストの観点では、重複テレメトリが最も見落とされやすいポイントです。更新後に「障害はないが Application Insights の取り込み量だけ増える」場合、OpenTelemetry の二重登録や exporter の二重送信を疑ってください。
移行・更新の進め方
まずはステージングでbeta.24を固定する
本番に直接入れるのではなく、ステージング環境で Azure.AI.AgentServer.Core のバージョンを固定して検証します。
<PackageReference Include="Azure.AI.AgentServer.Core" Version="1.0.0-beta.24" />中央管理をしている場合は、Directory.Packages.props 側を確認します。
<PackageVersion Include="Azure.AI.AgentServer.Core" Version="1.0.0-beta.24" />この時点で重要なのは、dotnet restore が成功することではなく、実際に起動し、テレメトリが期待通り流れることです。
環境変数を一覧化する
Azure App Service、Azure Container Apps、AKS、GitHub Actions、Azure DevOps など、実行環境ごとに OpenTelemetry 関連の環境変数を棚卸しします。
APPLICATIONINSIGHTS_CONNECTION_STRING
OTEL_EXPORTER_OTLP_ENDPOINT
OTEL_SERVICE_NAME
OTEL_RESOURCE_ATTRIBUTES
OTEL_TRACES_EXPORTER
OTEL_METRICS_EXPORTER
OTEL_LOGS_EXPORTERすべてを使っているとは限りませんが、「どの環境で何が設定されているか」を表にしておくと、トラブル時の切り分けが早くなります。
| 環境 | Application Insights | OTLP endpoint | 備考 |
|---|---|---|---|
| local | なし / あり | local collector | 開発者ごとの差分に注意 |
| staging | あり | あり / なし | 本番相当の確認用 |
| production | あり | あり / なし | 変更前後の件数比較が必須 |
更新後に確認するテストシナリオ
最低限、次のシナリオを実行してください。
| シナリオ | 確認すること |
|---|---|
| 正常な HTTP リクエスト | request span、応答時間、ステータスコード |
| 外部 API 呼び出し | dependency span、親子関係 |
| 例外発生 | exception / trace の出力 |
| 4xx / 5xx 応答 | ログレベル、アラート条件 |
| 高頻度アクセス | メトリック数、取り込み量、サンプリング |
| 再起動 | 初期化エラー、exporter の再接続 |
特に AgentServer 系のアプリでは、通常の Web API よりも「会話単位」「セッション単位」「外部ツール呼び出し単位」でトレースを見たいケースが多くなります。単発の疎通確認だけでなく、実際のエージェント利用シナリオに近いテストを行うべきです。
よくある失敗と対策
失敗: 更新したのにApplication Insightsにデータが出ない
まず、接続文字列が実行環境に渡っているか確認します。
echo $APPLICATIONINSIGHTS_CONNECTION_STRINGAzure App Service や Container Apps では、ポータル上のアプリケーション設定を更新しても、再起動が必要な場合があります。ローカルでは設定されているのにクラウド環境では未設定、というケースもよくあります。
失敗: トレースやメトリックが倍増した
アプリ側で OpenTelemetry を手動登録しているうえに、Core 側の統合 distro でも同じシグナルを登録している可能性があります。
確認する箇所は次の通りです。
Program.cs- 独自の
AddObservability()拡張メソッド - shared library の DI 登録
Azure.Monitor.OpenTelemetry.AspNetCoreの明示参照- OTLP exporter の明示登録
- worker service と web host の両方での初期化
重複が疑われる場合は、一度ステージングで手動登録を最小化し、送信件数を比較します。
失敗: InvocationsやResponsesも更新されたと思い込む
今回の PR では、Invocations と Responses はソース変更がないためリリース対象外とされています。(GitHub)
ただし、これらのパッケージを使っているアプリでも、Core を推移的に利用している場合は影響が完全にゼロとは限りません。dotnet list package --include-transitive で Core のバージョンを確認してください。
失敗: 監視の見え方だけ変わって障害に気づけない
テレメトリ基盤の変更では、アプリの機能テストだけでは不十分です。更新後は、アラートが本当に発火するかを検証してください。
例えば、ステージングで意図的に 500 エラーを発生させ、次を確認します。
- Application Insights に例外が記録される
- 失敗率アラートが期待通り発火する
- Teams やメールなど通知先に届く
- ダッシュボード上で該当リクエストを追跡できる
- 分散トレースで前後の処理を追える
本番適用前のチェックリスト
本番更新前には、次のチェックリストを使うと抜け漏れを減らせます。
| チェック | 完了条件 |
|---|---|
| パッケージバージョン確認 | Azure.AI.AgentServer.Core が意図した beta.24 になっている |
| 依存関係確認 | 古い Azure.Monitor.OpenTelemetry.AspNetCore の明示参照が必要か判断済み |
| 環境変数確認 | APPLICATIONINSIGHTS_CONNECTION_STRING と OTLP 関連設定を確認済み |
| 二重登録確認 | OpenTelemetry の手動登録と自動登録が競合していない |
| テレメトリ確認 | request、dependency、trace、metric が出力される |
| アラート確認 | 失敗率、例外、応答時間の通知が機能する |
| コスト確認 | 取り込み量が不自然に増えていない |
| ロールバック準備 | 旧バージョンへ戻す手順と設定を用意している |
ロールバックは、単に NuGet パッケージのバージョンを戻すだけでは足りない場合があります。OpenTelemetry の初期化コード、環境変数、CI/CD のキャッシュ、lock file も合わせて戻せるようにしておきましょう。
今回の更新で取るべき次の行動
Azure.AI.AgentServer.Core 1.0.0-beta.24 は、アプリの表面的な機能よりも、監視・可観測性の構成に注意すべき更新です。まずは利用中のパッケージと依存関係を確認し、次に Application Insights や OTLP の送信先、OpenTelemetry の手動登録、ダッシュボードとアラートを検証してください。
特に本番で AgentServer Core を使っている場合は、更新作業を「パッケージアップデート」ではなく「監視基盤の変更」として扱うのが安全です。ステージングで同じリクエストを流し、更新前後のテレメトリ件数、スパン構造、アラート動作を比較してから本番へ適用しましょう。
コメント