Azure Cosmos DBの今回の更新は、Data Explorerでクエリを実行したときのテレメトリを強化する変更です。結論から言うと、データベースの仕様、SQL構文、RU課金、アプリケーション側SDKの動作が変わる更新ではありません。主な変更点は、Data Explorerのクエリ実行について「成功」「失敗」「実行時間」をより追跡しやすくすることです。
管理者は、Data Explorerの利用権限、RUしきい値、監視ログ、エラー情報の扱いを確認しておくとよいでしょう。開発者は、このテレメトリをサーバー側のクエリメトリクスやSDK診断情報と混同せず、遅いクエリや失敗クエリの切り分けに使うことが重要です。
Azure Cosmos DBの今回の更新で何が変わるのか
2026年5月20日、Azureの公式GitHubリポジトリ Azure/cosmos-explorer で、Pull Request #2487「feat: Add telemetry for query execution success and failure and duration」が master ブランチへマージされました。このPRでは、Data Explorerのクエリ実行に対して、durationとfailureを追跡する追加テレメトリが導入されています。(GitHub)
変更されたファイルは src/Common/IteratorUtilities.ts で、クエリ結果の次ページを取得する nextPage 処理に対して、実行開始時刻、成功時のduration、失敗時のdurationとエラーメッセージを記録する処理が追加されています。(GitHub)
| 観点 | 変更前 | 変更後 | 実務上の意味 |
|---|---|---|---|
| 成功時の記録 | クエリ実行成功は記録される | 成功に加えて durationMs を記録 | Data Explorer上のクエリ実行時間を追跡しやすくなる |
| 失敗時の記録 | 明示的な失敗テレメトリが弱い | traceFailure で失敗、duration、エラー情報を記録 | 失敗傾向や遅延を伴う失敗を分析しやすくなる |
| 対象処理 | fetchNext() の実行 | fetchNext() の前後を計測 | ページ取得単位の挙動を把握しやすくなる |
| クエリ結果 | documents、RU、activityIdなどを返す | 返却内容は基本的に同じ | アプリやDBスキーマの移行は不要 |
| エラー処理 | 失敗時の追跡が限定的 | 失敗を記録したうえでエラーを再送出 | 画面側の失敗挙動を変えずに観測性を高める |
重要なのは、これはAzure Cosmos DBエンジンそのもののクエリ実行ロジックを変更する更新ではなく、Data Explorerという管理・操作UI側の観測性を高める変更だという点です。
対象範囲はAzure Cosmos DB Data Explorerのクエリ実行
Azure Cosmos DB Data Explorerは、Azure Cosmos DB内のデータを表示・管理できるWebベースのインターフェイスです。公式ドキュメントでは、データの参照、クエリ実行、クエリ結果の確認に使える管理画面として説明されています。(Microsoft Learn)
今回の更新で影響を受けるのは、主に次のような利用シーンです。
| 利用シーン | 影響 |
|---|---|
| Azure portalや専用Data Explorerでクエリを実行する | クエリ実行の成功・失敗・durationがData Explorer側で追跡されやすくなる |
| アプリケーションからSDKでCosmos DBにアクセスする | このPR自体による直接的な動作変更はない |
| コンテナー、パーティションキー、インデックスを管理する | スキーマや設定の移行は不要 |
| RU使用量やサーバー側レイテンシを監視する | 引き続きAzure MonitorやSDK診断情報で確認する |
| 自前でcosmos-explorerをビルド・運用している | テレメトリ送信内容、ログポリシー、テスト項目の確認が必要 |
Data Explorerは便利ですが、本番データに対して自由にクエリを実行できる画面でもあります。特に大規模コンテナーでは、管理画面からの調査クエリでもRUを消費します。今回のテレメトリ強化は、こうした操作の成功・失敗・所要時間を把握しやすくするための変更と見てよいでしょう。
durationMsは「サーバー側のクエリ時間」と同じではない
今回追加された durationMs は、documentsIterator.fetchNext() の前後で Date.now() を使って算出されています。つまり、Data Explorer側の非同期処理として、次のページを取得するまでにかかった時間を記録するものです。(GitHub)
ここで注意したいのは、durationMs をそのまま「Cosmos DBサーバー内部の純粋なクエリ実行時間」と解釈しないことです。
Azure Cosmos DBには、クエリパフォーマンスを分析するためのクエリ実行メトリクスがあります。公式ドキュメントでは、TotalTime、IndexLookupTime、DocumentLoadTime、RuntimeExecutionTime、IndexHitRatio などの指標を使って、クエリのどこに時間がかかっているかを分析できると説明されています。(Microsoft Learn)
| 指標 | 主な用途 | 確認すべき場面 |
|---|---|---|
Data Explorerの durationMs | Data Explorerでクエリ操作にかかった時間の把握 | 管理画面でのクエリが遅い、失敗する |
| Query execution metrics | サーバー側のクエリ実行内訳の分析 | インデックス、取得件数、パーティション横断の影響を調べたい |
| Request Charge | クエリが消費したRUの確認 | コストやスロットリングを調べたい |
| Azure Monitorメトリクス | アカウントやコンテナー全体の傾向監視 | RU使用率、レイテンシ、可用性を継続監視したい |
| SDK Diagnostics / OpenTelemetry | アプリケーション側からの詳細な追跡 | 本番アプリの遅延やエラーを調査したい |
たとえば、Data Explorer上の durationMs が長くても、原因がサーバー側のクエリ処理とは限りません。ネットワーク、ブラウザー、認証、ページング、結果件数、クライアント側の処理が影響している可能性があります。
一方で、Query execution metricsの IndexHitRatio が低い、RetrievedDocumentCount が多い、パーティションキーを指定していない、といった状況であれば、クエリ設計そのものを見直すべきです。
管理者が確認すべき設定と運用ポイント
Data Explorerの利用権限を見直す
まず確認すべきなのは、誰がData Explorerで本番データに対してクエリを実行できるかです。
Data Explorerは調査や保守に便利ですが、権限が広すぎると、意図しない高負荷クエリや機密データの閲覧につながります。特に本番環境では、閲覧専用、検証環境、運用管理者、開発者の権限を分けておくことが重要です。
確認すべきポイントは次の通りです。
| 確認項目 | 判断基準 |
|---|---|
| 本番Cosmos DBにData Explorerでアクセスできるユーザー | 最小権限になっているか |
| キーベース認証の利用 | 必要以上に主キーへ依存していないか |
| Microsoft Entra ID RBAC | 運用ルールに沿って有効化・利用されているか |
| 検証環境との分離 | 本番データで試行錯誤していないか |
| 監査・証跡 | 誰がどの環境で操作できるか説明できるか |
Data Explorerでは、Microsoft Entra IDベースのRBACを使う設定も用意されています。公式ドキュメントでは、Enable Entra ID (RBAC) の設定値として、自動、True、Falseの動作が説明されており、キーベース認証を使う設定では主キー取得要求が発生する可能性がある点にも触れられています。(Microsoft Learn)
RUしきい値を設定して高コストクエリを抑制する
Data Explorerには、クエリで使われるRU/sに対する制限を構成する機能があります。公式ドキュメントでは、この機能によりコストとパフォーマンスを制御でき、高コストのクエリを自動的に取り消すこともできると説明されています。(Microsoft Learn)
本番環境でData Explorerを使う場合、RUしきい値は特に重要です。
たとえば、次のようなクエリは注意が必要です。
SELECT * FROM cこのクエリは条件がなく、結果件数が多いコンテナーでは大量のRUを消費する可能性があります。調査目的であっても、まずは件数を絞るべきです。
SELECT TOP 100 c.id, c.status, c.createdAt
FROM c
WHERE c.tenantId = "tenant-001"
ORDER BY c.createdAt DESCパーティションキーに相当する条件を入れ、取得列と件数を絞るだけでも、調査時の負荷を抑えやすくなります。
テレメトリに含まれる情報の扱いを確認する
今回の変更では、失敗時に error.message がテレメトリデータとして渡されます。PR上の実装では、成功時に durationMs、失敗時に durationMs と error.message が追加されています。(GitHub)
通常、これは障害分析に役立ちます。ただし、組織のセキュリティポリシー上、エラーメッセージやアカウント情報の取り扱いに制約がある場合は、以下を確認しておきましょう。
| 確認項目 | 理由 |
|---|---|
| エラーメッセージに機密情報が含まれない運用になっているか | 調査ログやテレメトリに予期せぬ情報が残る可能性を下げるため |
| 本番環境でData Explorerを使うルールがあるか | 個人情報や業務データを含むクエリを安易に実行しないため |
| 自前ビルド版cosmos-explorerのテレメトリ送信先 | フォークや社内運用時にログ管理責任が発生するため |
| サポート調査時のログ共有ルール | エラー内容を外部に共有する前に確認できるようにするため |
特に自社でcosmos-explorerをフォークしている場合は、テレメトリ送信処理や収集先、保持期間、マスキング方針を確認する価値があります。
開発者が確認すべきポイント
Data Explorerの遅延とアプリケーションの遅延を分けて考える
Data Explorerでクエリが遅いからといって、すぐにアプリケーションも同じように遅いとは限りません。逆に、アプリケーションで遅いクエリがData Explorerでは再現しない場合もあります。
切り分けでは、次の順序で確認すると判断しやすくなります。
| 手順 | 確認内容 | 判断 |
|---|---|---|
| 1 | Data Explorerだけで遅いか | ブラウザー、認証、画面処理、ページングの影響を疑う |
| 2 | SDKから同じクエリを実行して遅いか | アプリ側のDiagnosticsを確認する |
| 3 | RU消費が高いか | クエリ設計、取得件数、インデックスを確認する |
| 4 | パーティションキー条件があるか | クロスパーティションクエリの可能性を確認する |
| 5 | Azure Monitorで全体傾向を見る | 特定クエリではなくアカウント全体の負荷を確認する |
Azure Cosmos DBの公式ドキュメントでは、パーティションキーを含むフィルターは低レイテンシになりやすく、フィルターのないクエリは複数パーティションにまたがり、RUやレイテンシが増えやすいと説明されています。(Microsoft Learn)
SDK診断情報とOpenTelemetryを併用する
本番アプリケーションの監視では、Data Explorerのテレメトリだけでは不十分です。アプリケーションからCosmos DBにアクセスしている場合は、SDKの診断情報やOpenTelemetryを使って、ステータスコード、サブステータスコード、request charge、接続モード、接触リージョンなどを追跡するのが現実的です。
Azure Cosmos DB SDKのObservabilityドキュメントでは、OpenTelemetryで Azure.Cosmos.Operation ソースを追加してトレースプロバイダーに設定できること、さらにCosmos DB関連の属性としてステータスコード、サブステータスコード、RU、接続モードなどが扱われることが説明されています。(Microsoft Learn)
Data Explorerは「管理画面での調査」に向いています。一方、SDK診断情報やOpenTelemetryは「実際のアプリケーション経路で何が起きているか」を見るために使います。両者を混同しないことが、トラブルシューティングの精度を上げるポイントです。
クエリの書き方を見直す
今回の更新で失敗やdurationを追いやすくなると、遅いクエリが見つかりやすくなります。見つけた後に重要なのは、クエリをどう改善するかです。
悪い例として、次のようなクエリがあります。
SELECT * FROM c
WHERE c.status = "active"一見シンプルですが、パーティションキー条件がなく、結果件数も制限していません。大規模なコンテナーでは、複数パーティションを対象に大量のドキュメントを走査する可能性があります。
改善例は次の通りです。
SELECT TOP 100 c.id, c.status, c.updatedAt
FROM c
WHERE c.tenantId = "tenant-001"
AND c.status = "active"
ORDER BY c.updatedAt DESC改善の観点は明確です。
| 改善ポイント | 効果 |
|---|---|
| パーティションキー条件を入れる | 対象範囲を絞り、低レイテンシ化しやすい |
SELECT * を避ける | 不要なデータ転送を減らせる |
TOP を使う | 調査時の取得件数を制限できる |
| 必要な並び替えだけにする | インデックスやRUへの影響を確認しやすい |
| Query metricsを見る | 推測ではなく実測で改善判断できる |
AI/Copilot更新と誤解しないための見方
見出し上は「AI/Copilot更新」と関連づけて紹介されることがありますが、今回のPR自体は、Copilotがクエリを生成する、AIがクエリを自動修正する、といった機能追加ではありません。
実体は、Data Explorerのクエリ実行におけるテレメトリ強化です。
ただし、Azure portalや管理画面でAI支援が広がるほど、操作結果を正しく観測できる基盤は重要になります。たとえば、管理者や開発者が次のような問いに答えるには、成功・失敗・durationの記録が役立ちます。
| 問い | テレメトリが役立つ理由 |
|---|---|
| Data Explorerのクエリがどの程度失敗しているか | failureの記録で傾向を把握しやすい |
| 失敗するクエリは遅延も大きいか | durationとfailureを合わせて見られる |
| UI上のクエリ操作が遅くなっていないか | 成功時のdurationを比較できる |
| サポート調査時に再現性があるか | エラー情報と実行タイミングを追いやすい |
つまり、今回の更新は派手な機能追加ではありませんが、運用品質を上げるための地味に重要な改善です。
移行・展開上の注意点
今回の変更に対して、通常のAzure Cosmos DB利用者がデータベース移行を行う必要はありません。コンテナー設計、パーティションキー、インデックス、SDKコード、クエリ構文をこのPRのためだけに変更する必要もありません。
ただし、次のケースでは確認が必要です。
| 対象 | 確認すべきこと |
|---|---|
| Azure portal / Data Explorerを使う管理者 | Data Explorerの利用権限、RUしきい値、RBAC設定 |
| 本番環境で調査クエリを実行する開発者 | クエリ条件、取得件数、RU消費、実行時間 |
| cosmos-explorerを自前ビルドしているチーム | テレメトリ送信先、プライバシー、テスト、リリース手順 |
| 監視基盤を整備しているSRE/運用担当 | Azure Monitor、SDK Diagnostics、OpenTelemetryとの役割分担 |
| セキュリティ・監査担当 | エラーメッセージやアカウント情報の取り扱い |
また、GitHubのPRが master にマージされたことと、Azure portal上のすべての利用環境へ即時反映されることは同義ではありません。実際の反映タイミングは、Azure側のリリースサイクルや利用しているData Explorer環境によって異なる可能性があります。プレビューURLで確認できる内容も、本番反映済みの保証として扱わない方が安全です。
実務での確認チェックリスト
今回の更新を受けて、管理者と開発者は次の順に確認するとよいでしょう。
| 優先度 | 確認項目 | 具体的なアクション |
|---|---|---|
| 高 | 本番Data Explorerの利用者 | Azure RBAC、Entra ID RBAC、アクセス権を棚卸しする |
| 高 | RUしきい値 | Data Explorerの設定で高コストクエリを抑制する |
| 高 | 遅いクエリの判断基準 | Data ExplorerのdurationだけでなくQuery metricsも確認する |
| 中 | SDK側の監視 | DiagnosticsやOpenTelemetryの収集を確認する |
| 中 | クエリ設計 | パーティションキー条件、取得列、TOP、インデックスを見直す |
| 中 | エラー情報の扱い | error messageの共有・保存ルールを確認する |
| 低 | 自前ビルド版の影響 | cosmos-explorerフォークのテレメトリ実装を確認する |
Azure Cosmos DBの監視では、Azure Monitor Metrics Explorerを使って、サーバー側レイテンシ、RU使用量、正規化RU使用量などを分析できます。クライアント側では、request charge、activity ID、例外、HTTPステータス、診断文字列などの収集がトラブルシューティングに役立つと公式ドキュメントでも説明されています。(Microsoft Learn)
今回の更新をどう活用すべきか
今回のAzure Cosmos DB Data Explorer更新は、利用者の画面操作を劇的に変えるものではありません。しかし、クエリ実行の成功・失敗・durationを追跡できるようになることで、管理画面上の「遅い」「失敗する」「再現しない」といった問題を切り分けやすくなります。
管理者は、Data Explorerの権限とRUしきい値を見直してください。開発者は、Data Explorerのdurationをサーバー側メトリクスと混同せず、Query metrics、Azure Monitor、SDK Diagnostics、OpenTelemetryを組み合わせて確認しましょう。
次に取るべき行動は明確です。まず本番Cosmos DBでData Explorerを使えるユーザーを確認し、RUしきい値を設定します。そのうえで、よく使う調査クエリを見直し、パーティションキー条件や取得件数の制限を入れてください。今回のテレメトリ強化は、その改善効果を追いやすくするための土台になります。
コメント