Partilhar via

Observabilidade .NET com OpenTelemetry

  • Artigo

Ao executar um aplicativo, você quer saber o desempenho do aplicativo e detetar possíveis problemas antes que eles se tornem maiores. Você pode fazer isso emitindo dados de telemetria, como logs ou métricas, do seu aplicativo e, em seguida, monitorando e analisando esses dados.

O que é observabilidade?

A observabilidade no contexto de um sistema distribuído é a capacidade de monitorar e analisar a telemetria sobre o estado de cada componente, ser capaz de observar mudanças no desempenho e diagnosticar por que essas mudanças ocorrem. Ao contrário da depuração, que é invasiva e pode afetar a operação do aplicativo, a observabilidade destina-se a ser transparente para a operação principal e ter um impacto de desempenho pequeno o suficiente para que possa ser usada continuamente.

A observabilidade é comumente feita usando uma combinação de:

  • Logs, que registram operações individuais, como uma solicitação de entrada, uma falha em um componente específico ou um pedido sendo feito.
  • Métricas, que medem contadores e medidores, como número de solicitações concluídas, solicitações ativas, widgets que foram vendidos ou um histograma da latência da solicitação.
  • Rastreamento distribuído, que rastreia solicitações e atividades entre componentes em um sistema distribuído para que você possa ver onde o tempo é gasto e rastrear falhas específicas.

Juntos, logs, métricas e rastreamento distribuído são às vezes conhecidos como os três pilares da observabilidade.

Cada pilar pode incluir dados de telemetria de:

  • O tempo de execução do .NET, como o coletor de lixo ou o compilador JIT.
  • Bibliotecas, tais como de Kestrel (o servidor web ASP.NET) e HttpClient.
  • Telemetria específica do aplicativo emitida pelo seu código.

Abordagens de observabilidade no .NET

Há algumas maneiras diferentes de alcançar a observabilidade em aplicativos .NET:

  • Explicitamente no código, fazendo referência e usando uma biblioteca como OpenTelemetry. Se você tem acesso ao código-fonte e pode reconstruir o aplicativo, então este é o mecanismo mais poderoso e configurável.
  • Fora do processo usando o EventPipe. Ferramentas como dotnet-monitor podem ouvir logs e métricas e, em seguida, processá-los sem afetar nenhum código.
  • Usando um gancho de inicialização, montagens podem ser injetadas no processo que pode coletar instrumentação. Um exemplo dessa abordagem é a Instrumentação Automática OpenTelemetry .NET.

O que é OpenTelemetry?

OpenTelemetry (OTel) é um padrão aberto multiplataforma para coletar e emitir dados de telemetria. OpenTelemetry inclui:

  • APIs para bibliotecas usarem para registrar dados de telemetria enquanto o código está em execução.
  • APIs que os desenvolvedores de aplicativos usam para configurar qual parte dos dados gravados será enviada pela rede, para onde serão enviados e como podem ser filtrados, armazenados em buffer, enriquecidos e transformados.
  • As convenções semânticas fornecem orientação sobre nomenclatura e conteúdo de dados de telemetria. É importante que os aplicativos que produzem dados de telemetria e as ferramentas que recebem os dados concordem sobre o que diferentes tipos de dados significam e que tipos de dados são úteis para que as ferramentas possam fornecer análises eficazes.
  • Uma interface para exportadores. Os exportadores são plugins que permitem que os dados de telemetria sejam transmitidos em formatos específicos para diferentes back-ends de telemetria.
  • O protocolo de fio OTLP é uma opção de protocolo de rede neutro do fornecedor para transmitir dados de telemetria. Algumas ferramentas e fornecedores suportam este protocolo, além dos protocolos proprietários pré-existentes que podem ter.

O uso do OTel permite o uso de uma ampla variedade de sistemas APM, incluindo sistemas de código aberto como Prometheus e Grafana, Azure Monitor - o produto APM da Microsoft no Azure, ou dos muitos fornecedores de APM que fazem parceria com a OpenTelemetry.

Existem implementações OpenTelemetry para a maioria das linguagens e plataformas, incluindo .NET.

Implementação .NET de OpenTelemetry

A implementação do .NET OpenTelemetry é um pouco diferente de outras plataformas, pois o .NET fornece log, métricas e APIs de atividade na estrutura. Isso significa que o OTel não precisa fornecer APIs para os autores de bibliotecas usarem. A implementação do .NET OTel usa estas APIs de plataforma para instrumentação:

Arquitetura OTel do .NET

Onde o OTel entra em jogo é que ele coleta telemetria dessas APIs e outras fontes (por meio de bibliotecas de instrumentação) e, em seguida, exporta-as para um sistema de monitoramento de desempenho de aplicativos (APM) para armazenamento e análise. O benefício que o OTel traz como padrão do setor é um mecanismo comum para coleta, esquemas e semânticas comuns para dados de telemetria e uma API para como os APMs podem se integrar ao OTel. Usar OTel significa que os aplicativos não precisam usar APIs ou estruturas de dados específicas do APM; eles funcionam contra o padrão OTel. Os APMs podem implementar um componente de exportador específico do APM ou usar OTLP, que é um novo padrão de fio para exportar dados de telemetria para os sistemas APM.

Pacotes OpenTelemetry

OpenTelemetry no .NET é implementado como uma série de pacotes NuGet que formam algumas categorias:

  • API principal
  • Instrumentação - esses pacotes coletam instrumentação do tempo de execução e bibliotecas comuns.
  • Exportadores - estes fazem interface com sistemas APM como Prometheus, Jaeger e OTLP.

A tabela a seguir descreve os principais pacotes.

Nome do Pacote Description
OpenTelemetria Biblioteca principal que fornece a funcionalidade OTEL principal
OpenTelemetry.Instrumentation.AspNetCore Instrumentação para ASP.NET Core e Peneireiro-das-torres
OpenTelemetry.Instrumentation.GrpcNetClient Instrumentação para gRPC Client para rastrear chamadas gRPC de saída
OpenTelemetry.Instrumentation.Http Instrumentação para HttpClient e HttpWebRequest para rastrear chamadas HTTP de saída
OpenTelemetry.Instrumentation.SqlClient Instrumentação usada SqlClient para rastrear operações de banco de dados
OpenTelemetry.Exporter.Console Exportador para o console, comumente usado para diagnosticar qual telemetria está sendo exportada
OpenTelemetry.Exporter.OpenTelemetryProtocol Exportador que utiliza o protocolo OTLP
OpenTelemetry.Exportador.Prometheus.AspNetCore Exportador para Prometheus implementado usando um ponto de extremidade ASP.NET Core
OpenTelemetry.Exporter.Zipkin Exportador para Zipkin tracing

Exemplos

Este tópico é continuado com alguns exemplos passo a passo para usar OpenTelemetry no .NET:

OpenTelemetry no .NET Aspire

O .NET Aspire é um conjunto de extensões para o .NET para facilitar a criação e o trabalho com aplicativos distribuídos. Um dos benefícios de usar o .NET Aspire é que a telemetria é incorporada, usando as bibliotecas OpenTelemetry para .NET. Os modelos de projeto padrão para o .NET Aspire contêm um ServiceDefaults projeto, parte do qual é instalar e configurar o OTel. O projeto Service Defaults é referenciado e inicializado por cada serviço em uma solução .NET Aspire .

O modelo de projeto Service Defaults inclui os pacotes OTel SDK, ASP.NET, HttpClient e Runtime Instrumentation, e esses são configurados Extensions.cs no arquivo. Para exportar telemetria, o .NET Aspire inclui o exportador OTLP por padrão para que ele possa fornecer visualização de telemetria usando o Painel do Aspire .

O Painel do Aspire foi concebido para trazer a observação de telemetria para o ciclo de depuração local, o que permite aos programadores não só garantir que as aplicações estão a produzir telemetria, mas também utilizar essa telemetria para diagnosticar essas aplicações localmente. Ser capaz de observar as chamadas entre serviços está provando ser tão útil no momento da depuração quanto na produção. O painel do .NET Aspire é iniciado automaticamente quando você F5 o AppHost projeto do Visual Studio ou dotnet run do AppHost projeto.

Painel de instrumentos do Aspire

Para obter mais detalhes sobre o .NET Aspire consulte:

Reutilizando o projeto Service Defaults sem o .NET Aspire Orchestration

Provavelmente, a maneira mais fácil de configurar o OTel para projetos ASP.NET é usar o projeto Aspire Service Defaults, mesmo que não use o resto do .NET Aspire como o AppHost para orquestração. O projeto Service Defaults está disponível como um modelo de projeto via Visual Studio ou dotnet new. Ele configura OTel e configura o exportador OTLP. Em seguida, você pode usar as variáveis de ambiente OTel para configurar o ponto de extremidade OTLP para enviar telemetria e fornecer as propriedades do recurso para o aplicativo.

As etapas para usar ServiceDefaults fora do .NET Aspire são:

  • Adicione o projeto ServiceDefaults à solução usando Add New Project no Visual Studio ou use dotnet new aspire-servicedefaults --output ServiceDefaults
  • Faça referência ao projeto ServiceDefaults a partir do seu aplicativo ASP.NET. No Visual Studio, use "Add -> Project Reference" e selecione o projeto ServiceDefaults "
  • Chame sua função de configuração OpenTelemetry como parte da inicialização do seu construtor de aplicativos.
var builder = WebApplication.CreateBuilder(args);
builder.ConfigureOpenTelemetry();

var app = builder.Build();

app.MapGet("/", () => "Hello World!");

app.Run();

Os Padrões de Serviço podem configurar as seguintes funcionalidades adicionais, se necessário, por meio AddServiceDefaults() ou das funções específicas:

  • Verificações de integridade com /health e /alive pontos finais
  • Descoberta de serviço que será um no-op sem o resto do .NET Aspire
  • Configurando a resiliência para HttpClient que tentará novamente a solicitação no caso de falhas