Uw Node.js toepassingen en services bewaken met Application Insights (klassieke API)

Application Insights bewaakt uw onderdelen na de implementatie om prestaties en andere problemen te detecteren. U kunt Application Insights gebruiken voor Node.js services die worden gehost in uw datacenter, Azure-VM's en web-apps, en zelfs in andere openbare clouds.

Als u uw bewakingsgegevens wilt ontvangen, opslaan en verkennen, neemt u de SDK op in uw code. Stel vervolgens een bijbehorende Application Insights-resource in Azure in. Met de SDK worden gegevens naar deze resource verzonden voor verdere analyse en onderzoek.

De Node.js-clientbibliotheek kan automatisch binnenkomende en uitgaande HTTP-aanvragen, uitzonderingen en enkele metrische systeemgegevens bewaken. Vanaf versie 0.20 kan de clientbibliotheek ook enkele algemene pakketten van derden bewaken, zoals MongoDB, MySQL en Redis.

Alle gebeurtenissen met betrekking tot een binnenkomende HTTP-aanvraag worden gecorreleerd voor snellere probleemoplossing.

U kunt de TelemetryClient-API gebruiken om handmatig meer aspecten van uw app en systeem te instrumenteren en te bewaken. De TelemetryClient-API wordt verderop in dit artikel meer gedetailleerd beschreven.

Aan de slag

Voltooi de volgende taken om de bewaking voor een app of service in te stellen.

Vereisten

Voordat u begint, moet u ervoor zorgen dat u een Azure-abonnement hebt of moet u een gratis nieuw abonnement aanvragen. Als uw organisatie al een Azure-abonnement heeft, kan een beheerder deze instructies volgen om u eraan toe te voegen.

Een Application Insights-resource instellen

1. Meld u aan bij het Azure-portaal.
2. Een Application Insights-resource maken.

De Node.js-clientbibliotheek instellen

Neem de SDK op in uw app, zodat deze gegevens kan verzamelen.

1. Kopieer de verbindingsreeks van uw resource uit uw nieuwe resource. Application Insights gebruikt de verbindingsreeks om gegevens toe te wijzen aan uw Azure-resource. Voordat de SDK uw verbindingsreeks kan gebruiken, moet u de verbindingsreeks opgeven in een omgevingsvariabele of in uw code.

   

2. Voeg de Node.js-clientbibliotheek toe aan de afhankelijkheden van uw app via package.json. Voer in de hoofdmap van uw app de volgende opdracht uit:

   npm install applicationinsights --save
   

   Notitie

   Als u TypeScript gebruikt, installeert u geen afzonderlijke 'typen'-pakketten. Dit NPM-pakket bevat ingebouwde typings.

3. Laad de bibliotheek expliciet in jouw code. Laad de bibliotheek zo vroeg mogelijk, zelfs vóór andere require-instructies, omdat de SDK instrumentatie in veel andere bibliotheken injecteert.

   let appInsights = require('applicationinsights');
   

4. U kunt ook een verbindingsreeks opgeven via de omgevingsvariabeleAPPLICATIONINSIGHTS_CONNECTION_STRING, in plaats van deze handmatig door te geven aan setup() ofnew appInsights.TelemetryClient(). Met deze procedure kunt u verbindingsreeksen uit vastgelegde broncode houden en kunt u verschillende verbindingsreeksen opgeven voor verschillende omgevingen. Als u handmatig wilt configureren, roept u het aan appInsights.setup('[your connection string]');.

   Zie de volgende secties voor meer configuratieopties.

   U kunt de SDK uitproberen zonder telemetrie te verzenden door appInsights.defaultClient.config.disableAppInsights = true in te stellen.

5. Begin automatisch met het verzamelen en verzenden van gegevens door aan te roepen appInsights.start();.

Uw app bewaken

De SDK verzamelt automatisch telemetrie over de Node.js runtime en enkele algemene modules van derden. Gebruik de toepassing om een aantal van deze gegevens te genereren.

Ga vervolgens in de Azure portal naar de Application Insights-resource die u eerder hebt gemaakt. Zoek in de Overzichtstijdlijn naar de eerste gegevenspunten. Selecteer verschillende onderdelen in de grafieken om meer gedetailleerde gegevens te zien.

Als u de topologie wilt bekijken die voor uw app is gedetecteerd, kunt u Toepassingsoverzicht gebruiken.

Geen gegevens

Omdat de SDK gegevens batcheert voor verzending, kan er een vertraging optreden voordat items in de portal worden weergegeven. Als u geen gegevens ziet in de resource, kunt u de volgende oplossingen proberen:

• Ga door met het gebruiken van de toepassing. Neem meer acties om meer telemetrie te genereren.
• Selecteer Vernieuwen in de portalresourceweergave. Grafieken worden periodiek ververst, maar handmatig vernieuwen zorgt ervoor dat ze onmiddellijk worden ververst.
• Controleer of de vereiste uitgaande poorten open zijn.
• Gebruik Zoeken om naar specifieke gebeurtenissen te zoeken.
• Raadpleeg de Veelgestelde vragen.

Basaal gebruik

Voor kant-en-klare verzameling van HTTP-aanvragen, gebeurtenissen van populaire bibliotheken van derden, onverwerkte uitzonderingen en systeemmetriek.

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

Laad de Application Insights-bibliotheek require("applicationinsights") zo vroeg mogelijk in uw scripts voordat u andere pakketten laadt. Deze stap is nodig, zodat de Application Insights-bibliotheek latere pakketten kan voorbereiden voor het bijhouden. Als er conflicten optreden met andere bibliotheken die een vergelijkbare voorbereiding uitvoeren, probeer dan de Application Insights-bibliotheek daarna te laden.

Vanwege de manier waarop JavaScript callbacks verwerkt, is er meer werk nodig om een aanvraag bij te houden voor externe afhankelijkheden en latere callbacks. Deze extra tracering is standaard ingeschakeld. Schakel dit uit door aan te roepen setAutoDependencyCorrelation(false) zoals beschreven in de sectie SDK-configuratie .

Migreren van versies vóór 0.22

Er zijn verstrekkende wijzigingen tussen releases van vóór versie 0.22 en daarna. Deze wijzigingen zijn ontworpen om consistentie te brengen met andere Application Insights SDK's en toekomstige uitbreidbaarheid mogelijk te maken.

Over het algemeen kunt u migreren met de volgende acties:

• Vervang verwijzingen naar appInsights.client door appInsights.defaultClient.
• Vervang verwijzingen naar appInsights.getClient() door new appInsights.TelemetryClient().
• Vervang alle argumenten door client.track*-methoden door één object met benoemde eigenschappen als argumenten. Zie de ingebouwde typehints van uw IDE of TelemetryTypes voor het behalve-object voor elk type telemetrie.

Als u toegang hebt tot SDK-configuratiefuncties zonder deze aan elkaar te appInsights.setup()koppelen, kunt u deze functies nu vinden op appInsights.Configurations. Een voorbeeld is appInsights.Configuration.setAutoCollectDependencies(true). Bekijk de wijzigingen in de standaardconfiguratie in de volgende sectie.

SDK-configuratie

Het appInsights object biedt veel configuratiemethoden. Ze worden weergegeven in het volgende codefragment met hun standaardwaarden.

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

Om gebeurtenissen in een service volledig te correleren, moet u .setAutoDependencyCorrelation(true) instellen. Als deze optie is ingesteld, kan met de SDK de context tussen asynchrone callbacks in Node.js worden getraceerd.

Bekijk de beschrijvingen in de ingebouwde type-hints van uw IDE of applicationinsights.ts voor gedetailleerde informatie en optionele bijkomende argumenten.

Gedistribueerde tracering

Moderne architecturen voor cloud- en microservices hebben eenvoudige, onafhankelijk implementeerbare services ingeschakeld die de kosten verlagen en tegelijkertijd de beschikbaarheid en doorvoer verhogen. Het heeft echter al het hele systeem moeilijker gemaakt om te redeneren over en fouten op te sporen. Gedistribueerde tracering lost dit probleem op door een prestatieprofiel te bieden dat werkt als aanroepstacks voor cloud- en microservicesarchitecturen.

Azure Monitor biedt twee ervaringen voor het gebruik van gedistribueerde traceringsgegevens: de weergave voor transactiediagnose voor één transactie/aanvraag en de toepassingsoverzichtsweergave om te laten zien hoe systemen communiceren.

Application Insights kan elk onderdeel afzonderlijk bewaken en detecteren welk onderdeel verantwoordelijk is voor fouten of prestatievermindering met behulp van gedistribueerde telemetriecorrelatie. In dit artikel wordt het gegevensmodel, technieken voor contextdoorgifte, protocollen en implementatie van correlatietactieken uitgelegd op verschillende talen en platforms die worden gebruikt door Application Insights.

Gedistribueerde tracering inschakelen via Application Insights door middel van autoinstrumentatie of SDK's

De Application Insights-agents en SDK's voor .NET, .NET Core, Java, Node.jsen JavaScript ondersteunen allemaal systeemeigen gedistribueerde tracering.

Wanneer de juiste Application Insights SDK is geïnstalleerd en geconfigureerd, worden traceringsgegevens automatisch verzameld voor populaire frameworks, bibliotheken en technologieën door autocollectors voor SDK-afhankelijkheden. De volledige lijst met ondersteunde technologieën is beschikbaar in de documentatie voor automatisch verzamelen van afhankelijkheden.

Elke technologie kan ook handmatig worden bijgehouden met een aanroep naar TrackDependency op de TelemetryClient.

Gegevensmodel voor telemetriecorrelatie

Application Insights definieert een gegevensmodel voor gedistribueerde telemetriecorrelatie. Als u telemetrie wilt koppelen aan een logische bewerking, heeft elk telemetrie-item een contextveld met de naam operation_Id. Elk telemetrie-item in de gedistribueerde tracering deelt deze id. Zelfs als u telemetrie van één laag kwijtraakt, kunt u nog steeds telemetrie koppelen die door andere onderdelen is gerapporteerd.

Een gedistribueerde logische bewerking bestaat doorgaans uit een set kleinere bewerkingen die worden verwerkt door een van de onderdelen. Telemetrie van aanvragen definieert deze bewerkingen. Elk aanvraagtelemetrie-item heeft een eigen id dat het wereldwijd en uniek identificeert. En alle telemetrie-items (zoals traceringen en uitzonderingen) die aan de aanvraag zijn gekoppeld, moeten worden ingesteld op de operation_parentId, naar de waarde van de aanvraag id.

Afhankelijkheidstelemetrie vertegenwoordigt elke uitgaande bewerking, zoals een HTTP-aanroep naar een ander onderdeel. Het definieert ook een eigen id dat wereldwijd uniek is. Telemetrieverzoek, geïnitieerd door deze afhankelijkheidsaanroep, gebruikt dit id als zijn operation_parentId.

U kunt een weergave van de gedistribueerde logische bewerking maken met behulp operation_Idvan , operation_parentIden request.id met dependency.id. Deze velden definiëren ook de causaliteitsvolgorde van telemetriegesprekken.

In een microservicesomgeving kunnen traceringen van onderdelen naar verschillende opslagitems gaan. Elk onderdeel kan een eigen verbindingsreeks hebben in Application Insights. Application Insights vraagt gegevens op uit elk opslagitem om telemetrie voor de logische bewerking op te halen.

Wanneer het aantal opslagitems groot is, hebt u een hint nodig over waar u hierna moet zoeken. Het Application Insights-gegevensmodel definieert twee velden om dit probleem op te lossen: request.source en dependency.target. Het eerste veld identificeert het onderdeel dat de afhankelijkheidsaanvraag heeft gestart. Het tweede veld identificeert welk onderdeel het antwoord van de afhankelijkheidsaanroep heeft geretourneerd.

Zie Querygegevens in Log Analytics-werkruimten, toepassingen en resources in Azure Monitor voor meer informatie over het uitvoeren van query's vanuit meerdere verschillende instanties.

Example

Laten we eens kijken naar een voorbeeld. In een toepassing met de naam Aandelenprijzen wordt de huidige marktkoers van een aandelen weergegeven met behulp van een externe API met de naam Aandelen. De toepassing Aandelenprijzen heeft een pagina met de naam Stock-pagina die de webbrowser van de client opent met behulp van GET /Home/Stock. De toepassing voert een query uit op de Stock-API met behulp van de HTTP-aanroep GET /api/stock/value.

U kunt de resulterende telemetrie analyseren door een query uit te voeren:

(requests | union dependencies | union pageViews)
| where operation_Id == "STYz"
| project timestamp, itemType, name, id, operation_ParentId, operation_Id

In de resultaten delen alle telemetrie-items de root operation_Id. Wanneer een Ajax-aanroep vanaf de pagina wordt gedaan, wordt er een nieuwe unieke id (qJSXU) toegewezen aan de telemetrie van de afhankelijkheid en wordt de id van de pageView gebruikt als operation_ParentId. De serveraanvraag gebruikt vervolgens de Ajax-id als operation_ParentId.

Wanneer de aanroep GET /api/stock/value naar een externe service wordt uitgevoerd, moet u de identiteit van die server weten, zodat u het veld op de dependency.target juiste manier kunt instellen. Wanneer de externe service geen ondersteuning biedt voor bewaking, target wordt deze ingesteld op de hostnaam van de service. Een voorbeeld is stock-prices-api.com. Maar als de service zichzelf identificeert door een vooraf gedefinieerde HTTP-header te retourneren, target bevat deze de service-identiteit waarmee Application Insights een gedistribueerde tracering kan maken door een query uit te voeren op telemetrie van die service.

Correlatieheaders met W3C TraceContext

Application Insights gaat over naar W3C Trace-Context, waarmee het volgende wordt gedefinieerd:

• traceparent: draagt de globaal unieke bewerkings-id en unieke id van de aanroep.
• tracestate: Draagt systeemspecifieke traceringscontext.

De nieuwste versie van de Application Insights SDK ondersteunt het Trace-Context-protocol, maar mogelijk moet u zich hiervoor aanmelden. (Achterwaartse compatibiliteit met het vorige correlatieprotocol van de Application Insights SDK wordt gehandhaafd.)

Het HTTP-correlatieprotocol, ook wel Request-Id genoemd, wordt afgeschaft. Dit protocol definieert twee headers:

• Request-Id: Draagt de Wereldwijd Unieke ID van de oproep.
• Correlation-Context: bevat de verzameling naam-waardeparen van de gedistribueerde traceringseigenschappen.

Application Insights definieert ook de extensie voor het HTTP-correlatieprotocol. Het maakt gebruik Request-Context van naam-waardeparen om de verzameling eigenschappen door te geven die door de directe beller of aanroeper worden gebruikt. De Application Insights SDK gebruikt deze header om de dependency.target velden en request.source velden in te stellen.

De W3C Trace-Context en Application Insights-gegevensmodellen worden op de volgende manier gemapt:

Zie het Application Insights-telemetriegegevensmodel voor meer informatie.

Steekproeven

Standaard verzendt de SDK alle verzamelde gegevens naar de Application Insights-service. Als u steekproeven wilt inschakelen om de hoeveelheid gegevens te verminderen, stelt u het samplingPercentage veld in op het config object van een client. Als samplingPercentage u op 100 (de standaardinstelling) instelt, worden alle gegevens verzonden en 0 betekent dat er niets wordt verzonden.

Als u automatische correlatie gebruikt, worden alle gegevens die aan één aanvraag zijn gekoppeld, opgenomen of uitgesloten als eenheid.

Voeg code toe, zoals het volgende om steekproeven in te schakelen:

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

Meerdere rollen voor toepassingen met meerdere onderdelen

In sommige scenario's bestaat uw toepassing mogelijk uit meerdere onderdelen die u allemaal wilt instrumenteren met dezelfde verbindingsreeks. U wilt deze onderdelen nog steeds zien als afzonderlijke eenheden in de portal, alsof ze afzonderlijke verbindingsreeks s gebruikten. Een voorbeeld is afzonderlijke knooppunten op toepassingsoverzicht. U moet het veld handmatig configureren om de telemetrie van het RoleName ene onderdeel te onderscheiden van andere onderdelen die gegevens naar uw Application Insights-resource verzenden.

Gebruik de volgende code om het RoleName veld in te stellen:

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

Browser-SDK-laadprogramma

Automatische webinstrumentatie kan worden ingeschakeld voor de Node-server via het injecteren van een JavaScript (Web) SDK Loader Script door middel van configuratie.

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

of door omgevingsvariabele APPLICATIONINSIGHTS_WEB_INSTRUMENTATION_ENABLED = truein te stellen.

Web Instrumentation is ingeschakeld op knooppuntserverreacties wanneer aan alle volgende vereisten wordt voldaan:

• Antwoord heeft statuscode 200.
• Antwoordmethode is GET.
• De serverreactie bevat Content-Type HTML.
• Serverantwoord bevat zowel <head> als </head> Tags.
• Als het antwoord is gecomprimeerd, moet het slechts één Content-Encoding type hebben en moet het coderingstype een van gzip, br of deflate.
• Antwoord bevat geen huidige CDN-eindpunten van /backup web Instrumentation. (huidige en back-up van WEB Instrumentation CDN-eindpunten hier)

Web Instrumentation CDN-eindpunt kan worden gewijzigd door omgevingsvariabele APPLICATIONINSIGHTS_WEB_INSTRUMENTATION_SOURCE = "web Instrumentation CDN endpoints"in te stellen. Web Instrumentation-verbindingsreeks kan worden gewijzigd door omgevingsvariabele in te stellen APPLICATIONINSIGHTS_WEB_INSTRUMENTATION_CONNECTION_STRING = "web Instrumentation connection string"

Automatische instrumentatie van derden

Als u context wilt bijhouden voor asynchrone aanroepen, zijn sommige wijzigingen vereist in bibliotheken van derden, zoals MongoDB en Redis. Application Insights gebruikt standaard diagnostic-channel-publishers om een aantal van deze bibliotheken te monkey-patchen. Deze functie kan worden uitgeschakeld door de APPLICATION_INSIGHTS_NO_DIAGNOSTIC_CHANNEL omgevingsvariabele in te stellen.

Afzonderlijke apenpatches kunnen worden uitgeschakeld door de APPLICATION_INSIGHTS_NO_PATCH_MODULES omgevingsvariabele in te stellen op een door komma's gescheiden lijst met pakketten die moeten worden uitgeschakeld. Gebruik bijvoorbeeld APPLICATION_INSIGHTS_NO_PATCH_MODULES=console,redis om het patchen van de console en redis pakketten te vermijden.

Op dit moment zijn er negen pakketten geïnstrumenteerd: bunyan, console, mongodb, mongodb-core, mysql, redis, winston, pg en pg-pool. Zie het README-bestand van de diagnostische kanaal-publiceerders voor informatie over welke versie van deze pakketten precies wordt gepatcht.

De patches bunyan, winston, en console genereren trace-evenementen voor Application Insights, afhankelijk van of setAutoCollectConsole is ingeschakeld. De rest genereert Application Insights-afhankelijkheidsevenementen op basis van of setAutoCollectDependencies deze is ingeschakeld.

Live statistieken

Als u het verzenden van live metrische gegevens vanuit uw app naar Azure wilt inschakelen, gebruikt u setSendLiveMetrics(true). Op dit moment wordt het filteren van live metrische gegevens in de portal niet ondersteund.

Uitgebreide metrische gegevens

Installeer het afzonderlijke systeemeigen metrische gegevenspakket om uitgebreide systeemeigen metrische gegevens van uw app naar Azure te verzenden. De SDK wordt automatisch geladen wanneer deze is geïnstalleerd en begint met het verzamelen van Node.js systeemeigen metrische gegevens.

npm install applicationinsights-native-metrics

Momenteel voert het native metrics-pakket de automatische verzameling uit van CPU-tijd voor garbage collection, event loop ticks en heap-gebruik.

• Garbage collection: de hoeveelheid CPU-tijd die is besteed aan elk type garbage collection en het aantal voorkomingen van elk type.
• Gebeurtenislus: hoeveel tikken er zijn opgetreden en hoeveel CPU-tijd er in totaal is besteed.
• Heap versus non-heap: hoeveel van het geheugengebruik van uw app bevindt zich in de heap of buiten de heap.

Gedistribueerde traceringsmodi

De SDK verzendt standaard headers die worden begrepen door andere toepassingen of services die zijn geïnstrueerd met een Application Insights SDK. U kunt het verzenden en ontvangen van W3C Trace Context-headers inschakelen naast de bestaande AI-headers. Op deze manier breekt u de correlatie met een van uw bestaande verouderde services niet. Als u W3C-headers inschakelt, kan uw app correleren met andere services die niet zijn geïnstrueerd met Application Insights, maar die wel gebruikmaken van deze W3C-standaard.

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

TelemetryClient-API

Zie Application Insights-API voor aangepaste gebeurtenissen en metrische gegevens voor een volledige beschrijving van de TelemetryClient-API.

U kunt elke aanvraag, gebeurtenis, metrische gegevens of uitzondering bijhouden met behulp van de Application Insights-clientbibliotheek voor Node.js. Het volgende codevoorbeeld toont enkele API's die u kunt gebruiken:

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

Afhankelijkheden bijhouden

Gebruik de volgende code om de afhankelijkheden bij te houden:

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

Een voorbeeldhulpprogramma dat trackMetric gebruikt om te meten hoe lang het duurt om een gebeurtenislus in te plannen.

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

Een aangepaste eigenschap toevoegen aan alle gebeurtenissen

Gebruik de volgende code om een aangepaste eigenschap toe te voegen aan alle gebeurtenissen:

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

HTTP GET-aanvragen traceren

Gebruik de volgende code om HTTP GET-aanvragen handmatig bij te houden:

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

U kunt aanvragen ook bijhouden met behulp van de trackNodeHttpRequest methode:

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

Serveropstarttijd traceren

Gebruik de volgende code om serveropstarttijd bij te houden:

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

Spoelen

Telemetrie wordt standaard gedurende 15 seconden gebufferd voordat deze naar de opnameserver wordt verzonden. Als uw toepassing een korte levensduur heeft, zoals een CLI-hulpprogramma, kan het nodig zijn om uw gebufferde telemetrie handmatig leeg te maken wanneer de toepassing wordt beëindigd met behulp van appInsights.defaultClient.flush().

Als de SDK detecteert dat uw toepassing crasht, voert het voor u een flush uit met behulp van appInsights.defaultClient.flush({ isAppCrashing: true }). Met de optie isAppCrashing"flush" wordt aangenomen dat uw applicatie zich in een abnormale toestand bevindt en daarom ongeschikt is om telemetrie te verzenden. In plaats daarvan slaat de SDK alle gebufferde telemetrie op in permanente opslag en kan uw toepassing worden beëindigd. Wanneer uw toepassing opnieuw wordt gestart, wordt geprobeerd om telemetriegegevens te verzenden die zijn opgeslagen in permanente opslag.

Telemetrie filteren en vooraf verwerken

U kunt code schrijven om uw telemetrie te filteren, te wijzigen of te verrijken voordat deze wordt verzonden vanuit de SDK. De verwerking omvat gegevens die worden verzonden vanuit de standaardtelemetriemodules, zoals het verzamelen van HTTP-aanvragen en het verzamelen van afhankelijkheden.

• Filteren kan telemetrie wijzigen of verwijderen voordat deze wordt verzonden vanuit de SDK door deze te implementeren ITelemetryProcessor. U kunt bijvoorbeeld het volume van telemetrie verminderen door aanvragen van robots uit te sluiten. In tegenstelling tot steekproeven hebt u volledige controle over wat er wordt verzonden of verwijderd, maar dit is van invloed op metrische gegevens op basis van geaggregeerde logboeken. Afhankelijk van hoe u items negeert, verliest u mogelijk ook de mogelijkheid om tussen gerelateerde items te navigeren.

• Voeg eigenschappen toe aan of wijzig deze voor alle telemetrie die vanuit uw app wordt verzonden door een ITelemetryInitializer. U kunt bijvoorbeeld berekende waarden of versienummers toevoegen waarmee de gegevens in de portal moeten worden gefilterd.

• Steekproeven verminderen het volume van telemetrie zonder dat dit van invloed is op uw statistieken. Hiermee worden gerelateerde gegevenspunten bijeengehouden, zodat u ertussen kunt navigeren wanneer u een probleem diagnosticeren. In de portal worden de totale aantallen vermenigvuldigd om de steekproef te compenseren.

Filtering

Deze techniek geeft u directe controle over wat er is opgenomen of uitgesloten van de telemetriestroom. Filteren kan worden gebruikt om te voorkomen dat telemetrie-items naar Application Insights verzonden worden. U kunt filteren met steekproeven of afzonderlijk gebruiken.

Als u telemetrie wilt filteren, schrijft u een telemetrieprocessor en registreert u deze bij TelemetryConfiguration. Alle telemetrie gaat via uw processor. U kunt ervoor kiezen om deze uit de stream te verwijderen of deze aan de volgende processor in de keten te geven. Telemetrie van de standaardmodules, zoals de HTTP-aanvraagverzamelaar en de afhankelijkheidsverzamelaar, en telemetrie die u zelf hebt bijgehouden, wordt opgenomen. U kunt bijvoorbeeld telemetrie filteren over aanvragen van robots of geslaagde afhankelijkheidsaanroepen.

ITelemetryProcessor en ITelemetryInitializer

Wat is het verschil tussen telemetrieprocessors en initialisatiefuncties voor telemetrie?

• Er zijn enkele overlappingen in wat u ermee kunt doen. Beide kunnen worden gebruikt om eigenschappen van telemetrie toe te voegen of te wijzigen, hoewel we u aanraden initialisatiefuncties voor dat doel te gebruiken.
• Telemetrie-initialisatiefuncties worden altijd uitgevoerd vóór telemetrieprocessors.
• Telemetrie-initialisatiefuncties kunnen meerdere keren worden aangeroepen. Standaard stellen ze geen eigenschap in die al is ingesteld.
• Met telemetrieprocessors kunt u een telemetrie-item volledig vervangen of verwijderen.
• Alle geregistreerde telemetrie-initialisatiefuncties worden aangeroepen voor elk telemetrie-item. Voor telemetrieprocessors garandeert SDK dat de eerste telemetrieprocessor wordt aangeroepen. Of de rest van de processors worden aangeroepen of niet, wordt beslist door de voorgaande telemetrieprocessors.
• Gebruik telemetrie-initialisatiefuncties om telemetrie te verrijken met meer eigenschappen of om een bestaande te overschrijven. Gebruik een telemetrieprocessor om telemetrie uit te filteren.

Eigenschappen toevoegen/wijzigen

Gebruik telemetrie-initialisatiefuncties om telemetrie te verrijken met aanvullende informatie of om telemetrie-eigenschappen te overschrijven die zijn ingesteld door de standaardtelemetriemodules.

Application Insights voor een webpakket verzamelt bijvoorbeeld telemetrie over HTTP-aanvragen. Standaard wordt elke aanvraag met een antwoordcode >=400 als mislukt gevlagd. Als u in plaats daarvan 400 als een succes wilt behandelen, kunt u een initialisatiefunctie voor telemetrie opgeven waarmee de eigenschap succes wordt ingesteld.

Als u een initialisatiefunctie voor telemetrie opgeeft, wordt deze aangeroepen wanneer een van de methoden Track*() wordt aangeroepen. Deze initialisatiefunctie bevat Track() methoden die worden aangeroepen door de standaardtelemetriemodules. Deze modules stellen standaard geen eigenschappen in die al door een initialisatiefunctie zijn ingesteld. Initialisatiefuncties voor telemetrie worden aangeroepen voordat telemetrieprocessors worden aangeroepen, dus alle verrijkingen die door initialisatiefuncties worden uitgevoerd, zijn zichtbaar voor processors.

De gegevens vooraf verwerken met telemetrieprocessors

U kunt verzamelde gegevens verwerken en filteren voordat deze worden verzonden voor retentie met behulp van telemetrieprocessors. Telemetrieprocessors worden één voor één genoemd in de volgorde waarin ze zijn toegevoegd voordat het telemetrie-item naar de cloud wordt verzonden.

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

Als een telemetrieprocessor retourneert false, wordt dat telemetrie-item niet verzonden.

Alle telemetrieprocessors ontvangen de telemetriegegevens en de envelop om deze te inspecteren en aan te passen. Ze ontvangen ook een contextobject. De inhoud van dit object wordt gedefinieerd door de contextObjects parameter bij het aanroepen van een trackmethode voor handmatig bijgehouden telemetrie. Voor automatisch verzamelde telemetrie wordt dit object gevuld met beschikbare aanvraaggegevens en de inhoud van de permanente aanvraag zoals opgegeven appInsights.getCorrelationContext() (als automatische afhankelijkheidscorrelatie is ingeschakeld).

Het TypeScript voor een telemetrieprocessor is:

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

Een processor die stapeltraceringsgegevens uit uitzonderingen verwijdert, kan bijvoorbeeld als volgt worden geschreven en toegevoegd:

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

Een cloudrolnaam en cloudrolinstantie toevoegen

Stel de naam van de cloudrol in via directe contexttags:

var appInsights = require("applicationinsights");
appInsights.setup('INSTRUMENTATION_KEY').start();
appInsights.defaultClient.context.tags["ai.cloud.role"] = "your role name";
appInsights.defaultClient.context.tags["ai.cloud.roleInstance"] = "your role instance";

Stel de naam van de cloudrol in via telemetrieprocessor:

var appInsights = require("applicationinsights");
appInsights.setup('INSTRUMENTATION_KEY').start();

appInsights.defaultClient.addTelemetryProcessor(envelope => {
    envelope.tags["ai.cloud.role"] = "your role name";
    envelope.tags["ai.cloud.roleInstance"] = "your role instance"
});

Meerdere verbindingsreeks s gebruiken

U kunt meerdere Application Insights-resources maken en verschillende gegevens naar elke resource verzenden met behulp van hun respectieve verbindingsreeksen.

Voorbeeld:

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

Geavanceerde configuratieopties

Het clientobject bevat een config eigenschap met veel optionele instellingen voor geavanceerde scenario's. Als u deze wilt instellen, gebruikt u:

client.config.PROPERTYNAME = VALUE;

Deze eigenschappen zijn clientspecifiek, zodat u afzonderlijk kunt configureren appInsights.defaultClient van clients die zijn gemaakt met new appInsights.TelemetryClient().

Kern-API voor aangepaste gebeurtenissen en metrische gegevens

Voeg een paar regels code in uw toepassing in om erachter te komen wat gebruikers ermee doen of om problemen vast te stellen. U kunt telemetrie verzenden vanuit apparaat- en bureaublad-apps, webclients en webservers. Gebruik de Application Insights-kerntelemetrie-API om aangepaste gebeurtenissen en metrische gegevens en uw eigen versies van standaardtelemetrie te verzenden. Deze API is dezelfde API die door de standaard Application Insights-gegevensverzamelaars wordt gebruikt.

API-samenvatting

De kern-API is uniform op alle platforms, afgezien van enkele variaties zoals GetMetric (alleen.NET).

U kunt eigenschappen en metrische gegevens koppelen aan de meeste van deze telemetriegesprekken.

Vereisten

Als u nog geen verwijzing naar de Application Insights SDK heeft:

1. Voeg de Application Insights SDK toe aan uw project.

2. Neem in de code van uw apparaat of webserver het volgende op:

   • .NET
   • Node.js

   using Microsoft.ApplicationInsights;
   

Een TelemetryClient-exemplaar ophalen

Haal een exemplaar op van TelemetryClient:

private TelemetryClient telemetry = new TelemetryClient();

TelemetryClient.Context.User.Id = "...";
TelemetryClient.Context.Device.Id = "...";

var telemetry = applicationInsights.defaultClient;

TrackEvent

In Application Insights is een aangepaste gebeurtenis een gegevenspunt dat u in Metrics Explorer kunt weergeven als een geaggregeerd aantal en in Diagnostische zoekopdrachten als afzonderlijke exemplaren. (Het is niet gerelateerd aan MVC of andere framework -gebeurtenissen.)

Voeg TrackEvent aanroepen in uw code in om verschillende gebeurtenissen te tellen. U kunt bijvoorbeeld bijhouden hoe vaak gebruikers een bepaalde functie kiezen. Of misschien wilt u weten hoe vaak ze bepaalde doelen bereiken of specifieke soorten fouten maken.

Verzend bijvoorbeeld in een game-app een gebeurtenis wanneer een gebruiker het spel wint:

telemetry.TrackEvent("WinGame");

telemetry.trackEvent({name: "WinGame"});

Aangepaste gebeurtenissen in Log Analytics

De telemetrie is beschikbaar in de customEvents tabel op het tabblad Application Insights-logboeken of de gebruikservaring. Gebeurtenissen kunnen afkomstig zijn van trackEvent(..) of de invoegtoepassing Click Analytics AutoCollection.

Als steekproeven worden uitgevoerd, wordt in de itemCount eigenschap een waarde weergegeven die groter is dan 1. Betekent bijvoorbeeld itemCount==10 dat van 10 aanroepen naar trackEvent(), het steekproefproces slechts één van hen heeft verzonden. Als u een correct aantal aangepaste gebeurtenissen wilt ophalen, gebruikt u code zoals customEvents | summarize sum(itemCount).

GetMetric

Zie GetMetric() voor meer informatie over het effectief gebruik van de aanroep om lokaal geaggregeerde metrische gegevens vast te leggen voor .NET- en .NET Core-toepassingen.

TrackMetric

Application Insights kan metrische gegevens weergeven die niet zijn gekoppeld aan bepaalde gebeurtenissen. U kunt bijvoorbeeld een wachtrijlengte met regelmatige tussenpozen bewaken. Met metrische gegevens zijn de afzonderlijke metingen minder interessant dan de variaties en trends, en dus zijn statistische grafieken nuttig.

Als u metrische gegevens naar Application Insights wilt verzenden, kunt u de TrackMetric(..) API gebruiken. Er zijn twee manieren om een metrische waarde te verzenden:

• Eén waarde. Telkens wanneer u een meting uitvoert in uw toepassing, verzendt u de bijbehorende waarde naar Application Insights.

  Stel dat u een metrische waarde hebt die het aantal items in een container beschrijft. Tijdens een bepaalde periode plaatst u eerst drie items in de container en vervolgens verwijdert u twee items. Daarom zou u TrackMetric twee keer aanroepen. Eerst geeft u de waarde 3 door en geeft u vervolgens de waarde -2door. In Application Insights worden beide waarden voor u opgeslagen.

• Aggregatie. Wanneer u met metingen werkt, is elke afzonderlijke meting zelden interessant. In plaats daarvan is een samenvatting van wat er is gebeurd tijdens een bepaalde periode belangrijk. Een dergelijke samenvatting wordt aggregatie genoemd.

  In het voorgaande voorbeeld is 1 de geaggregeerde metrische som voor die periode en het aantal metrische waarden 2. Wanneer u de aggregatiebenadering gebruikt, roept TrackMetric u slechts één keer per periode aan en verzendt u de geaggregeerde waarden. We raden deze aanpak aan omdat deze de kosten en prestatieoverhead aanzienlijk kan verminderen door minder gegevenspunten naar Application Insights te verzenden, terwijl alle relevante informatie nog steeds wordt verzameld.

Voorbeelden van één waarde

Eén metrische waarde verzenden:

var sample = new MetricTelemetry();
sample.Name = "queueLength";
sample.Sum = 42.3;
telemetryClient.TrackMetric(sample);

telemetry.trackMetric({name: "queueLength", value: 42.0});

Aangepaste metrische gegevens in Log Analytics

De telemetrie is beschikbaar in de customMetrics tabel in Application Insights Analytics. Elke rij vertegenwoordigt een aanroep naar trackMetric(..) in uw app.

• valueSum: De som van de metingen. Als u de gemiddelde waarde wilt ophalen, deelt u door valueCount.
• valueCount: Het aantal metingen dat in deze trackMetric(..) aanroep is samengevoegd.

Paginaweergaven

In een apparaat- of webapp wordt paginaweergavetelemetrie standaard verzonden wanneer elk scherm of elke pagina wordt geladen. Maar u kunt de standaardinstelling wijzigen om paginaweergaven op meer of verschillende tijdstippen bij te houden. In een app met tabbladen of deelvensters kunt u bijvoorbeeld een pagina bijhouden wanneer de gebruiker een nieuw deelvenster opent.

Gebruikers- en sessiegegevens worden verzonden als eigenschappen, samen met paginaweergaven, zodat de gebruikers- en sessiegrafieken tot leven komen wanneer er telemetriegegevens over de paginaweergave zijn.

Aangepaste paginaweergaven

telemetry.TrackPageView("GameReviewPage");

Pagina-telemetrie in Log Analytics

In Log Analytics worden in twee tabellen gegevens uit browserbewerkingen weergegeven:

• pageViews: bevat gegevens over de URL en paginatitel.
• browserTimings: bevat gegevens over clientprestaties, zoals de tijd die nodig is om de binnenkomende gegevens te verwerken.

Ga als volgt te werk om te zien hoe lang het duurt voordat de browser verschillende pagina's verwerkt:

browserTimings
| summarize avg(networkDuration), avg(processingDuration), avg(totalDuration) by name

De populariteit van verschillende browsers ontdekken:

pageViews
| summarize count() by client_Browser

Als u paginaweergaven wilt koppelen aan AJAX-aanroepen, koppel met afhankelijkheden.

pageViews
| join (dependencies) on operation_Id

TrackRequest

De server-SDK gebruikt TrackRequest om HTTP-aanvragen te registreren.

U kunt deze ook zelf aanroepen als u aanvragen wilt simuleren in een context waarin de webservicemodule niet wordt uitgevoerd.

De aanbevolen manier om aanvraagtelemetrie te verzenden, is waar de aanvraag fungeert als een bewerkingscontext.

Bewerkingscontext

U kunt telemetrie-items aan elkaar correleren door ze te koppelen aan de bewerkingscontext. De standaardmodule voor het bijhouden van aanvragen doet dit voor uitzonderingen en andere gebeurtenissen die worden verzonden terwijl een HTTP-aanvraag wordt verwerkt. In Search and Analytics kunt u eenvoudig gebeurtenissen vinden die zijn gekoppeld aan de aanvraag met behulp van de bewerkings-id.

Wanneer u telemetrie handmatig bijhoudt, is de eenvoudigste manier om ervoor te zorgen dat telemetriecorrelatie dit patroon gebruikt:

// Establish an operation context and associated telemetry item:
using (var operation = telemetryClient.StartOperation<RequestTelemetry>("operationName"))
{
    // Telemetry sent in here uses the same operation ID.
    ...
    telemetryClient.TrackTrace(...); // or other Track* calls
    ...

    // Set properties of containing telemetry item--for example:
    operation.Telemetry.ResponseCode = "200";

    // Optional: explicitly send telemetry item:
    telemetryClient.StopOperation(operation);

} // When operation is disposed, telemetry item is sent.

// Establish an operation context and associated telemetry item:
const operation = appInsights.startOperation(client, { name: "operationName" });

appInsights.wrapWithCorrelationContext(() => {
    // Telemetry sent in here uses the same operation ID.
    ...
    client.trackTrace({ message: "..." }); // or other track* calls
    ...

    // Set properties of containing telemetry item—for example:
    operation.telemetry.responseCode = "200";

    // Optional: explicitly send telemetry item:
    client.stopOperation(operation);

}, operation.context)(); // When callback completes, telemetry item is sent.

Naast het instellen van een bewerkingscontext, StartOperation maakt u een telemetrie-item van het type dat u opgeeft. Het telemetrie-item wordt verzonden wanneer u de bewerking hebt verwijderd of als u expliciet aanroept StopOperation. Als u als telemetrietype gebruikt RequestTelemetry , wordt de duur ervan ingesteld op het tijdsinterval tussen het begin en einde.

Telemetrie-items die binnen een bewerkingsbereik worden gerapporteerd, worden ondergeschikte componenten van een dergelijke bewerking. Bewerkingscontexten kunnen worden genest.

In Search wordt de bewerkingscontext gebruikt om de lijst Gerelateerde items te maken.

Zie Aangepaste bewerkingen bijhouden met Application Insights .NET SDK voor meer informatie over het bijhouden van aangepaste bewerkingen.

Aanvragen in Log Analytics

In Application Insights Analytics worden aanvragen weergegeven in de requests tabel.

Als steekproeven worden uitgevoerd, wordt in de itemCount eigenschap een waarde weergegeven die groter is dan 1. Betekent bijvoorbeeld itemCount==10 dat van 10 aanroepen naar trackRequest(), het steekproefproces slechts één van hen heeft verzonden. Als u een correct aantal aanvragen en de gemiddelde duur wilt ophalen die is gesegmenteerd op aanvraagnamen, gebruikt u code zoals:

requests
| summarize count = sum(itemCount), avgduration = avg(duration) by name

TrackException

Uitzonderingen verzenden naar Application Insights:

• Om ze te tellen als indicatie van de frequentie van een probleem.
• Afzonderlijke exemplaren onderzoeken.

De rapporten bevatten de stacktraceringen.

try
{
    ...
}
catch (Exception ex)
{
    telemetry.TrackException(ex);
}

try
{
    ...
}
catch (ex)
{
    telemetry.trackException({exception: ex});
}

De SDK's vangen automatisch veel uitzonderingen op, dus u hoeft niet altijd expliciet aan te roepen TrackException .

Uitzonderingen in Log Analytics

In Application Insights Analytics worden uitzonderingen weergegeven in de exceptions tabel.

Als steekproeven worden uitgevoerd, wordt in de itemCount eigenschap een waarde weergegeven die groter is dan 1. Betekent bijvoorbeeld itemCount==10 dat van 10 aanroepen naar trackException(), het steekproefproces slechts één van hen heeft verzonden. Als u een correct aantal uitzonderingen wilt ophalen dat is gesegmenteerd op type uitzondering, gebruikt u code zoals:

exceptions
| summarize sum(itemCount) by type

De meeste belangrijke stackgegevens worden al geëxtraheerd in afzonderlijke variabelen, maar u kunt de details structuur uit elkaar trekken om meer te krijgen. Omdat deze structuur dynamisch is, moet u het resultaat casten naar het type dat u verwacht. Voorbeeld:

exceptions
| extend method2 = tostring(details[0].parsedStack[1].method)

Als u uitzonderingen aan hun gerelateerde aanvragen wilt koppelen, gebruikt u een join:

exceptions
| join (requests) on operation_Id

TrackTrace

Gebruik TrackTrace dit om problemen te diagnosticeren door een 'breadcrumb trail' naar Application Insights te verzenden. U kunt segmenten met diagnostische gegevens verzenden en inspecteren in Diagnostisch zoeken.

telemetry.TrackTrace(message, SeverityLevel.Warning, properties);

telemetry.trackTrace({
    message: message,
    severity: applicationInsights.Contracts.SeverityLevel.Warning,
    properties: properties
});

Een diagnostische gebeurtenis registreren, zoals het invoeren of verlaten van een methode.

U kunt zoeken op berichtinhoud, maar in tegenstelling tot eigenschapswaarden kunt u er niet op filteren.

De limiet voor de grootte message is veel hoger dan de limiet voor eigenschappen. Een voordeel hiervan TrackTrace is dat u relatief lange gegevens in het bericht kunt plaatsen. U kunt bijvoorbeeld POST-gegevens daar coderen.

U kunt ook een ernstniveau toevoegen aan uw bericht. En net als andere telemetrie kunt u eigenschapswaarden toevoegen om u te helpen bij het filteren of zoeken naar verschillende sets traceringen. Voorbeeld:

var telemetry = new Microsoft.ApplicationInsights.TelemetryClient();
telemetry.TrackTrace("Slow database response",
                SeverityLevel.Warning,
                new Dictionary<string,string> { {"database", db.ID} });

In Zoeken kunt u vervolgens eenvoudig alle berichten van een bepaald ernstniveau filteren die betrekking hebben op een bepaalde database.

Traceringen in Log Analytics

In Application Insights Analytics worden aanroepen weergegeven TrackTrace in de traces tabel.

Als steekproeven worden uitgevoerd, wordt in de itemCount eigenschap een waarde weergegeven die groter is dan 1. Betekent bijvoorbeeld itemCount==10 dat van 10 aanroepen naar trackTrace(), het steekproefproces slechts één van hen heeft verzonden. Als u een correct aantal traceringsoproepen wilt ophalen, gebruikt u code zoals traces | summarize sum(itemCount).

TrackDependency

Gebruik de TrackDependency aanroep om de reactietijden en slagingspercentages van aanroepen naar een extern codefragment bij te houden. De resultaten worden weergegeven in de afhankelijkheidsdiagrammen in de portal. Het volgende codefragment moet worden toegevoegd waar een afhankelijkheidsaanroep wordt gedaan.

var success = false;
var startTime = DateTime.UtcNow;
var timer = System.Diagnostics.Stopwatch.StartNew();
try
{
    success = dependency.Call();
}
catch(Exception ex)
{
    success = false;
    telemetry.TrackException(ex);
    throw new Exception("Operation went wrong", ex);
}
finally
{
    timer.Stop();
    telemetry.TrackDependency("DependencyType", "myDependency", "myCall", startTime, timer.Elapsed, success);
}

var success = false;
var startTime = new Date().getTime();
try
{
    success = dependency.Call();
}
finally
{
    var elapsed = new Date() - startTime;
    telemetry.trackDependency({
        dependencyTypeName: "myDependency",
        name: "myCall",
        duration: elapsed,
        success: success
    });
}

Houd er rekening mee dat de server-SDK's een afhankelijkheidsmodule bevatten waarmee bepaalde afhankelijkheidsaanroepen automatisch worden gedetecteerd en bijgehouden, bijvoorbeeld naar databases en REST API's. U moet een agent op uw server installeren om de module te laten werken.

U gebruikt deze aanroep als u oproepen wilt bijhouden die niet door de automatische tracering worden geregistreerd.

Als u de standaardmodule voor het bijhouden van afhankelijkheden in C# wilt uitschakelen, bewerkt uApplicationInsights.config en verwijdert u de verwijzing naar DependencyCollector.DependencyTrackingTelemetryModule.

Afhankelijkheden in Log Analytics

In Application Insights AnalyticstrackDependency worden aanroepen weergegeven in de dependencies tabel.

Als er steekproeven worden genomen , wordt in de itemCount eigenschap een waarde weergegeven die groter is dan 1. Betekent bijvoorbeeld itemCount==10 dat van 10 aanroepen naar trackDependency(), het steekproefproces slechts één van hen heeft verzonden. Als u een correct aantal afhankelijkheden wilt ophalen dat per doelonderdeel is gesegmenteerd, gebruikt u code zoals:

dependencies
| summarize sum(itemCount) by target

Als je afhankelijkheden aan hun gerelateerde aanvragen wilt koppelen, gebruik je een join.

dependencies
| join (requests) on operation_Id

Gegevens leegmaken

Normaal gesproken verzendt de SDK gegevens met vaste intervallen, meestal 30 seconden of wanneer de buffer vol is, wat meestal 500 items is. In sommige gevallen wilt u de buffer mogelijk leegmaken. Een voorbeeld is als u de SDK gebruikt in een toepassing die wordt afgesloten.

telemetry.Flush();
// Allow some time for flushing before shutdown.
System.Threading.Thread.Sleep(5000);

await telemetryClient.FlushAsync()
// No need to sleep

telemetry.flush();

Geverifieerde gebruikers

In een web-app worden gebruikers standaard geïdentificeerd door cookies . Een gebruiker kan meerdere keren worden geteld als hij of zij toegang heeft tot uw app vanaf een andere computer of browser of als ze cookies verwijderen.

Als gebruikers zich aanmelden bij uw app, kunt u een nauwkeuriger aantal krijgen door de geverifieerde gebruikers-id in de browsercode in te stellen. Het is niet nodig om de werkelijke aanmeldingsnaam van de gebruiker te gebruiken. Het hoeft alleen een id te zijn die uniek is voor die gebruiker. Het mag geen spaties of een van de tekens ,;=|bevatten.

De gebruikers-id wordt ook ingesteld in een sessiecooky en verzonden naar de server. Als de server-SDK is geïnstalleerd, wordt de geverifieerde gebruikers-id verzonden als onderdeel van de contexteigenschappen van zowel client- als servertelemetrie. Vervolgens kunt u erop filteren en zoeken.

Als uw app gebruikers in accounts groepeert, kunt u ook een id voor het account doorgeven. Dezelfde tekenbeperkingen gelden.

In Metrics Explorer kunt u een grafiek maken waarmee gebruikers, geverifieerde en gebruikersaccounts worden geteld.

U kunt ook zoeken naar clientgegevenspunten met specifieke gebruikersnamen en accounts.

Uw gegevens filteren, zoeken en segmenteren met behulp van eigenschappen

U kunt eigenschappen en metingen koppelen aan uw gebeurtenissen, metrische gegevens, paginaweergaven, uitzonderingen en andere telemetriegegevens.

Eigenschappen zijn tekenreekswaarden die u kunt gebruiken om uw telemetrie in de gebruiksrapporten te filteren. Als uw app bijvoorbeeld verschillende games biedt, kunt u de naam van het spel koppelen aan elke gebeurtenis, zodat u kunt zien welke games populairder zijn.

Er geldt een limiet van 8.192 voor de tekenreekslengte. Als u grote stukken gegevens wilt verzenden, gebruikt u de berichtparameter van TrackTrace.

Metrische gegevens zijn numerieke waarden die grafisch kunnen worden weergegeven. U kunt bijvoorbeeld zien of er een geleidelijke toename is van de scores die uw gamers behalen. De grafieken kunnen worden gesegmenteerd door de eigenschappen die met de gebeurtenis worden verzonden, zodat u afzonderlijke of gestapelde grafieken voor verschillende games kunt krijgen.

Metrische waarden moeten groter zijn dan of gelijk zijn aan 0 om correct weer te geven.

Er gelden enkele limieten voor het aantal eigenschappen, eigenschapswaarden en metrische gegevens die u kunt gebruiken.

// Set up some properties and metrics:
var properties = new Dictionary <string, string>
    {{"game", currentGame.Name}, {"difficulty", currentGame.Difficulty}};
var metrics = new Dictionary <string, double>
    {{"Score", currentGame.Score}, {"Opponents", currentGame.OpponentCount}};

// Send the event:
telemetry.TrackEvent("WinGame", properties, metrics);

// Set up some properties and metrics:
var properties = {"game": currentGame.Name, "difficulty": currentGame.Difficulty};
var metrics = {"Score": currentGame.Score, "Opponents": currentGame.OpponentCount};

// Send the event:
telemetry.trackEvent({name: "WinGame", properties: properties, measurements: metrics});

Alternatieve manier om eigenschappen en metrische gegevens in te stellen

Als het handiger is, kunt u de parameters van een gebeurtenis in een afzonderlijk object verzamelen:

var event = new EventTelemetry();

event.Name = "WinGame";
event.Metrics["processingTime"] = stopwatch.Elapsed.TotalMilliseconds;
event.Properties["game"] = currentGame.Name;
event.Properties["difficulty"] = currentGame.Difficulty;
event.Metrics["Score"] = currentGame.Score;
event.Metrics["Opponents"] = currentGame.Opponents.Length;

telemetry.TrackEvent(event);

Aangepaste metingen en eigenschappen in Log Analytics

In Log Analytics worden aangepaste metrische gegevens en eigenschappen weergegeven in de customMeasurements en customDimensions kenmerken van elke telemetrierecord.

Als u bijvoorbeeld een eigenschap met de naam 'game' toevoegt aan uw aanvraagtelemetrie, telt deze query het aantal exemplaren van verschillende waarden van 'game' en toont het gemiddelde van de aangepaste metrische waarde 'score':

requests
| summarize sum(itemCount), avg(todouble(customMeasurements.score)) by tostring(customDimensions.game)

U ziet dat:

• Wanneer u een waarde uit de customDimensions of customMeasurements JSON extraheert, heeft deze een dynamisch type, dus moet u deze tostring casten of todouble.
• Om rekening te houden met de mogelijkheid van steekproeven, gebruik sum(itemCount) niet count().

Tijdgebeurtenissen

Soms wilt u een grafiek maken hoe lang het duurt om een actie uit te voeren. U wilt bijvoorbeeld weten hoelang gebruikers rekening houden met keuzes in een game. Gebruik de meetparameter om deze informatie te verkrijgen.

var stopwatch = System.Diagnostics.Stopwatch.StartNew();

// ... perform the timed action ...

stopwatch.Stop();

var metrics = new Dictionary <string, double>
    {{"processingTime", stopwatch.Elapsed.TotalMilliseconds}};

// Set up some properties:
var properties = new Dictionary <string, string>
    {{"signalSource", currentSignalSource.Name}};

// Send the event:
telemetry.TrackEvent("SignalProcessed", properties, metrics);

Standaardeigenschappen voor aangepaste telemetrie

Als u standaardeigenschapswaarden wilt instellen voor een aantal van de aangepaste gebeurtenissen die u schrijft, stelt u deze in een TelemetryClient instantie in. Ze worden gekoppeld aan elk telemetrie-item dat vanaf die client wordt verzonden.

using Microsoft.ApplicationInsights.DataContracts;

var gameTelemetry = new TelemetryClient();
gameTelemetry.Context.GlobalProperties["Game"] = currentGame.Name;
// Now all telemetry is automatically sent with the context property:
gameTelemetry.TrackEvent("WinGame");

var gameTelemetry = new applicationInsights.TelemetryClient();
gameTelemetry.commonProperties["Game"] = currentGame.Name;

gameTelemetry.TrackEvent({name: "WinGame"});

Afzonderlijke telemetrie-aanroepen kunnen de standaardwaarden in hun eigenschapswoordenlijsten overschrijven.

Als u eigenschappen wilt toevoegen aan alle telemetriegegevens, inclusief de gegevens uit standaardverzamelingsmodules, implementeert u ITelemetryInitializer.

Telemetrie uitschakelen

De verzameling en verzending van telemetrie dynamisch stoppen en starten :

using  Microsoft.ApplicationInsights.Extensibility;

TelemetryConfiguration.Active.DisableTelemetry = true;

telemetry.config.disableAppInsights = true;

applicationInsights.setup()
    .setAutoCollectRequests(false)
    .setAutoCollectPerformance(false)
    .setAutoCollectExceptions(false)
    .setAutoCollectDependencies(false)
    .setAutoCollectConsole(false)
    .start();

Ontwikkelaarsmodus

Tijdens foutopsporing is het handig om uw telemetrie te laten versnellen via de pijplijn, zodat u direct resultaten kunt zien. U krijgt ook andere berichten waarmee u problemen met de telemetrie kunt traceren. Schakel het uit in de productieomgeving omdat uw app kan vertragen.

TelemetryConfiguration.Active.TelemetryChannel.DeveloperMode = true;

applicationInsights.setup("ikey")
  .setInternalLogging(true, true)
  .start()
applicationInsights.defaultClient.config.maxBatchSize = 0;

De instrumentatiesleutel instellen voor geselecteerde aangepaste telemetrie

var telemetry = new TelemetryClient();
telemetry.InstrumentationKey = "---my key---";
// ...

Dynamische verbindingsreeks

Om te voorkomen dat telemetrie wordt vermengd vanuit ontwikkel-, test- en productieomgevingen, kunt u afzonderlijke Application Insights-resources maken en hun sleutels wijzigen, afhankelijk van de omgeving.

In plaats van de instrumentatiesleutel op te halen uit het configuratiebestand, kunt u deze instellen in uw code. Stel de sleutel in een initialisatiemethode in, zoals global.aspx.cs in een ASP.NET-service:

protected void Application_Start()
{
    Microsoft.ApplicationInsights.Extensibility.
    TelemetryConfiguration.Active.InstrumentationKey =
        // - for example -
        WebConfigurationManager.Settings["ikey"];
    ...
}

TelemetryContext

TelemetryClient heeft een contexteigenschap, die waarden bevat die samen met alle telemetriegegevens worden verzonden. Ze worden normaal gesproken ingesteld door de standaardtelemetriemodules, maar u kunt ze ook zelf instellen. Voorbeeld:

telemetry.Context.Operation.Name = "MyOperationName";

Als u een van deze waarden zelf instelt, kunt u overwegen om de relevante regel uit ApplicationInsights.config te verwijderen, zodat uw waarden en de standaardwaarden niet in de war raken.

• Onderdeel: de app en de bijbehorende versie.
• Apparaat: gegevens over het apparaat waarop de app wordt uitgevoerd. In web-apps is het de server of het clientapparaat waaruit de telemetrie wordt verzonden.
• InstrumentationKey: de Application Insights-resource in Azure waar de telemetrie wordt weergegeven. Het wordt meestal opgehaald uit ApplicationInsights.config.
• Locatie: De geografische locatie van het apparaat.
• Bewerking: In web-apps wordt de huidige HTTP-aanvraag gebruikt. In andere app-typen kunt u deze waarde instellen om gebeurtenissen samen te groeperen.
  • Id: Een gegenereerde waarde die verschillende gebeurtenissen correleert, zodat u gerelateerde items kunt vinden wanneer u een gebeurtenis inspecteert in diagnostische zoekopdrachten.
  • Naam: een id, meestal de URL van de HTTP-aanvraag.
  • SyntheticSource: Als dit niet null of leeg is, is het een tekenreeks die aangeeft dat de bron van de aanvraag als een robot of webtest is geïdentificeerd. Standaard wordt deze uitgesloten van berekeningen in Metrics Explorer.
• Sessie: de sessie van de gebruiker. De id wordt ingesteld op een gegenereerde waarde, die wordt gewijzigd wanneer de gebruiker al een tijdje niet actief is geweest.
• Gebruiker: Gebruikersgegevens.

Limits

Er gelden enkele beperkingen voor het aantal meetgegevens en gebeurtenissen per toepassing, per instrumentatiesleutel. De limieten zijn afhankelijk van de prijscategorie die u kiest.

Zie Application Insights-facturering voor meer informatie over prijzen en quota.

Gebruik steekproeven om te voorkomen dat de gegevenssnelheidslimiet wordt bereikt.

Zie Gegevensretentie en privacy om te bepalen hoe lang gegevens worden bewaard.

Probleemoplossing

Zie Troubleshoot Application Insights-bewaking van Node.js-apps en -services voor informatie over het oplossen van problemen, inclusief 'geen gegevens'-scenario's en het aanpassen van logboeken.

Volgende stappen

• Als u veelgestelde vragen (FAQ) wilt bekijken, raadpleegt u:
  • Veelgestelde vragen overNode.js
  • Veelgestelde vragen over Application Insights-API voor aangepaste gebeurtenissen en metrische gegevens
• Bewaak uw telemetrie in de portal.
• Meer informatie over het gebruik van Log Analytics en het schrijven van analysequery's via uw telemetrie.