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
Para usar OpenTelemetry con los SDK 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.
