Observabilidad del SDK de Azure Cosmos DB

Los SDK de .NET y Java de Azure Cosmos DB admiten el seguimiento distribuido para ayudarle a supervisar las aplicaciones. El seguimiento del flujo de solicitudes resulta útil para depurar, analizar la latencia y el rendimiento y recopilar diagnósticos. Instrumente el seguimiento de las aplicaciones mediante OpenTelemetry, que es independiente del proveedor y tiene un conjunto de convenciones semánticas para garantizar un formato de datos estandarizado independientemente del exportador elegido, o use el SDK de Application Insights o la distribución de OpenTelemetry de Azure Monitor.

Empieza ahora

El seguimiento distribuido está disponible en los siguientes SDK:

Atributos de seguimiento

Los seguimientos de Azure Cosmos DB siguen la especificación de base de datos OpenTelemetry y también proporcionan varios atributos personalizados. Puede ver atributos diferentes en función del funcionamiento de la solicitud y estos atributos son atributos principales para todas las solicitudes.

Recopilación de diagnósticos

Si configuró registros en el proveedor de seguimiento, puede obtener automáticamente diagnósticos para solicitudes de Azure Cosmos DB con errores o con una latencia alta. Estos registros pueden ayudarle a diagnosticar solicitudes con errores y lentas sin necesidad de ningún código personalizado para capturarlos.

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

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

    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();

Configuración de OpenTelemetry

Para usar OpenTelemetry con los SDK de Azure Cosmos DB, agregue el Azure.Cosmos.Operation origen al proveedor de seguimiento. OpenTelemetry es compatible con muchos exportadores que pueden ingerir tus datos. En el ejemplo siguiente se usa Azure Monitor OpenTelemetry Exporter, pero puede elegir configurar cualquier exportador que desee. Dependiendo del exportador elegido, puede haber un retraso en la ingestión de datos de hasta unos minutos.

En este ejemplo se muestra cómo configurar OpenTelemetry para una aplicación de consola de .NET. Consulte el ejemplo completo en 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();

Configuración del SDK de Application Insights

Hay muchas maneras diferentes de configurar Application Insights en función del lenguaje en el que se escribe la aplicación y el entorno de proceso. Para más información, consulte la documentación de Application Insights. La ingesta de datos en Application Insights puede tardar hasta unos minutos.

En el ejemplo siguiente se muestra cómo configurar Application Insights para una aplicación de consola de .NET. Consulte el ejemplo completo en GitHub.

IServiceCollection services = new ServiceCollection();
services.AddApplicationInsightsTelemetryWorkerService((ApplicationInsightsServiceOptions options) => options.ConnectionString = aiConnectionString);

IServiceProvider serviceProvider = services.BuildServiceProvider();
telemetryClient = serviceProvider.GetRequiredService<TelemetryClient>();

Una vez que los datos de seguimiento se ingieren en Application Insights, puede visualizarlos en Azure Portal para comprender el flujo de solicitudes de la aplicación. Este es un ejemplo de datos de seguimiento de una consulta entre particiones en la búsqueda de transacciones en la navegación izquierda del portal de Azure.

Pasos siguientes

• Introducción al SDK de .NET
• Introducción al SDK de Java
• Supervisión de Azure Cosmos DB