Habilitar o Azure Monitor OpenTelemetry para aplicativos .NET, Node.js, Python e Java
Este artigo descreve como habilitar e configurar a coleta de dados baseada em OpenTelemetry para potencializar as experiências no Azure Monitor Application Insights. Explicamos como instalar a Distro OpenTelemetry do Azure Monitor. A Distro OpenTelemetry do Azure Monitor fornece uma distribuição OpenTelemetry que inclui suporte para recursos específicos do Azure Monitor. A Distro permite a telemetria automática incluindo bibliotecas de instrumentação 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 Distro para monitorar e coletar mais telemetria de aplicativos Web ao vivo em produção. Para obter mais informações sobre as vantagens de usar a Distro OpenTelemetry do Azure Monitor, consulte Por que devo usar a "Distro OpenTelemetry do Azure Monitor"?.
Para saber mais sobre como coletar dados usando OpenTelemetry, consulte Noções básicas de coleta de dados ou Perguntas frequentes sobre OpenTelemetria.
Status da versão do OpenTelemetry
As ofertas OpenTelemetry estão disponíveis para aplicativos .NET, Node.js, Python e Java.
Nota
- Para obter um status de versão recurso por recurso, consulte as Perguntas frequentes.
- A segunda guia deste artigo abrange todos os cenários .NET, incluindo ASP.NET clássico, aplicativos de console, Windows Forms (WinForms), etc.
Começar agora
Siga as etapas nesta seção para instrumentar seu aplicativo com OpenTelemetry.
Pré-requisitos
- Uma assinatura do Azure: crie uma assinatura do Azure gratuitamente
- Um recurso do Application Insights: Criar um recurso do Application Insights
- ASP.NET Core Application usando uma versão oficialmente suportada do .NET
Gorjeta
Se você estiver migrando da API do Application Insights Classic, consulte nossa documentação de migração.
Instalar a biblioteca de cliente
Instale o pacote NuGet mais recente:Azure.Monitor.OpenTelemetry.AspNetCore
dotnet add package Azure.Monitor.OpenTelemetry.AspNetCore
Habilitar o Azure Monitor Application Insights
Para habilitar o Azure Monitor Application Insights, faça uma pequena modificação em seu aplicativo e defina sua "Cadeia de Conexão". A Cadeia de Conexão informa ao seu aplicativo para onde enviar a telemetria que a Distro coleta e é exclusiva para você.
Modificar a sua Aplicação
Adicione UseAzureMonitor()
à inicialização do aplicativo, localizada em sua program.cs
classe.
// 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();
Copie a cadeia de conexão do recurso do Application Insights
Gorjeta
Se você ainda não tem um, agora é um ótimo momento para criar um recurso do Application Insights. Veja quando recomendamos que você crie um novo recurso do Application Insights em vez de usar um existente.
Para copiar sua Cadeia de Conexão exclusiva:
- Vá para o painel Visão geral do recurso do Application Insights.
- Encontre sua cadeia de conexão.
- Passe o cursor sobre a cadeia de conexão e selecione o ícone Copiar para a área de transferência.
Cole a cadeia de conexão em seu ambiente
Para colar a Cadeia de Conexão, selecione uma das seguintes opções:
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.4.jar
com o seguinte conteúdo:
{
"connectionString": "<Your Connection String>"
}
Substitua <Your Connection String>
o JSON anterior por sua cadeia de conexão exclusiva.
C. Definir via código - apenas ASP.NET Core, Node.js e Python (não recomendado)
Consulte Configuração da Cadeia de Conexão para obter um exemplo de configuração da Cadeia de Conexão via código.
Nota
Se você definir a cadeia de conexão em mais de um lugar, respeitaremos a seguinte precedência:
- Código
- Variável de Ambiente
- Arquivo de configuração
Confirmar que os dados estão fluindo
Execute seu aplicativo e abra a guia Application Insights Resource no portal do Azure. Pode levar alguns minutos para que os dados apareçam no portal.
O Application Insights agora está habilitado para seu aplicativo. Todas as etapas a seguir são opcionais e permitem mais personalização.
Importante
Se você tiver dois ou mais serviços que emitem telemetria para o mesmo recurso do Application Insights, será necessário definir Nomes de Função na 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 melhorar o Application Insights. Para saber mais, consulte Statsbeat no Azure Application Insights.
Exemplos
Os aplicativos de exemplo do Azure Monitor OpenTelemetry estão disponíveis para todos os idiomas com suporte.
Próximos passos
- Para obter detalhes sobre como adicionar e modificar o Azure Monitor OpenTelemetry, consulte Adicionar e modificar o Azure Monitor OpenTelemetry.
- Para configurar ainda mais a distro OpenTelemetry , consulte Configuração do Azure Monitor OpenTelemetry .
- Para revisar o código-fonte, consulte o repositório GitHub do Azure Monitor AspNetCore.
- Para instalar o pacote NuGet, verificar se há atualizações ou exibir notas de versão, consulte a página Pacote NuGet do Azure Monitor AspNetCore.
- Para se familiarizar com o Azure Monitor e o OpenTelemetry, consulte o Aplicativo de exemplo do Azure Monitor.
- Para saber mais sobre o OpenTelemetry e sua comunidade, consulte o repositório OpenTelemetry .NET GitHub.
- Para habilitar experiências de uso, habilite o monitoramento de usuários da Web ou do navegador.
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á investindo no OpenTelemetry pelos seguintes motivos:
- É independente do fornecedor e fornece APIs/SDKs consistentes em todos os 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 expande os tipos de dados que você pode coletar por meio de um rico conjunto de bibliotecas de instrumentação.
- Os SDKs (Software Development Kits) OpenTelemetry tendem a ter um desempenho mais eficiente em escala do que seus antecessores, os SDKs do Application Insights.
- 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:
- Reduz o esforço de habilitação
- Suportado pela Microsoft
- Traz recursos específicos do Azure, como:
- Amostragem compatível com SDKs clássicos do Application Insights
- Autenticação do Microsoft Entra
- Armazenamento off-line e novas tentativas automáticas
- Statsbeat
- Métricas padrão do Application Insights
- Detetar metadados de recursos para preencher automaticamente o Nome da Função de Nuvem e a Instância de Função de Nuvem em vários ambientes do Azure
- Live Metrics
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, Windows Forms (WinForms), etc., recomendamos o uso do 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 | ✅ | ✅ | ✅ | ✅ |
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 | ✅ | ✅ | ✅ | ✅ |
Filtragem de métricas em tempo real | ✅ | ❌ | ❌ | ❌ |
Detetar contexto de recursos para VM/VMSS e Serviço de Aplicativo | ✅ | ❌ | ✅ | ✅ |
Detetar contexto de recursos para o Serviço Kubernetes do Azure (AKS) e funções | ❌ | ❌ | ❌ | ✅ |
Eventos de teste de disponibilidade gerados usando a API de controle de disponibilidade | ❌ | ❌ | ❌ | ✅ |
Filtrar solicitações, dependências, logs e exceções por ID de usuário anônimo e fonte sintética | ❌ | ❌ | ❌ | ✅ |
Filtrar dependências, logs e exceções por nome da operação | ❌ | ❌ | ❌ | ✅ |
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?
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.
Em Grafana, por que eu vejo Status: 500. Can't visualize trace events using the trace visualizer
?
Você pode estar tentando visualizar logs de texto bruto em vez de rastreamentos OpenTelemetry .
No Application Insights, a tabela 'Rastreamentos' armazena logs de texto bruto para fins de diagnóstico. Eles ajudam a identificar e correlacionar rastreamentos associados a solicitações de usuários, outros eventos e relatórios de exceções. No entanto, a tabela 'Rastreamentos' não contribui diretamente para a visualização de transação de ponta a ponta (gráfico em cascata) em ferramentas de visualização como o Grafana.
Com a crescente adoção de práticas nativas da nuvem, há uma evolução na coleta de telemetria e na terminologia. OpenTelemetry tornou-se um padrão para coletar e instrumentar dados de telemetria. Neste contexto, o termo «vestígios» adquiriu um novo significado. Em vez de logs brutos, 'Traces' no OpenTelemetry referem-se a uma forma mais rica e estruturada de telemetria que inclui vãos, que representam unidades individuais de trabalho. Essas extensões são cruciais para construir visualizações detalhadas de transações, permitindo um melhor monitoramento e diagnóstico de aplicativos nativos da nuvem.
Resoluçã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 ao aceitar a fonte nomeada OpenTelemetry-AzureMonitor-Exporter
. Para conhecer 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
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 seu servidor Web ou computador host de 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 Azure Monitor Application Insights.
Problemas conhecidos
Os seguintes itens são problemas conhecidos para os Exportadores 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 de 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 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:
- Preencha a pesquisa de feedback do cliente da comunidade OpenTelemetria.
- Informe a Microsoft sobre si mesmo juntando-se à OpenTelemetry Early Adopter Community.
- Interaja com outros usuários do Azure Monitor na Comunidade Técnica da Microsoft.
- Faça uma solicitação de recurso no Fórum de Comentários do Azure.