共用方式為

Azure Cosmos DB SDK 可觀察性

  • 適用於: ✅ NoSQL

Azure Cosmos DB、.NET 和 Java SDK 支援分散式追蹤，幫助你監控應用程式。 追蹤請求流程有助於除錯、分析延遲與效能，以及收集診斷資料。 使用 OpenTelemetry 為你的應用程式進行儀器追蹤，該系統對廠商中立，並有一套語意慣例，確保無論你選擇哪種匯出器都能達到標準化的資料格式;或者使用 Application Insights SDK 或 Azure Monitor OpenTelemetry Distro。

開始

分散式追蹤可在以下 SDK 中提供：

SDK 支援的版本 註釋
.NET v3 SDK >= 3.36.0 此功能提供預覽版與非預覽版兩種版本。 非預覽版本預設是關閉的。 你可以在 CosmosClientOptions.CosmosClientTelemetryOptions 中設定 DisableDistributedTracing = false 以啟用追蹤。
.NET v3 SDK preview >= 3.33.0-preview 此功能提供預覽版與非預覽版兩種版本。 預覽版預設是開啟的。 你可以透過設定 DisableDistributedTracing = trueCosmosClientOptions.CosmosClientTelemetryOptions來關閉追蹤。
Java v4 SDK >= 4.43.0

追蹤屬性

Azure Cosmos DB 追蹤遵循 OpenTelemetry 資料庫規範 ，並提供多項自訂屬性。 你可以根據請求的操作看到不同的屬性，而這些屬性是所有請求的核心屬性。

Attribute 類型 Description
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 雙倍 RUs被消耗在這次行動中。
db.cosmosdb.regions_contacted 字串 Azure Cosmos 資料庫帳戶中已聯絡的區域列表。
user_agent.original 字串 完整的用戶代理字串由 Azure Cosmos DB SDK 產生。

收集診斷資料

如果你在追蹤提供者中設定了日誌，可以自動取得 Azure Cosmos 資料庫中失敗或高延遲請求的診斷。 這些日誌可以幫助你診斷失敗或緩慢的請求，無需自訂程式碼來擷取。

除了取得失敗請求的診斷日誌外，你還可以設定不同的延遲閾值，決定何時從成功請求中收集診斷資料。 預設值為點式操作 1 秒，非點式操作 3 秒。 這些門檻可以透過客戶選項調整。

CosmosClientOptions options = new CosmosClientOptions()
{
    CosmosClientTelemetryOptions = new CosmosClientTelemetryOptions()
    {
        DisableDistributedTracing = false,
        CosmosThresholdOptions = new CosmosThresholdOptions()
        {
            PointOperationLatencyThreshold = TimeSpan.FromMilliseconds(100),
            NonPointOperationLatencyThreshold = TimeSpan.FromMilliseconds(500)
        }
    },
};

你可以設定日誌層級來控制你收到的診斷日誌。

記錄層級 Description
錯誤 僅記錄錯誤。
警告 根據設定的閾值，記錄錯誤與高延遲請求。
資訊 沒有特定的資訊層級日誌。 此等級的日誌等同於使用警告。

根據你的應用程式環境，有不同的方式來設定日誌層級。 以下是 appSettings.json 中的範例組態：

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

設定 OpenTelemetry

要將 OpenTelemetry 與 Azure Cosmos DB SDK 一起使用，請將 Azure.Cosmos.Operation 新增到您的追蹤提供者來源中。 OpenTelemetry 支援許多能匯入資料的匯出器。 以下範例使用 Azure Monitor OpenTelemetry Exporter，但你可以選擇設定任何你想要的匯出器。 根據你選擇的匯出器，資料擷取可能會延遲幾分鐘。

小提示

如果你使用該 Azure.Monitor.OpenTelemetry.Exporter 套件，請確保你使用的是 version >= 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 可能需要幾分鐘。

備註

針對你的目標 .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 入口網站中視覺化，了解應用程式中的請求流程。 這裡有一個 Azure 入口網站左側導覽中交易搜尋中跨分割區查詢的追蹤資料範例。

Azure Cosmos DB 跨分割區查詢在 Application Insights 交易搜尋中的分散式追蹤截圖。

後續步驟

  • Last updated on