Partilhar via


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.

Captura de tela do rastreamento distribuído de uma consulta entre partições do Azure Cosmos DB na pesquisa de transações do Application Insights.

Passos Seguintes