Compartilhar via

Configurar o OpenTelemetry do Azure Monitor

  • Artigo

Este artigo aborda as definições da configuração da distro do OpenTelemetry do Azure Monitor.

Cadeia de conexão

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

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

  • Adicione UseAzureMonitor() ao arquivo program.cs:

    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 arquivo de configuração appsettings.json.

    {
  "AzureMonitor": {
      "ConnectionString": "<Your Connection String>"
  }
}

Observação

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

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

Definir o Nome da Função de Nuvem e a Instância de Função de Nuvem

Para idiomas com suporte, a distribuição OpenTelemetry do Azure Monitor detecta automaticamente o contexto do recurso e fornece valores padrão para o Nome da função de nuvem e as propriedades da Instância da função de nuvem do componente. No entanto, talvez você queira substituir os valores padrão para algo que faça sentido para a sua equipe. O valor do nome da função de nuvem aparece no mapa do aplicativo 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 de atributos de Recurso. O Nome da Função de Nuvem usa os atributos service.namespace e service.name, embora ele volte 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, confira Convenções semânticas do 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(_testResourceAttributes));

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

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

Habilitar amostragem

Talvez você queira habilitar a amostragem para reduzir o volume de ingestão de dados, o que reduz o custo. O Azure Monitor fornece uma amostra de taxa fixa personalizada que preenche eventos com uma "taxa de amostragem" e o Application Insights a converte em ItemCount. A amostra de taxa fixa garante contagens precisas de experiências e eventos. O amostrador foi projetado para preservar seus rastreamentos entre serviços e é interoperável com kits de desenvolvimento de software (SDKs) mais antigos do Application Insights. Para obter mais informações, confira Saiba mais sobre amostragem.

Observação

As métricas não são afetadas pela amostragem.

A amostra espera uma taxa de amostra entre 0 e 1 inclusiva. Uma taxa de 0,1 significa que aproximadamente 10% dos seus rastreamentos foram enviados.

// 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 sampling ratio to 10%. This means that 10% of all traces will be sampled and sent to Azure Monitor.
    options.SamplingRatio = 0.1F;
});

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

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

Dica

Ao usar a amostragem de taxa fixa/porcentagem e você não tiver certeza de como definir a taxa de amostragem, comece em 5% (ou seja, taxa de amostragem de 0,05) e ajuste a taxa com base na precisão das operações mostradas nos painéis de falhas e desempenho. Geralmente, uma taxa mais alta resulta em precisão maior. No entanto, TODA amostragem afetará a precisão, sendo assim, é recomendável alertar sobre as Métricas do OpenTelemetry, que não são afetadas pela amostragem.

Live Metrics

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

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.

Esse recurso está habilitado por padrão.

Os usuários podem desabilitar 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 (antigo Azure AD)

Talvez você queira habilitar a autenticação do Microsoft Entra para ter uma conexão mais segura com o Azure, o que impede que dados telemétricos não autorizados sejam ingeridos em sua assinatura.

Oferecemos suporte às classes de credenciais fornecidas pelo Azure Identity.

  • Recomendamos DefaultAzureCredential para o desenvolvimento local.
  • ManagedIdentityCredential é recomendado para identidades gerenciadas atribuídas pelo usuário e atribuídas pelo sistema.
    • Para atribuído pelo sistema, use o construtor padrão sem parâmetros.
    • Para atribuído pelo usuário, forneça o ID do cliente para o construtor.
  • Recomendamos ClientSecretCredential para entidades de serviço.
    • Forneça a ID do locatário, a ID do cliente e o segredo do cliente para o construtor.

  1. Instalar o pacote mais recente do Azure.Identity:

    dotnet add package Azure.Identity

  2. Forneça a classe de credencial desejada:

    // 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 credential to the DefaultAzureCredential.
    // This credential will use the Azure identity of the current user or
    // the service principal that the application is running as to authenticate
    // to Azure Monitor.
    options.Credential = new DefaultAzureCredential();
});

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

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

Armazenamento offline e novas tentativas automáticas

Para melhorar a confiabilidade e a resiliência, as ofertas baseadas em OpenTelemetry do Azure Monitor são gravadas no armazenamento offline/local por padrão quando um aplicativo perde sua conexão com o Application Insights. Ele salva a telemetria do aplicativo no disco e tenta enviá-la outra vez periodicamente por até 48 horas. Em aplicações de alta carga, a telemetria é ocasionalmente descartada por dois motivos. Primeiro, quando o tempo permitido for excedido e, segundo, quando o tamanho máximo do arquivo for excedido ou o SDK não tiver a oportunidade de limpar o arquivo. Se precisarmos escolher, o produto salva os eventos mais recentes em relação aos antigos. Saiba mais

O pacote Distro inclui o AzureMonitorExporter que, por padrão, usa um dos seguintes locais para armazenamento offline (listado 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 cannot 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 desabilitar esse recurso, você deve definir AzureMonitorOptions.DisableOfflineStorage = true.

Habilitar o Exportador OTLP

Talvez você queira habilitar o exportador do protocolo OpenTelemetry (OTLP) junto com o exportador do Azure Monitor para enviar os seus dados telemétricos para dois locais.

Observação

O Exportador OTLP é mostrado apenas para fins de conveniência. Nós não damos suporte oficialmente ao Exportador OTLP nem a qualquer componente ou experiência de terceiros downstream.

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

    dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol

  2. Adicione o trecho de código a seguir. Este exemplo pressupõe que você tenha um coletor de OpenTelemetry com um receptor OTLP em execução. Para obter detalhes, confira o exemplo do 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 do OpenTelemetry

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

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

Redigir sequências de consulta de URL

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

Ao usar o pacote de distribuição Azure.Monitor.OpenTelemetry.AspNetCore, as bibliotecas de instrumentação ASP.NET Core e HttpClient são incluídas. Nosso pacote de distribuição desativa a Redação de String de Consulta por padrão.

Para alterar esse comportamento, você deve definir uma variável de ambiente como "verdadeiro" ou "falso".

  • Instrumentação do ASP.NET Core: OTEL_DOTNET_EXPERIMENTAL_ASPNETCORE_DISABLE_URL_QUERY_REDACTION A redação da cadeia de caracteres de consulta está desabilitada por padrão. Para habilitar, defina essa variável de ambiente como "false".
  • Instrumentação do cliente HTTP: OTEL_DOTNET_EXPERIMENTAL_HTTPCLIENT_DISABLE_URL_QUERY_REDACTION A redação da cadeia de caracteres de consulta está desabilitada por padrão. Para habilitar, defina essa variável de ambiente como "false".