Azure Cosmos DB SDK の監視
適用対象: 
NoSQL
Azure Cosmos DB .NET および Java SDK では、アプリケーションの監視に役立つ分散トレースがサポートされています。 要求のフローのトレースは、デバッグ、待機時間とパフォーマンスの分析、診断の収集に役立ちます。 OpenTelemetry を使用してアプリケーションのトレースをインストルメント化します。これはベンダーに依存せず、選択したエクスポーターに関係なく標準化されたデータ形式を確保するための一連のセマンティック規則を備えています。または、Application Insights SDK または Azure Monitor OpenTelemetry ディストリビューションを使用します。
作業の開始
分散トレースは、次の SDK で使用できます。
| SDK | サポートされているバージョン | メモ |
|---|---|---|
| .NET v3 SDK | >= 3.36.0 |
この機能は、プレビュー バージョンでも、プレビュー バージョン以外でも使用できます。 プレビュー バージョン以外では、既定でオフになっています。 トレースを有効にするには、CosmosClientOptions.CosmosClientTelemetryOptions で DisableDistributedTracing = false を設定します。 |
| .NET v3 SDK プレビュー | >= 3.33.0-preview |
この機能は、プレビュー バージョンでも、プレビュー バージョン以外でも使用できます。 プレビュー バージョンでは、既定でオンになっています。 CosmosClientOptions.CosmosClientTelemetryOptions で DisableDistributedTracing = true を設定することで、トレースを無効にすることができます。 |
| Java v4 SDK | >= 4.43.0 |
トレースの属性
Azure Cosmos DB トレースは、OpenTelemetry データベースの仕様に従い、いくつかのカスタム属性も提供します。 要求の操作に応じて異なる属性が表示される場合があり、これらの属性はすべての要求のコア属性です。
| 属性 | Type | 説明 |
|---|---|---|
net.peer.name |
string | Azure Cosmos DB ホスト名。 |
db.name |
string | Azure Cosmos DB データベース名。 |
db.system |
string | データベース サービスの識別子。 すべての要求に対して cosmosdb です。 |
db.operation |
string | 操作名、例: CreateItemAsync |
db.cosmosdb.container |
string | Azure Cosmos DB コンテナー名。 |
db.cosmosdb.client_id |
string | 一意のクライアント インスタンスを表す識別子。 |
db.cosmosdb.operation_type |
string | 操作の種類、例: Create |
db.cosmosdb.connection_mode |
string | クライアント接続モード。 direct または gateway のいずれかです。 |
db.cosmosdb.status_code |
INT | 要求のステータス コード。 |
db.cosmosdb.sub_status_code |
INT | 要求のサブ ステータス コード。 |
db.cosmosdb.request_charge |
double | 操作に使用された RU。 |
db.cosmosdb.regions_contacted |
string | Azure Cosmos DB アカウントで接続されているリージョンの一覧。 |
user_agent.original |
string | Azure Cosmos DB SDK によって生成された完全なユーザー エージェント文字列。 |
診断情報を収集する
トレース プロバイダーでログを構成した場合は、失敗した、または待機時間が長かった Azure Cosmos DB 要求の診断を自動的に取得できます。 これらのログは、失敗した要求と低速な要求を診断するのに役立ちます。カスタム コードで要求を捉える必要はありません。
失敗した要求の診断ログの取得だけではなく、成功した要求から診断を収集するタイミングに対してさまざまな待機時間のしきい値を構成できます。 既定値は、ポイント操作の場合は 100 ミリ秒、ポイント操作以外の場合は 500 ミリ秒です。 これらのしきい値は、クライアント オプションを使用して調整できます。
CosmosClientOptions options = new CosmosClientOptions()
{
CosmosClientTelemetryOptions = new CosmosClientTelemetryOptions()
{
DisableDistributedTracing = false,
CosmosThresholdOptions = new CosmosThresholdOptions()
{
PointOperationLatencyThreshold = TimeSpan.FromMilliseconds(100),
NonPointOperationLatencyThreshold = TimeSpan.FromMilliseconds(500)
}
},
};
ログ レベルを構成して、受信する診断ログを制御できます。
| ログ レベル | 説明 |
|---|---|
| エラー | エラーのみのログ。 |
| 警告 | 構成されたしきい値に基づくエラーと待機時間の長い要求のログ。 |
| 情報 | 特定の情報レベルのログはありません。 このレベルのログは、警告の使用と同じです。 |
アプリケーション環境に応じて、ログ レベルを構成する方法は異なります。 appSettings.json の構成例を次に示します。
{
"Logging": {
"LogLevel": {
"Azure-Cosmos-Operation-Request-Diagnostics": "Information"
}
}
}
OpenTelemetry を構成する
Azure Cosmos DB SDK で OpenTelemetry を使用するには、Azure.Cosmos.Operation ソースをトレース プロバイダーに追加します。 OpenTelemetry は、データを取り込むことができる多くのエクスポーターと互換性があります。 次の例では Azure Monitor OpenTelemetry Exporter を使用しますが、任意のエクスポーターを構成することもできます。 選択したエクスポーターによっては、最大数分のデータの取り込み遅延が発生する場合があります。
ヒント
Azure.Monitor.OpenTelemetry.Exporter パッケージを使用する場合は、バージョン >= 1.0.0-beta.11 を使用していることを確認します。
ASP.NET Core と Azure Monitor を使用している場合は、代わりに Azure Monitor OpenTelemetry ディストリビューションを使用することをお勧めします。
このサンプルでは、.NET コンソール アプリ向けに OpenTelemetry を構成する方法を示します。 GitHub で 完全なサンプル を参照してください。
ResourceBuilder resource = ResourceBuilder.CreateDefault().AddService(
serviceName: serviceName,
serviceVersion: "1.0.0");
// Set up logging to forward logs to chosen exporter
using ILoggerFactory loggerFactory
= LoggerFactory.Create(builder => builder
.AddConfiguration(configuration.GetSection("Logging"))
.AddOpenTelemetry(options =>
{
options.IncludeFormattedMessage = true;
options.SetResourceBuilder(resource);
options.AddAzureMonitorLogExporter(o => o.ConnectionString = aiConnectionString); // Set up exporter of your choice
}));
/*.AddFilter(level => level == LogLevel.Error) // Filter is irrespective of event type or event name*/
AzureEventSourceLogForwarder logforwader = new AzureEventSourceLogForwarder(loggerFactory);
logforwader.Start();
// Configure OpenTelemetry trace provider
AppContext.SetSwitch("Azure.Experimental.EnableActivitySource", true);
_traceProvider = Sdk.CreateTracerProviderBuilder()
.AddSource("Azure.Cosmos.Operation", // Cosmos DB source for operation level telemetry
"Sample.Application")
.AddAzureMonitorTraceExporter(o => o.ConnectionString = aiConnectionString) // Set up exporter of your choice
.AddHttpClientInstrumentation() // Added to capture HTTP telemetry
.SetResourceBuilder(resource)
.Build();
Application Insights SDK を構成する
Application Insights を構成するには、アプリケーションの記述言語とコンピューティング環境に応じて、さまざまな方法があります。 詳細については、Application Insights のドキュメントを参照してください。 Application Insights へのデータの取り込みには、最大で数分かかる場合があります。
Note
ターゲットの .NET 環境に Application Insights パッケージのバージョン >= 2.22.0-beta2 を使用します。
次のサンプルは、.NET コンソール アプリ向けに Application Insights を構成する方法を示しています。 GitHub で 完全なサンプル を参照してください。
IServiceCollection services = new ServiceCollection();
services.AddApplicationInsightsTelemetryWorkerService((ApplicationInsightsServiceOptions options) => options.ConnectionString = aiConnectionString);
IServiceProvider serviceProvider = services.BuildServiceProvider();
telemetryClient = serviceProvider.GetRequiredService<TelemetryClient>();
トレース データが Application Insights に取り込まれたら、Azure portal で視覚化して、アプリケーションの要求フローを理解できます。 Azure portal の左側のナビゲーションにあるトランザクション検索のクロス パーティション クエリからのトレース データの例を次に示します。
