Partilhar via

Configurar o Azure Monitor OpenTelemetry

Este guia explica como configurar o OpenTelemetry (OTel) no Azure Monitor Application Insights usando a distro OpenTelemetry do Azure Monitor. A configuração adequada garante a coleta consistente de dados de telemetria em aplicativos .NET, Java, Node.jse Python, permitindo monitoramento e diagnóstico mais confiáveis.

Nota

Para Aplicativos de Função do Azure, consulte Usar OpenTelemetry com o Azure Functions.

String de conexão

Uma cadeia de conexão no Application Insights define o local de destino para o envio de dados de telemetria.

Use uma das três maneiras a seguir para configurar a cadeia de conexão:

  • Adiciona UseAzureMonitor() ao teu program.cs ficheiro.

        var builder = WebApplication.CreateBuilder(args);

    // Add the OpenTelemetry telemetry service to the application.
    // This service will collect and send telemetry data to Azure Monitor.
    builder.Services.AddOpenTelemetry().UseAzureMonitor(options => {
        options.ConnectionString = "<YOUR-CONNECTION-STRING>";
    });

    var app = builder.Build();

    app.Run();

  • Defina uma variável de ambiente.

    APPLICATIONINSIGHTS_CONNECTION_STRING=<YOUR-CONNECTION-STRING>

  • Adicione a seção a seguir ao seu appsettings.json arquivo de configuração.

      {
    "AzureMonitor": {
        "ConnectionString": "<YOUR-CONNECTION-STRING>"
    }
  }

Nota

Se você definir a cadeia de conexão em mais de um lugar, respeitaremos a seguinte precedência:

  1. Código
  2. Variável de Ambiente
  3. Arquivo de configuração

Defina o Nome da Função na Nuvem e a Instância da Função na Nuvem

Para idiomas suportados, a Distro OpenTelemetry do Azure Monitor deteta automaticamente o contexto do recurso e fornece valores padrão para as propriedades Nome da Função de Nuvem e Instância de Função de Nuvem do seu componente. No entanto, talvez você queira substituir os valores padrão por algo que faça sentido para sua equipe. O valor do nome da função na nuvem aparece no Mapa de Aplicação como o nome abaixo de um nó.

Defina o Nome da Função de Nuvem e a Instância de Função de Nuvem por meio dos atributos de Recurso . O Nome da Função de Nuvem usa os atributos service.namespace e service.name, embora reverta para service.name se service.namespace não estiver definido. A Instância de Função de Nuvem usa o valor do atributo service.instance.id. Para obter informações sobre atributos padrão para recursos, consulte Convenções semânticas OpenTelemetry .

// Setting role name and role instance

// Create a dictionary of resource attributes.
var resourceAttributes = new Dictionary<string, object> {
    { "service.name", "my-service" },
    { "service.namespace", "my-namespace" },
    { "service.instance.id", "my-instance" }};

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

// Add the OpenTelemetry telemetry service to the application.
// This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry()
    .UseAzureMonitor()
    // Configure the ResourceBuilder to add the custom resource attributes to all signals.
    // Custom resource attributes should be added AFTER AzureMonitor to override the default ResourceDetectors.
    .ConfigureResource(resourceBuilder => resourceBuilder.AddAttributes(resourceAttributes));

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

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

Ativar amostragem

A amostragem reduz o volume e o custo da ingestão de telemetria. A distribuição OpenTelemetry do Azure Monitor suporta duas estratégias de amostragem para rastreios e (opcionalmente) permite alinhar os logs da aplicação com as suas decisões de amostragem de rastreios. O sampler associa a razão ou taxa de amostragem selecionada aos intervalos exportados para que o Application Insights possa ajustar as contagens de experiência com precisão. Para uma visão conceptual, veja Saiba mais sobre amostragem.

Importante

  • As decisões de amostragem aplicam-se a trilhos (intervalos).
  • As métricas nunca são amostradas.
  • Os registos não são processados por padrão. Pode optar por amostragem baseada em rastreios para logs para que os logs que pertencem a rastreios não amostrados sejam eliminados. Para mais detalhes, Configure amostragem baseada em traços para registos.

Nota

Se está a observar custos inesperados ou elevados no Application Insights, as causas comuns incluem elevado volume de telemetria, picos de ingestão de dados e amostragem mal configurada. Para iniciar a resolução de problemas, consulte Solucionar a alta ingestão de dados em Application Insights.

Configurar a amostragem usando variáveis de ambiente

Use variáveis padrão do ambiente OpenTelemetry para selecionar o sampler e fornecer o seu argumento:

  • OTEL_TRACES_SAMPLER — tipo de sampler

    • microsoft.fixed.percentage — amostrar uma fração de rastros.
    • microsoft.rate_limited — traços de capacitor por segundo.

  • OTEL_TRACES_SAMPLER_ARG — argumento do sampler

    • Para microsoft.fixed.percentage: valor em 0,0–1,0 (por exemplo, 0.1 = ~10%).
    • Para microsoft.rate_limited: traços máximos por segundo (por exemplo, 1.5).

Os exemplos seguintes mostram como configurar a amostragem usando variáveis de ambiente.

Amostragem com percentagem fixa (~10%)

export OTEL_TRACES_SAMPLER="microsoft.fixed.percentage"
export OTEL_TRACES_SAMPLER_ARG=0.1

Amostragem limitada por taxa (~1,5 rastros/segundo)

export OTEL_TRACES_SAMPLER="microsoft.rate_limited"
export OTEL_TRACES_SAMPLER_ARG=1.5

Configurar amostragem no código

Nota

Quando tanto as opções ao nível do código como as variáveis de ambiente são configuradas, as variáveis de ambiente têm prioridade. O comportamento predefinido dos samplers pode variar consoante o idioma, consulte as seguintes abas.

Amostragem percentual fixa

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddOpenTelemetry().UseAzureMonitor(o =>
{
    o.SamplingRatio = 0.1F; // ~10%
});
var app = builder.Build();
app.Run();

Amostragem limitada à taxa

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddOpenTelemetry().UseAzureMonitor(o =>
{
    o.TracesPerSecond = 1.5; // ~1.5 traces/sec
});
var app = builder.Build();
app.Run();

Nota

Se não definires um sampler no código ou através de variáveis de ambiente, o Azure Monitor usa o ApplicationInsightsSampler por defeito.

Gorjeta

Ao usar amostragem com percentagem fixa e não tiver a certeza do que definir a taxa de amostragem, comece em 5% (0.05). Ajuste a taxa com base na precisão das operações apresentadas nos painéis de falhas e desempenho. Qualquer amostragem reduz a precisão, por isso recomendamos alertar nas métricas OpenTelemetry, que não são afetadas pela amostragem.

Configurar amostragem baseada em traços para registos

Quando ativado, os registos que pertencem a traços não amostrados são eliminados para que os seus registos permaneçam alinhados com a amostragem de registos.

  • Um registo de log é considerado parte de um rastreio quando tem um SpanId válido.
  • Se os TraceFlags traços associados indicarem que não foi amostrado, o registo logarítmico é eliminado.
  • Registos de registo sem qualquer contexto de rasto não são afetados.
  • A funcionalidade está desativada por defeito. A capacitação está no idioma, veja os separadores seguintes.

Use a seguinte definição na sua configuração para que permita a amostragem de logs baseados em traços:

builder.Services.AddOpenTelemetry().UseAzureMonitor(o =>
{
    o.EnableTraceBasedLogsSampler = true;
});

Métricas em tempo real

As métricas em tempo real fornecem um painel de análise em tempo real para obter informações sobre a atividade e o desempenho do aplicativo.

Importante

Veja Termos de Utilização Complementares das Pré-visualizações do Microsoft Azure para obter os termos legais que se aplicam às funcionalidades do Azure que estão na versão beta, na pré-visualização ou que ainda não foram disponibilizadas ao público geral.

Esta caraterística está ativada por predefinição.

Os usuários podem desativar o Live Metrics ao configurar a Distro.

builder.Services.AddOpenTelemetry().UseAzureMonitor(options => {
	// Disable the Live Metrics feature.
    options.EnableLiveMetrics = false;
});

Habilitar a autenticação do Microsoft Entra ID (anteriormente Azure AD)

Talvez você queira habilitar a autenticação do Microsoft Entra para uma conexão mais segura com o Azure, o que impede que a telemetria não autorizada seja ingerida em sua assinatura.

Para obter mais informações, consulte nossa página dedicada de autenticação do Microsoft Entra vinculada para cada idioma suportado.

Para obter informações sobre como configurar a autenticação do Entra ID, consulte Autenticação do Microsoft Entra para o Application Insights

Armazenamento offline e novas tentativas automáticas

As ofertas baseadas em OpenTelemetry do Azure Monitor fazem cache de telemetria quando uma aplicação se desconecta do Application Insights e tenta reenviar por até 48 horas. Para obter recomendações de tratamento de dados, consulte Exportar e excluir dados privados. Aplicativos de alta carga ocasionalmente descartam a telemetria por dois motivos: exceder o tempo permitido ou exceder o tamanho máximo do arquivo. Quando necessário, o produto prioriza eventos recentes em detrimento de antigos.

O pacote Distro inclui o AzureMonitorExporter, que por padrão usa um dos seguintes locais para armazenamento offline (listados em ordem de precedência):

  • Windows

    • %LOCALAPPDATA%\Microsoft\AzureMonitor
    • %TEMP%\Microsoft\AzureMonitor

  • não Windows

    • %TMPDIR%/Microsoft/AzureMonitor
    • /var/tmp/Microsoft/AzureMonitor
    • /tmp/Microsoft/AzureMonitor

Para substituir o diretório padrão, você deve definir AzureMonitorOptions.StorageDirectory.

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

// Add the OpenTelemetry telemetry service to the application.
// This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor(options =>
{
    // Set the Azure Monitor storage directory to "C:\\SomeDirectory".
    // This is the directory where the OpenTelemetry SDK will store any telemetry data that can't be sent to Azure Monitor immediately.
    options.StorageDirectory = "C:\\SomeDirectory";
});

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

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

Para desativar esse recurso, você deve definir AzureMonitorOptions.DisableOfflineStorage = true.

Habilitar o Exportador OTLP

Talvez você queira habilitar o Exportador de Protocolo de Telemetria Aberta (OTLP) junto com o Exportador do Azure Monitor para enviar sua telemetria para dois locais.

Nota

O Exportador OTLP é mostrado apenas por conveniência. Não suportamos oficialmente o Exportador OTLP ou quaisquer componentes ou experiências de terceiros relacionados a ele.

  1. Instale o pacote OpenTelemetry.Exporter.OpenTelemetryProtocol em seu projeto.

    dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol

  2. Adicione o seguinte trecho de código. Este exemplo pressupõe que você tenha um OpenTelemetry Collector com um recetor OTLP em execução. Para obter detalhes, consulte o exemplo no GitHub.

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

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

// Add the OpenTelemetry OTLP exporter to the application.
// This exporter will send telemetry data to an OTLP receiver, such as Prometheus
builder.Services.AddOpenTelemetry().WithTracing(builder => builder.AddOtlpExporter());
builder.Services.AddOpenTelemetry().WithMetrics(builder => builder.AddOtlpExporter());

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

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

Configurações OpenTelemetry

As seguintes configurações do OpenTelemetry podem ser acessadas por meio de variáveis de ambiente ao usar as Distros OpenTelemetry do Azure Monitor.

Variável de ambiente Descrição
APPLICATIONINSIGHTS_CONNECTION_STRING Defina-o como a cadeia de conexão do recurso Application Insights.
APPLICATIONINSIGHTS_STATSBEAT_DISABLED Defina-o como true para desativar a coleta de métricas internas.
OTEL_RESOURCE_ATTRIBUTES Pares chave-valor a serem usados como atributos de recurso. Para obter mais informações sobre atributos de recursos, consulte a especificação do SDK de recursos.
OTEL_SERVICE_NAME Define o valor do atributo de recurso service.name. Se service.name também for fornecido em OTEL_RESOURCE_ATTRIBUTES, então OTEL_SERVICE_NAME tem precedência.

Editar Cadeias de Consulta de URLs

Para redigir cadeias de caracteres de consulta de URL, desative a coleção de cadeias de caracteres de consulta. Recomendamos essa configuração se você chamar o armazenamento do Azure usando um token SAS.

Quando você estiver usando o pacote de distribuição Azure.Monitor.OpenTelemetry.AspNetCore , as bibliotecas de instrumentação ASP.NET Core e HttpClient estão incluídas. O nosso pacote de distribuição desativa a Redação de Cadeia de Consulta por padrão.

Para alterar esse comportamento, deve-se definir uma variável de ambiente como true ou false.

  • ASP.NET Instrumentação principal: OTEL_DOTNET_EXPERIMENTAL_ASPNETCORE_DISABLE_URL_QUERY_REDACTION a Redação da Cadeia de Caracteres de Consulta está desativada por padrão. Para habilitar, defina essa variável de ambiente como false.

  • Instrumentação de Cliente HTTP: OTEL_DOTNET_EXPERIMENTAL_HTTPCLIENT_DISABLE_URL_QUERY_REDACTION A Edição de Cadeia de Caracteres de Consulta está desativada por padrão. Para habilitar, defina essa variável de ambiente como false.

Intervalo de exportação de métricas

Você pode configurar o intervalo de exportação de métrica usando a OTEL_METRIC_EXPORT_INTERVAL variável de ambiente.

OTEL_METRIC_EXPORT_INTERVAL=60000

O valor padrão é 60000 milissegundos (60 segundos). Essa configuração controla a frequência com que o SDK do OpenTelemetry exporta métricas.

Gorjeta

O Azure Monitor Metrics e o Azure Monitor Workspace ingerem métricas personalizadas em um intervalo fixo de 60 segundos. As métricas enviadas com mais frequência são armazenadas em buffer e processadas uma vez a cada 60 segundos. O Log Analytics registra métricas no intervalo em que são enviadas, o que pode aumentar o custo em intervalos mais curtos e atrasar a visibilidade em intervalos mais longos.

Para referência, consulte as seguintes especificações OpenTelemetry :

  • Last updated on