Observabilidade do SDK do Azure Cosmos DB
APLICA-SE A: 
NoSQL
Os SDKs do Azure Cosmos DB .NET e Java oferecem 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 de latência e desempenho e na coleta de diagnósticos. Rastreamento de instrumentos para seus aplicativos usando OpenTelemetry, que é independente do fornecedor 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 a Distro OpenTelemetry do Azure Monitor.
Começar agora
O rastreamento distribuído está disponível nos seguintes SDKs:
| SDK | Versão suportada | Notas |
|---|---|---|
| SDK do .NET v3 | >= 3.36.0 |
Esta funcionalidade está disponível nas versões de pré-visualização e não pré-visualização. Para versões que não são de pré-visualização, está desativado por predefinição. Você pode habilitar o rastreamento definindo DisableDistributedTracing = false em CosmosClientOptions.CosmosClientTelemetryOptions. |
| Visualização do SDK do .NET v3 | >= 3.33.0-preview |
Esta funcionalidade está disponível nas versões de pré-visualização e não pré-visualização. Para versões de visualização, ele está ativado por padrão. Você pode desativar o rastreamento definindo DisableDistributedTracing = true em CosmosClientOptions.CosmosClientTelemetryOptions. |
| Java v4 SDK | >= 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 diferentes atributos, dependendo da operação da sua solicitação, e esses atributos são atributos principais para todas as solicitações.
| Atributo | Tipo | Description |
|---|---|---|
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 de banco de dados. É cosmosdb para todos os pedidos. |
db.operation |
string | Nome da operação, ex. 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, ex. Create. |
db.cosmosdb.connection_mode |
string | Modo de conexão do cliente. direct ou gateway. |
db.cosmosdb.status_code |
número inteiro | Código de status para a solicitação. |
db.cosmosdb.sub_status_code |
número inteiro | Sub código de status para a solicitação. |
db.cosmosdb.request_charge |
duplo | RUs consumidos 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. |
Reunir diagnósticos
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 lentas e com falha sem exigir nenhum código personalizado para capturá-las.
Além de obter logs de diagnóstico para solicitações com falha, você pode configurar limites de latência diferentes para quando coletar diagnósticos de solicitações bem-sucedidas. Os valores padrão são 100 ms para operações pontuais e 500 ms para operações sem ponto. Esses limites podem ser ajustados através das opções do 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 do registo | Description |
|---|---|
| Erro | Registra apenas erros. |
| Aviso | Registra erros e solicitações de alta latência com base em limites configurados. |
| Informação | Não existem registos de nível de informação específicos. Os logs neste nível são os mesmos que usar Aviso. |
Dependendo do ambiente do aplicativo, há diferentes maneiras de configurar o nível de log. Aqui está um exemplo de configuração em appSettings.json:
{
"Logging": {
"LogLevel": {
"Azure-Cosmos-Operation-Request-Diagnostics": "Information"
}
}
}
Configurar OpenTelemetry
Para usar o OpenTelemetry com os SDKs do Azure Cosmos DB, adicione a Azure.Cosmos.Operation origem ao seu provedor de rastreamento. 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ê pode ver um atraso na ingestão de dados de até alguns minutos.
Gorjeta
Se você usar o pacote, certifique-se de que está usando a Azure.Monitor.OpenTelemetry.Exporter versão >= 1.0.0-beta.11.
Se você estiver usando o ASP.NET Core e o Azure Monitor, recomendamos usar a Distro OpenTelemetry do Azure Monitor.
Este exemplo mostra como configurar o OpenTelemetry para um aplicativo de console .NET. Veja 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á muitas maneiras diferentes de configurar o Application Insights, dependendo do idioma em que seu aplicativo está escrito e do seu 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.
Nota
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 .NET. Veja 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 são ingeridos no Application Insights, você pode visualizá-los no portal do Azure para entender o fluxo de solicitações em seu aplicativo. Aqui está um exemplo de dados de rastreamento de uma consulta entre partições na pesquisa de transações na navegação esquerda do portal do Azure.
