Biblioteca de clientes do Exportador do Azure Monitor para .NET – versão 1.0.0

Artigo
10/03/2023

Os exportadores .NET do OpenTelemetry que enviam dados de telemetria para o Azure Monitor seguindo a Especificação do OpenTelemetry.

Introdução

Pré-requisitos

Assinatura do Azure: Para usar os serviços do Azure, incluindo o Exportador do Azure Monitor para OpenTelemetry .NET, você precisará de uma assinatura. Se você não tiver uma conta existente do Azure, poderá se inscrever para uma avaliação gratuita ou usar seus benefícios de assinatura do Visual Studio ao criar uma conta.
cadeia de conexão do Aplicativo Azure Insights: para enviar dados de telemetria para o serviço de monitoramento, você precisará da cadeia de conexão do Aplicativo Azure Insights. Se você não estiver familiarizado com a criação de recursos do Azure, convém seguir o guia passo a passo para Criar um recurso do Application Insights e copiar a cadeia de conexão.

Instalar o pacote

Versão mais recente:

Instale o Exportador do Azure Monitor para OpenTelemetry .NET com o NuGet:

dotnet add package Azure.Monitor.OpenTelemetry.Exporter

Builds noturnos

Os builds noturnos estão disponíveis no feed de desenvolvimento deste repositório. Eles são fornecidos sem suporte e não se destinam a cargas de trabalho de produção.

Adicionar o exportador

Os exemplos a seguir demonstram como adicionar o à configuração do AzureMonitorExporter OpenTelemetry.

Rastreamentos

Sdk.CreateTracerProviderBuilder()
    .AddAzureMonitorTraceExporter(o => o.ConnectionString = "InstrumentationKey=00000000-0000-0000-0000-000000000000")
    .Build();

Para obter um exemplo completo, consulte TraceDemo.cs.

Métricas

Sdk.CreateMeterProviderBuilder()
    .AddAzureMonitorMetricExporter(o => o.ConnectionString = "InstrumentationKey=00000000-0000-0000-0000-000000000000")
    .Build();

Para obter um exemplo completo, consulte MetricDemo.cs.

Logs

LoggerFactory.Create(builder =>
{
    builder.AddOpenTelemetry(options =>
    {
        options.AddAzureMonitorLogExporter(o => o.ConnectionString = "InstrumentationKey=00000000-0000-0000-0000-000000000000");
    });
});

Para obter um exemplo completo, consulte LogDemo.cs.

Autenticar o cliente

A autenticação do AAD (Azure Active Directory) é um recurso opcional que pode ser usado com o Exportador do Azure Monitor. Isso é facilitado com a biblioteca de Identidade do Azure, que fornece suporte para autenticar clientes do SDK do Azure com seus serviços do Azure correspondentes.

Há duas opções para habilitar a autenticação do AAD. Observe que, se ambos tiverem sido definidos, AzureMonitorExporterOptions terá precedência.

Defina o como Credential o AzureMonitorExporterOptions.

var credential = new DefaultAzureCredential();

Sdk.CreateTracerProviderBuilder()
    .AddAzureMonitorTraceExporter(o =>
    {
        o.ConnectionString = "InstrumentationKey=00000000-0000-0000-0000-000000000000";
        o.Credential = credential;
    })
    .Build();

Forneça seu Credential ao método AddAzureMonitorExporter.

var credential = new DefaultAzureCredential();

Sdk.CreateTracerProviderBuilder()
    .AddAzureMonitorTraceExporter(o => o.ConnectionString = "InstrumentationKey=00000000-0000-0000-0000-000000000000", credential)
    .Build();

Principais conceitos

Alguns dos principais conceitos do .NET incluem:

Visão geral do rastreamento distribuído do .NET: o rastreamento distribuído é uma técnica de diagnóstico que ajuda os engenheiros a localizar falhas e problemas de desempenho em aplicativos, especialmente aqueles que podem ser distribuídos entre vários computadores ou processos.
Visão geral do registro em log no .NET: o .NET dá suporte a uma API de registro em log que funciona com uma variedade de provedores de log internos e de terceiros.

Alguns dos principais conceitos do Azure Monitor incluem:

Endereços IP usados pelo Azure Monitor: esse exportador envia rastreamentos para o recurso do Azure Monitor configurado usando HTTPS. Talvez seja necessário conhecer os endereços IP se o aplicativo ou a infraestrutura que você está monitorando estiver hospedada atrás de um firewall.

Alguns dos principais conceitos do OpenTelemetry incluem:

OpenTelemetry: OpenTelemetry é um conjunto de bibliotecas usadas para coletar e exportar dados de telemetria (métricas, logs e rastreamentos) para análise para entender o desempenho e o comportamento do software.
Instrumentação: a capacidade de chamar a API OpenTelemetry diretamente por qualquer aplicativo é facilitada pela instrumentação. Uma biblioteca que habilita a observabilidade do OpenTelemetry para outra biblioteca é chamada de Biblioteca de Instrumentação.
Sinal de rastreamento: rastreamento refere-se ao rastreamento distribuído. Ele pode ser considerado como um DAG (grafo direcionado acíclico) de Spans, em que as bordas entre intervalos são definidas como relação pai/filho.
Amostragem: a amostragem é um mecanismo para controlar o ruído e a sobrecarga introduzidos pelo OpenTelemetry, reduzindo o número de amostras de rastreamentos coletados e enviados para o back-end.
Sinal de Métrica: o OpenTelemetry permite registrar medidas ou métricas brutas com agregação predefinida e um conjunto de atributos (dimensões).
Sinal de Log: uma gravação de um evento. Normalmente, o registro inclui um carimbo de data/hora que indica quando o evento aconteceu, bem como outros dados que descrevem o que aconteceu, onde aconteceu etc.

Para obter mais informações sobre o projeto OpenTelemetry, examine as Especificações do OpenTelemetry.

Exemplos

Consulte para Program.cs obter uma demonstração completa.

Solução de problemas

O exportador de Azure Monitor usa EventSource para seu próprio registro interno. Os logs do exportador estão disponíveis para qualquer EventListener, optando pela fonte denominada "OpenTelemetry-AzureMonitor-exportador".

O OpenTelemetry também fornece seu próprio recurso de diagnóstico para coletar logs internos. Um exemplo disso está disponível em nosso projeto de demonstração aqui.

Próximas etapas

Para obter mais informações sobre o SDK do Azure, consulte este site

Participante

Consulte CONTRIBUTING.md para obter detalhes sobre o processo de contribuição.