Övervaka dina Node-js-tjänster och -appar med Application Insights

Application Insights övervakar dina komponenter efter distributionen för att identifiera prestanda och andra problem. Du kan använda Application Insights för Node.js tjänster som finns i ditt datacenter, virtuella Azure-datorer och webbappar, och även i andra offentliga moln.

Om du vill ta emot, lagra och utforska dina övervakningsdata inkluderar du SDK:et i koden. Konfigurera sedan en motsvarande Application Insights-resurs i Azure. SDK:t skickar data till den resursen för ytterligare analys och undersökning.

Node.js-klientbiblioteket kan automatiskt övervaka inkommande och utgående HTTP-begäranden, undantag och vissa systemmått. Från och med version 0.20 kan klientbiblioteket även övervaka några vanliga tredjepartspaket, till exempel MongoDB, MySQL och Redis.

Alla händelser som relaterar till en inkommande HTTP-begäran korreleras för snabbare felsökning.

Du kan använda TelemetryClient-API:et för att manuellt instrumentera och övervaka fler aspekter av din app och ditt system. Vi beskriver TelemetryClient-API:n mer ingående senare i den här artikeln.

Kommentar

Följande dokumentation förlitar sig på det klassiska API:et Application Insights. Den långsiktiga planen för Application Insights är att samla in data med OpenTelemetry. Mer information finns i Aktivera Azure Monitor OpenTelemetry för .NET-, Node.js-, Python- och Java-program.

Kom igång

Utför följande uppgifter för att konfigurera övervakning för en app eller tjänst.

Förutsättningar

Innan du börjar ska du se till att ha en Azure-prenumeration eller så skaffar du en kostnadsfritt. Om din organisation redan har en Azure-prenumeration kan en administratör följa de här instruktionerna för att lägga till dig.

Konfigurera en Application Insights-resurs

1. Logga in på Azure-portalen.
2. Skapa en Application Insights-resurs.

Kommentar

Stödet för inmatning av instrumentationsnycklar upphör den 31 mars 2025. Inmatningen av instrumenteringsnyckeln fortsätter att fungera, men vi kommer inte längre att tillhandahålla uppdateringar eller stöd för funktionen. Övergå till anslutningssträng för att dra nytta av nya funktioner.

Konfigurera klientbiblioteket för Node.js

Inkludera SDK:et i din app så att den kan samla in data.

1. Kopiera resursens anslutningssträng från den nya resursen. Application Insights använder anslutningssträng för att mappa data till din Azure-resurs. Innan SDK:t kan använda din anslutningssträng måste du ange anslutningssträng i en miljövariabel eller i koden.

   

2. Lägg till Node.js-klientbiblioteket i appens beroenden via package.json. Från appens rotmapp kör du:

   npm install applicationinsights --save
   

   Kommentar

   Om du använder TypeScript ska du inte installera separata "skrivningar"-paket. Det här NPM-paketet innehåller inbyggda indata.

3. Läs uttryckligen in biblioteket i din kod. Eftersom SDK:n lägger in instrumentationen i många andra bibliotek ska du läsa in biblioteket så tidigt som möjligt, till och med före andra require-uttryck.

   let appInsights = require('applicationinsights');
   

4. Du kan också ange en anslutningssträng via miljövariabeln APPLICATIONINSIGHTS_CONNECTION_STRINGi stället för att skicka den manuellt till setup() eller new appInsights.TelemetryClient(). Med den här metoden kan du hålla anslutningssträng borta från den incheckade källkoden och du kan ange olika anslutningssträng för olika miljöer. Om du vill konfigurera manuellt anropar du appInsights.setup('[your connection string]');.

   Fler konfigurationsalternativ finns i följande avsnitt.

   Du kan testa SDK:n utan att skicka telemetri genom att ställa in appInsights.defaultClient.config.disableAppInsights = true.

5. Börja samla in och skicka data automatiskt genom att anropa appInsights.start();.

Kommentar

Som en del av användningen av Application Insights-instrumentation samlar vi in och skickar diagnostikdata till Microsoft. Dessa data hjälper oss att köra och förbättra Application Insights. Du kan inaktivera icke-nödvändig datainsamling. Läs mer.

Övervaka din app

SDK samlar automatiskt in telemetri om Node.js-körning och några vanliga moduler från tredje part. Använd ditt program för att skapa vissa av dessa data.

På Azure Portal går du sedan till Application Insights och öppnar den resurs som du skapade tidigare. I Översiktstidslinje letar du efter dina första datapunkter. Välj olika komponenter i schemana för att se mer detaljerade data.

Om du vill visa topologin som har identifierats för din app kan du använda Programkarta.

Inga data

Eftersom SDK batchar data för sändning kan det uppstå en fördröjning innan objekt visas i portalen. Om du inte ser några data i resursen kan du prova något av följande:

• Fortsätta att använda programmet. Vidta fler åtgärder för att generera mer telemetri.
• Välj Uppdatera i portalresursvyn. Diagram uppdaterar sig själva regelbundet, men när du trycker på uppdateringsknappen manuellt tvingas de att uppdatera genast.
• Verifiera att nödvändiga utgående portar är öppna.
• Använd Sök för att söka efter specifika händelser.
• Se Vanliga frågor.

Grundläggande användning

För den färdiga samlingen av HTTP-begäranden, populära bibliotekshändelser från tredje part, ohanterade undantag och systemmått:

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

Kommentar

Om anslutningssträng anges i miljövariabeln APPLICATIONINSIGHTS_CONNECTION_STRING.setup() kan anropas utan argument. Det gör det enkelt att använda olika anslutningssträng för olika miljöer.

Läs in Application Insights-biblioteket require("applicationinsights") så tidigt som möjligt i skripten innan du läser in andra paket. Det här steget behövs så att Application Insights-biblioteket kan förbereda senare paket för spårning. Om du stöter på konflikter med andra bibliotek som utför liknande förberedelser kan du prova att läsa in Application Insights-biblioteket efteråt.

På grund av hur JavaScript hanterar återanrop krävs mer arbete för att spåra en begäran över externa beroenden och senare återanrop. Som standard är den här extra spårningen aktiverad. Inaktivera det genom att anropa setAutoDependencyCorrelation(false) enligt beskrivningen i avsnittet SDK-konfiguration .

Migrera från versioner före 0.22

Det finns icke-bakåtkompatibla ändringar mellan versioner före version 0.22 och senare. Dessa ändringar är utformade för att ge konsekvens med andra Application Insights-SDK:er och tillåta framtida utökningsbarhet.

I allmänhet kan du migrera med följande åtgärder:

• Ersätt referenser till appInsights.client med appInsights.defaultClient.
• Ersätt referenser till appInsights.getClient() med new appInsights.TelemetryClient().
• Ersätt alla argument med client.track*-metoder med ett enda objekt som innehåller namngivna egenskaper som argument. Se IDE:s inbyggda typtips eller TelemetryTypes för det undantagna objektet för varje typ av telemetri.

Om du kommer åt SDK-konfigurationsfunktioner utan att länka dem till appInsights.setup()kan du nu hitta dessa funktioner på appInsights.Configurations. Ett exempel är appInsights.Configuration.setAutoCollectDependencies(true). Granska ändringarna i standardkonfigurationen i nästa avsnitt.

SDK-konfiguration

Objektet appInsights innehåller många konfigurationsmetoder. De visas i följande kodfragment med sina standardvärden.

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

Ställ in .setAutoDependencyCorrelation(true) för att korrelera händelser i en tjänst fullständigt. När det alternativet är inställt kan SDK:n spåra innehåll över asynkrona återanrop i Node.js.

Granska beskrivningarna i din IDE:s inbyggda typtips eller applicationinsights.ts för detaljerad information och valfria sekundära argument.

Kommentar

Som standard setAutoCollectConsole är konfigurerad för att undanta anrop till console.log och andra konsolmetoder. Endast anrop till tredjepartsloggare som stöds (till exempel winston och bunyan) samlas in. Du kan ändra det här beteendet så att det inkluderar anrop till console metoder med hjälp setAutoCollectConsole(true, true)av .

Sampling

Som standard skickar SDK:et alla insamlade data till Application Insights-tjänsten. Om du vill aktivera sampling för att minska mängden data anger du samplingPercentage fältet på objektet för config en klient. Inställningen samplingPercentage till 100 (standardvärdet) innebär att alla data skickas och 0 innebär att ingenting skickas.

Om du använder automatisk korrelation inkluderas eller exkluderas alla data som är associerade med en enskild begäran som en enhet.

Lägg till kod som följande för att aktivera sampling:

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

Flera roller för program med flera komponenter

I vissa scenarier kan ditt program bestå av flera komponenter som du vill instrumentera alla med samma anslutningssträng. Du vill fortfarande se dessa komponenter som separata enheter i portalen, som om de använde separata anslutningssträng. Ett exempel är separata noder på programkartan. Du måste konfigurera fältet RoleName manuellt för att skilja en komponents telemetri från andra komponenter som skickar data till din Application Insights-resurs.

Använd följande kod för att ange fältet RoleName :

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

Webbläsar-SDK-inläsare

Kommentar

Tillgänglig som en offentlig förhandsversion. Kompletterande användningsvillkor för Microsoft Azure-förhandsversioner

Automatisk webbinstrumentation kan aktiveras för nodservern via JavaScript (Web) SDK Loader Script injection by configuration.

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

eller genom att ange miljövariabeln APPLICATIONINSIGHTS_WEB_INSTRUMENTATION_ENABLED = true.

Webbinstrumentation är aktiverat på nodserversvar när alla följande krav uppfylls:

• Svaret har statuskoden 200.
• Svarsmetoden är GET.
• Serversvaret har Content-Type html.
• Serversvaret innehåller både <head> och </head> Taggar.
• Om svaret komprimeras måste det bara ha en Content-Encoding typ och kodningstypen måste vara en av gzip, br eller deflate.
• Svaret innehåller inte aktuella /backup web Instrumentation CDN-slutpunkter. (aktuella cdn-slutpunkter för webbinstrumentation och säkerhetskopiering här)

cdn-slutpunkten för webbinstrumentation kan ändras genom att miljövariabeln APPLICATIONINSIGHTS_WEB_INSTRUMENTATION_SOURCE = "web Instrumentation CDN endpoints"anges. web Instrumentation anslutningssträng kan ändras genom att ange miljövariabelAPPLICATIONINSIGHTS_WEB_INSTRUMENTATION_CONNECTION_STRING = "web Instrumentation connection string"

Kommentar

Webbinstrumentation kan göra serverns svarstid långsammare, särskilt när svarsstorleken är stor eller om svaret komprimeras. För det fall där vissa mellanlager tillämpas kan det leda till att webbinstrumentationen inte fungerar och att det ursprungliga svaret returneras.

Automatisk instrumentering från tredje part

För att spåra kontext över asynkrona anrop krävs vissa ändringar i bibliotek från tredje part, till exempel MongoDB och Redis. Som standard använder diagnostic-channel-publishers Application Insights för att apa-korrigera några av dessa bibliotek. Den här funktionen kan inaktiveras genom att APPLICATION_INSIGHTS_NO_DIAGNOSTIC_CHANNEL ange miljövariabeln.

Kommentar

Genom att ange miljövariabeln kanske händelser inte är korrekt kopplade till rätt åtgärd.

Enskilda apkorrigeringar kan inaktiveras genom att ställa in APPLICATION_INSIGHTS_NO_PATCH_MODULES miljövariabeln på en kommaavgränsad lista över paket som ska inaktiveras. Använd till exempel APPLICATION_INSIGHTS_NO_PATCH_MODULES=console,redis för att undvika att korrigera paketen console och redis .

För närvarande instrumenteras nio paket: bunyan,,,mongodbmongodb-core,mysql,redis,,winstonpg, och pg-pool.console Information om exakt vilken version av dessa paket som korrigeras finns i README för diagnostic-channel-publishers.

Korrigeringarna bunyan, winstonoch console genererar Application Insights-spårningshändelser baserat på om setAutoCollectConsole är aktiverat. Resten genererar Application Insights-beroendehändelser baserat på om setAutoCollectDependencies är aktiverat.

Live-mått

Om du vill aktivera sändning av live-mått från din app till Azure använder du setSendLiveMetrics(true). För närvarande stöds inte filtrering av livemått i portalen.

Utökade mått

Kommentar

Möjligheten att skicka utökade interna mått lades till i version 1.4.0.

Om du vill aktivera sändning av utökade interna mått från din app till Azure installerar du det separata interna måttpaketet. SDK:et läses in automatiskt när det installeras och börjar samla in Node.js interna mått.

npm install applicationinsights-native-metrics

För närvarande utför det inbyggda måttpaketet automatisk insamling av cpu-tid för skräpinsamling, händelseloop-fästingar och heapanvändning:

• Skräpinsamling: Mängden CPU-tid som spenderas på varje typ av skräpinsamling och hur många förekomster av varje typ.
• Händelseloop: Hur många fästingar som har inträffat och hur mycket CPU-tid som spenderades totalt.
• Heap jämfört med icke-heap: Hur mycket av appens minnesanvändning som finns i heap eller icke-heap.

Distribuerade spårningslägen

Som standard skickar SDK:t rubriker som förstås av andra program eller tjänster som instrumenterats med en Application Insights SDK. Du kan aktivera sändning och mottagning av W3C Trace Context-huvuden utöver de befintliga AI-huvudena. På så sätt bryter du inte korrelationen med någon av dina befintliga äldre tjänster. Om du aktiverar W3C-huvuden kan din app korrelera med andra tjänster som inte instrumenterats med Application Insights, men som använder den här W3C-standarden.

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

TelemetryClient-API

En fullständig beskrivning av TelemetryClient-API:n finns i Application Insights API for custom events and metrics (Application Insights-API för anpassade händelser och mått).

Du kan spåra alla förfrågningar, händelser, mått eller undantag med hjälp av Application Insights-klientbiblioteket för Node.js. I följande kodexempel visas några av de tillgängliga API:erna som du kan använda:

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

Spåra dina beroenden

Du kan använda följande kod för att spåra dina beroenden:

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

Ett exempelverktyg som använder trackMetric för att mäta hur lång tid det tar att schemalägga händelseloopar:

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

Lägga till en anpassad egenskap i alla händelser

Använd följande kod för att lägga till en anpassad egenskap i alla händelser:

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

Spåra HTTP GET-begäranden

Använd följande kod för att manuellt spåra HTTP GET-begäranden:

Kommentar

Alla begäranden spåras som standard. Om du vill inaktivera automatisk samling anropar du .setAutoCollectRequests(false) innan du anropar start().

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

Du kan också spåra begäranden med hjälp trackNodeHttpRequest av metoden:

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

Spåra starttiden för server

Du kan använda följande kod för att spåra starttiden för servern:

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

Spola

Som standard buffrad telemetri i 15 sekunder innan den skickas till inmatningsservern. Om ditt program har en kort livslängd, till exempel ett CLI-verktyg, kan det vara nödvändigt att manuellt rensa din buffrade telemetri när programmet avslutas med hjälp appInsights.defaultClient.flush()av .

Om SDK:t upptäcker att programmet kraschar anropas tömning åt dig med hjälp appInsights.defaultClient.flush({ isAppCrashing: true })av . Med tömningsalternativet isAppCrashingantas programmet vara i ett onormalt tillstånd och är inte lämpligt att skicka telemetri. I stället sparar SDK:t all buffrad telemetri till beständig lagring och låter programmet avslutas. När programmet startar igen försöker det skicka all telemetri som har sparats till beständig lagring.

Förbearbeta data med telemetriprocessorer

Du kan bearbeta och filtrera insamlade data innan de skickas för kvarhållning med hjälp av telemetriprocessorer. Telemetriprocessorer anropas en i taget i den ordning de lades till innan telemetriobjektet skickas till molnet.

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

Om en telemetriprocessor returnerar falseskickas inte telemetriobjektet.

Alla telemetriprocessorer tar emot telemetridata och dess kuvert för att inspektera och ändra. De får också ett kontextobjekt. Innehållet i det här objektet definieras av parametern contextObjects när du anropar en spårningsmetod för manuellt spårad telemetri. För automatiskt insamlad telemetri fylls det här objektet med tillgänglig information om begäranden och det beständiga begärandeinnehållet som tillhandahålls av appInsights.getCorrelationContext() (om automatisk beroendekorrelation är aktiverat).

TypeScript-typen för en telemetriprocessor är:

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

Till exempel kan en processor som tar bort stacksspårningsdata från undantag skrivas och läggas till på följande sätt:

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

Använda flera anslutningssträng

Du kan skapa flera Application Insights-resurser och skicka olika data till var och en med hjälp av respektive anslutningssträng.

Till exempel:

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

Avancerade konfigurationsalternativ

Klientobjektet innehåller en config egenskap med många valfria inställningar för avancerade scenarier. Om du vill ange dem använder du:

client.config.PROPERTYNAME = VALUE;

Dessa egenskaper är klientspecifika, så du kan konfigurera appInsights.defaultClient separat från klienter som skapats med new appInsights.TelemetryClient().

Property	Beskrivning
Connectionstring	En identifierare för din Application Insights-resurs.
endpointUrl	Inmatningsslutpunkten som telemetrinyttolaster ska skickas till.
quickPulseHost	Live Metrics Stream-värden som ska skicka telemetri för live-mått till.
proxyHttpUrl	En proxyserver för SDK HTTP-trafik. (Valfritt. Standardvärdet hämtas från http_proxy miljövariabeln.)
proxyHttpsUrl	En proxyserver för SDK HTTPS-trafik. (Valfritt. Standardvärdet hämtas från https_proxy miljövariabeln.)
httpAgent	En http. Agent som ska användas för SDK HTTP-trafik. (Valfritt. Standardvärdet är odefinierat.)
httpsAgent	En https. Agent som ska användas för SDK HTTPS-trafik. (Valfritt. Standardvärdet är odefinierat.)
maxBatchSize	Det maximala antalet telemetriobjekt som ska inkluderas i en nyttolast till inmatningsslutpunkten. (Standard är 250.)
maxBatchIntervalMs	Den maximala väntetiden för att en nyttolast ska nå maxBatchSize. (Standard är 15000.)
disableAppInsights	En flagga som anger om telemetriöverföring är inaktiverad. (Standard är false.)
samplingPercentage	Procentandelen telemetriobjekt som spåras och som ska överföras. (Standard är 100.)
correlationIdRetryIntervalMs	Tiden att vänta innan du försöker hämta ID:t för korrelation mellan komponenter igen. (Standard är 30000.)
correlationHeaderExcludedDomains	En lista över domäner som ska undantas från korskomponentens korrelationsrubrikinmatning. (Standard. Se Config.ts.)

Felsökning

Felsökningsinformation, inklusive scenarier utan data och anpassning av loggar, finns i Felsöka Application Insights-övervakning av Node.js appar och tjänster.

Nästa steg

• Övervaka din telemetri i portalen
• Skriv Analytics-frågor via din telemetri