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 o envio de dados de telemetria, garantindo que ela atinja 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 aplicativo, em sua classe program.cs.

    // 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 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 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();

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. A amostra foi criada para preservar seus rastreamentos entre os serviços e é interoperável com SDKs do Application Insights mais antigos. 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(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();

Dica

Ao usar a amostragem a taxa fixa ou por percentual e não ter a certeza a que índice 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 nas folhas de desempenho e falhas. 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.

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.

Perguntas frequentes

Esta seção fornece respostas para perguntas comuns.

O que é o OpenTelemetry?

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

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

A Microsoft está entre os maiores colaboradores do OpenTelemetry.

As principais propostas de valor do OpenTelemetry são a neutralidade de fornecedor e o fornecimento de APIs/SDKs consistentes em várias linguagens.

Ao longo do tempo, acreditamos que o OpenTelemetry permitirá que os clientes do Azure Monitor observem os aplicativos escritos em linguagens além das nossas linguagens com suporte. Ele também expande os tipos de dados que você pode coletar através de um conjunto avançado de bibliotecas de instrumentação. Além disso, os SDKs do OpenTelemetry tendem a ter mais desempenho em escala do que seus antecessores, os SDKs do Application Insights.

Por fim, o OpenTelemetry se alinha com a estratégia da Microsoft de adoção de código aberto.

Qual é o status do OpenTelemetry?

Confira Status do OpenTelemetry.

O que é a "Distribuição OpenTelemetry do Azure Monitor"?

Você pode pensar nisso como um invólucro fino que reúne todos os componentes do OpenTelemetry para uma experiência de primeira classe no Azure. Esse wrapper também é chamado de distribuição no OpenTelemetry.

Por que devo usar a "Distribuição OpenTelemetry do Azure Monitor"?

Há várias vantagens em usar a Distribuição OpenTelemetry do Azure Monitor em relação ao OpenTelemetry nativo da comunidade:

No espírito do OpenTelemetry, projetamos a distribuição para ser aberta e extensível. Por exemplo, você pode adicionar:

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

Como a Distribuição oferece uma distribuição do OpenTelemetry, ela suporta tudo o que é suportado pelo OpenTelemetry. Por exemplo, você pode adicionar mais processadores de telemetria, exportadores ou bibliotecas de instrumentação se o OpenTelemetry der suporte a eles.

Observação

A Distribuição define o amostrador para um amostrador personalizado de taxa fixa para o Application Insights. Você pode alterar isso para um amostrador diferente, mas fazê-lo pode desabilitar alguns dos recursos incluídos na Distribuição. Para obter mais informações sobre o amostrador com suporte, consulte a seção Habilitar Amostragem de Configurar o OpenTelemetry do Azure Monitor.

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

Como posso testar a Distribuição 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?

É recomendável usar a Distribuição do OpenTelemetry, a menos que você exija um recurso disponível apenas com suporte formal no SDK do Application Insights.

A adoção do OpenTelemetry agora impede a migração em uma data posterior.

Quando devo usar a o exportador do OpenTelemetry do Azure Monitor?

No caso do ASP.NET Core, do Java, do Node.js e do Python, recomendamos usar a Distribuição do OpenTelemetry para Azure Monitor. Basta uma linha de código para começar.

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

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

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

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

Recurso .NET Node.js Python Java
Rastreamento distribuído ✅ ✅ ✅ ✅
Métricas personalizadas ✅ ✅ ✅ ✅
Métricas Padrão (precisão atualmente afetada pela amostragem) ✅ ✅ ✅ ✅
Amostragem de taxa fixa ✅ ✅ ✅ ✅
Armazenamento offline e novas tentativas automáticas ✅ ✅ ✅ ✅
Relatório de exceção ✅ ✅ ✅ ✅
Coleção de logs ✅ ⚠️ ✅ ✅
Eventos personalizados ⚠️ ⚠️ ⚠️ ✅
autenticação do Microsoft Entra ✅ ✅ ✅ ✅
Live Metrics ❌ ❌ ❌ ✅
Detectar Contexto do Recurso de VM/VMSS e Serviço de Aplicativo ✅ ❌ ✅ ✅
Detectar o Contexto do Recurso do AKS e das Funções ❌ ❌ ❌ ✅
Filtragem da Extensão do Teste de Disponibilidade ❌ ❌ ❌ ✅
Preenchimento automático da ID de usuário, ID de usuário autenticado e IP do usuário ❌ ❌ ❌ ✅
Substituir/definir manualmente o nome da operação, a ID de usuário ou a ID de usuário autenticado ❌ ❌ ❌ ✅
amostragem adaptável ❌ ❌ ❌ ✅
Profiler ❌ ❌ ❌ ⚠️
Depurador de instantâneo ❌ ❌ ❌ ❌

Chave

O OpenTelemetry pode ser usado para navegadores da Web?

Sim, mas não recomendamos e o Azure não dá suporte a ele. O Javascript do OpenTelemetry é altamente otimizado para Node.js. Nesse caso, recomendamos usar o SDK do JavaScript do Application Insights.

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

O SDK da Web do OpenTelemetry não tem uma linha do tempo de disponibilidade determinada. Deve demorar alguns anos para algum SDK de navegador ser uma alternativa viável ao SDK do JavaScript do Application Insights.

Posso testar o OpenTelemetry em um navegador da Web hoje?

A área restrita Web do 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.

Há suporte para a execução do Application Insights junto com agentes concorrentes, como o AppDynamics, DataDog e NewRelic?

Não. Essa prática não é algo que planejamos testar ou oferecer suporte, embora nossas distribuições permitam que você exporte para um ponto de extremidade OTLP junto com o Azure Monitor simultaneamente.

Posso usar versão prévia do recurso em ambientes de produção?

Não recomendamos isso. Consulte os Termos de uso complementares para versões prévias do Microsoft Azure.

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

Consulte a Visão geral do OpenTelemetry.

Posso usar o Coletor do OpenTelemetry?

Alguns clientes usam o Coletor do OpenTelemetry como uma alternativa de agente, embora a Microsoft ainda não dê suporte oficial a uma abordagem baseada em agente para o monitoramento de aplicativos. Enquanto isso, a comunidade de código aberto contribuiu com um Exportador do Azure Monitor para o Coletor do OpenTelemetry, que alguns clientes estão usando para enviar dados para o Application Insights do Azure Monitor. Isso não tem suporte da Microsoft.

Qual é a diferença entre o OpenCensus e o OpenTelemetry?

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

Solução de problemas

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

Suporte

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

Comentários sobre o OpenTelemetry

Para fornecer comentários: