Habilitar 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 em Azure Monitor Application Insights usando o Azure Monitor OpenTelemetry Distro. OpenTelemetry é o padrão de observabilidade de código aberto da CNCF; o Azure Monitor OpenTelemetry Distro é a distribuição da Microsoft desse padrão, otimizada para o Azure Monitor. A distribuição:

• Fornece uma distribuição OpenTelemetry, que inclui suporte para recursos específicos de Azure Monitor.
• Ativa a coleta automática de telemetria por meio da inclusão de bibliotecas de instrumentação do OpenTelemetry para coletar rastreamentos, métricas, registros e exceções.
• Permite coletar telemetria personalizada.
• Dá suporte às Métricas em Tempo Real para monitorar e coletar telemetria de aplicativos web em produção.

Para obter mais informações sobre as vantagens de usar o Azure Monitor OpenTelemetry Distro, consulte Por que devo usar o Azure Monitor OpenTelemetry Distro.

Para saber mais sobre como coletar dados usando o OpenTelemetry, confira a visão geral do Application Insights ou as perguntas frequentes sobre o OpenTelemetry.

Siga as etapas neste artigo para instalar a distribuição, conectá-la ao recurso do Application Insights e verificar se os dados de telemetria fluem para Azure Monitor.

Dica

Para obter uma visão conceitual geral das opções do OpenTelemetry no Azure Monitor — ingestão OTLP nativa, a distribuição Microsoft OpenTelemetry e experiências de observabilidade de ponta a ponta — consulte OpenTelemetry com Azure Monitor.

Status de versão do OpenTelemetry

As ofertas do OpenTelemetry estão disponíveis para aplicativos .NET, Node.js, Python e Java. Para obter um status de versão de recurso por recurso, confira as Perguntas frequentes.

Observação

Para aplicativos do Azure Functions, consulte Usar OpenTelemetry com o Azure Functions.

Habilitar o OpenTelemetry com o Application Insights

Siga as etapas nesta seção para instrumentar seu aplicativo com o OpenTelemetry. Selecione uma aba para instruções específicas do idioma.

A tabela a seguir resume os pacotes e os comandos de instalação para cada idioma com suporte:

Linguagem	Package	Comando de Instalação
ASP.NET Core	Azure.Monitor.OpenTelemetry.AspNetCore	dotnet add package Azure.Monitor.OpenTelemetry.AspNetCore
.NET	Azure.Monitor.OpenTelemetry.Exporter	dotnet add package Azure.Monitor.OpenTelemetry.Exporter
Java	applicationinsights-agent-3.7.8.jar	Download de GitHub
Node.js	@azure/monitor-opentelemetry	npm install @azure/monitor-opentelemetry
Python	azure-monitor-opentelemetry	pip install azure-monitor-opentelemetry

Observação

.NET abrange vários cenários, incluindo ASP.NET clássicos, aplicativos de console, Windows Forms (WinForms) e muito mais.

Pré-requisitos

• Azure assinatura: Criar uma assinatura Azure gratuitamente
• Recurso do Application Insights: criar um recurso do Application Insights

ASP.NET Core

• ASP.NET Core Application usando uma versão oficialmente compatível do .NET

Dica

Se você estiver migrando de SDKs mais antigos do Application Insights, consulte nossa documentação de migração.

.NET

• Aplicativo usando uma versão suportada de .NET ou .NET Framework 4.6.2 e posterior.

Dica

Se você estiver migrando de SDKs mais antigos do Application Insights, consulte nossa documentação de migração.

Java

• Um aplicativo Java usando Java 8+

Java nativo

• Um aplicativo Java usando GraalVM 17+

Node.js

• Aplicativo usando uma versão oficialmente suportada de Node.js runtime:
  • Tempos de execução com suporte do OpenTelemetry
  • Azure Monitor tempos de execução com suporte do exportador OpenTelemetry

Observação

Se você não depende de nenhuma propriedade informada na tabela não compatível, o ApplicationInsights shim é o caminho mais fácil a seguir depois que sair do beta.

Se você depender de qualquer uma dessas propriedades, prossiga com o Azure Monitor OpenTelemetry Distro.

Dica

Se você estiver migrando de SDKs mais antigos do Application Insights, consulte nossa documentação de migração.

Python

• aplicativo Python usando Python 3.8+

Dica

Se você estiver migrando do OpenCensus, consulte nossa documentação de migração.

Instalar a biblioteca de clientes

ASP.NET Core

Instale o pacote Azure.Monitor.OpenTelemetry.AspNetCoreNuGet mais recente:

dotnet add package Azure.Monitor.OpenTelemetry.AspNetCore

.NET

Instale o pacote Azure.Monitor.OpenTelemetry.ExporterNuGet mais recente:

dotnet add package Azure.Monitor.OpenTelemetry.Exporter

Java

Baixe o arquivo applicationinsights-agent-3.7.8.jar mais recente.

Aviso

Se você estiver atualizando de uma versão anterior do 3.x, 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 sobre a versão. 3.5.0, 3.4.03.3.0, 3.2.0 e 3.1.0

Java nativo

Para aplicativos nativos do Spring Boot:

• Importe as Notas de Materiais do OpenTelemetry (BOM).
• Adicione a dependência Spring Cloud Azure Starter Monitor.
• Siga essas instruções para os arquivos JAR (Java Archive) do SDK Azure.

Para aplicativos nativos do Quarkus:

• Adicione a dependência Quarkus OpenTelemetry Exporter for Azure.

Observação

A comunidade do Quarkus dá suporte e mantém extensões do Quarkus. Para obter ajuda, use os canais de suporte da comunidade do Quarkus. Microsoft não fornece suporte técnico para essa integração.

Node.js

Instale o pacote mais recente @azure/monitor-opentelemetry :

npm install @azure/monitor-opentelemetry

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

• @opentelemetry/api
• @opentelemetry/sdk-metrics
• @opentelemetry/resources
• @opentelemetry/semantic-conventions
• @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 a versão mais recente do pacote PyPI azure-monitor-opentelemetry:

pip install azure-monitor-opentelemetry

Modificar o aplicativo

ASP.NET Core

Importe o namespace Azure.Monitor.OpenTelemetry.AspNetCore, adicione OpenTelemetry e configure-o para usar Azure Monitor na classe program.cs:

// Import the Azure.Monitor.OpenTelemetry.AspNetCore namespace.
using Azure.Monitor.OpenTelemetry.AspNetCore;

var builder = WebApplication.CreateBuilder(args);

// Add OpenTelemetry and configure it to use Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor();

var app = builder.Build();

app.Run();

.NET

Adicione o exportador de Azure Monitor a cada sinal OpenTelemetry na 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.
// See https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/docs/trace#tracerprovider-management
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.
// See https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/docs/metrics#meterprovider-management
var metricsProvider = Sdk.CreateMeterProviderBuilder()
    .AddAzureMonitorMetricExporter();

// Create a new logger factory.
// It is important to keep the LoggerFactory instance active throughout the process lifetime.
// See https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/docs/logs#logger-management
var loggerFactory = LoggerFactory.Create(builder =>
{
    builder.AddOpenTelemetry(logging =>
    {
        logging.AddAzureMonitorLogExporter();
    });
});

Observação

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

Java

A instrumentação automática é habilitada por meio de alterações de configuração. Nenhuma alteração de código é necessária.

Direcione a máquina virtual Java (JVM) para o arquivo jar adicionando -javaagent:"path/to/applicationinsights-agent-3.7.8.jar" aos argumentos da JVM do aplicativo.

Observação

A amostragem é habilitada por padrão a uma taxa de cinco solicitações por segundo, auxiliando no gerenciamento de custos. Os dados de telemetria podem estar ausentes em cenários que excedem essa taxa. Para obter mais informações sobre como modificar a configuração da amostragem, consulte substituições de amostragem. Se você estiver vendo encargos inesperados ou custos altos no Application Insights, este guia poderá ajudar. Ele aborda causas comuns, como alto volume de telemetria, picos de ingestão de dados e amostragem configurada incorretamente. É especialmente útil se você estiver solucionando problemas relacionados a picos de custo, volume de telemetria, amostragem não funcionando, limites de dados, ingestão alta ou cobrança inesperada. Para começar, veja Solucionar problemas de alta ingestão de dados no Application Insights.

Dica

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

Dica

Se você desenvolver um aplicativo Spring Boot, poderá 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.

Java nativo

A instrumentação automática é habilitada por meio de alterações de configuração. Nenhuma alteração de código é necessária.

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 logging
# Import the `configure_azure_monitor()` function from the
# `azure.monitor.opentelemetry` package.
from azure.monitor.opentelemetry import configure_azure_monitor

# Configure OpenTelemetry to use Azure Monitor with the
# APPLICATIONINSIGHTS_CONNECTION_STRING environment variable.
configure_azure_monitor(
    logger_name="<your_logger_namespace>",  # Set the namespace for the logger in which you would like to collect telemetry for if you are collecting logging telemetry. This is imperative so you do not collect logging telemetry from the SDK itself.
)
logger = logging.getLogger("<your_logger_namespace>")  # Logging telemetry will be collected from logging calls made with this logger and all of it's children loggers.

Copie a cadeia de conexão do recurso do Application Insights

O cadeia de conexão é exclusivo e especifica onde o Azure Monitor OpenTelemetry Distro envia a telemetria coletada.

Dica

Se você ainda não tem um recurso do Application Insights, crie um seguindo este guia. Recomendamos que você crie um novo recurso em vez de usar um recurso existente.

Para copiar a cadeia de conexão:

1. Acesse o painel Visão geral do recurso Application Insights.
2. Encontre sua cadeia de conexão.
3. Passe o mouse sobre a cadeia de conexão e selecione o ícone Copiar para a área de transferência.

Colar a cadeia de conexão em seu ambiente

Para colar seu cadeia de conexão, use um dos seguintes métodos:

Método	Idiomas com suporte	Recomendado para
Variável de ambiente	All	Produção
Arquivo de configuração (applicationinsights.json)	Somente Java	Produção (Java)
Code	ASP.NET Core, Node.js, Python	Somente desenvolvimento/teste local

Importante

É recomendável definir o cadeia de conexão por meio do código somente em ambientes de desenvolvimento e teste locais.

Para produção, use uma variável de ambiente ou arquivo de configuração (somente Java).

• Defina a cadeia de conexão do Application Insights como uma variável de ambiente (recomendado para produção)

  Substitua <Your cadeia de conexão> no comando a seguir por sua cadeia de conexão.

  APPLICATIONINSIGHTS_CONNECTION_STRING=<Your connection string>
  

• Defina a cadeia de conexão do Application Insights em um arquivo de configuração - Somente Java

  Crie um arquivo de configuração chamado applicationinsights.json e coloque-o no mesmo diretório que applicationinsights-agent-3.7.8.jar com o seguinte conteúdo:

  {
    "connectionString": "<Your connection string>"
  }
  

  Substitua <Your cadeia de conexão> no JSON anterior por sua cadeia de conexão exclusiva.

• Defina a cadeia de conexão do Application Insights no código - Somente para ASP.NET Core, Node.js e Python

  Consulte configuração da string de conexão para obter um exemplo de configuração da string de conexão através do código.

Observação

Se você definir a cadeia de conexão em vários lugares, ela será resolvida na seguinte ordem de precedência (mais alta para a mais baixa):

1. Code
2. Variável de ambiente
3. Arquivo de configuração

Confirmar se os dados estão fluindo

Depois de configurar o Azure Monitor OpenTelemetry Distro e definir o cadeia de conexão, execute seu aplicativo e abra o recurso do Application Insights no portal Azure para verificar se os rastreamentos, as métricas e os logs são exibidos. Pode levar alguns minutos para os dados aparecerem.

Agora, o Application Insights está habilitado para seu aplicativo. As etapas a seguir são opcionais e permitem uma personalização adicional.

Observação

Como parte do uso da instrumentação do Application Insights, coletamos e enviamos dados de diagnóstico para Microsoft. Esses dados nos ajudam a executar e a aprimorar o Application Insights. Saiba mais nas perguntas frequentes do Application Insights.

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.

Solução de problemas, comentários e suporte

Dica

As seções a seguir estão disponíveis em todos os artigos do OpenTelemetry Distro.

Solução de problemas

ASP.NET Core

Para obter informações de solução de problemas, consulte Solucionar problemas de OpenTelemetry no .NET e Solucionar problemas de telemetria ausente de aplicativos no Azure Monitor Application Insights.

.NET

Para obter informações de solução de problemas, consulte Solucionar problemas de OpenTelemetry no .NET e Solucionar problemas de telemetria ausente de aplicativos no Azure Monitor Application Insights.

Java

Para obter informações de solução de problemas, consulte Solucionar problemas do OpenTelemetry em Java e Solucionar problemas de telemetria de aplicações ausente no Azure Monitor Application Insights.

Java nativo

Para obter informações sobre a solução de problemas, consulte Solução de problemas relacionados ao OpenTelemetry em aplicativos de imagem nativa do Spring Boot e Solução de problemas de ausência de telemetria de aplicações no Azure Monitor Application Insights.

Node.js

Para informações sobre como resolver problemas, consulte Resolver problemas de OpenTelemetry no Node.js e Resolver problemas de telemetria de aplicativo ausente no Azure Monitor Application Insights.

Python

Para obter informações de solução de problemas, consulte Resolver problemas de OpenTelemetry em Python e Resolver problemas de telemetria de aplicativo ausente no Azure Monitor Application Insights.

Comentários sobre o OpenTelemetry

Para fornecer comentários:

• Preencha a pesquisa de comentários do cliente da Comunidade do OpenTelemetry.
• Conte Microsoft sobre si mesmo juntando-se à OpenTelemetry Early Adopter Community.
• Envolva-se com outros usuários Azure Monitor no Microsoft Tech Community.
• Faça uma solicitação de recurso no Azure Feedback Forum.

Suporte

Selecione uma aba do idioma de sua escolha para descobrir as opções de suporte.

ASP.NET Core

• Se você tiver problemas com o Suporte do Azure, abra um tíquete de suporte do Azure.
• Para problemas do OpenTelemetry, entre em contato diretamente com a OpenTelemetry .NET community.
• Para obter uma lista de problemas abertos relacionados ao exportador de Azure Monitor, consulte a página GitHub Issues.

.NET

• Se você tiver problemas com o Suporte do Azure, abra um tíquete de suporte do Azure.
• Para problemas do OpenTelemetry, entre em contato diretamente com a OpenTelemetry .NET community.
• Para obter uma lista de problemas abertos relacionados ao exportador de Azure Monitor, consulte a página GitHub Issues.

Java

• Se você tiver problemas com o Suporte do Azure, abra um tíquete de suporte do Azure.
• Para obter ajuda com a solução de problemas, revise as etapas da solução de problemas.
• Para problemas de OpenTelemetry, entre em contato diretamente com a comunidade do OpenTelemetry.
• Para obter uma lista de problemas abertos relacionados à autoinstrumentação Azure Monitor Java, consulte a página GitHub Issues.

Java nativo

• 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.
• Para obter uma lista de problemas abertos com aplicativos nativos do Spring Boot, consulte a GitHub Issues Page.
• Para obter uma lista de problemas abertos com aplicativos nativos do Quarkus, consulte a página GitHub Issues.

Observação

A comunidade do Quarkus dá suporte e mantém extensões do Quarkus. Para obter ajuda, use os canais de suporte da comunidade do Quarkus. Microsoft não fornece suporte técnico para essa integração.

Node.js

• 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 JavaScript do OpenTelemetry.
• Para obter uma lista de problemas abertos relacionados ao exportador de Azure Monitor, consulte a página GitHub Issues.

Python

• Se você tiver problemas com o Suporte do Azure, abra um tíquete de suporte do Azure.
• Para problemas com o OpenTelemetry, entre em contato diretamente com a comunidade OpenTelemetry Python OpenTelemetry.
• Para obter uma lista de problemas abertos relacionados à Distribuição Azure Monitor, consulte a página GitHub Issues.

Próximas etapas

ASP.NET Core

• Para examinar o código-fonte, consulte o Azure Monitor ASP.NET Core GitHub repositório.
• Para examinar um aplicativo de exemplo, consulte Azure Monitor OpenTelemetry para ASP.NET Core.
• Para instalar o pacote NuGet, verificar atualizações ou ver as notas de versão, consulte a página Azure Monitor AspNetCore NuGet Package.
• Para saber mais sobre o OpenTelemetry e sua comunidade, consulte o OpenTelemetry .NET GitHub repositório.
• Para habilitar experiências de uso, habilite o monitoramento do usuário no navegador ou na Web.

.NET

• Para examinar o código-fonte, consulte o repositório GitHub do Azure Monitor Exporter.
• Para examinar um aplicativo de exemplo, consulte Azure Monitor OpenTelemetry para .NET.
• Para instalar o pacote NuGet, verificar se há atualizações ou exibir notas de versão, consulte a página Azure Monitor Exporter NuGet Package.
• Para saber mais sobre o OpenTelemetry e sua comunidade, consulte o OpenTelemetry .NET GitHub repositório.
• Para habilitar experiências de uso, habilite o monitoramento do usuário no navegador ou na Web.

Java

• Para examinar as opções de configuração, consulte opções de configuração de autoinstrumentação do Java.
• Para examinar o código-fonte, consulte o repositório GitHub de autoinstrumentação do Azure Monitor Java.
• Para examinar aplicativos de exemplo, consulte Application Insights Java Samples.
• Revise as notas de versão no GitHub.
• Para saber mais sobre o OpenTelemetry e sua comunidade, examine o OpenTelemetry Java GitHub repositório.
• Para habilitar experiências de usuário, examine Habilitar o monitoramento de usuários da Web ou do navegador.

Java nativo

• Para revisar o código-fonte, consulte Distribuição do OpenTelemetry do Azure Monitor no aplicativo Java de imagem nativa do Spring Boot e no Quarkus OpenTelemetry Exporter for Azure.
• Para examinar um aplicativo de exemplo, veja Telemetria para imagens nativas GraalVM.
• Revise as notas de versão no GitHub.
• Saiba mais sobre os recursos para aplicativos de imagem nativa do Spring Boot no início do SpringBoot do OpenTelemetry
• Saiba mais sobre os recursos para aplicativos nativos do Quarkus no Quarkus OpenTelemetry Export for Azure.
• Para saber mais sobre o OpenTelemetry e sua comunidade, examine o OpenTelemetry Java GitHub repositório.

Node.js

• Para examinar o código-fonte, consulte o repositório OpenTelemetry do Azure Monitor para JavaScript.
• Para examinar um aplicativo de exemplo, consulte Azure Monitor OpenTelemetry para Node.js.
• Para instalar o pacote npm e verificar se há atualizações, confira a página @azure/monitor-opentelemetry Pacote npm.
• Para saber mais sobre o OpenTelemetry e sua comunidade, consulte o OpenTelemetry JavaScript GitHub repositório.
• Para habilitar experiências de uso, habilite o monitoramento do usuário no navegador ou na Web.

Python

• Para examinar o código-fonte e a documentação extra, consulte o Azure Monitor Python GitHub repositório.
• Para examinar aplicativos de exemplo, consulte Azure Monitor OpenTelemetry para Python.
• Para instalar o pacote PyPI e verificar se há atualizações, consulte a página Azure Monitor Distro PyPI Package.
• Revise as notas de versão no GitHub.
• Para examinar as instrumentações e os componentes OpenTelemetry disponíveis, consulte o repositório GitHub do OpenTelemetry Contributor Python.
• Para saber mais sobre o OpenTelemetry e sua comunidade, examine o OpenTelemetry Python GitHub repositório.
• Para habilitar experiências de uso, habilite o monitoramento do usuário no navegador ou na Web.