Como monitorar seus serviços do Node.js e aplicativos com o Application InsightsMonitor your Node.js services and apps with Application Insights

O Application insights monitora seus serviços de back-end e componentes após a implantação, para ajudá-lo a descobrir e diagnosticar rapidamente o desempenho e outros problemas.Application Insights monitors your backend services and components after deployment, to help you discover and rapidly diagnose performance and other issues. Você pode usar Application Insights para Node.js serviços hospedados em seu datacenter, em VMs do Azure e em aplicativos Web e até mesmo em outras nuvens públicas.You can use Application Insights for Node.js services that are hosted in your datacenter, Azure VMs and web apps, and even in other public clouds.

Para receber, armazenar e explorar os dados de monitoramento, incluir o SDK em seu código e, em seguida, configurar um recurso do Application Insights correspondente no Azure.To receive, store, and explore your monitoring data, include the SDK in your code, and then set up a corresponding Application Insights resource in Azure. O SDK envia dados a esse recurso para análise e exploração.The SDK sends data to that resource for further analysis and exploration.

O SDK do Node.js pode monitorar automaticamente as solicitações HTTP de entrada e saída, exceções e algumas métricas de sistema.The Node.js SDK can automatically monitor incoming and outgoing HTTP requests, exceptions, and some system metrics. A partir da versão 0,20, o SDK também pode monitorar alguns pacotes de terceiroscomuns, como MongoDB, MySQL e Redis.Beginning in version 0.20, the SDK also can monitor some common third-party packages, like MongoDB, MySQL, and Redis. Todos os eventos relacionados a uma solicitação HTTP de entrada são correlacionados para solução de problemas mais rápida.All events related to an incoming HTTP request are correlated for faster troubleshooting.

Você pode usar a API TelemetryClient para instrumentar e monitorar manualmente outros aspectos do aplicativo e do sistema.You can use the TelemetryClient API to manually instrument and monitor additional aspects of your app and system. Descrevemos a API TelemetryClient em mais detalhes mais adiante neste artigo.We describe the TelemetryClient API in more detail later in this article.

IntroduçãoGet started

Conclua as seguintes tarefas para configurar o monitoramento em um aplicativo ou serviço.Complete the following tasks to set up monitoring for an app or service.

Pré-requisitosPrerequisites

Antes de iniciar, verifique se você tem uma assinatura do Azure ou obtenha uma gratuitamente.Before you begin, make sure that you have an Azure subscription, or get a new one for free. Se sua organização já tiver uma assinatura do Azure, um administrador pode seguir estas instruções para adicioná-lo a ela.If your organization already has an Azure subscription, an administrator can follow these instructions to add you to it.

Configurar um recurso de Application InsightsSet up an Application Insights resource

  1. Entre no portal do Azure.Sign in to the Azure portal.
  2. Criar um recurso do Application InsightsCreate an Application Insights resource

Configurar o SDK do Node.jsSet up the Node.js SDK

Inclua o SDK em seu aplicativo, para que ele possa coletar dados.Include the SDK in your app, so it can gather data.

  1. Copie a chave de instrumentação do recurso (também chamada de iKey) de seu recurso recém-criado.Copy your resource's instrumentation Key (also called an ikey) from your newly created resource. O Application Insights usa a ikey para mapear os dados para o recurso do Azure.Application Insights uses the ikey to map data to your Azure resource. Antes de o SDK poder usar a ikey, você deverá especificar a ikey em uma variável de ambiente ou em seu código.Before the SDK can use your ikey, you must specify the ikey in an environment variable or in your code.

    Copie a chave de instrumentação

  2. Adicione a biblioteca de SDK do Node.js para as dependências do seu aplicativo por meio do package.json.Add the Node.js SDK library to your app's dependencies via package.json. Na pasta raiz do seu aplicativo, execute:From the root folder of your app, run:

    npm install applicationinsights --save
    

    Observação

    Se você estiver usando o TypeScript, não instale pacotes de "digitações" separados.If you are using TypeScript, do not install separate "typings" packages. Este pacote NPM contém digitações internas.This NPM package contains built-in typings.

  3. Carregue a biblioteca em seu código explicitamente.Explicitly load the library in your code. 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.Because the SDK injects instrumentation into many other libraries, load the library as early as possible, even before other require statements.

    let appInsights = require('applicationinsights');
    
  4. Você também pode fornecer um iKey por meio da variável de ambiente APPINSIGHTS_INSTRUMENTATIONKEY , em vez de passá-lo manualmente para setup() ou new appInsights.TelemetryClient() .You also can provide an ikey via the environment variable APPINSIGHTS_INSTRUMENTATIONKEY, instead of passing it manually to setup() or new appInsights.TelemetryClient(). Essa prática permite manter ikeys fora do código-fonte comprometido e também especificar ikeys diferentes para ambientes diferentes.This practice lets you keep ikeys out of committed source code, and you can specify different ikeys for different environments. Para configurar a chamada manualmente appInsights.setup('[your ikey]'); .To configure manually call appInsights.setup('[your ikey]');.

    Para outras opções de configuração, confira as seções a seguir.For additional configuration options, see the following sections.

    Você pode experimentar o SDK sem enviar telemetria definindo appInsights.defaultClient.config.disableAppInsights = true.You can try the SDK without sending telemetry by setting appInsights.defaultClient.config.disableAppInsights = true.

  5. Inicie a coleta e o envio de dados automaticamente chamando appInsights.start(); .Start automatically collecting and sending data by calling appInsights.start();.

Monitorar seu aplicativoMonitor your app

O SDK reúne automaticamente a telemetria sobre o tempo de execução de Node.js e alguns módulos de terceiros comuns.The SDK automatically gathers telemetry about the Node.js runtime and some common third-party modules. Use o aplicativo para gerar alguns desses dados.Use your application to generate some of this data.

Em seguida, no portal do Azure, vá para o recurso do Application Insights criado anteriormente.Then, in the Azure portal go to the Application Insights resource that you created earlier. Na Linha do tempo de visão geral, procure seus primeiros pontos de dados.In the Overview timeline, look for your first few data points. Para obter dados mais detalhadas, selecione componentes diferentes nos gráficos.To see more detailed data, select different components in the charts.

Para exibir a topologia descoberta para seu aplicativo, você pode usar o mapa do aplicativo.To view the topology that is discovered for your app, you can use Application map.

Sem dadosNo data

Como o SDK envia lotes de dados, pode haver um atraso antes de os itens serem exibidos no portal.Because the SDK batches data for submission, there might be a delay before items are displayed in the portal. Se você não visualizar os dados em seu recurso, experimente algumas das seguintes correções:If you don't see data in your resource, try some of the following fixes:

  • Continue a usar o aplicativo.Continue to use the application. Execute mais ações para gerar mais telemetria.Take more actions to generate more telemetry.
  • Clique em Atualizar no modo de exibição de recursos do portal.Click Refresh in the portal resource view. Os gráficos se atualizam sozinhos de tempos em tempos, mas a atualização manual força a atualização imediatamente.Charts periodically refresh on their own, but manually refreshing forces them to refresh immediately.
  • Verifique se as portas de saída obrigatórias estão abertas.Verify that required outgoing ports are open.
  • Use Pesquisar para procurar eventos específicos.Use Search to look for specific events.
  • Verifique as perguntas frequentes.Check the FAQ.

Uso básicoBasic Usage

Para uma coleção integrada de solicitações HTTP, eventos de biblioteca de terceiros populares, exceções sem tratamento e métricas do sistema:For out-of-the-box collection of HTTP requests, popular third-party library events, unhandled exceptions, and system metrics:


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

Observação

Se a chave de instrumentação for definida na variável de ambiente APPINSIGHTS_INSTRUMENTATIONKEY , o .setup() poderá ser chamado sem argumentos.If the instrumentation key is set in the environment variable APPINSIGHTS_INSTRUMENTATIONKEY, .setup() can be called with no arguments. Isso facilita o uso de diferentes ikeys para ambientes diferentes.This makes it easy to use different ikeys for different environments.

Carregue a biblioteca de Application Insights, o require("applicationinsights") mais cedo possível em seus scripts antes de carregar outros pacotes.Load the Application Insights library ,require("applicationinsights"), as early as possible in your scripts before loading other packages. Isso é necessário para que a biblioteca de Application Insights possa preparar pacotes posteriores para rastreamento.This is needed so that the Application Insights library can prepare later packages for tracking. Se você encontrar conflitos com outras bibliotecas fazendo uma preparação semelhante, tente carregar a biblioteca de Application Insights depois delas.If you encounter conflicts with other libraries doing similar preparation, try loading the Application Insights library after those.

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.Because of the way JavaScript handles callbacks, additional work is necessary to track a request across external dependencies and later callbacks. Por padrão, esse controle adicional é habilitado; Desabilite- setAutoDependencyCorrelation(false) a chamando conforme descrito na seção configuração abaixo.By default this additional tracking is enabled; disable it by calling setAutoDependencyCorrelation(false) as described in the configuration section below.

Migrando de versões anteriores a 0,22Migrating from versions prior to 0.22

Há alterações significativas entre as versões anteriores à versão 0,22 e posteriores.There are breaking changes between releases prior to version 0.22 and after. Essas alterações foram projetadas para trazer consistência com outros SDKs de Application Insights e permitir extensibilidade futura.These changes are designed to bring consistency with other Application Insights SDKs and allow future extensibility.

Em geral, você pode migrar com o seguinte:In general, you can migrate with the following:

  • Substitua referências a appInsights.client com appInsights.defaultClient .Replace references to appInsights.client with appInsights.defaultClient.
  • Substituir referências a appInsights.getClient() por new appInsights.TelemetryClient()Replace references to appInsights.getClient() with new appInsights.TelemetryClient()
  • Substitua todos os argumentos para os métodos Client. Track * por um único objeto que contém propriedades nomeadas como argumentos.Replace all arguments to client.track* methods with a single object containing named properties as arguments. Consulte a dica de tipo interno do IDE ou TelemetryTypes para o objeto excetuado para cada tipo de telemetria.See your IDE's built-in type hinting or TelemetryTypes for the excepted object for each type of telemetry.

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 (por exemplo, appInsights.Configuration.setAutoCollectDependencies(true) ).If you access SDK configuration functions without chaining them to appInsights.setup(), you can now find these functions at appInsights.Configurations (for example, appInsights.Configuration.setAutoCollectDependencies(true)). Examine as alterações na configuração padrão na próxima seção.Review the changes to the default configuration in the next section.

Configuração do SDKSDK configuration

O appInsights objeto fornece vários métodos de configuração.The appInsights object provides a number of configuration methods. Eles são listados no trecho a seguir com seus valores padrão.They are listed in the following snippet with their default values.

let appInsights = require("applicationinsights");
appInsights.setup("<instrumentation_key>")
    .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).To fully correlate events in a service, be sure to set .setAutoDependencyCorrelation(true). Com essa opção definida, o SDK pode acompanhar o contexto entre retornos de chamada assíncronos no Node.js.With this option set, the SDK can track context across asynchronous callbacks in Node.js.

Examine suas descrições na dica de tipo interno do IDE ou applicationinsights. TS para obter informações detalhadas sobre o que esses controles e os argumentos secundários opcionais.Review their descriptions in your IDE's built-in type hinting, or applicationinsights.ts for detailed information on what these control, and optional secondary arguments.

Observação

Por padrão, o setAutoCollectConsole é configurado para excluir chamadas para console.log (e outros métodos de console).By default setAutoCollectConsole is configured to exclude calls to console.log (and other console methods). Somente chamadas para agentes de terceiros com suporte (por exemplo, Winston e Bunyan) serão coletadas.Only calls to supported third-party loggers (for example, winston and bunyan) will be collected. Você pode alterar esse comportamento para incluir chamadas para console métodos usando o setAutoCollectConsole(true, true) .You can change this behavior to include calls to console methods by using setAutoCollectConsole(true, true).

amostragemSampling

Por padrão, o SDK enviará todos os dados coletados para o serviço de Application Insights.By default, the SDK will send all collected data to the Application Insights service. Se você coletar muitos dados, talvez queira habilitar a amostragem para reduzir a quantidade de dados enviados.If you collect a lot of data, you might want to enable sampling to reduce the amount of data sent. Defina o samplingPercentage campo no config objeto de um cliente para fazer isso.Set the samplingPercentage field on the config object of a client to accomplish this. Definir samplingPercentage como 100 (o padrão) significa que todos os dados serão enviados e 0 significa que nada será enviado.Setting samplingPercentage to 100(the default) means all data will be sent and 0 means nothing will be sent.

Se você estiver usando correlação automática, todos os dados associados a uma única solicitação serão incluídos ou excluídos como uma unidade.If you are using automatic correlation, all data associated with a single request will be included or excluded as a unit.

Adicione um código como o seguinte para habilitar a amostragem:Add code such as the following to enable sampling:

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

Várias funções para aplicativos de vários componentesMultiple roles for multi-components applications

Se seu aplicativo consiste em vários componentes que você deseja instrumentar com a mesma chave de instrumentação e ainda vir esses componentes como unidades separadas no portal, como se estivessem usando chaves de instrumentação separadas (por exemplo, como nós separados no mapa do aplicativo), talvez seja necessário configurar manualmente o campo RoleName para distinguir a telemetria de um componente de outros componentes que enviam dados para Application Insights o recursoIf your application consists of multiple components that you wish to instrument all with the same instrumentation key and still see these components as separate units in the portal, as if they were using separate instrumentation keys (for example, as separate nodes on the Application Map), you may need to manually configure the RoleName field to distinguish one component's telemetry from other components sending data to your Application Insights resource.

Use o seguinte para definir o campo RoleName:Use the following to set the RoleName field:

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

Instrumentação automática de terceirosAutomatic third-party instrumentation

Para rastrear o contexto entre chamadas assíncronas, algumas alterações são necessárias em bibliotecas de terceiros, como MongoDB e Redis.In order to track context across asynchronous calls, some changes are required in third party libraries such as MongoDB and Redis. Por padrão, Application Insights será usado diagnostic-channel-publishers para aplicar patches a algumas dessas bibliotecas.By default, Application Insights will use diagnostic-channel-publishers to monkey-patch some of these libraries. Isso pode ser desabilitado definindo a APPLICATION_INSIGHTS_NO_DIAGNOSTIC_CHANNEL variável de ambiente.This can be disabled by setting the APPLICATION_INSIGHTS_NO_DIAGNOSTIC_CHANNEL environment variable.

Observação

Ao definir essa variável de ambiente, os eventos podem não estar mais corretamente associados à operação correta.By setting that environment variable, events may no longer be correctly associated with the right operation.

Macaco individual-os patches podem ser desabilitados definindo a APPLICATION_INSIGHTS_NO_PATCH_MODULES variável de ambiente como uma lista separada por vírgulas de pacotes a serem desabilitados (por exemplo, APPLICATION_INSIGHTS_NO_PATCH_MODULES=console,redis ) para evitar a aplicação de patches nos console redis pacotes e.Individual monkey-patches can be disabled by setting the APPLICATION_INSIGHTS_NO_PATCH_MODULES environment variable to a comma separated list of packages to disable (for example, APPLICATION_INSIGHTS_NO_PATCH_MODULES=console,redis) to avoid patching the console and redis packages.

Atualmente, há nove pacotes que são instrumentados:,,,,, bunyan console ,, mongodb mongodb-core mysql redis winston pg e pg-pool .Currently there are nine packages that are instrumented: bunyan,console,mongodb,mongodb-core,mysql,redis,winston,pg, and pg-pool. Visite o Leiame Diagnostic-Channel-Publishers para obter informações sobre exatamente quais versões desses pacotes são corrigidas.Visit the diagnostic-channel-publishers' README for information about exactly which version of these packages are patched.

Os bunyan winston console patches, e irão gerar Application insights eventos de rastreamento com base em se o setAutoCollectConsole está habilitado.The bunyan, winston, and console patches will generate Application Insights trace events based on whether setAutoCollectConsole is enabled. O restante irá gerar Application Insights eventos de dependência com base no fato de setAutoCollectDependencies estar habilitado.The rest will generate Application Insights Dependency events based on whether setAutoCollectDependencies is enabled.

Live Metrics Live Metrics

Para habilitar o envio de métricas ao vivo de seu aplicativo para o Azure, use setSendLiveMetrics(true) .To enable sending Live Metrics from your app to Azure, use setSendLiveMetrics(true). Atualmente, não há suporte para a filtragem de métricas em tempo real no Portal.Filtering of live metrics in the portal is currently not supported.

Métricas estendidasExtended metrics

Observação

A capacidade de enviar métricas nativas estendidas foi adicionada na versão 1.4.0The ability to send extended native metrics was added in version 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.To enable sending extended native metrics from your app to Azure, install the separate native metrics package. O SDK será carregado automaticamente quando for instalado e começará a coletar Node.js métricas nativas.The SDK will automatically load when it is installed and start collecting Node.js native metrics.

npm install applicationinsights-native-metrics

Atualmente, o pacote de métricas nativas executa a coleta autocoleção de tempo de CPU de coleta de lixo, tiques de loop de eventos e uso de heap:Currently, the native metrics package performs autocollection of garbage collection CPU time, event loop ticks, and heap usage:

  • Coleta de lixo: a quantidade de tempo de CPU gasto em cada tipo de coleta de lixo e quantas ocorrências de cada tipo.Garbage collection: The amount of CPU time spent on each type of garbage collection, and how many occurrences of each type.
  • Loop de eventos: quantas tiques ocorreram e quanto tempo de CPU foi gasto no total.Event loop: How many ticks occurred and how much CPU time was spent in total.
  • Heap vs não heap: a quantidade de uso de memória do aplicativo está no heap ou não heap.Heap vs non-heap: How much of your app's memory usage is in the heap or non-heap.

Modos de rastreamento distribuídosDistributed Tracing modes

Por padrão, o SDK enviará cabeçalhos compreendidos por outros aplicativos/serviços instrumentados com um SDK Application Insights.By default, the SDK will send headers understood by other applications/services instrumented with an Application Insights SDK. Opcionalmente, você pode habilitar o envio/recebimento de cabeçalhos de contexto de rastreamento W3C , além dos cabeçalhos de ia existentes, para que você não interrompa a correlação com nenhum dos seus serviços herdados existentes.You can optionally enable sending/receiving of W3C Trace Context headers in addition to the existing AI headers, so you will not break correlation with any of your existing legacy services. Habilitar cabeçalhos W3C permitirá que seu aplicativo correlacione-se com outros serviços não instrumentados com Application Insights, mas adote esse padrão W3C.Enabling W3C headers will allow your app to correlate with other services not instrumented with Application Insights, but do adopt this W3C standard.

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

API TelemetryClientTelemetryClient API

Para obter uma descrição completa da API TelemetryClient, confira API do Application Insights para métricas e eventos personalizados.For a full description of the TelemetryClient API, see Application Insights API for custom events and metrics.

Você pode acompanhar qualquer solicitação, evento, métrica ou exceção usando o SDK do Node.js para Application Insights.You can track any request, event, metric, or exception by using the Application Insights Node.js SDK. O exemplo de código abaixo demonstra algumas das APIs que você pode usar:The following code example demonstrates some of the APIs that you can use:

let appInsights = require("applicationinsights");
appInsights.setup().start(); // assuming ikey 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ênciasTrack your dependencies

Use o código abaixo para acompanhar suas dependências:Use the following code to track your dependencies:

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:An example utility using trackMetric to measure how long event loop scheduling takes:

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 eventosAdd a custom property to all events

Use o código abaixo para adicionar uma propriedade personalizada a todos os eventos:Use the following code to add a custom property to all events:

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

Acompanhamento das solicitações GET HTTPTrack HTTP GET requests

Use o código a seguir para rastrear manualmente as solicitações HTTP GET:Use the following code to manually track HTTP GET requests:

Observação

Todas as solicitações são rastreadas por padrão.All requests are tracked by default. Para desabilitar a coleta automática, chame. setAutoCollectRequests (false) antes de chamar Start ().To disable automatic collection, call .setAutoCollectRequests(false) before calling start().

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

Como alternativa, você pode controlar solicitações usando o trackNodeHttpRequest método:Alternatively you can track requests using trackNodeHttpRequest method:

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 acompanhamentoTrack server startup time

Use o código abaixo para acompanhar o tempo de inicialização do servidor:Use the following code to track server startup time:

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

Pré-processar dados com processadores de telemetriaPreprocess data with telemetry processors

Você pode processar e filtrar os dados coletados antes que eles sejam enviados para retenção usando processadores de telemetria.You can process and filter collected data before it is sent for retention using Telemetry Processors. 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.Telemetry processors are called one by one in the order they were added before the telemetry item is sent to the cloud.

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.If a telemetry processor returns false, that telemetry item will not be sent.

Todos os processadores de telemetria recebem os dados de telemetria e seu envelope para inspecionar e modificar.All telemetry processors receive the telemetry data and its envelope to inspect and modify. Eles também recebem um objeto de contexto.They also receive a context object. O conteúdo desse objeto é definido pelo contextObjects parâmetro ao chamar um método Track para telemetria rastreada manualmente.The contents of this object is defined by the contextObjects parameter when calling a track method for manually tracked telemetry. 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).For automatically collected telemetry, this object is filled with available request information and the persistent request content as provided by appInsights.getCorrelationContext() (if automatic dependency correlation is enabled).

O tipo TypeScript para um processador de telemetria é:The TypeScript type for a telemetry processor is:

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:For example, a processor that removes stacks trace data from exceptions might be written and added as follows:

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 chaves de instrumentaçãoUse multiple instrumentation keys

Você pode criar vários recursos de Application Insights e enviar dados diferentes para cada usando suas respectivas chaves de instrumentação ("iKey").You can create multiple Application Insights resources and send different data to each by using their respective instrumentation keys ("ikey").

Por exemplo:For example:

let appInsights = require("applicationinsights");

// configure auto-collection under one ikey
appInsights.setup("_ikey-A_").start();

// track some events manually under another ikey
let otherClient = new appInsights.TelemetryClient("_ikey-B_");
otherClient.trackEvent({name: "my custom event"});

Opções de configuração avançadaAdvanced configuration options

O objeto Client contém uma config propriedade com muitas configurações opcionais para cenários avançados.The client object contains a config property with many optional settings for advanced scenarios. Eles podem ser definidos da seguinte maneira:These can be set as follows:

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() .These properties are client specific, so you can configure appInsights.defaultClient separately from clients created with new appInsights.TelemetryClient().

PropriedadeProperty DescriçãoDescription
instrumentationKeyinstrumentationKey Um identificador para o recurso de Application Insights.An identifier for your Application Insights resource.
endpointUrlendpointUrl O ponto de extremidade de ingestão para o qual enviar cargas de telemetria.The ingestion endpoint to send telemetry payloads to.
quickPulseHostquickPulseHost O host de Live Metrics Stream para o qual enviar a telemetria de métricas ao vivo.The Live Metrics Stream host to send live metrics telemetry to.
proxyHttpUrlproxyHttpUrl Um servidor proxy para tráfego HTTP do SDK (opcional, padrão extraído da http_proxy variável de ambiente).A proxy server for SDK HTTP traffic (Optional, Default pulled from http_proxy environment variable).
proxyHttpsUrlproxyHttpsUrl Um servidor proxy para o tráfego HTTPS do SDK (opcional, padrão extraído da https_proxy variável de ambiente).A proxy server for SDK HTTPS traffic (Optional, Default pulled from https_proxy environment variable).
httpAgenthttpAgent Um http. Agente a ser usado para o tráfego HTTP do SDK (opcional, padrão indefinido).An http.Agent to use for SDK HTTP traffic (Optional, Default undefined).
httpsAgenthttpsAgent Um https. Agente a ser usado para o tráfego HTTPS do SDK (opcional, padrão indefinido).An https.Agent to use for SDK HTTPS traffic (Optional, Default undefined).
maxBatchSizemaxBatchSize O número máximo de itens de telemetria a serem incluídos em uma carga para o ponto de extremidade de ingestão (padrão 250 ).The maximum number of telemetry items to include in a payload to the ingestion endpoint (Default 250).
maxBatchIntervalMsmaxBatchIntervalMs A quantidade máxima de tempo de espera para que uma carga chegue a maxBatchSize (padrão 15000 ).The maximum amount of time to wait to for a payload to reach maxBatchSize (Default 15000).
disableAppInsightsdisableAppInsights Um sinalizador que indica se a transmissão de telemetria está desabilitada (padrão false ).A flag indicating if telemetry transmission is disabled (Default false).
samplingPercentagesamplingPercentage A porcentagem de itens de telemetria rastreados que devem ser transmitidos (padrão 100 ).The percentage of telemetry items tracked that should be transmitted (Default 100).
correlationIdRetryIntervalMscorrelationIdRetryIntervalMs O tempo de espera antes de tentar recuperar a ID da correlação entre componentes (padrão 30000 ).The time to wait before retrying to retrieve the ID for cross-component correlation (Default 30000).
correlationHeaderExcludedDomainscorrelationHeaderExcludedDomains Uma lista de domínios para excluir da injeção de cabeçalho de correlação entre componentes (padrão, consulte config. TS).A list of domains to exclude from cross-component correlation header injection (Default See Config.ts).

Próximas etapasNext steps