Observabilidade do SDK do Azure Cosmos DB
APLICA-SE A: 
NoSQL
Os SDKs do .NET e Java do Azure Cosmos DB dão suporte ao rastreamento distribuído para ajudá-lo a monitorar seus aplicativos. O rastreamento do fluxo de solicitações é útil na depuração, na análise da latência e do desempenho e na coleta de diagnóstico. O rastreamento de instrumentos para seus aplicativos usando o OpenTelemetry, que é neutro em relação a fornecedores e tem um conjunto de convenções semânticas para garantir um formato de dados padronizado, independentemente do exportador escolhido, ou use o SDK do Application Insights ou o OpenTelemetry Distro do Azure Monitor.
Introdução
O rastreamento distribuído está disponível nos seguintes SDKs:
| . | Versão compatível | Observações |
|---|---|---|
| SDK v3 do .NET | >= 3.36.0 |
Esse recurso está disponível nas versões prévias ou não. Para versões não prévias, isto está desativado por padrão. Você pode habilitar o rastreamento definindo DisableDistributedTracing = false em CosmosClientOptions.CosmosClientTelemetryOptions. |
| Versão prévia do SDK do .NET v3 | >= 3.33.0-preview |
Esse recurso está disponível nas versões prévias ou não. Para versões prévias, isto está ativado por padrão. Você pode desabilitar o rastreamento definindo DisableDistributedTracing = true em CosmosClientOptions.CosmosClientTelemetryOptions. |
| SDK do Java v4 | >= 4.43.0 |
Atributos de rastreamento
Os rastreamentos do Azure Cosmos DB seguem a Especificação do banco de dados OpenTelemetry e também fornecem vários atributos personalizados. Você pode ver atributos diferentes dependendo da operação de sua solicitação e esses atributos são atributos principais para todas as solicitações.
| Atributo | Tipo | Descrição |
|---|---|---|
net.peer.name |
string | Nome do host do Azure Cosmos DB. |
db.name |
string | Nome do banco de dados do Azure Cosmos DB. |
db.system |
string | Identificador do serviço do banco de dados. cosmosdb é para todas as solicitações. |
db.operation |
string | Nome da operação, por exemplo CreateItemAsync. |
db.cosmosdb.container |
string | Nome do contêiner do Azure Cosmos DB. |
db.cosmosdb.client_id |
string | Identificador que representa uma instância de cliente exclusiva. |
db.cosmosdb.operation_type |
string | Tipo de operação, por exemplo Create. |
db.cosmosdb.connection_mode |
string | Modo de conexão do cliente. direct ou gateway. |
db.cosmosdb.status_code |
INT | O código de status da solicitação. |
db.cosmosdb.sub_status_code |
INT | O código de substatus HTTP da solicitação. |
db.cosmosdb.request_charge |
double | RUs consumidas para a operação. |
db.cosmosdb.regions_contacted |
string | Lista de regiões contatadas na conta do Azure Cosmos DB. |
user_agent.original |
string | Cadeia de caracteres completa do agente do usuário gerada pelo SDK do Azure Cosmos DB. |
Coletar diagnóstico
Se você configurou logs em seu provedor de rastreamento, poderá obter automaticamente diagnósticos para solicitações do Azure Cosmos DB que falharam ou tiveram alta latência. Esses logs podem ajudá-lo a diagnosticar solicitações com falha e lentas sem exigir código personalizado para capturá-las.
Além de obter logs de diagnóstico para solicitações com falha, você pode configurar diferentes limites de latência para quando coletar diagnóstico de solicitações bem-sucedidas. Os valores padrão são 100 ms para operações de ponto e 500 ms para operações não de ponto. Esses limites podem ser ajustados por meio de opções de cliente.
CosmosClientOptions options = new CosmosClientOptions()
{
CosmosClientTelemetryOptions = new CosmosClientTelemetryOptions()
{
DisableDistributedTracing = false,
CosmosThresholdOptions = new CosmosThresholdOptions()
{
PointOperationLatencyThreshold = TimeSpan.FromMilliseconds(100),
NonPointOperationLatencyThreshold = TimeSpan.FromMilliseconds(500)
}
},
};
Você pode configurar o nível de log para controlar quais logs de diagnóstico você recebe.
| Nível de log | Descrição |
|---|---|
| Erro | Logs somente para erros. |
| Aviso | Logs de erros e solicitações de alta latência com base nos limites configurados. |
| Informações | Não há logs de nível de informação específicos. Os logs nesse nível são iguais ao uso de Aviso. |
Dependendo do ambiente do aplicativo, há diferentes maneiras de configurar o nível de log. Veja uma configuração de exemplo em appSettings.json:
{
"Logging": {
"LogLevel": {
"Azure-Cosmos-Operation-Request-Diagnostics": "Information"
}
}
}
Configurar o OpenTelemetry
Para usar o OpenTelemetry com os SDKs do Azure Cosmos DB, adicione a fonte Azure.Cosmos.Operation ao provedor de rastreamento. O OpenTelemetry é compatível com muitos exportadores que podem ingerir seus dados. O exemplo a seguir usa o Azure Monitor OpenTelemetry Exporter, mas você pode optar por configurar qualquer exportador desejado. Dependendo do exportador escolhido, você poderá ver um atraso na ingestão de dados de até alguns minutos.
Dica
Se você usar o pacote Azure.Monitor.OpenTelemetry.Exporter, verifique se está usando a versão >= 1.0.0-beta.11.
Se você estiver usando ASP.NET Core e o Azure Monitor, recomendamos usar o OpenTelemetry Distro do Azure Monitor.
Este exemplo mostra como configurar o OpenTelemetry para um aplicativo de console .NET. Confira o exemplo completo no 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();
Configurar o SDK do Application Insights
Há várias maneiras diferentes de configurar o Application Insights, dependendo da linguagem em que seu aplicativo é gravado e do ambiente de computação. Para obter mais informações, consulte a documentação do Application Insights. A ingestão de dados no Application Insights pode levar até alguns minutos.
Observação
Use a versão >= 2.22.0-beta2 do pacote do Application Insights para seu ambiente .NET de destino.
O exemplo a seguir mostra como configurar o Application Insights para um aplicativo de console do .NET. Confira o exemplo completo no GitHub.
IServiceCollection services = new ServiceCollection();
services.AddApplicationInsightsTelemetryWorkerService((ApplicationInsightsServiceOptions options) => options.ConnectionString = aiConnectionString);
IServiceProvider serviceProvider = services.BuildServiceProvider();
telemetryClient = serviceProvider.GetRequiredService<TelemetryClient>();
Depois que os dados de rastreamento forem ingeridos no Application Insights, você poderá visualizá-los no portal do Azure para entender o fluxo de solicitação em seu aplicativo. Aqui está um exemplo de dados de rastreamento de uma consulta de partição cruzada na pesquisa de transações na navegação à esquerda do portal do Azure.
