Como monitorar seus serviços do Node.js e aplicativos com o Application Insights

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

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

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

Todos os eventos relacionados a uma solicitação HTTP de entrada são correlacionados para solução de problemas mais rápida.

Você pode usar a API TelemetryClient para instrumentar e monitorar manualmente outros aspectos do aplicativo e do sistema. Descrevemos a API TelemetryClient em mais detalhes mais adiante neste artigo.

Observação

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

Introdução

Conclua as seguintes tarefas para configurar o monitoramento em um aplicativo ou serviço.

Pré-requisitos

Antes de iniciar, verifique se você tem uma assinatura do Azure ou obtenha uma gratuitamente. Se sua organização já tiver uma assinatura do Azure, um administrador pode seguir estas instruções para adicioná-lo a ela.

Configurar um recurso do Application Insights

1. Entre no portal do Azure.
2. Crie um recurso do Application Insights.

Observação

Em 31 de março de 31, 2025, o suporte à ingestão de chave de instrumentação será encerrado. A ingestão de chave de instrumentação continuará funcionando, mas não forneceremos mais atualizações ou suporte para o recurso. Transição para cadeias de conexão para aproveitar as novas funcionalidades.

Configurar a biblioteca de cliente do Node.js

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

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

   

2. Adicione a biblioteca de clientes do Node.js nas dependências do seu aplicativo por meio de package.json. Na pasta raiz do seu aplicativo, execute:

   npm install applicationinsights --save
   

   Observação

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

3. Carregue a biblioteca em seu código explicitamente. Como o SDK injeta instrumentação em muitas outras bibliotecas, carregue a biblioteca o mais cedo possível, mesmo antes de outras instruções require.

   let appInsights = require('applicationinsights');
   

4. Você também pode fornecer uma cadeia de conexão por meio da variável de ambiente APPLICATIONINSIGHTS_CONNECTION_STRING em vez de transmiti-lo manualmente a setup() ou new appInsights.TelemetryClient(). Essa prática permite manter cadeias de conexão fora do código-fonte comprometido e também especificar cadeias de conexão diferentes para ambientes diferentes. Para fazer a configuração manual, chame appInsights.setup('[your connection string]');.

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

   Você pode experimentar o SDK sem enviar telemetria definindo appInsights.defaultClient.config.disableAppInsights = true.

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

Observação

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. Você tem a opção de desabilitar a coleta de dados não essenciais. Saiba mais.

Monitorar o aplicativo

O SDK reúne automaticamente a telemetria sobre o runtime do Node.js e alguns módulos de terceiros comuns. Use o aplicativo para gerar alguns desses dados.

Em seguida, no portal do Azure, vá para o recurso do Application Insights criado anteriormente. Na Linha do tempo de visão geral, procure seus primeiros pontos de dados. Para obter dados mais detalhadas, selecione componentes diferentes nos gráficos.

Para exibir a topologia que foi descoberta para seu aplicativo, você pode utilizar Mapa do Aplicativo.

Sem dados

Como o SDK envia lotes de dados, pode haver um atraso antes de os itens aparcerem no portal. Se você não visualizar os dados em seu recurso, experimente algumas das seguintes correções:

• Continue a usar o aplicativo. Execute mais ações para gerar mais telemetria.
• Selecione Atualizar no modo de exibição de recursos do portal. Os gráficos se atualizam sozinhos de tempos em tempos, mas a atualização manual força a atualização imediatamente.
• Verifique se as portas de saída obrigatórias estão abertas.
• Use Pesquisar para procurar eventos específicos.
• Leia as Perguntas Frequentes.

Uso básico

Para uma coleção integrada de solicitações HTTP, eventos de biblioteca de terceiros populares, exceções sem tratamento e métricas do sistema:

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

Observação

Se a cadeia de conexão for definida na variável de ambiente APPLICATIONINSIGHTS_CONNECTION_STRING, o .setup() poderá ser chamado sem argumentos. Isso facilita o uso de diferentes cadeias de conexão para ambientes diferentes.

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

Devido à maneira como o JavaScript manipula retornos de chamada, é necessário trabalho adicional para rastrear uma solicitação entre dependências externas e retornos de chamada posteriores. Por padrão, esse acompanhamento extra fica habilitado. Desabilite-o chamando setAutoDependencyCorrelation(false), conforme descrito na seção 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 de Application Insights e permitir extensibilidade futura.

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

• Substitua referências a appInsights.client com appInsights.defaultClient.
• Substitua referências a appInsights.getClient() com new appInsights.TelemetryClient().
• Substitua todos os argumentos para os métodos Client. Track * por um único objeto que contém propriedades nomeadas como argumentos. Consulte a dica de tipo interno do IDE ou TelemetryTypes para o objeto excetuado para cada tipo de telemetria.

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

Configuração do SDK

O objeto appInsights fornece diversos métodos de configuração. Eles sã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 eventos em um serviço, você deve definir .setAutoDependencyCorrelation(true). Com essa opção definida, o SDK pode acompanhar o contexto entre retornos de chamada assíncronos no Node.js.

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

Observação

Por padrão, o setAutoCollectConsole é configurado para excluir chamadas para console.log e outros métodos de console. Somente chamadas para agentes de terceiros com suporte (por exemplo, Winston e Bunyan) serão coletadas. Você pode alterar esse comportamento para incluir chamadas para console métodos usando o 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 campo samplingPercentage no objeto config 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 correlação automática, todos os dados associados a uma única solicitação sã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 ser composto por vários componentes que você deseja instrumentar com a mesma cadeia de conexão. Você ainda quer 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 Mapa do Aplicativo. Você precisa configurar manualmente o campo RoleName para distinguir a telemetria de um componente de outros componentes que enviam dados para o recurso do Application Insights.

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

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

Carregador do SDK do Navegador

Observação

Disponível como uma versão prévia pública. Termos de Uso Adicionais para Versões Prévias do Microsoft Azure

A instrumentação automática da web pode ser habilitada para o servidor de nós por meio da injeção de Script do Carregador de SDK (Web) JavaScript por configuração.

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

ou definindo a variável de ambiente APPLICATIONINSIGHTS_WEB_INSTRUMENTATION_ENABLED = true.

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

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

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

Observação

A Instrumentação web pode reduzir 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 que a instrumentação web não funcione e a resposta original será retornada.

Instrumentação automática de terceiros

Para rastrear o contexto entre 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 fazer monkey patching em algumas dessas bibliotecas. Esse recurso pode ser desabilitado configurando a variável de ambiente APPLICATION_INSIGHTS_NO_DIAGNOSTIC_CHANNEL.

Observação

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

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

Atualmente, nove pacotes são instrumentados: bunyan, console, mongodb, mongodb-core, mysql, redis, winston, pg e pg-pool. Para obter informações sobre exatamente quais versões desses pacotes receberam patches. consulte o LEIAME de diagnostic-channel-publishers.

Os patches bunyan, winston e console geram eventos de rastreamento do Application Insights com base no fato de setAutoCollectConsole estar habilitado. O restante gera eventos de dependência do Application Insights com base no fato de setAutoCollectDependencies estar habilitado.

Métricas em tempo real

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

Métricas estendidas

Observação

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 métricas nativas do Node.js.

npm install applicationinsights-native-metrics

Atualmente, o pacote de métricas nativas executa a autocoleção de tempo de CPU de coleta de lixo, tiques 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: quantas tiques ocorreram e quanto tempo de CPU foi gasto no total.
• Heap versus não heap: a quantidade de uso de memória do aplicativo que está no heap ou fora do heap.

Modos de rastreamento distribuído

Por padrão, o SDK envia cabeçalhos reconhecidos 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 W3C, além dos cabeçalhos de IA existentes. Dessa forma, você não interromperá a correlação com nenhum dos serviços herdados existentes. Habilitar cabeçalhos de W3C permite que seu aplicativo se correlacione com outros serviços não instrumentados com o Application Insights, mas que adotam esse padrão de 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, confira API do Application Insights para métricas e eventos personalizados.

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

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
});

Acompanhamento das suas dependências

Use o código abaixo para acompanhar 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 trackMetric que usa para medir por quanto tempo o agendamento do loop de evento leva:

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);
}

Adição de uma propriedade personalizada para todos os eventos

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

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

Acompanhamento das solicitações GET HTTP

Use o código abaixo para controlar as solicitações GET HTTP manualmente:

Observação

Todas as solicitações são rastreadas por padrão. Para desabilitar a coleta automática, chame .setAutoCollectRequests(false) antes de chamar start().

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

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

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

Tempo de inicialização do servidor de acompanhamento

Use o código abaixo para acompanhar o tempo de inicialização do servidor:

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

Liberar

Por padrão, a telemetria é armazenada em buffer por 15 segundos antes de ser enviada para o servidor de ingestão. Se o aplicativo tiver um curto período de vida como, por exemplo, uma ferramenta CLI, poderá ser necessário liberar manualmente sua telemetria armazenada em buffer quando o aplicativo for encerrado usando appInsights.defaultClient.flush().

Se o SDK detectar que seu aplicativo está falhando, ele chama uma atualização para você usando appInsights.defaultClient.flush({ isAppCrashing: true }). Com a opção de liberação isAppCrashing, supõe-se que o aplicativo esteja em um estado anormal e não seja adequado para o envio de telemetria. Em vez disso, o SDK salva toda a telemetria armazenada em buffer no armazenamento persistente e permite que seu aplicativo seja encerrado. Quando seu aplicativo é iniciado novamente, ele tenta enviar qualquer telemetria que tenha sido salva no armazenamento persistente.

Pré-processar dados com 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 por 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 é 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 desse objeto é definido pelo parâmetro contextObjects ao chamar um método de rastreio para telemetria rastreada manualmente. Para telemetria coletada automaticamente, esse objeto é preenchido com as informações de solicitação disponíveis e o conteúdo de solicitação persistente conforme fornecido pelo 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 os 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 de Application Insights e enviar dados diferentes para cada usando suas respectivas 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 de configuração avançada

O objeto cliente 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, para que você possa configurar appInsights.defaultClient separadamente de clientes criados com o new appInsights.TelemetryClient().

Propriedade	Descrição
connectionString	um Identificador para seu recurso do Application Insights.
endpointUrl	O ponto de extremidade de ingestão para o qual enviar cargas de telemetria.
quickPulseHost	O host de Live Metrics Stream para o qual enviar a telemetria de métricas ao vivo.
proxyHttpUrl	Um servidor proxy para tráfego HTTP do SDK. (Opcional. O padrão é extraído da variável de ambiente http_proxy.)
proxyHttpsUrl	Um servidor proxy para tráfego HTTPS do SDK. (Opcional. O padrão é extraído da variável de ambiente https_proxy.)
httpAgent	Um http.Agent a ser usado para o tráfego HTTP do SDK. (Opcional. O padrão é indefinido.)
httpsAgent	Um https.Agent a ser usado para o 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 para o ponto de extremidade de ingestão. (O padrão é 250.)
maxBatchIntervalMs	A quantidade máxima de tempo de espera para que uma carga chegue a maxBatchSize. (O padrão é 15000.)
disableAppInsights	Um sinalizador que indica se a transmissão de telemetria está desabilitada. (O padrão é false.)
samplingPercentage	A porcentagem de itens de telemetria rastreados que devem ser transmitidos. (O padrão é 100.)
correlationIdRetryIntervalMs	O tempo de espera antes de tentar recuperar a ID da correlação entre componentes. (O padrão é 30000.)
correlationHeaderExcludedDomains	Uma lista de domínios para excluir da injeção de cabeçalho de correlação entre componentes. (Padrão. Consulte Config.ts.)

Solução de problemas

Para obter informações de 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óximas etapas

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