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 coleta automaticamente rastreamentos, métricas, logs e exceções em seu aplicativo e suas dependências. 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.

Linguagem	Status da versão
.NET (Exportador)	✅ ¹
Java	✅ ¹
Node.js	✅ ¹
Python	✅ ¹
ASP.NET Core	⚠️ ²

Notas de rodapé

• ✅ ¹ : OpenTelemetry está disponível para todos os clientes com suporte formal.
• ⚠² ️ : OpenTelemetry está disponível como uma pré-visualização pública. Termos de Utilização Suplementares das Pré-visualizações do Microsoft Azure

Nota

Para obter um status de versão recurso por recurso, consulte as Perguntas frequentes. A ASP.NET Core Distro está passando por testes adicionais de estabilidade antes da GA. Você pode usar o .NET Exporter se precisar de uma solução OpenTelemetry totalmente suportada para seu aplicativo ASP.NET Core.

Introdução

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

• ASP.NET aplicativo principal usando uma versão oficialmente suportada do .NET Core

.NET

• Aplicativo usando uma versão oficialmente suportada do .NET Core ou .NET Framework que seja pelo menos o .NET Framework 4.6.2

Java

• Uma aplicação Java usando Java 8+

Node.js

Nota

Se você confia em quaisquer propriedades na tabela sem suporte, use a distribuição e forneceremos um guia de migração em breve. Se não, o shim do App Insights é o caminho mais fácil a seguir quando está fora da versão beta.

• Aplicação usando uma versão oficialmente suportada do tempo de execução .js Node:
  • Tempos de execução suportados pelo OpenTelemetry
  • Runtimes suportados pelo Azure Monitor OpenTelemetry Exporter

Python

• Aplicação Python usando Python 3.7+

Gorjeta

Não recomendamos o uso do SDK/API da Comunidade OTel com a Distro OTel do Azure Monitor, pois ela as carrega automaticamente como dependências.

Instalar a biblioteca de cliente

ASP.NET Core

Instale o pacote NuGet Azure.Monitor.OpenTelemetry.AspNetCore mais recente:

dotnet add package --prerelease Azure.Monitor.OpenTelemetry.AspNetCore 

.NET

Instale o pacote NuGet Azure.Monitor.OpenTelemetry.Exporter mais recente:

dotnet add package Azure.Monitor.OpenTelemetry.Exporter 

Java

Baixe o arquivo applicationinsights-agent-3.4.18.jar .

Aviso

Se você estiver atualizando de uma versão 3.x anterior, poderá ser afetado pela alteração de padrões ou pequenas diferenças nos dados que coletamos. Para obter mais informações, consulte a seção de migração nas notas de versão. 3.4.0, 3.3.0, 3.2.0 e 3.1.0

Node.js

Instale estes pacotes:

• @azure/monitor-opentelemetry

npm install @azure/monitor-opentelemetry

Os pacotes a seguir também são usados para alguns cenários específicos descritos posteriormente neste artigo:

• @opentelemetry/api
• @opentelemetry/sdk-metrics
• @opentelemetry/recursos
• @opentelemetry/convenções semânticas
• @opentelemetry/sdk-trace-base

npm install @opentelemetry/api
npm install @opentelemetry/sdk-metrics
npm install @opentelemetry/resources
npm install @opentelemetry/semantic-conventions
npm install @opentelemetry/sdk-trace-base

Python

Instale o pacote azure-monitor-opentelemetry PyPI mais recente:

pip install azure-monitor-opentelemetry

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

ASP.NET Core

Adicione UseAzureMonitor() à inicialização do seu aplicativo. Dependendo da sua versão do .NET, ele está na sua classe ou na sua startup.cs 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 the OpenTelemetry NuGet package to the application's services and configure OpenTelemetry to use Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor();

// Build the application.
var app = builder.Build();

// Run the application.
app.Run();

.NET

Adicione o Exportador do Azure Monitor a cada sinal OpenTelemetry na inicialização do aplicativo. Dependendo da sua versão do .NET, ele está na sua classe ou na sua startup.cs classe program.cs .

// Create a new tracer provider builder and add an Azure Monitor trace exporter to the tracer provider builder.
// It is important to keep the TracerProvider instance active throughout the process lifetime.
var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .AddAzureMonitorTraceExporter();

// Add an Azure Monitor metric exporter to the metrics provider builder.
// It is important to keep the MetricsProvider instance active throughout the process lifetime.
var metricsProvider = Sdk.CreateMeterProviderBuilder()
    .AddAzureMonitorMetricExporter();

// Create a new logger factory.
// It is important to keep the LoggerFactory instance active throughout the process lifetime.
var loggerFactory = LoggerFactory.Create(builder =>
{
    builder.AddOpenTelemetry(options =>
    {
        options.AddAzureMonitorLogExporter();
    });
});

Nota

Para obter mais informações, consulte o tutorial de introdução para OpenTelemetry .NET

Java

A autoinstrumentação Java é ativada através de alterações de configuração; não são necessárias alterações de código.

Aponte a JVM para o arquivo jar adicionando -javaagent:"path/to/applicationinsights-agent-3.4.18.jar" aos args da JVM do seu aplicativo.

Gorjeta

Para obter orientações específicas do cenário, consulte Introdução (suplementar).

Gorjeta

Se você desenvolver um aplicativo Spring Boot, poderá opcionalmente substituir o argumento JVM por uma configuração programática. Para obter mais informações, consulte Usando o Azure Monitor Application Insights com o Spring Boot.

Node.js

// Import the `useAzureMonitor()` function from the `@azure/monitor-opentelemetry` package.
const { useAzureMonitor } = require("@azure/monitor-opentelemetry");

// Call the `useAzureMonitor()` function to configure OpenTelemetry to use Azure Monitor.
useAzureMonitor();

Python

# Import the `configure_azure_monitor()` function from the
# `azure.monitor.opentelemetry` package.
from azure.monitor.opentelemetry import configure_azure_monitor

# Import the tracing api from the `opentelemetry` package.
from opentelemetry import trace

# Configure OpenTelemetry to use Azure Monitor with the specified connection
# string.
configure_azure_monitor(
    connection_string="<Your Connection String>",
)

# Get a tracer for the current module.
tracer = trace.get_tracer(__name__)

# Start a new span with the name "hello". This also sets this created span as the current span in this context. This span will be exported to Azure Monitor as part of the trace.
with tracer.start_as_current_span("hello"):
    print("Hello, World!")

# Wait for export to take place in the background.
input()

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:

1. Vá para o painel Visão geral do recurso do Application Insights.
2. Encontre sua cadeia de conexão.
3. 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.4.18.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 - ASP.NET Core, Node.js e Python Only (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, seguimos a seguinte precedência:

1. Código
2. Variável de Ambiente
3. 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.

Agora você habilitou o Application Insights 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.

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 a Matriz de conformidade de especificações 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.

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:
  • Preserva rastreamentos com componentes de serviço usando SDKs 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 no Azure
  • Métricas ao vivo (futuro)

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

• Um exportador OTLP e enviar para um segundo destino simultaneamente
• Bibliotecas de instrumentação da comunidade além do que está incluído no pacote

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?

Depende. Considere que a Distro OpenTelemetry do Azure Monitor ainda é "Visualização" e não está exatamente em paridade de recursos com os SDKs do Application Insights.

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.

Funcionalidade	.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 App Svc	✅	❌	✅	✅
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 cronograma de disponibilidade para o SDK da Web OpenTelemetry ainda não foi determinado. Provavelmente estamos a vários anos de distância de um SDK de navegador que será uma alternativa viável ao SDK JavaScript do Application Insights.

Posso testar o OpenTelemetry em um navegador da Web hoje?

O sandbox 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. Atualmente, o SDK não tem eventos gerais de cliente definidos.

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

Não 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 compilações 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.

Posso usar o Azure Monitor Exporter como um componente autônomo?

Sim, entendemos que alguns clientes podem querer instrumentar usando uma "abordagem fragmentada". No entanto, a distro fornece a maneira mais fácil de começar com a melhor experiência no Azure.

Qual é a diferença entre instrumentação manual e auto-instrumentação?

Consulte a Visão geral do OpenTelemetry .

Posso usar o OpenTelemetry Collector?

Alguns clientes começaram a usar 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.

Planejamos oferecer suporte a uma abordagem baseada em agente no futuro, mas os detalhes e o cronograma ainda não estão disponíveis. Nosso objetivo é fornecer um caminho para qualquer linguagem com suporte a OpenTelemetry enviar para o Azure Monitor por meio do Protocolo OpenTelemetry (OTLP). Essa abordagem permite que os clientes observem aplicativos escritos em idiomas além dos nossos idiomas suportados.

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. Eventualmente, todos os SDKs do Azure Monitor serão baseados no OpenTelemetry.

Resolução de problemas

ASP.NET Core

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

.NET

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

Java

Não está funcionando? Confira a página de solução de problemas para Java.

Node.js

Não está funcionando? Confira a página de solução de problemas do Node.js.

Python

Não está funcionando? Confira a página de solução de problemas para Python.

Suporte

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

ASP.NET Core

• Para problemas de suporte do Azure, abra um tíquete de suporte do Azure.
• Para problemas do OpenTelemetry , 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.

.NET

• Para problemas de suporte do Azure, abra um tíquete de suporte do Azure.
• Para problemas do OpenTelemetry , 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.

Java

• Para problemas de suporte do Azure, abra um tíquete de suporte do Azure.
• Para obter ajuda com a solução de problemas, revise as etapas de solução de problemas.
• Para problemas de OpenTelemetria, entre em contato diretamente com a comunidade OpenTelemetria.
• Para obter uma lista de problemas em aberto relacionados à Autoinstrumentação Java do Azure Monitor, consulte a página Problemas do GitHub.

Node.js

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

Python

• 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 Python.
• Para obter uma lista de problemas em aberto relacionados ao Azure Monitor Distro, 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.

Próximos passos

ASP.NET Core

• 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 OpenTelemetria, 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.

.NET

• 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 OpenTelemetria, consulte Configuração do Azure Monitor OpenTelemetry
• Para revisar o código-fonte, consulte o repositório GitHub do Exportador do Azure Monitor.
• Para instalar o pacote NuGet, verificar se há atualizações ou exibir notas de versão, consulte a página Pacote NuGet do Exportador do Azure Monitor.
• 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.

Java

• Para obter detalhes sobre como adicionar e modificar o Azure Monitor OpenTelemetry, consulte Adicionar e modificar o Azure Monitor OpenTelemetry
• Analise as opções de configuração de autoinstrumentação Java.
• Para revisar o código-fonte, consulte o repositório GitHub de autoinstrumentação Java do Azure Monitor.
• Para saber mais sobre o OpenTelemetry e sua comunidade, consulte o repositório JavaTelemetry GitHub do OpenTelemetry .
• Para habilitar experiências de uso, consulte Habilitar o monitoramento de usuários da Web ou do navegador.
• Veja as notas de versão no GitHub.

Node.js

• Para obter detalhes sobre como adicionar e modificar o Azure Monitor OpenTelemetry, consulte Adicionar e modificar o Azure Monitor OpenTelemetry
• Para revisar o código-fonte, consulte o repositório GitHub do Azure Monitor OpenTelemetry .
• Para instalar o pacote npm e verificar se há atualizações, consulte a página Pacote npm.@azure/monitor-opentelemetry
• Para se familiarizar com o Azure Monitor Application Insights 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 JavaScript GitHub.
• Para habilitar experiências de uso, habilite o monitoramento de usuários da Web ou do navegador.

Python

• Para obter detalhes sobre como adicionar e modificar o Azure Monitor OpenTelemetry, consulte Adicionar e modificar o Azure Monitor OpenTelemetry
• Para revisar o código-fonte e a documentação extra, consulte o repositório do Azure Monitor Distro GitHub.
• Para ver exemplos e casos de uso extras, consulte Exemplos de Distro do Azure Monitor.
• Veja as notas de versão no GitHub.
• Para instalar o pacote PyPI, verificar se há atualizações ou exibir notas de versão, consulte a página Azure Monitor Distro PyPI Package .
• Para se familiarizar com o Azure Monitor Application Insights 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 Python GitHub.
• Para ver as instrumentações e componentes OpenTelemetry disponíveis, consulte o repositório Python GitHub do OpenTelemetry Contributor.
• Para habilitar experiências de uso, habilite o monitoramento de usuários da Web ou do navegador.