Compartilhar via

Adicionar e modificar o OpenTelemetry do Azure Monitor para aplicativos .NET, Node.js, Python e Java

Este guia fornece instruções sobre como integrar e personalizar a instrumentação do OpenTelemetry (OTel) no Azure Monitor Application Insights.

Para saber mais sobre os conceitos do OpenTelemetry, confira a Visão geral do OpenTelemetry ou as Perguntas frequentes sobre o OpenTelemetry.

Observação

Para aplicativos de funções do Azure, consulte Usar OpenTelemetry com o Azure Functions.

Coleta automática de dados

As distribuições coletam dados automaticamente ao integrar as bibliotecas de instrumentação do OpenTelemetry.

Bibliotecas de instrumentação incluídas

Solicitações

Dependências

Registro

  • ILogger

Para reduzir ou aumentar o número de logs enviados ao Azure Monitor, configure o log para definir o nível de log apropriado ou aplicar filtros. Por exemplo, você pode optar por enviar somente Warning e Error logs para o OpenTelemetry/Azure Monitor. O OpenTelemetry não controla o roteamento ou a filtragem de logs . Sua ILogger configuração toma essas decisões. Para obter mais informações sobre a configuração ILogger, veja Configurar registro.

Para obter mais informações sobre o ILogger, veja Logging em C# e .NET e exemplos de código.

Notas de rodapé

  • ¹: dá suporte a relatórios automáticos de exceções não tratadas/não detectadas
  • ²: dá suporte a métricas do OpenTelemetry

Observação

As distribuições OpenTelemetry do Azure Monitor incluem mapeamento e lógica personalizados para emitir automaticamente métricas padrão do Application Insights.

Dica

Todas as métricas do OpenTelemetry, sejam coletadas automaticamente de bibliotecas de instrumentação ou coletadas manualmente da codificação personalizada, atualmente são consideradas "métricas personalizadas" do Application Insights para fins de cobrança. Saiba mais.

Adicionar uma biblioteca de instrumentação da comunidade

Você pode coletar mais dados automaticamente quando incluir as bibliotecas de instrumentação da comunidade OpenTelemetry.

Cuidado

Não damos suporte nem garantimos a qualidade das bibliotecas de instrumentação da comunidade. Para sugerir uma para nossa distribuição, faça uma postagem ou vote a favor em nossa comunidade de comentários. Esteja ciente de que algumas são baseadas em especificações experimentais do OpenTelemetry e podem introduzir mudanças significativas no futuro.

Para adicionar uma biblioteca de comunidade, use os métodos ConfigureOpenTelemetryMeterProvider ou ConfigureOpenTelemetryTracerProvider depois de adicionar o pacote NuGet à biblioteca.

O exemplo a seguir demonstra como a Instrumentação em Tempo de Execução pode ser adicionada para coletar métricas adicionais.

dotnet add package OpenTelemetry.Instrumentation.Runtime 

// Create a new ASP.NET Core web application builder.
var builder = WebApplication.CreateBuilder(args);

// Configure the OpenTelemetry meter provider to add runtime instrumentation.
builder.Services.ConfigureOpenTelemetryMeterProvider((sp, builder) => builder.AddRuntimeInstrumentation());

// Add the Azure Monitor telemetry service to the application.
// This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor();

// Build the ASP.NET Core web application.
var app = builder.Build();

// Start the ASP.NET Core web application.
app.Run();

Coletar telemetria personalizada

Esta seção explica como coletar telemetria personalizada do aplicativo.

Dependendo do idioma e do tipo de sinal, há diferentes maneiras de coletar telemetria personalizada, incluindo:

  • API do OpenTelemetry
  • Bibliotecas de registro/métricas específicas de idioma
  • API Clássica do Application Insights

A seguinte tabela representa os tipos de telemetria personalizada com suporte no momento:

Idioma Eventos personalizados Métricas personalizadas Dependências Exceções Visualizações de página Solicitações Rastreamentos
ASP.NET Core
   API do OpenTelemetry Sim Sim Sim Sim
   API ILogger Sim
   API clássica de IA
Java
   API do OpenTelemetry Sim Sim Sim Sim
   Logback, Log4j, JUL Sim Sim
   Métricas do Micrometer Sim
   API clássica de IA Sim Sim Sim Sim Sim Sim Sim
Node.js
   API do OpenTelemetry Sim Sim Sim Sim
Python
   API do OpenTelemetry Sim Sim Sim Sim
   Módulo de registro Python Sim
   Extensão de eventos Sim Sim

Observação

O Application Insights Java 3.x e o Application Insights Node.js 3.x coletam telemetria da API Clássica do Application Insights. Esse comportamento simplifica as atualizações e dá suporte temporariamente à telemetria personalizada até que a API OpenTelemetry inclua todos os tipos de telemetria personalizados.

Adicionar métricas personalizadas

Nesse contexto, o termo de métricas personalizadas refere-se a instrumentar manualmente seu código para coletar métricas extras além do que as Bibliotecas de Instrumentação OpenTelemetry coletam automaticamente.

A API do OpenTelemetry oferece seis “instrumentos” métricos para cobrir vários cenários métricos e você precisa escolher o “Tipo de Agregação” correto ao visualizar as métricas no Metrics Explorer. Esse requisito é válido ao usar a API de Métrica do OpenTelemetry para enviar métricas e ao usar uma biblioteca de instrumentação.

A tabela a seguir mostra os tipos de agregação recomendados para cada um dos Instrumentos de Métrica do OpenTelemetry.

Instrumento do OpenTelemetry Tipo de agregação do Azure Monitor
Contador Soma
Contador assíncrono Soma
Histograma Min, Max, Média, Soma e Contagem
Medidor assíncrono Média
UpDownCounter Soma
Contador Assíncrono UpDownCounter Soma

Cuidado

Outros tipos de agregação não são significativos na maioria dos casos.

A Especificação do OpenTelemetry descreve os instrumentos e fornece exemplos de quando usar cada um deles.

Dica

O histograma é o mais versátil e mais equivalente à Application Insights GetMetric API Clássica. Atualmente, o Azure Monitor nivela o instrumento de histograma em nossos cinco tipos de agregação suportados, e o suporte para percentis está em andamento. Embora menos versátil, outros instrumentos OpenTelemetry têm um efeito menor no desempenho do aplicativo.

Exemplo de histograma

A inicialização do aplicativo deve se inscrever em um medidor por nome:

// Create a new ASP.NET Core web application builder.
var builder = WebApplication.CreateBuilder(args);

// Configure the OpenTelemetry meter provider to add a meter named "OTel.AzureMonitor.Demo".
builder.Services.ConfigureOpenTelemetryMeterProvider((sp, builder) => builder.AddMeter("OTel.AzureMonitor.Demo"));

// Add the Azure Monitor telemetry service to the application.
// This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor();

// Build the ASP.NET Core web application.
var app = builder.Build();

// Start the ASP.NET Core web application.
app.Run();

O Meter deve ser inicializado usando esse mesmo nome:

// Create a new meter named "OTel.AzureMonitor.Demo".
var meter = new Meter("OTel.AzureMonitor.Demo");

// Create a new histogram metric named "FruitSalePrice".
Histogram<long> myFruitSalePrice = meter.CreateHistogram<long>("FruitSalePrice");

// Create a new Random object.
var rand = new Random();

// Record a few random sale prices for apples and lemons, with different colors.
myFruitSalePrice.Record(rand.Next(1, 1000), new("name", "apple"), new("color", "red"));
myFruitSalePrice.Record(rand.Next(1, 1000), new("name", "lemon"), new("color", "yellow"));
myFruitSalePrice.Record(rand.Next(1, 1000), new("name", "lemon"), new("color", "yellow"));
myFruitSalePrice.Record(rand.Next(1, 1000), new("name", "apple"), new("color", "green"));
myFruitSalePrice.Record(rand.Next(1, 1000), new("name", "apple"), new("color", "red"));
myFruitSalePrice.Record(rand.Next(1, 1000), new("name", "lemon"), new("color", "yellow"));

Exemplo de contador

A inicialização do aplicativo deve se inscrever em um medidor por nome:

// Create a new ASP.NET Core web application builder.
var builder = WebApplication.CreateBuilder(args);

// Configure the OpenTelemetry meter provider to add a meter named "OTel.AzureMonitor.Demo".
builder.Services.ConfigureOpenTelemetryMeterProvider((sp, builder) => builder.AddMeter("OTel.AzureMonitor.Demo"));

// Add the Azure Monitor telemetry service to the application.
// This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor();

// Build the ASP.NET Core web application.
var app = builder.Build();

// Start the ASP.NET Core web application.
app.Run();

O Meter deve ser inicializado usando esse mesmo nome:

// Create a new meter named "OTel.AzureMonitor.Demo".
var meter = new Meter("OTel.AzureMonitor.Demo");

// Create a new counter metric named "MyFruitCounter".
Counter<long> myFruitCounter = meter.CreateCounter<long>("MyFruitCounter");

// Record the number of fruits sold, grouped by name and color.
myFruitCounter.Add(1, new("name", "apple"), new("color", "red"));
myFruitCounter.Add(2, new("name", "lemon"), new("color", "yellow"));
myFruitCounter.Add(1, new("name", "lemon"), new("color", "yellow"));
myFruitCounter.Add(2, new("name", "apple"), new("color", "green"));
myFruitCounter.Add(5, new("name", "apple"), new("color", "red"));
myFruitCounter.Add(4, new("name", "lemon"), new("color", "yellow"));

Exemplo de medidor

A inicialização do aplicativo deve se inscrever em um medidor por nome:

// Create a new ASP.NET Core web application builder.
var builder = WebApplication.CreateBuilder(args);

// Configure the OpenTelemetry meter provider to add a meter named "OTel.AzureMonitor.Demo".
builder.Services.ConfigureOpenTelemetryMeterProvider((sp, builder) => builder.AddMeter("OTel.AzureMonitor.Demo"));

// Add the Azure Monitor telemetry service to the application.
// This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor();

// Build the ASP.NET Core web application.
var app = builder.Build();

// Start the ASP.NET Core web application.
app.Run();

O Meter deve ser inicializado usando esse mesmo nome:

// Get the current process.
var process = Process.GetCurrentProcess();

// Create a new meter named "OTel.AzureMonitor.Demo".
var meter = new Meter("OTel.AzureMonitor.Demo");

// Create a new observable gauge metric named "Thread.State".
// This metric will track the state of each thread in the current process.
ObservableGauge<int> myObservableGauge = meter.CreateObservableGauge("Thread.State", () => GetThreadState(process));

private static IEnumerable<Measurement<int>> GetThreadState(Process process)
{
    // Iterate over all threads in the current process.
    foreach (ProcessThread thread in process.Threads)
    {
        // Create a measurement for each thread, including the thread state, process ID, and thread ID.
        yield return new((int)thread.ThreadState, new("ProcessId", process.Id), new("ThreadId", thread.Id));
    }
}

Adicionar exceções personalizadas

Selecione as bibliotecas de instrumentação para reportar automaticamente as exceções ao Application Insights. No entanto, talvez você queira relatar manualmente exceções além daquelas relatadas pelas bibliotecas de instrumentação. Por exemplo, exceções capturadas pelo seu código normalmente não são reportadas. Talvez você queira relatá-los para chamar a atenção em experiências relevantes, incluindo a seção de falhas e visualizações de transações de ponta a ponta.

  • Para registrar uma exceção usando uma atividade:

    // Start a new activity named "ExceptionExample".
using (var activity = activitySource.StartActivity("ExceptionExample"))
{
    // Try to execute some code.
    try
    {
        throw new Exception("Test exception");
    }
    // If an exception is thrown, catch it and set the activity status to "Error".
    catch (Exception ex)
    {
        activity?.SetStatus(ActivityStatusCode.Error);
        activity?.RecordException(ex);
    }
}

  • Para registrar uma exceção usando o ILogger:

    // Create a logger using the logger factory. The logger category name is used to filter and route log messages.
var logger = loggerFactory.CreateLogger(logCategoryName);

// Try to execute some code.
try
{
    throw new Exception("Test Exception");
}
catch (Exception ex)
{
    // Log an error message with the exception. The log level is set to "Error" and the event ID is set to 0.
    // The log message includes a template and a parameter. The template will be replaced with the value of the parameter when the log message is written.
    logger.Log(
        logLevel: LogLevel.Error,
        eventId: 0,
        exception: ex,
        message: "Hello {name}.",
        args: new object[] { "World" });
}

Adicionar intervalos personalizados

Talvez você queira adicionar um intervalo personalizado em dois cenários. Primeiro, quando há uma solicitação de dependência que ainda não foi coletada por uma biblioteca de instrumentação. Segundo, quando você deseja modelar um processo de aplicação como um intervalo na visão de transação de ponta a ponta.

Observação

As classes Activity e ActivitySource do namespace System.Diagnostics representam os conceitos Span e Tracer do OpenTelemetry, respectivamente. Você cria ActivitySource diretamente usando o construtor dele em vez de usar TracerProvider. Cada classe ActivitySource deve ser conectada explicitamente ao TracerProvider usando AddSource(). Isso ocorre porque partes da API de rastreamento do OpenTelemetry são incorporadas diretamente ao runtime do .NET. Para saber mais, confira Introdução à API de rastreamento do OpenTelemetry .NET.

// Define an activity source named "ActivitySourceName". This activity source will be used to create activities for all requests to the application.
internal static readonly ActivitySource activitySource = new("ActivitySourceName");

// Create an ASP.NET Core application builder.
var builder = WebApplication.CreateBuilder(args);

// Configure the OpenTelemetry tracer provider to add a source named "ActivitySourceName". This will ensure that all activities created by the activity source are traced.
builder.Services.ConfigureOpenTelemetryTracerProvider((sp, builder) => builder.AddSource("ActivitySourceName"));

// Add the Azure Monitor telemetry service to the application. This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor();

// Build the ASP.NET Core application.
var app = builder.Build();

// Map a GET request to the root path ("/") to the specified action.
app.MapGet("/", () =>
{
    // Start a new activity named "CustomActivity". This activity will be traced and the trace data will be sent to Azure Monitor.
    using (var activity = activitySource.StartActivity("CustomActivity"))
    {
        // your code here
    }

    // Return a response message.
    return $"Hello World!";
});

// Start the ASP.NET Core application.
app.Run();

StartActivity tem ActivityKind.Internal como padrão, mas você pode fornecer qualquer outro ActivityKind. ActivityKind.Client, ActivityKind.Producer e ActivityKind.Internal são mapeados para o Application Insights dependencies. ActivityKind.Server e ActivityKind.Consumer são mapeados para o Application Insights requests.

Enviar eventos personalizados

O Application Insights armazena eventos personalizados na customEvents tabela. Uma maneira de analisá-las, filtrar e visualizá-las é usando as experiências de uso do Application Insights.

Se você quiser automatizar a coleção de eventos de interação do lado do cliente, poderá usar o plug-in no SDK do JavaScript.

Os eventos personalizados estão em Visualização Pública e uso Azure.Monitor.OpenTelemetry.AspNetCore 1.3.0-beta.3.

Importante

Veja os Termos de Uso Complementares para Versões Prévias do Microsoft Azure para obter termos legais que se aplicam aos recursos do Azure que estão em versão beta, versão prévia ou que, de outra forma, ainda não foram lançados em disponibilidade geral.

Para enviar um CustomEvent usando ILogger, defina o atributo "microsoft.custom_event.name" no modelo de mensagem.

// Create a logger factory and configure OpenTelemetry with Azure Monitor
var loggerFactory = LoggerFactory.Create(builder =>
{
    builder
        .AddOpenTelemetry(options =>
        {
            options.AddAzureMonitorLogExporter();
        });
});

// Create a logger for the specified category
var logger = loggerFactory.CreateLogger(logCategoryName);

// Log a custom event with a custom name and additional attribute
// The 'microsoft.custom_event.name' value will be used as the name of the customEvent
logger.LogInformation("{microsoft.custom_event.name} {additional_attrs}", "test-event-name", "val1");

Modificar telemetria

Esta seção explica como modificar a telemetria.

Adicionar atributos de intervalo

Esses atributos podem incluir a adição de uma propriedade personalizada à telemetria. Você também pode usar atributos para definir campos opcionais no esquema do Application Insights, como IP do Cliente.

Adicionar uma propriedade personalizada a um Span

Todos os atributos adicionados aos intervalos são exportados como propriedades personalizadas. Elas preenchem o campo customDimensions na tabela de solicitações, dependências, rastreamentos ou exceções.

Para adicionar atributos de span, use uma das duas maneiras a seguir:

Dica

A vantagem de usar as opções fornecidas pelas bibliotecas de instrumentação, quando disponíveis, é que todo o contexto fica disponível. Assim, os usuários podem optar por adicionar ou filtrar mais atributos. Por exemplo, a opção de enriquecimento na biblioteca de instrumentação do HttpClient oferece aos usuários acesso ao HttpRequestMessage e ao próprio HttpResponseMessage. Eles podem selecionar qualquer coisa nela e armazenar como um atributo.

  1. Muitas bibliotecas de instrumentação oferecem uma opção de enriquecimento. Para obter diretrizes, confira os arquivos Leiame das bibliotecas de instrumentação individuais:

  2. Usar um processador personalizado:

    Dica

    Adicione o processador mostrado aqui antes de adicionar o Azure Monitor.

    // Create an ASP.NET Core application builder.
var builder = WebApplication.CreateBuilder(args);

// Configure the OpenTelemetry tracer provider to add a new processor named ActivityEnrichingProcessor.
builder.Services.ConfigureOpenTelemetryTracerProvider((sp, builder) => builder.AddProcessor(new ActivityEnrichingProcessor()));

// Add the Azure Monitor telemetry service to the application. This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor();

// Build the ASP.NET Core application.
var app = builder.Build();

// Start the ASP.NET Core application.
app.Run();

    Adicione ActivityEnrichingProcessor.cs ao seu projeto com o seguinte código:

    public class ActivityEnrichingProcessor : BaseProcessor<Activity>
{
    public override void OnEnd(Activity activity)
    {
        // The updated activity will be available to all processors which are called after this processor.
        activity.DisplayName = "Updated-" + activity.DisplayName;
        activity.SetTag("CustomDimension1", "Value1");
        activity.SetTag("CustomDimension2", "Value2");
    }
}

Definir o IP do usuário

Você pode preencher o campo client_IP de solicitações definindo um atributo no span. A Application Insights usa o endereço IP para gerar atributos de localização do usuário e, em seguida, o descarta por padrão.

Use o exemplo de propriedade personalizada, mas substitua as seguintes linhas de código em ActivityEnrichingProcessor.cs:

// Add the client IP address to the activity as a tag.
// only applicable in case of activity.Kind == Server
activity.SetTag("client.address", "<IP Address>");

Definir a ID do usuário ou a ID do usuário autenticado

Você pode preencher o campo user_Id ou user_AuthenticatedId para solicitações usando as diretrizes a seguir. A ID do usuário é um identificador de usuário anônimo. A ID do usuário autenticado é um identificador de usuário conhecido.

Importante

Veja as leis de privacidade aplicáveis antes de configurar a ID de Usuário autenticado.

Use o exemplo de propriedade personalizada:

// Add the user ID to the activity as a tag, but only if the activity is not null.
activity?.SetTag("enduser.id", "<User Id>");

Adicionar atributos de log

OpenTelemetry usa .NET ILogger. A anexação de dimensões personalizadas aos registros pode ser realizada usando um modelo de mensagem.

Obter o ID do rastreamento ou o ID do intervalo

Você pode obter o Trace ID e o Span ID do Span atualmente ativo seguindo os seguintes passos.

Observação

As classes Activity e ActivitySource do namespace System.Diagnostics representam os conceitos Span e Tracer do OpenTelemetry, respectivamente. Isso ocorre porque partes da API de rastreamento do OpenTelemetry são incorporadas diretamente ao runtime do .NET. Para saber mais, confira Introdução à API de rastreamento do OpenTelemetry .NET.

// Get the current activity.
Activity activity = Activity.Current;
// Get the trace ID of the activity.
string traceId = activity?.TraceId.ToHexString();
// Get the span ID of the activity.
string spanId = activity?.SpanId.ToHexString();

Próximas etapas