Habilitar o OpenTelemetry do Azure Monitor para aplicativos .NET, Node.js, Python e Java
Este artigo descreve como habilitar e configurar a coleta de dados baseada em OpenTelemetry para alimentar as experiências no Application Insights do Azure Monitor. Explicamos como instalar a Distribuição do OpenTelemetry do Azure Monitor. A Distribuição do OpenTelemetry do Azure Monitor fornece uma distribuição do OpenTelemetry que inclui suporte para recursos específicos do Azure Monitor. A Distribuição habilita telemetria automática, incluindo bibliotecas de instrumentação do OpenTelemetry para coletar rastreamentos, métricas, logs e exceções e permite coletar telemetria personalizada. Você também pode usar o recurso Live Metrics incluído na Distribuição para monitorar e coletar mais telemetria de aplicativos Web ao vivo e em produção. Para obter mais informações sobre as vantagens de usar a Distribuição do OpenTelemetry do Azure Monitor, consulte Por que devo usar a "Distribuição do OpenTelemetry do Azure Monitor"?.
Para saber mais sobre como coletar dados usando o OpenTelemetry, confira Noções básicas de coleta de dados ou Perguntas frequentes sobre o OpenTelemetry.
Status de versão do OpenTelemetry
As ofertas do OpenTelemetry estão disponíveis para aplicativos .NET, Node.js, Python e Java.
Observação
- Para obter um status de versão de recurso por recurso, confira as Perguntas frequentes.
- A segunda guia deste artigo aborda todos os cenários do .NET, incluindo ASP.NET clássico, aplicativos de console, Windows Forms (WinForms), etc.
Introdução
Siga as etapas nesta seção para instrumentar seu aplicativo com o OpenTelemetry.
Pré-requisitos
- Uma assinatura do Azure: criar uma assinatura do Azure gratuitamente
- Um recurso do Application Insights: criar um recurso do Application Insights
- Aplicativo ASP.NET Core que usa uma versão com suporte oficial do .NET
Dica
Se você estiver migrando da API Clássica do Application Insights, consulte nossa documentação de migração.
Instalar a biblioteca de clientes
Instale o pacote Azure.Monitor.OpenTelemetry.AspNetCore
NuGet mais recente:
dotnet add package Azure.Monitor.OpenTelemetry.AspNetCore
Habilitar o Application Insights do Azure Monitor
Para habilitar o Application Insights do Azure Monitor, faça uma pequena modificação em seu aplicativo e defina a "Cadeia de Conexão". A Cadeia de Conexão informa ao aplicativo para onde enviar a telemetria que o Distro coleta e é exclusiva para você.
Modificar o Aplicativo
Adicione UseAzureMonitor()
à inicialização do aplicativo, localizada em sua classe program.cs
.
// Import the Azure.Monitor.OpenTelemetry.AspNetCore namespace.
using Azure.Monitor.OpenTelemetry.AspNetCore;
// Create a new WebApplicationBuilder instance.
var builder = WebApplication.CreateBuilder(args);
// Add OpenTelemetry and configure it to use Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor();
// Build the application.
var app = builder.Build();
// Run the application.
app.Run();
Copiar a Cadeia de Conexão do seu Recurso do Application Insights
Dica
Se você ainda não tiver um, agora é um ótimo momento para Criar um recurso do Application Insights . Neste momento é quando recomendamos criar um novo recurso do Application Insights Resource em vez de usar um existente.
Para copiar sua Cadeia de Conexão exclusiva:
- Acesse o painel Visão geral do recurso Application Insights.
- Localize sua Cadeia de Conexão.
- Passe o mouse sobre a cadeia de conexão e selecione o ícone Copiar para a área de transferência.
Cole a cadeia de conexão no seu ambiente
Para colar sua Cadeia de Conexão, selecione uma das opções a seguir:
a. Definir via Variável de Ambiente (recomendado)
Substitua <Your Connection String>
no comando a seguir por sua cadeia de conexão exclusiva.
APPLICATIONINSIGHTS_CONNECTION_STRING=<Your Connection String>
B. Definir via Arquivo de Configuração - Somente Java (Recomendado)
Crie um arquivo de configuração chamado applicationinsights.json
e coloque-o no mesmo diretório que applicationinsights-agent-3.5.3.jar
com o seguinte conteúdo:
{
"connectionString": "<Your Connection String>"
}
Substitua <Your Connection String>
no JSON anterior por sua cadeia de conexão exclusiva.
C. Definido via Código; Somente ASP.NET Core, Node.js e Python (Não recomendado)
Consulte Configuração da Cadeia de Conexão para, por exemplo, definir a Cadeia de Conexão por meio de código.
Observação
Se você definir a cadeia de conexão em mais de um local, seguiremos a seguinte precedência:
- Código
- Variável de ambiente
- Arquivo de configuração
Confirmar se os dados estão fluindo
Execute o aplicativo e abra a guia Recurso do Application Insights no portal do Azure. Pode levar alguns minutos para os dados aparecerem no portal.
Agora, o Application Insights está habilitado para seu aplicativo. Todas as etapas a seguir são opcionais e permitem uma personalização adicional.
Importante
Se você tem dois ou mais serviços que emitem telemetria para o mesmo recurso do Application Insights, precisa definir Nomes de Função de Nuvem para representá-los corretamente no Mapa do Aplicativo.
Como parte do uso da instrumentação do Application Insights, coletamos e enviamos dados de diagnóstico para a Microsoft. Esses dados nos ajudam a executar e a aprimorar o Application Insights. Para saber mais, confira Statsbeat no Azure Application Insights.
Exemplos
Os aplicativos de exemplo do OpenTelemetry do Azure Monitor estão disponíveis para todos os idiomas com suporte.
Próximas etapas
- Para mais detalhes sobre como adicionar e modificar o OpenTelemetry do Azure Monitor, confira Adicionar e modificar o OpenTelemetry do Azure Monitor.
- Para configurar ainda mais a Distribuição do OpenTelemetry, confira Configuração do OpenTelemetry do Azure Monitor.
- Para revisar o código-fonte, acesse o repositório do GitHub AspNetCore do Azure Monitor.
- Para instalar o pacote NuGet, verificar se há atualizações ou exibir as notas de versão, consulte a página Pacote NuGet AspNetCore do Azure Monitor.
- Para se familiarizar com o Application Insights do Azure Monitor e o OpenTelemetry, confira o Aplicativo de exemplo do Azure Monitor.
- Para saber mais sobre o OpenTelemetry e a respectiva comunidade, confira o Repositório GitHub do .NET do OpenTelemetry.
- Para habilitar experiências de usuário, habilite o monitoramento de usuário de navegador ou da Web.
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 (Software Development Kits) 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:
- Reduz o esforço da habilitação
- Compatível com a Microsoft
- Inclui recursos específicos do Azure, como:
- Amostragem compatível com os SDKs clássicos do Application Insights
- autenticação do Microsoft Entra
- Armazenamento offline e novas tentativas automáticas
- Statsbeat
- Métricas Padrão do Application Insights
- Detectar metadados de recurso para preencher automaticamente o Nome da Função na Nuvem e a Instância da Função na Nuvem em vários ambientes do Azure
- Métricas Dinâmicas
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 de .NET, incluindo ASP.NET clássico, aplicativos de console, Windows Forms (WinForms) etc., recomendamos o uso do exportador OpenTelemetry do Azure Monitor para .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 | ✅ | ✅ | ✅ | ✅ |
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 | ✅ | ✅ | ✅ | ✅ |
Filtragem de métricas dinâmicas | ❌ | ❌ | ❌ | ❌ |
Detectar Contexto do Recurso de VM/VMSS e Serviço de Aplicativo | ✅ | ❌ | ✅ | ✅ |
Detectar o contexto de recursos para o AKS (Serviço de Kubernetes do Azure) e o Functions | ❌ | ❌ | ❌ | ✅ |
Eventos de teste de disponibilidade gerados usando a API de Disponibilidade de Acompanhamento | ❌ | ❌ | ❌ | ✅ |
Filtrar solicitações, dependências, logs e exceções por ID de usuário anônima e origem sintética | ❌ | ❌ | ❌ | ✅ |
Filtrar dependências, logs e exceções por nome da operação | ❌ | ❌ | ❌ | ✅ |
amostragem adaptável | ❌ | ❌ | ❌ | ✅ |
Profiler | ✅ | ❌ | ❌ | ⚠️ |
Depurador de instantâneo | ✅ | ❌ | ❌ | ❌ |
Chave
- ✅ Esse recurso está disponível para todos os clientes com suporte formal.
- ⚠ Esse recurso está disponível em versão prévia pública. Consulte os Termos de uso complementares para versões prévias do Microsoft Azure.
- ❌ Esse recurso não está disponível ou não é aplicável.
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?
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
Etapa 1: Habilitar o log de diagnóstico
O Exportador do Azure Monitor usa EventSource para seu log interno. Os logs do exportador estão disponíveis para qualquer EventListener aceitando a origem chamada OpenTelemetry-AzureMonitor-Exporter
. Para obter as etapas de solução de problemas, consulte Solução de problemas do OpenTelemetry no GitHub.
Etapa 2: Testar a conectividade entre o host do aplicativo e o serviço de ingestão
Os SDKs e agentes do Application Insights enviam telemetria para serem ingeridos como chamadas REST em nossos pontos de extremidade de ingestão. Para testar a conectividade do servidor Web ou do computador host do aplicativo com os pontos de extremidade do serviço de ingestão, use comandos cURL ou solicitações REST brutas do PowerShell. Para obter mais informações, consulte Solucionar problemas de telemetria de aplicativo ausente no Application Insights do Azure Monitor.
Problemas conhecidos
Os seguintes itens são problemas conhecidos para os exportadores do OpenTelemetry do Azure Monitor:
O nome da operação está ausente da telemetria de dependência. O nome da operação ausente causa falhas e afeta negativamente a experiência da guia de desempenho.
O modelo do dispositivo está ausente da telemetria de solicitação e dependência. O modelo de dispositivo ausente afeta negativamente a análise de coorte de dispositivos.
Suporte
Selecione uma guia para o idioma de sua escolha para descobrir as opções de suporte.
- Se você tiver problemas com o Suporte do Azure, abra um tíquete de suporte do Azure.
- Para problemas de OpenTelemetry, entre em contato diretamente com a comunidade do OpenTelemetry .NET.
- Para obter uma lista de problemas abertos relacionados ao Exportador do Azure Monitor, confira a Página de Problemas do GitHub.
Comentários sobre o OpenTelemetry
Para fornecer comentários:
- Preencha a pesquisa de comentários do cliente da Comunidade do OpenTelemetry.
- Fale um pouco sobre você para a Microsoft: ingresse na Comunidade de usuário pioneiro do OpenTelemetry.
- Entre em contato com outros usuários do Azure Monitor na Comunidade de tecnologia da Microsoft.
- Solicite um recurso no Fórum de comentários do Azure.
Comentários
https://aka.ms/ContentUserFeedback.
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulteEnviar e exibir comentários de