共用方式為

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

若要搭配使用 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 入口網站左側導覽中交易搜尋內跨分割區查詢的追蹤資料。

Application Insights 交易搜尋中 Azure Cosmos DB 跨分割區查詢的分散式追蹤螢幕快照。

後續步驟