Azure Cosmos DB SDK 可檢視性

適用於：NoSQL

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

開始

下列 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 資料庫規格，同時提供數個自訂屬性。根據您要求的作業，您可能會看到不同的屬性，而且這些屬性是所有要求的核心屬性。

屬性	類型	描述
`net.peer.name`	字串	Azure Cosmos DB 主機名稱。
`db.name`	字串	Azure Cosmos DB 資料庫名稱。
`db.system`	字串	資料庫服務的識別碼。是所有要求的 `cosmosdb`。
`db.operation`	字串	作業名稱，例如 `CreateItemAsync`.
`db.cosmosdb.container`	字串	Azure Cosmos DB 容器名稱。
`db.cosmosdb.client_id`	字串	代表唯一用戶端執行個體的識別碼。
`db.cosmosdb.operation_type`	字串	作業類型，例如 `Create`.
`db.cosmosdb.connection_mode`	字串	用戶端連線模式。 `direct` 或 `gateway`。
`db.cosmosdb.status_code`	int	要求的狀態碼。
`db.cosmosdb.sub_status_code`	int	要求的子狀態碼。
`db.cosmosdb.request_charge`	double	用於作業的 RU。
`db.cosmosdb.regions_contacted`	字串	Azure Cosmos DB 帳戶中所連絡區域的清單。
`user_agent.original`	字串	Azure Cosmos DB SDK 所產生的完整使用者代理人字串。

收集診斷

如果您已在追蹤提供者中設定記錄，則可以自動取得失敗或高延遲 Azure Cosmos DB 要求的診斷。這些記錄可協助您診斷失敗和緩慢要求，而不需要任何自訂程式碼來進行擷取。

.NET
Java

除了取得失敗要求的診斷記錄之外，您還可以設定何時從成功要求中收集診斷資料的不同延遲閾值。點作業的預設值為 1 秒，非點作業的預設值為 3 秒。這些閾值可以透過用戶端選項進行調整。

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"
        }
    }
}

除了取得失敗要求的診斷記錄之外，您還可以設定何時收集成功要求診斷的不同條件。條件包括點作業和非點作業的延遲閾值，以及超過 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
               "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 入口網站左側導覽中交易搜尋內跨分割區查詢的追蹤資料。

後續步驟

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-08-14