Exemplo: Utilizar OpenTelemetry com OTLP e o Aspire Dashboard autónomo

Este artigo é um de uma série de exemplos para ilustrar a observabilidade do .NET com OpenTelemetry.

Para além de ser uma parte padrão do Aspire, o Aspire Dashboard está disponível como um contentor Docker independente, que fornece um endpoint OTLP para onde a telemetria pode ser enviada. O painel visualiza os registos, métricas e traços. Usar o dashboard desta forma não depende do Aspire, e visualiza a telemetria de qualquer aplicação que a envie via OTLP. Funciona igualmente bem para aplicações escritas em Java, GoLang ou Python, desde que consigam enviar a sua telemetria para um endpoint OTLP.

Usar o Aspire Dashboard tem menos passos de configuração e configuração do que usar soluções Open Source como Prometheus, Grafana e Jaeger. Mas, ao contrário dessas ferramentas, o Aspire Dashboard destina-se a ser uma ferramenta de visualização para programadores, e não para monitorização de produção.

1. Crie o projeto

Crie um projeto de API Web simples usando o modelo ASP.NET Core Empty no Visual Studio ou o seguinte comando da CLI do .NET:

dotnet new web

2. Adicione métricas e definições de atividade

O código a seguir define uma nova métrica (greetings.count) para o número de vezes que a API foi chamada e uma nova fonte de atividade (Otel.Example).

// Custom metrics for the application
var greeterMeter = new Meter("OTel.Example", "1.0.0");
var countGreetings = greeterMeter.CreateCounter<int>("greetings.count", description: "Counts the number of greetings");

// Custom ActivitySource for the application
var greeterActivitySource = new ActivitySource("OTel.Example");

3. Criar um endpoint da API

Insira o seguinte código entre builder.Build(); e app.Run()

app.MapGet("/", SendGreeting);

Insira a seguinte função na parte inferior do ficheiro:

async Task<string> SendGreeting(ILogger<Program> logger)
{
    // Create a new Activity scoped to the method
    using var activity = greeterActivitySource.StartActivity("GreeterActivity");

    // Log a message
    logger.LogInformation("Sending greeting");

    // Increment the custom counter
    countGreetings.Add(1);

    // Add a tag to the Activity
    activity?.SetTag("greeting", "Hello World!");

    return "Hello World!";
}

4. Faça referência aos pacotes OpenTelemetry

Use o Gerenciador de Pacotes NuGet ou a linha de comando para adicionar os seguintes pacotes NuGet:

  <ItemGroup>
    <PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.9.0" />
    <PackageReference Include="OpenTelemetry.Extensions.Hosting" Version="1.9.0" />
    <PackageReference Include="OpenTelemetry.Instrumentation.AspNetCore" Version="1.9.0" />
    <PackageReference Include="OpenTelemetry.Instrumentation.Http" Version="1.9.0" />
  </ItemGroup>

5. Configure o OpenTelemetry com os provedores corretos

Insira o seguinte código antes de builder.Build();:

// Setup logging to be exported via OpenTelemetry
builder.Logging.AddOpenTelemetry(logging =>
{
    logging.IncludeFormattedMessage = true;
    logging.IncludeScopes = true;
});

var otel = builder.Services.AddOpenTelemetry();

// Add Metrics for ASP.NET Core and our custom metrics and export via OTLP
otel.WithMetrics(metrics =>
{
    // Metrics provider from OpenTelemetry
    metrics.AddAspNetCoreInstrumentation();
    //Our custom metrics
    metrics.AddMeter(greeterMeter.Name);
    // Metrics provides by ASP.NET Core in .NET 8
    metrics.AddMeter("Microsoft.AspNetCore.Hosting");
    metrics.AddMeter("Microsoft.AspNetCore.Server.Kestrel");
});

// Add Tracing for ASP.NET Core and our custom ActivitySource and export via OTLP
otel.WithTracing(tracing =>
{
    tracing.AddAspNetCoreInstrumentation();
    tracing.AddHttpClientInstrumentation();
    tracing.AddSource(greeterActivitySource.Name);
});

// Export OpenTelemetry data via OTLP, using env vars for the configuration
var OtlpEndpoint = builder.Configuration["OTEL_EXPORTER_OTLP_ENDPOINT"];
if (OtlpEndpoint != null)
{
    otel.UseOtlpExporter();
}

Este código configura o OpenTelemetry com as diferentes fontes de telemetria:

• Ele adiciona um provedor OTel ao ILogger para coletar registros de log.
• Ele configura métricas, registrando fornecedores de instrumentação e medidores para ASP.NET e nosso medidor personalizado.
• Ele configura o rastreamento, registrando provedores de instrumentação e nosso ActivitySource personalizado.

Em seguida, ele regista o exportador OTLP usando variáveis de ambiente para a sua configuração.

6. Configurar variáveis de ambiente OTLP

O exportador OTLP pode ser configurado via APIs em código, mas é mais comum configurá-lo através de variáveis de ambiente. Adicione o seguinte ao AppSettings.Development.json

"OTEL_EXPORTER_OTLP_ENDPOINT": "http://localhost:4317",
"OTEL_SERVICE_NAME": "OTLP-Example"

Você pode adicionar variáveis de ambiente adicionais para o Exportador de OTLP do .NET ou variáveis OTel comuns, como OTEL_RESOURCE_ATTRIBUTES para definir atributos de recurso.

7. Inicie o contentor do Aspire Dashboard

Uso docker para descarregar e executar o contentor do dashboard.

docker run --rm -it `
-p 18888:18888 `
-p 4317:18889 `
--name aspire-dashboard `
mcr.microsoft.com/dotnet/aspire-dashboard:latest

Os dados exibidos no painel podem ser confidenciais. Por defeito, o painel está protegido com autenticação que requer um token para iniciar sessão. O token é exibido na saída resultante ao executar o contêiner.

Copie o URL mostrado e substitua 0.0.0.0 por localhost, por exemplo, http://localhost:18888/login?t=123456780abcdef123456780, e abra isso no seu navegador. Ou também podes colar a chave depois /login?t= de aparecer o diálogo de login. O token muda cada vez que inicias o contentor.

8. Execute o projeto

Execute o projeto e, em seguida, acesse a API com o navegador ou curl.

curl -k http://localhost:7275

Cada vez que solicita a página, ela incrementa a contagem do número de cumprimentos feitos.

8.1 Saída de log

As instruções de log do código são emitidas usando ILogger. Por padrão, o Provedor de Console é habilitado para que a saída seja direcionada para o console.

Existem algumas opções sobre como os logs podem ser retirados do .NET:

• stdout e stderr a saída é redirecionada para arquivos de log por sistemas de contêiner, como o Kubernetes.
• Usar bibliotecas de registo que se integram com o ILogger. Estas bibliotecas incluem Serilog e NLog.
• Usando provedores de registro para OTel, como OTLP. A seção de registro no código da etapa 5 adiciona o provedor OTel.

Os logs são mostrados no painel como logs estruturados - todas as propriedades definidas na mensagem de log são extraídas como campos no registro de log.

8.2 Visualizando as métricas

O painel do Aspire mostra métricas por recurso (um recurso é a maneira OTel de falar sobre fontes de telemetria, como um processo). Quando um recurso é selecionado, o painel enumera cada métrica que foi enviada ao seu endpoint OTLP pelo recurso. A lista de métricas é dinâmica e é atualizada à medida que novas métricas são recebidas.

A visualização das métricas depende do tipo de métrica que está a ser utilizada:

• Os contadores são mostrados diretamente.
• Histogramas que acompanham um valor por pedido, como um intervalo de tempo ou bytes enviados por pedido, são recolhidos numa série de buckets. O painel de controlo representa graficamente os percentis P50, P90 e P99. Os resultados do histograma podem incluir exemplares, que são pontos de dados individuais juntamente com o trace/spanId para essa solicitação. Estes são mostrados como pontos no gráfico. Ao selecionar um, navega para o respetivo traço para que possas ver o que aconteceu para causar esse valor. Isso é útil para diagnosticar valores atípicos.
• As métricas podem incluir dimensões, que são pares chave/valor associados a valores individuais. Os valores são agregados por dimensão. Usando os menus pendentes na interface, pode filtrar os resultados para analisar dimensões específicas, como apenas pedidos GET, ou para uma rota de URL específica no ASP.NET.

8.3 Visualização do rastreamento

A vista de rastreamento mostra uma lista de rastros. Cada trace é um conjunto de atividades que partilham o mesmo traceId. O trabalho é monitorizado com spans, que representam uma unidade de trabalho. Processar um pedido de ASP.NET cria um intervalo. Fazer um pedido HttpClient é um intervalo de tempo. Ao rastrear o pai da extensão, uma hierarquia de extensões pode ser visualizada. Ao recolher intervalos de cada recurso (processo), pode acompanhar o trabalho que ocorre numa série de serviços. Os pedidos HTTP têm um cabeçalho que é usado para passar o traceId e o spanId pai ao serviço seguinte. Cada recurso precisa coletar telemetria e enviá-la para o mesmo coletor. Em seguida, agregará e apresentará uma hierarquia dos segmentos.

O painel mostra uma lista de rastreios com informação resumida. Sempre que aparecem spans com um novo traceId, aparecem uma linha na tabela. Clicar em visualizar mostra todos os intervalos no rastreio.

Selecionar um vão mostra os seus detalhes, incluindo quaisquer propriedades do vão, como a greeting etiqueta que definiste no passo 3.