Azure Cosmos DB SDK 可檢視性

發行項
03/20/2024

適用於：NoSQL

Azure Cosmos DB .NET 和 Java SDK 支援分散式追蹤，以協助您監視應用程式。追蹤要求流程有助於偵錯、分析延遲和效能，以及收集診斷。使用 OpenTelemetry 來檢測應用程式的追蹤，而 OpenTelemetry 與廠商無關，並且具有一組語意慣例來確保標準化資料格式 (不論您所選擇的匯出工具為何)，或使用 Application Insights SDK 或 Azure 監視器 OpenTelemetry Distro。

開始使用

下列 SDK 提供分散式追蹤：

SDK	支援的版本	備註
.NET v3 SDK	>= `3.33.0-preview`	如果您要使用支援的預覽 SDK 版本，則此功能預設為開啟。您可以在 `CosmosClientOptions` 中設定 `IsDistributedTracingEnabled = false` 來停用追蹤。
Java v4 SDK	>= `4.43.0`

追蹤屬性

Azure Cosmos DB 追蹤會遵循 OpenTelemetry 資料庫規格，同時提供數個自訂屬性。根據您要求的作業，您可能會看到不同的屬性，而且這些屬性是所有要求的核心屬性。

屬性	類型	描述
`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 要求的診斷。這些記錄可協助您診斷失敗和緩慢要求，而不需要任何自訂程式碼來進行擷取。

.NET
Java

除了取得失敗要求的診斷記錄之外，取用超過 100 毫秒的點作業以及取用超過 500 毫秒的查詢作業也會產生診斷。您可以設定記錄層級來控制您所收到的診斷記錄。

記錄層級	描述
錯誤	僅限錯誤的記錄。
警告	錯誤和高延遲要求的記錄。
資訊	沒有特定資訊層級記錄。此層級中的記錄與使用「警告」相同。

根據您的應用程式環境，有不同的方式可以設定記錄層級。以下是 appSettings.json 中的範例設定：

{ 
    "Logging": {
        "LogLevel": {
            "Azure-Cosmos-Operation-Request-Diagnostics": "Information"
        }
    }
}

除了取得失敗要求的診斷記錄之外，您還可以設定何時收集成功要求診斷的不同條件。條件包括點作業和非點作業的延遲閾值，以及超過 RU 數目的要求閾值。您可以在 Azure Cosmos DB 用戶端中設定這些閾值。

    CosmosAsyncClient client = new CosmosClientBuilder()
            .endpoint("<Your account endpoint>")
            .key("<Your account key>")
            .clientTelemetryConfig(new CosmosClientTelemetryConfig()
                .diagnosticsThresholds(
                    new CosmosDiagnosticsThresholds()
                        .setPointOperationLatencyThreshold(Duration.ofMillis(100))
                        .setNonPointOperationLatencyThreshold(Duration.ofMillis(2000))
                        .setRequestChargeThreshold(100)))
            .buildAsyncClient();

設定 OpenTelemetry

若要搭配使用 OpenTelemetry 與 Azure Cosmos DB SDK，請將 Azure.Cosmos.Operation 來源新增至您的追蹤提供者。 OpenTelemetry 與許多可內嵌資料的匯出工具相容。下列範例使用 Azure Monitor OpenTelemetry Exporter，但您可以選擇設定您想要的任何匯出工具。根據您選擇的匯出工具，您可能會看到最多幾分鐘的延遲內嵌資料。

提示

如果您使用 Azure.Monitor.OpenTelemetry.Exporter 套件，則請確定使用版本 >= 1.0.0-beta.11。如果您要使用 ASP.NET Core 和 Azure 監視器，則建議您改用 Azure 監視器 OpenTelemetry Distro。

此範例顯示如何設定 .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
               "Azure.Cosmos.Request", // Cosmos DB source for DIRECT Mode network request 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 可能需要幾分鐘的時間。

注意

針對目標 .NET 環境，使用版本 >= 2.22.0-beta2 的 Application Insights 套件。

下列範例顯示如何設定 .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 入口網站中將其可視化，以瞭解應用程式中的要求流程。以下範例說明來自 Azure 入口網站左側導覽中交易搜尋內跨分割區查詢的追蹤資料。

Share via