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 no Application Insights. Distribuições do OpenTelemetry do Azure Monitor:

• Fornece uma distribuição do OpenTelemetry que inclui suporte para recursos específicos do Azure Monitor.
• Habilita telemetria automática, incluindo bibliotecas de instrumentação OpenTelemetry para coletar rastreamentos, métricas, logs e exceções.
• Permite coletar telemetria personalizada.
• Oferece suporte ao recurso Live Metrics 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 as 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. Para obter um status de versão de recurso por recurso, confira as Perguntas frequentes.

Habilitar o OpenTelemetry com o Application Insights

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

Observação

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

Pré-requisitos

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

ASP.NET Core

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

.NET

• Aplicativo que usa uma versão suportada do .NET ou .NET Framework 4.6.2 e posterior.

Dica

Se você estiver migrando da API Clássica do Application Insights, consulte nossa documentação de migração.

Java

• Um aplicativo Java que usa o Java 8+

Nativo do Java

• Um aplicativo Java usando GraalVM 17+

Node.js

• Aplicativo que usa uma versão com suporte oficial do runtime do Node.js.:
  • 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 listada na tabela sem suporte, o shim do ApplicationInsights será o caminho mais fácil para avançar quando estiver mais no beta.

Se você depende dessas propriedades, prossiga com a Distribuição OpenTelemetry do Azure Monitor. Forneceremos um guia de migração em breve.

Dica

Se você estiver migrando da API Clássica 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:

CLI do .NET

dotnet add package Azure.Monitor.OpenTelemetry.AspNetCore 

.NET

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

CLI do .NET

dotnet add package Azure.Monitor.OpenTelemetry.Exporter 

Java

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

Aviso

Se você estiver atualizando de uma versão 3.x anterior, poderá ser afetado pela alteração de padrões ou por 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.0, 3.3.0, 3.2.0 e 3.1.0

Nativo do Java

Para aplicativos nativos do Spring Boot:

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

Para aplicativos nativos do Quarkus:

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

Node.js

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

sh

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

sh

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 PyPI mais recente do azure-monitor-opentelemetry:

sh

pip install azure-monitor-opentelemetry

Modificar o aplicativo

ASP.NET Core

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

C#

// 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 do Azure Monitor a cada sinal do OpenTelemetry na classe do program.cs:

C#

// 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 para 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.

Aponte a JVM (Máquina Virtual Java) para o arquivo jar adicionando -javaagent:"path/to/applicationinsights-agent-3.7.0.jar" aos argumentos 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 telemétricos 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.

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 Usar o Application Insights do Azure Monitor com o Spring Boot.

Nativo do Java

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

Node.js

TypeScript

// 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

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.

Copiar a cadeia de conexão do seu recurso do Application Insights

A cadeia de conexão é exclusiva e especifica para onde as Distribuições do OpenTelemetry do Azure Monitor enviam 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.

Cole a cadeia de conexão em seu ambiente

Para colar sua cadeia de conexão, selecione uma das opções a seguir:

Importante

Recomendamos definir a cadeia de conexão por meio de 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).

• Definir por meio de variável de ambiente - recomendado

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

  Console

  APPLICATIONINSIGHTS_CONNECTION_STRING=<Your connection string>
  

• Definir por meio de 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.0.jar com o seguinte conteúdo:

  JSON

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

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

• Definir por meio de código - ASP.NET Core, Node.js e Python somente

  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 vários locais, a variável de ambiente será priorizada na seguinte ordem:

1. Código
2. Variável de ambiente
3. Arquivo de configuração

Confirmar se os dados estão fluindo

Abra o seu aplicativo e, em seguida, abra o Application Insights no portal do Azure. 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.

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.

Aplicativos de exemplo

Os aplicativos de exemplo do OpenTelemetry do Azure Monitor estão disponíveis para todos os idiomas com suporte:

• Aplicativo de exemplo do ASP.NET Core
• Aplicativo de exemplo do NET
• Aplicativos de exemplo do Java
• Aplicativos de exemplo nativos do Java GraalVM
• Aplicativo de exemplo do Node.js
• Aplicativos de exemplo do Python

Próximas etapas

ASP.NET Core

• 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.
• Para revisar perguntas frequentes, etapas de solução de problemas, opções de suporte ou fornecer comentários do OpenTelemetry, confira a ajuda, o suporte e os comentários do OpenTelemetry para o Azure Monitor Application Insights.

.NET

• 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 examinar o código-fonte, confira o Repositório do GitHub do Exportador do Azure Monitor.
• Para instalar o pacote de NuGet, verificar se há atualizações ou exibir notas de versão, visite a página Pacote de NuGet do Exportador do Azure Monitor.
• Para se familiarizar com o Azure Monitor e o OpenTelemetry, confira oAplicativo 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.
• Para revisar perguntas frequentes, etapas de solução de problemas, opções de suporte ou fornecer comentários do OpenTelemetry, confira a ajuda, o suporte e os comentários do OpenTelemetry para o Azure Monitor Application Insights.

Java

• Confira Adicionar e modificar o OpenTelemetry do Azure Monitor para mais detalhes sobre como adicionar e modificar o OpenTelemetry do Azure Monitor.
• Revise as opções de configuração de instrumentação automática do Java.
• Revise o código-fonte em repositório do GitHub de instrumentação automática do Java do Azure Monitor.
• Saiba mais sobre o OpenTelemetry e a comunidade no repositório GitHub do OpenTelemetry para Java.
• Habilite as experiências de uso consultando Habilite o monitoramento de usuários da Web ou do navegador.
• Examine as notas sobre a versão no GitHub.
• Para revisar perguntas frequentes, etapas de solução de problemas, opções de suporte ou fornecer comentários do OpenTelemetry, confira a ajuda, o suporte e os comentários do OpenTelemetry para o Azure Monitor Application Insights.

Nativo do Java

• Confira Adicionar e modificar o OpenTelemetry do Azure Monitor para mais detalhes sobre como adicionar e modificar o OpenTelemetry do Azure Monitor.
• Examine o código-fonte na distro do OpenTelemetry do Azure Monitor no aplicativo Java de imagem nativa do Spring Boot e no Quarkus OpenTelemetry Exporter for Azure.
• Saiba mais sobre o OpenTelemetry e a comunidade no repositório GitHub do OpenTelemetry para Java.
• Saiba mais 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 em Quarkus OpenTelemetry Exporter for Azure.
• Examine as notas sobre a versão no GitHub.
• Para revisar perguntas frequentes, etapas de solução de problemas, opções de suporte ou fornecer comentários do OpenTelemetry, confira a ajuda, o suporte e os comentários do OpenTelemetry para o Azure Monitor Application Insights.

Node.js

• Para mais detalhes sobre como adicionar e modificar o OpenTelemetry do Azure Monitor, confira Adicionar e modificar o OpenTelemetry do Azure Monitor.
• Para revisar o código-fonte, acesse o repositório do GitHub do OpenTelemetry do Azure Monitor.
• Para instalar o pacote npm e verificar se há atualizações, confira a página @azure/monitor-opentelemetry Pacote npm.
• Para se familiarizar com o Application Insights do Azure Monitor e o OpenTelemetry, confira oAplicativo de exemplo do Azure Monitor.
• Para saber mais sobre o OpenTelemetry e a respectiva comunidade, confira o repositório de GitHub em JavaScript para OpenTelemetry .
• Para habilitar experiências de usuário, habilite o monitoramento de usuário de navegador ou da Web.
• Para revisar perguntas frequentes, etapas de solução de problemas, opções de suporte ou fornecer comentários do OpenTelemetry, confira a ajuda, o suporte e os comentários do OpenTelemetry para o Azure Monitor Application Insights.

Python

• Confira Adicionar e modificar o OpenTelemetry do Azure Monitor para mais detalhes sobre como adicionar e modificar o OpenTelemetry do Azure Monitor.
• Revise o código-fonte e a documentação adicional no Repositório do GitHub da Distribuição do Azure Monitor.
• Veja exemplos adicionais e casos de uso em Amostras da Distribuição do Azure Monitor.
• Examine o log de alterações no GitHub.
• Instale o pacote de PyPI, verifique se há atualizações ou exiba notas sobre a versão na página Pacote de PyPI de Distribuição do Azure Monitor.
• Familiarize-se com o Application Insights do Azure Monitor e o OpenTelemetry no Aplicativo de exemplo do Azure Monitor.
• Saiba mais sobre o OpenTelemetry e a respectiva comunidade, no repositório GitHub em Python para OpenTelemetry.
• Veja as instrumentações e os componentes do OpenTelemetry disponíveis no Repositório do GitHub do Colaborador do Python do OpenTelemetry.
• Habilite as experiências de uso habilitando o monitoramento de usuários da Web ou do navegador.
• Para revisar perguntas frequentes, etapas de solução de problemas, opções de suporte ou fornecer comentários do OpenTelemetry, confira a ajuda, o suporte e os comentários do OpenTelemetry para o Azure Monitor Application Insights.