Monitorizar os seus serviços e aplicações Node.js com o Application Insights

O Application Insights monitora seus componentes após a implantação para descobrir o desempenho e outros problemas. Você pode usar o Application Insights para Node.js serviços hospedados em seu datacenter, VMs do Azure e aplicativos Web, e até mesmo em outras nuvens públicas.

Para receber, armazenar e explorar seus dados de monitoramento, inclua o SDK em seu código. Em seguida, configure um recurso correspondente do Application Insights no Azure. O SDK envia dados para esse recurso para análise e exploração adicionais.

A biblioteca de cliente Node.js pode monitorar automaticamente solicitações HTTP de entrada e saída, exceções e algumas métricas do sistema. A partir da versão 0.20, a biblioteca do cliente também pode monitorar alguns pacotes comuns de terceiros, como MongoDB, MySQL e Redis.

Todos os eventos relacionados com pedidos HTTP de entrada são correlacionados para resolução de problemas mais rápida.

Você pode usar a API TelemetryClient para instrumentar e monitorar manualmente mais aspetos do seu aplicativo e sistema. A API TelemetryClient está descrita em mais detalhe posteriormente neste artigo.

Nota

A documentação a seguir depende da API clássica do Application Insights. O plano de longo prazo para o Application Insights é coletar dados usando OpenTelemetry. Para obter mais informações, consulte Habilitar o Azure Monitor OpenTelemetry para aplicativos .NET, Node.js, Python e Java e nosso OpenTelemetry Roadmap. As diretrizes de migração estão disponíveis para .NET, Node.js e Python.

Começar agora

Conclua as tarefas seguintes para configurar a monitorização para uma aplicação ou serviço.

Pré-requisitos

Antes de começar, confirme que tem uma subscrição do Azure ou obtenha uma nova gratuitamente. Se a sua organização já tiver uma subscrição do Azure, um administrador pode seguir estas instruções para o adicionar à mesma.

Configurar um recurso do Application Insights

1. Inicie sessão no portal do Azure.
2. Crie um recurso do Application Insights.

Nota

A 31 de março de 2025, o suporte da ingestão de chaves de instrumentação terminará. A ingestão de chaves de instrumentação continuará a funcionar, mas não forneceremos mais atualizações ou suporte para o recurso. Transição para cadeias de conexão para aproveitar os novos recursos.

Configurar a biblioteca de cliente Node.js

Inclua o SDK em seu aplicativo para que ele possa coletar dados.

1. Copie a cadeia de conexão do recurso do novo recurso. O Application Insights usa a cadeia de conexão para mapear dados para seu recurso do Azure. Antes que o SDK possa usar sua cadeia de conexão, você deve especificar a cadeia de conexão em uma variável de ambiente ou em seu código.

   

2. Adicione a biblioteca de cliente Node.js às dependências do seu aplicativo via package.json. Na pasta raiz da aplicação, execute:

   npm install applicationinsights --save
   

   Nota

   Se você estiver usando o TypeScript, não instale pacotes de "digitação" separados. Este pacote NPM contém digitações internas.

3. Carregue explicitamente a biblioteca para o seu código. Uma vez que o SDK injeta instrumentação em muitas outras bibliotecas, carregue a biblioteca o mais cedo possível, até antes de outras declarações require.

   let appInsights = require('applicationinsights');
   

4. Você também pode fornecer uma cadeia de conexão através da variável APPLICATIONINSIGHTS_CONNECTION_STRINGde ambiente , em vez de passá-la manualmente para setup() ou new appInsights.TelemetryClient(). Essa prática permite manter as cadeias de conexão fora do código-fonte confirmado e especificar cadeias de conexão diferentes para ambientes diferentes. Para configurar manualmente, chame appInsights.setup('[your connection string]');.

   Para obter mais opções de configuração, consulte as seções a seguir.

   Pode definir appInsights.defaultClient.config.disableAppInsights = true para experimentar o SDK sem enviar telemetria.

5. Comece a coletar e enviar dados automaticamente ligando para appInsights.start();.

Nota

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. Você tem a opção de desativar a coleta de dados não essenciais. Mais informações.

Monitore seu aplicativo

O SDK reúne automaticamente a telemetria sobre o tempo de execução do Node.js e alguns módulos comuns de terceiros. Utilize a sua aplicação para gerar alguns destes dados.

Em seguida, no portal do Azure, aceda ao recurso do Application Insights que criou anteriormente. Na Linha cronológica geral, procure os seus primeiros pontos de dados. Para ver dados mais detalhadas, selecione diferentes componentes nos gráficos.

Para exibir a topologia descoberta para seu aplicativo, você pode usar o Mapa de Aplicativos.

Sem dados

Como o SDK envia dados em lotes para envio, pode haver um atraso antes que os itens apareçam no portal. Se não vir dados no seu recurso, experimente algumas das correções seguintes:

• Continue a utilizar a aplicação. Realize mais ações para gerar mais telemetria.
• Selecione Atualizar na visualização de recursos do portal. Os gráficos atualizam-se periodicamente por si próprios, mas atualizá-los manualmente força-os a fazer a atualização de imediato.
• Confirme que as portas de saída necessárias estão abertas.
• Utilize a Pesquisa para procurar eventos específicos.
• Veja as FAQ.

Utilização básica

Para uma coleção pronta para uso de solicitações HTTP, eventos populares de bibliotecas de terceiros, exceções não tratadas e métricas do sistema:

let appInsights = require("applicationinsights");
appInsights.setup("[your connection string]").start();

Nota

Se a cadeia de conexão estiver definida na variável APPLICATIONINSIGHTS_CONNECTION_STRINGde ambiente , .setup() pode ser chamada sem argumentos. Isso facilita o uso de diferentes cadeias de conexão para diferentes ambientes.

Carregue a biblioteca require("applicationinsights") do Application Insights o mais cedo possível em seus scripts antes de carregar outros pacotes. Esta etapa é necessária para que a biblioteca do Application Insights possa preparar pacotes posteriores para rastreamento. Se você encontrar conflitos com outras bibliotecas que fazem uma preparação semelhante, tente carregar a biblioteca do Application Insights posteriormente.

Devido à maneira como o JavaScript lida com retornos de chamada, é necessário mais trabalho para rastrear uma solicitação em dependências externas e retornos de chamada posteriores. Por padrão, esse rastreamento extra está habilitado. Desative-o chamando setAutoDependencyCorrelation(false) conforme descrito na seção de configuração do SDK.

Migrar de versões anteriores à 0.22

Há alterações significativas entre as versões anteriores à versão 0.22 e posteriores. Essas alterações foram projetadas para trazer consistência com outros SDKs do Application Insights e permitir extensibilidade futura.

Em geral, você pode migrar com as seguintes ações:

• Substitua as referências a appInsights.client por appInsights.defaultClient.
• Substitua as referências a appInsights.getClient() por new appInsights.TelemetryClient().
• Substitua todos os argumentos para métodos client.track* por um único objeto contendo propriedades nomeadas como argumentos. Consulte a dica de tipo interna do IDE ou TelemetryTypes para obter o objeto excetuado para cada tipo de telemetria.

Se você acessar as funções de configuração do SDK sem encadeá-las ao appInsights.setup(), agora poderá encontrar essas funções em appInsights.Configurations. Um exemplo é appInsights.Configuration.setAutoCollectDependencies(true). Analise as alterações na configuração padrão na próxima seção.

Configuração do SDK

O appInsights objeto fornece muitos métodos de configuração. Eles estão listados no trecho a seguir com seus valores padrão.

let appInsights = require("applicationinsights");
appInsights.setup("<connection_string>")
    .setAutoDependencyCorrelation(true)
    .setAutoCollectRequests(true)
    .setAutoCollectPerformance(true, true)
    .setAutoCollectExceptions(true)
    .setAutoCollectDependencies(true)
    .setAutoCollectConsole(true)
    .setUseDiskRetryCaching(true)
    .setSendLiveMetrics(false)
    .setDistributedTracingMode(appInsights.DistributedTracingModes.AI)
    .start();

Para correlacionar totalmente os eventos num serviço, confirme que define .setAutoDependencyCorrelation(true). Com esta opção definida, o SDK pode monitorizar o contexto em chamadas de retorno assíncronas em Node.js.

Analise suas descrições na dica ou applicationinsights.ts de tipo interno do IDE para obter informações detalhadas e argumentos secundários opcionais.

Nota

Por padrão, setAutoCollectConsole é configurado para excluir chamadas para console.log e outros métodos de console. Apenas as chamadas para registadores de terceiros suportados (por exemplo, winston e bunyan) serão recolhidas. Você pode alterar esse comportamento para incluir chamadas para console métodos usando setAutoCollectConsole(true, true).

Amostragem

Por padrão, o SDK envia todos os dados coletados para o serviço Application Insights. Se você quiser habilitar a amostragem para reduzir a quantidade de dados, defina o samplingPercentage config campo no objeto de um cliente. Definir samplingPercentage como 100 (o padrão) significa que todos os dados serão enviados e 0 significa que nada será enviado.

Se você estiver usando a correlação automática, todos os dados associados a uma única solicitação serão incluídos ou excluídos como uma unidade.

Adicione um código como o seguinte para habilitar a amostragem:

const appInsights = require("applicationinsights");
appInsights.setup("<connection_string>");
appInsights.defaultClient.config.samplingPercentage = 33; // 33% of all telemetry will be sent to Application Insights
appInsights.start();

Várias funções para aplicativos com vários componentes

Em alguns cenários, seu aplicativo pode consistir em vários componentes que você deseja instrumentar todos com a mesma cadeia de conexão. Você ainda deseja ver esses componentes como unidades separadas no portal, como se estivessem usando cadeias de conexão separadas. Um exemplo são nós separados no Application Map. Você precisa configurar manualmente o campo para distinguir a telemetria RoleName de um componente de outros componentes que enviam dados para seu recurso do Application Insights.

Use o seguinte código para definir o RoleName campo:

const appInsights = require("applicationinsights");
appInsights.setup("<connection_string>");
appInsights.defaultClient.context.tags[appInsights.defaultClient.context.keys.cloudRole] = "MyRoleName";
appInsights.start();

Carregador SDK do navegador

Nota

Disponível como pré-visualização pública. Termos de Utilização Suplementares das Pré-visualizações do Microsoft Azure

A instrumentação automática da Web pode ser ativada para o servidor de nó via JavaScript (Web) SDK Loader Script injection by configuration.

let appInsights = require("applicationinsights");
appInsights.setup("<connection_string>")
    .enableWebInstrumentation(true)
    .start();

ou definindo a variável APPLICATIONINSIGHTS_WEB_INSTRUMENTATION_ENABLED = truede ambiente .

A Instrumentação da Web é habilitada nas respostas do servidor de nó quando todos os seguintes requisitos são atendidos:

• A resposta tem o código de 200estado .
• O método de resposta é GET.
• A resposta do servidor tem Content-Type html.
• A resposta do servidor contém ambas as <head> tags e </head> .
• Se a resposta for compactada, ela deverá ter apenas um Content-Encoding tipo, e o tipo de codificação deverá ser um dos gzip, br ou deflate.
• A resposta não contém pontos de extremidade CDN de instrumentação da Web /backup atuais. (pontos de extremidade CDN de instrumentação da Web atuais e de backup aqui)

O ponto de extremidade CDN de instrumentação da Web pode ser alterado definindo a variável APPLICATIONINSIGHTS_WEB_INSTRUMENTATION_SOURCE = "web Instrumentation CDN endpoints"de ambiente . A cadeia de conexão de instrumentação da Web pode ser alterada definindo a variável de ambiente APPLICATIONINSIGHTS_WEB_INSTRUMENTATION_CONNECTION_STRING = "web Instrumentation connection string"

Nota

A Instrumentação da Web pode diminuir o tempo de resposta do servidor, especialmente quando o tamanho da resposta é grande ou a resposta é compactada. Para o caso em que algumas camadas intermediárias são aplicadas, isso pode resultar em instrumentação web não funcionando e a resposta original será retornada.

Instrumentação automática de terceiros

Para controlar o contexto em chamadas assíncronas, algumas alterações são necessárias em bibliotecas de terceiros, como MongoDB e Redis. Por padrão, o Application Insights usa diagnostic-channel-publishers para corrigir algumas dessas bibliotecas. Esse recurso pode ser desativado definindo a variável de APPLICATION_INSIGHTS_NO_DIAGNOSTIC_CHANNEL ambiente.

Nota

Ao definir essa variável de ambiente, os eventos podem não estar corretamente associados à operação correta.

Os patches de macaco individuais podem ser desativados definindo a variável de ambiente como uma lista separada por vírgulas APPLICATION_INSIGHTS_NO_PATCH_MODULES de pacotes a serem desabilitados. Por exemplo, use APPLICATION_INSIGHTS_NO_PATCH_MODULES=console,redis para evitar a aplicação de patches nos console e redis pacotes.

Atualmente, nove pacotes são instrumentados: bunyan,console,mongodb,mongodb-core,,mysql,redis,,winstonpg e pg-pool. Para obter informações sobre exatamente qual versão desses pacotes é corrigida, consulte o README dos editores de canal de diagnóstico.

Os patches , winstone console geram bunyaneventos de rastreamento do Application Insights com base na habilitaçãosetAutoCollectConsole. O restante gera eventos de dependência do Application Insights com base na habilitação setAutoCollectDependencies .

Métricas em tempo real

Para habilitar o envio de métricas em tempo real do seu aplicativo para o Azure, use setSendLiveMetrics(true). Atualmente, a filtragem de métricas em tempo real no portal não é suportada.

Métricas estendidas

Nota

A capacidade de enviar métricas nativas estendidas foi adicionada na versão 1.4.0.

Para habilitar o envio de métricas nativas estendidas do seu aplicativo para o Azure, instale o pacote de métricas nativas separado. O SDK é carregado automaticamente quando é instalado e começa a coletar Node.js métricas nativas.

npm install applicationinsights-native-metrics

Atualmente, o pacote de métricas nativo executa a coleta automática de tempo de CPU de coleta de lixo, ticks de loop de eventos e uso de heap:

• Coleta de lixo: A quantidade de tempo de CPU gasto em cada tipo de coleta de lixo e quantas ocorrências de cada tipo.
• Loop de eventos: quantos ticks ocorreram e quanto tempo de CPU foi gasto no total.
• Heap vs. non-heap: quanto do uso de memória do seu aplicativo está no heap ou não-heap.

Modos de rastreamento distribuído

Por padrão, o SDK envia cabeçalhos compreendidos por outros aplicativos ou serviços instrumentados com um SDK do Application Insights. Você pode habilitar o envio e o recebimento de cabeçalhos de contexto de rastreamento do W3C, além dos cabeçalhos de IA existentes. Dessa forma, você não quebrará a correlação com nenhum dos seus serviços legados existentes. Habilitar cabeçalhos W3C permite que seu aplicativo se correlacione com outros serviços não instrumentados com o Application Insights, mas que adotam esse padrão W3C.

const appInsights = require("applicationinsights");
appInsights
  .setup("<your connection string>")
  .setDistributedTracingMode(appInsights.DistributedTracingModes.AI_AND_W3C)
  .start()

API TelemetryClient

Para obter uma descrição completa da API TelemetryClient, veja Application Insights API for custom events and metrics (API do Application Insights para eventos e métricas personalizadas).

Você pode acompanhar qualquer solicitação, evento, métrica ou exceção usando a biblioteca de cliente do Application Insights para Node.js. O exemplo de código seguinte demonstra algumas das APIs que pode utilizar:

let appInsights = require("applicationinsights");
appInsights.setup().start(); // assuming connection string in env var. start() can be omitted to disable any non-custom data
let client = appInsights.defaultClient;
client.trackEvent({name: "my custom event", properties: {customProperty: "custom property value"}});
client.trackException({exception: new Error("handled exceptions can be logged with this method")});
client.trackMetric({name: "custom metric", value: 3});
client.trackTrace({message: "trace message"});
client.trackDependency({target:"http://dbname", name:"select customers proc", data:"SELECT * FROM Customers", duration:231, resultCode:0, success: true, dependencyTypeName: "ZSQL"});
client.trackRequest({name:"GET /customers", url:"http://myserver/customers", duration:309, resultCode:200, success:true});

let http = require("http");
http.createServer( (req, res) => {
  client.trackNodeHttpRequest({request: req, response: res}); // Place at the beginning of your request handler
});

Monitorizar as dependências

Utilize o código abaixo para fazer o acompanhamento das suas dependências:

let appInsights = require("applicationinsights");
let client = new appInsights.TelemetryClient();

var success = false;
let startTime = Date.now();
// execute dependency call here....
let duration = Date.now() - startTime;
success = true;

client.trackDependency({target:"http://dbname", name:"select customers proc", data:"SELECT * FROM Customers", duration:duration, resultCode:0, success: true, dependencyTypeName: "ZSQL"});;

Um utilitário de exemplo usado trackMetric para medir quanto tempo leva o agendamento de loop de eventos:

function startMeasuringEventLoop() {
  var startTime = process.hrtime();
  var sampleSum = 0;
  var sampleCount = 0;

  // Measure event loop scheduling delay
  setInterval(() => {
    var elapsed = process.hrtime(startTime);
    startTime = process.hrtime();
    sampleSum += elapsed[0] * 1e9 + elapsed[1];
    sampleCount++;
  }, 0);

  // Report custom metric every second
  setInterval(() => {
    var samples = sampleSum;
    var count = sampleCount;
    sampleSum = 0;
    sampleCount = 0;

    if (count > 0) {
      var avgNs = samples / count;
      var avgMs = Math.round(avgNs / 1e6);
      client.trackMetric({name: "Event Loop Delay", value: avgMs});
    }
  }, 1000);
}

Adicionar propriedades personalizadas a todos os eventos

Utilize o código abaixo para adicionar uma propriedade personalizada a todos os eventos:

appInsights.defaultClient.commonProperties = {
  environment: process.env.SOME_ENV_VARIABLE
};

Monitorizar pedidos HTTP GET

Use o código a seguir para rastrear manualmente as solicitações HTTP GET:

Nota

• Todas as solicitações são rastreadas por padrão. Para desativar a coleta automática, ligue antes de .setAutoCollectRequests(false) chamar start().
• As solicitações de API de busca nativas não são rastreadas automaticamente pelo Application Insights clássico; É necessário o acompanhamento manual da dependência.

appInsights.defaultClient.trackRequest({name:"GET /customers", url:"http://myserver/customers", duration:309, resultCode:200, success:true});

Como alternativa, você pode rastrear solicitações usando o trackNodeHttpRequest método:

var server = http.createServer((req, res) => {
  if ( req.method === "GET" ) {
      appInsights.defaultClient.trackNodeHttpRequest({request:req, response:res});
  }
  // other work here....
  res.end();
});

Monitorizar o tempo de arranque do servidor

Utilize o código abaixo para fazer o acompanhamento do tempo de arranque do servidor:

let start = Date.now();
server.on("listening", () => {
  let duration = Date.now() - start;
  appInsights.defaultClient.trackMetric({name: "server startup time", value: duration});
});

Rubor

Por padrão, a telemetria é armazenada em buffer por 15 segundos antes de ser enviada ao servidor de ingestão. Se seu aplicativo tiver uma vida útil curta, como uma ferramenta CLI, talvez seja necessário liberar manualmente a telemetria em buffer quando o aplicativo for encerrado usando appInsights.defaultClient.flush()o .

Se o SDK detetar que seu aplicativo está falhando, ele chamará flush para você usando appInsights.defaultClient.flush({ isAppCrashing: true }). Com a opção isAppCrashingflush , presume-se que a sua aplicação está num estado anormal e não é adequada para enviar telemetria. Em vez disso, o SDK salva toda a telemetria em buffer no armazenamento persistente e permite que seu aplicativo seja encerrado. Quando seu aplicativo é iniciado novamente, ele tenta enviar qualquer telemetria que foi salva no armazenamento persistente.

Pré-processar dados com os processadores de telemetria

Você pode processar e filtrar os dados coletados antes que eles sejam enviados para retenção usando processadores de telemetria. Os processadores de telemetria são chamados um a um na ordem em que foram adicionados antes que o item de telemetria seja enviado para a nuvem.

public addTelemetryProcessor(telemetryProcessor: (envelope: Contracts.Envelope, context: { http.RequestOptions, http.ClientRequest, http.ClientResponse, correlationContext }) => boolean)

Se um processador de telemetria retornar false, esse item de telemetria não será enviado.

Todos os processadores de telemetria recebem os dados de telemetria e seu envelope para inspecionar e modificar. Eles também recebem um objeto de contexto. O conteúdo deste objeto é definido pelo parâmetro ao chamar um método track para telemetria contextObjects rastreada manualmente. Para telemetria coletada automaticamente, esse objeto é preenchido com informações de solicitação disponíveis e o conteúdo de solicitação persistente conforme fornecido por appInsights.getCorrelationContext() (se a correlação de dependência automática estiver habilitada).

O tipo TypeScript para um processador de telemetria é:

telemetryProcessor: (envelope: ContractsModule.Contracts.Envelope, context: { http.RequestOptions, http.ClientRequest, http.ClientResponse, correlationContext }) => boolean;

Por exemplo, um processador que remove dados de rastreamento de pilhas de exceções pode ser escrito e adicionado da seguinte maneira:

function removeStackTraces ( envelope, context ) {
  if (envelope.data.baseType === "Microsoft.ApplicationInsights.ExceptionData") {
    var data = envelope.data.baseData;
    if (data.exceptions && data.exceptions.length > 0) {
      for (var i = 0; i < data.exceptions.length; i++) {
        var exception = data.exceptions[i];
        exception.parsedStack = null;
        exception.hasFullStack = false;
      }
    }
  }
  return true;
}

appInsights.defaultClient.addTelemetryProcessor(removeStackTraces);

Usar várias cadeias de conexão

Você pode criar vários recursos do Application Insights e enviar dados diferentes para cada um usando suas respetivas cadeias de conexão.

Por exemplo:

let appInsights = require("applicationinsights");

// configure auto-collection under one connection string
appInsights.setup("Connection String A").start();

// track some events manually under another connection string
let otherClient = new appInsights.TelemetryClient("Connection String B");
otherClient.trackEvent({name: "my custom event"});

Opções avançadas de configuração

O objeto client contém uma config propriedade com muitas configurações opcionais para cenários avançados. Para defini-los, use:

client.config.PROPERTYNAME = VALUE;

Essas propriedades são específicas do cliente, portanto, você pode configurar appInsights.defaultClient separadamente dos clientes criados com new appInsights.TelemetryClient()o .

Property	Descrição
connectionString	Um identificador para seu recurso do Application Insights.
endpointUrl	O ponto de extremidade de ingestão para o qual enviar cargas úteis de telemetria.
quickPulseHost	O host do Live Metrics Stream para o qual enviar telemetria de métricas ao vivo.
proxyHttpUrl	Um servidor proxy para tráfego HTTP SDK. (Opcional. O padrão é extraído da variável de http_proxy ambiente.)
proxyHttpsUrl	Um servidor proxy para tráfego HTTPS SDK. (Opcional. O padrão é extraído da variável de https_proxy ambiente.)
httpAgente	Um http. Agente a ser usado para tráfego HTTP do SDK. (Opcional. O padrão é indefinido.)
httpsAgente	Um https. Agente a ser usado para tráfego HTTPS do SDK. (Opcional. O padrão é indefinido.)
maxBatchSize	O número máximo de itens de telemetria a serem incluídos em uma carga útil até o ponto de extremidade de ingestão. (O padrão é 250.)
maxBatchIntervalMs	A quantidade máxima de tempo para esperar que uma carga atinja maxBatchSize. (O padrão é 15000.)
disableAppInsights	Um sinalizador que indica se a transmissão de telemetria está desativada. (O padrão é false.)
amostragemPercentagem	A porcentagem de itens de telemetria rastreados que devem ser transmitidos. (O padrão é 100.)
correlationIdRetryIntervalMs	O tempo de espera antes de tentar recuperar novamente a ID para correlação entre componentes. (O padrão é 30000.)
correlationHeaderExcludedDomains	Uma lista de domínios a serem excluídos da injeção de cabeçalho de correlação entre componentes. (Padrão. Ver Config.ts.)

Perguntas mais frequentes

Como posso desativar a correlação de telemetria?

Para desabilitar a correlação de telemetria, use a correlationHeaderExcludedDomains propriedade em configuration. Para obter mais informações, consulte ApplicationInsights-node.js.

Resolução de Problemas

Para obter informações sobre solução de problemas, incluindo cenários "sem dados" e personalização de logs, consulte Solucionar problemas de monitoramento do Application Insights de aplicativos e serviços Node.js.

Próximos passos

• Monitorizar a telemetria no portal
• Escrever consultas de análise sobre a telemetria