Compartir a través de


Observabilidad del SDK de Azure Cosmos DB

SE APLICA A: NoSQL

Los SDK para .NET y Java de Azure Cosmos DB admiten el seguimiento distribuido para ayudarle a supervisar las aplicaciones. El seguimiento del flujo de solicitudes es ú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 bien use el SDK de Application Insights o la distribución OpenTelemetry de Azure Monitor.

Introducción

El seguimiento distribuido está disponible en los siguientes SDK:

SDK Versión admitida Notas
SDK de .NET v3 >= 3.36.0 Esta característica está disponible en versiones preliminares y no en versión preliminar. En el caso de las versiones que no son de versión preliminar, se desactiva de forma predeterminada. Puede activar el rastreo configurando DisableDistributedTracing = false en CosmosClientOptions.CosmosClientTelemetryOptions.
Vista previa.NET v3 SDK >= 3.33.0-preview Esta característica está disponible en versiones preliminares y no en versión preliminar. Para las versiones preliminares, se activa de forma predeterminada. Puede deshabilitar el seguimiento si establece DisableDistributedTracing = true en CosmosClientOptions.CosmosClientTelemetryOptions.
SDK de Java v4 >= 4.43.0

Seguimiento de atributos

Los seguimientos de Azure Cosmos DB siguen la especificación de la base de datos OpenTelemetry y también proporcionan varios atributos personalizados. Es posible que vea otros atributos según el funcionamiento de la solicitud y estos atributos son atributos principales para todas las solicitudes.

Attribute Tipo Description
net.peer.name string Nombre de host de Azure Cosmos DB.
db.name string Nombre de la base de datos de Azure Cosmos DB.
db.system string Identificador del servicio de base de datos. Es cosmosdb para todas las solicitudes.
db.operation string Nombre de la operación, por ejemplo, CreateItemAsync.
db.cosmosdb.container string Nombre del contenedor de Azure Cosmos DB.
db.cosmosdb.client_id string Identificador que representa una instancia de cliente única.
db.cosmosdb.operation_type string Tipo de operación, por ejemplo, Create.
db.cosmosdb.connection_mode string Modo de conexión del cliente. direct o gateway.
db.cosmosdb.status_code int Código de estado de la solicitud.
db.cosmosdb.sub_status_code int Subcódigo de estado de la solicitud.
db.cosmosdb.request_charge double RU consumidas para la operación.
db.cosmosdb.regions_contacted string Lista de regiones contactadas en la cuenta de Azure Cosmos DB.
user_agent.original string Cadena de agente de usuario completa generada por el SDK de Azure Cosmos DB.

Recopilación de información de diagnóstico

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

Además de obtener registros de diagnóstico para las solicitudes con errores, puede configurar otras condiciones para cuándo recopilar diagnósticos de las solicitudes correctas. Los valores predeterminados son 100 ms para las operaciones de punto y 500 ms para las operaciones que no son de punto. Estos umbrales se pueden ajustar a través de las opciones de cliente.

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

Puede configurar el nivel de registro para controlar qué registros de diagnóstico recibe.

Nivel de registro Descripción
Error Solo registros de errores.
Advertencia Registra errores y solicitudes de alta latencia en función de los umbrales configurados.
Información No hay registros de nivel de información específicos. Los registros de este nivel son los mismos que el uso de advertencias.

En función del entorno de la aplicación, hay otras maneras de configurar el nivel de registro. Esta es una configuración de ejemplo de appSettings.json:

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

Configuración de OpenTelemetry

En esta sección se describe la configuración necesaria para el SDK de Java de Azure Cosmos DB y los SDK de .NET.

Para usar OpenTelemetry con el SDK de .NET de Azure Cosmos DB, agregue el origen Azure.Cosmos.Operation al proveedor de seguimiento. OpenTelemetry es compatible con muchos exportadores que pueden ingerir los datos. En el ejemplo siguiente se usa Azure Monitor OpenTelemetry Exporter, pero puede elegir configurar cualquier exportador que quiera. Según el exportador elegido, es posible que vea un retraso en la ingesta de datos de hasta unos minutos.

Sugerencia

Si usa el paquete Azure.Monitor.OpenTelemetry.Exporter, asegúrese de que utiliza la versión >= 1.0.0-beta.11. Si usa ASP.NET Core y Azure Monitor, en su lugar se recomienda utilizar la distribución OpenTelemetry de Azure Monitor.

En este ejemplo se muestra cómo configurar OpenTelemetry para una aplicación de consola de .NET. Vea 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 escriba la aplicación y el entorno de proceso. Para más información, vea la documentación de Application Insights. La ingesta de datos en Application Insights puede tardar varios minutos.

Nota:

Use la version >= 2.22.0-beta2 del paquete de Application Insights para el entorno de .NET de destino.

En el ejemplo siguiente se muestra cómo configurar Application Insights para una aplicación de consola de .NET. Vea 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 han ingerido en Application Insights, puede visualizarlos en Azure Portal para comprender el flujo de solicitudes en la aplicación. Este es un ejemplo de datos de seguimiento de una consulta entre particiones en la búsqueda de transacciones en el panel de navegación izquierdo de Azure Portal.

Captura de pantalla del seguimiento distribuido de una consulta entre particiones de Azure Cosmos DB en la búsqueda de transacciones de Application Insights.

Pasos siguientes