Configurar o Azure Monitor OpenTelemetry

  • Artigo

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

Connection string

Uma cadeia de conexão no Application Insights define o local de destino para o envio de dados de telemetria, garantindo que eles atinjam o recurso apropriado para monitoramento e análise.

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

  • Adicione UseAzureMonitor() à inicialização do seu aplicativo, em sua program.cs classe.

    // 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 => {
    options.ConnectionString = "<Your Connection String>";
});

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

// Start the ASP.NET Core web application.    
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

Definir o nome da função de nuvem e a instância de função de 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 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 dos atributos de Recurso . O Nome da Função de Nuvem usa service.namespace e service.name atributa, embora caia para service.name se service.namespace não estiver definido. A Instância de Função de Nuvem usa o valor do service.instance.id atributo. 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 OpenTelemetry tracer provider to add the resource attributes to all traces.
builder.Services.ConfigureOpenTelemetryTracerProvider((sp, builder) => 
    builder.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

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

Nota

As métricas e os logs não são afetados pela amostragem.

O amostrador espera uma taxa de amostragem entre 0 e 1, inclusive. Uma taxa de 0,1 significa que aproximadamente 10% dos seus vestígios são 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(o =>
{
    // Set the sampling ratio to 10%. This means that 10% of all traces will be sampled and sent to Azure Monitor.
    o.SamplingRatio = 0.1F;
});

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

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

Gorjeta

Ao usar amostragem de taxa fixa/porcentagem e você não tiver certeza do que definir a taxa de amostragem, comece em 5% (ou seja, razão de amostragem de 0,05) e ajuste a taxa com base na precisão das operações mostradas nas falhas e lâminas de desempenho. Uma taxa mais alta geralmente resulta em maior precisão. No entanto, QUALQUER amostragem afetará a precisão, por isso recomendamos alertar sobre as métricas OpenTelemetry que não são afetadas pela amostragem.

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.

Damos suporte às classes de credenciais fornecidas pela Identidade do Azure.

  • Recomendamos para o DefaultAzureCredential desenvolvimento local.
  • Recomendamos ManagedIdentityCredential para identidades gerenciadas atribuídas pelo sistema e pelo usuário.
    • Para system-assigned, use o construtor padrão sem parâmetros.
    • Para o usuário atribuído, 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. Instale o pacote Azure.Identity mais recente:

    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 off-line e novas tentativas automáticas

Para melhorar a confiabilidade e a resiliência, as ofertas baseadas em OpenTelemetria do Azure Monitor gravam 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 periodicamente tenta enviá-lo novamente por até 48 horas. Em aplicações de alta carga, a telemetria é ocasionalmente descartada por dois motivos. Primeiro, quando o tempo permitido é excedido e, segundo, quando o tamanho máximo do arquivo é excedido ou o SDK não tem a oportunidade de limpar o arquivo. Se precisarmos escolher, o produto salva eventos mais recentes do que os antigos. Saiba Mais

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 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 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 a jusante do mesmo.

  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 Description
APPLICATIONINSIGHTS_CONNECTION_STRING Defina-o como a cadeia de conexão do recurso do 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 service.name valor do atributo de recurso. Se service.name também for fornecido em OTEL_RESOURCE_ATTRIBUTES, então OTEL_SERVICE_NAME tem precedência.

Perguntas mais frequentes

Esta secção fornece respostas a perguntas comuns.

O que é OpenTelemetry?

É um novo padrão de código aberto para observabilidade. Saiba mais em OpenTelemetry.

Por que o Microsoft Azure Monitor está investindo em OpenTelemetry?

A Microsoft está entre os maiores contribuintes para o OpenTelemetry.

As principais propostas de valor do OpenTelemetry são que ele é neutro em relação ao fornecedor e fornece APIs/SDKs consistentes entre idiomas.

Com o tempo, acreditamos que o OpenTelemetry permitirá que os clientes do Azure Monitor observem aplicativos escritos em idiomas além dos nossos idiomas suportados. Ele também expande os tipos de dados que você pode coletar por meio de um rico conjunto de bibliotecas de instrumentação. Além disso, os SDKs OpenTelemetry tendem a ter mais desempenho em escala do que seus antecessores, os SDKs do Application Insights.

Finalmente, o OpenTelemetry está alinhado com a estratégia da Microsoft de adotar o código aberto.

Qual é o status do OpenTelemetry?

Consulte Status do OpenTelemetry .

O que é a "Distro OpenTelemetry do Azure Monitor"?

Você pode pensar nele como um wrapper fino que agrupa todos os componentes do OpenTelemetry para uma experiência de primeira classe no Azure. Este wrapper também é chamado de distribuição em OpenTelemetry.

Por que devo usar a "Distro OpenTelemetry do Azure Monitor"?

Há várias vantagens em usar a Distro OpenTelemetry do Azure Monitor em relação à OpenTelemetry nativa da comunidade:

No espírito da OpenTelemetry, projetamos a distro para ser aberta e extensível. Por exemplo, você pode adicionar:

  • Um exportador de protocolo OpenTelemetry (OTLP) e enviar para um segundo destino simultaneamente
  • Outras bibliotecas de instrumentação não incluídas na distribuição

Como a Distro fornece uma distribuição OpenTelemetria, a Distro suporta qualquer coisa suportada pela OpenTelemetry. Por exemplo, você pode adicionar mais processadores de telemetria, exportadores ou bibliotecas de instrumentação, se o OpenTelemetry oferecer suporte a eles.

Nota

A Distro define o amostrador como um amostrador personalizado de taxa fixa para o Application Insights. Você pode alterar isso para um amostrador diferente, mas isso pode desativar alguns dos recursos incluídos da distro. Para obter mais informações sobre o amostrador suportado, consulte a seção Habilitar amostragem de Configurar o Azure Monitor OpenTelemetry.

Para idiomas sem um exportador OpenTelemetry autônomo com suporte, a Distro OpenTelemetry do Azure Monitor é a única maneira atualmente suportada de usar o OpenTelemetry com o Azure Monitor. Para idiomas com um exportador OpenTelemetry autônomo com suporte, você tem a opção de usar a Distro OpenTelemetry do Azure Monitor ou o exportador OpenTelemetry autônomo apropriado, dependendo do seu cenário de telemetria. Para obter mais informações, consulte Quando devo usar o exportador do Azure Monitor OpenTelemetria?.

Como posso testar a Distro OpenTelemetry do Azure Monitor?

Confira nossos documentos de ativação para .NET, Java, JavaScript (Node.js) e Python.

Devo usar o OpenTelemetry ou o SDK do Application Insights?

Recomendamos o uso da Distro OpenTelemetry a menos que você precise de um recurso que só esteja disponível com suporte formal no SDK do Application Insights.

A adoção do OpenTelemetry agora evita a necessidade de migrar posteriormente.

Quando devo usar o exportador OpenTelemetry do Azure Monitor?

Para ASP.NET Core, Java, Node.js e Python, recomendamos o uso da Distro OpenTelemetry do Azure Monitor. É uma linha de código para começar.

Para todos os outros cenários .NET, incluindo ASP.NET clássico, aplicativos de console, etc., recomendamos usar o exportador OpenTelemetry do .NET Azure Monitor: Azure.Monitor.OpenTelemetry.Exporter.

Para cenários de telemetria Python mais complexos que exigem configuração avançada, recomendamos o uso do Python Azure Monitor OpenTelemetry Exporter.

Qual é o estado atual da versão dos recursos na Distro OpenTelemetry do Azure Monitor?

O gráfico a seguir detalha o suporte ao recurso OpenTelemetry para cada idioma.

Caraterística .NET Node.js Python Java
Rastreio distribuído ✅ ✅ ✅ ✅
Métricas personalizadas ✅ ✅ ✅ ✅
Métricas padrão (precisão atualmente afetada pela amostragem) ✅ ✅ ✅ ✅
Amostragem de taxa fixa ✅ ✅ ✅ ✅
Armazenamento offline e repetições automáticas ✅ ✅ ✅ ✅
Relatório de exceções ✅ ✅ ✅ ✅
Recolha de registos ✅ ⚠️ ✅ ✅
Eventos personalizados ⚠️ ⚠️ ⚠️ ✅
Autenticação do Microsoft Entra ✅ ✅ ✅ ✅
Métricas em tempo real ❌ ❌ ❌ ✅
Detetar contexto de recursos para VM/VMSS e Serviço de Aplicativo ✅ ❌ ✅ ✅
Detetar contexto de recursos para AKS e funções ❌ ❌ ❌ ✅
Filtragem de extensão de teste de disponibilidade ❌ ❌ ❌ ✅
Preenchimento automático de ID de usuário, ID de usuário autenticado e IP de usuário ❌ ❌ ❌ ✅
Substituir/definir manualmente o nome da operação, o ID do usuário ou o ID do usuário autenticado ❌ ❌ ❌ ✅
Amostragem adaptável ❌ ❌ ❌ ✅
Gerador de perfis ❌ ❌ ❌ ⚠️
Depurador de Instantâneos ❌ ❌ ❌ ❌

Chave

  • ✅ Este recurso está disponível para todos os clientes com suporte formal.
  • ⚠️ Esta funcionalidade está disponível como pré-visualização pública. Consulte Termos de utilização suplementares para pré-visualizações do Microsoft Azure.
  • ❌ Este recurso não está disponível ou não é aplicável.

O OpenTelemetry pode ser usado para navegadores da web?

Sim, mas não o recomendamos e o Azure não o suporta. OpenTelemetry JavaScript é altamente otimizado para Node.js. Em vez disso, recomendamos o uso do SDK JavaScript do Application Insights.

Quando podemos esperar que o SDK OpenTelemetry esteja disponível para uso em navegadores da Web?

O SDK da Web OpenTelemetry não tem um cronograma de disponibilidade determinado. É provável que estejamos a vários anos de distância de um SDK de navegador que seja uma alternativa viável ao SDK JavaScript do Application Insights.

Posso testar o OpenTelemetry em um navegador da Web hoje?

A área restrita da Web OpenTelemetry é uma bifurcação projetada para fazer o OpenTelemetry funcionar em um navegador. Ainda não é possível enviar telemetria para o Application Insights. O SDK não define eventos gerais do cliente.

A execução do Application Insights ao lado de agentes concorrentes como AppDynamics, DataDog e NewRelic é suportada?

N.º Essa prática não é algo que planejamos testar ou suportar, embora nossas Distros permitam que você exporte para um ponto de extremidade OTLP ao lado do Azure Monitor simultaneamente.

Posso usar recursos de visualização em ambientes de produção?

Nós não recomendamos. Consulte Termos de utilização suplementares para pré-visualizações do Microsoft Azure.

Qual é a diferença entre instrumentação manual e automática?

Consulte a Visão geral do OpenTelemetry .

Posso usar o OpenTelemetry Collector?

Alguns clientes usam o OpenTelemetry Collector como uma alternativa de agente, embora a Microsoft ainda não ofereça suporte oficial a uma abordagem baseada em agente para monitoramento de aplicativos. Enquanto isso, a comunidade de código aberto contribuiu com um OpenTelemetry Collector Azure Monitor Exporter que alguns clientes estão usando para enviar dados para o Azure Monitor Application Insights. Isso não é suportado pela Microsoft.

Qual é a diferença entre OpenCensus e OpenTelemetry?

OpenCensus é o precursor do OpenTelemetry. A Microsoft ajudou a reunir o OpenTracing e o OpenCensus para criar o OpenTelemetry, um padrão único de observabilidade para o mundo. O SDK Python recomendado de produção atual para o Azure Monitor é baseado no OpenCensus. A Microsoft está empenhada em tornar o Azure Monitor baseado no OpenTelemetry.

Resolução de Problemas

Não está funcionando? Consulte a página de resolução de problemas do ASP.NET Core.

Suporte

Selecione uma guia para o idioma de sua escolha para descobrir opções de suporte.

  • Para problemas de suporte do Azure, abra um tíquete de suporte do Azure.
  • Para problemas de OpenTelemetria, entre em contato diretamente com a comunidade OpenTelemetry .NET.
  • Para obter uma lista de problemas em aberto relacionados ao Azure Monitor Exporter, consulte a página Problemas do GitHub.

Comentários do OpenTelemetry

Para fornecer comentários: