Application Insights-API für benutzerdefinierte Ereignisse und Metriken

Fügen Sie einige Codezeilen in Ihre Anwendung ein, um herauszufinden, wie sie von Benutzern eingesetzt wird, oder um Probleme zu diagnostizieren. Sie können Telemetriedaten von Geräte- und Desktop-Apps, Webclients und Webservern senden. Verwenden Sie die Kerntelemetrie-API von Application Insights, um benutzerdefinierte Ereignisse und Metriken sowie Ihre eigenen Versionen von Standardtelemetriedaten zu senden. Dies ist die gleiche API, die von den standardmäßigen Application Insights-Datensammlern verwendet wird.

API-Zusammenfassung

Die Kern-API ist abgesehen von einigen Abweichungen wie GetMetric (nur .NET) auf allen Plattformen einheitlich.

Methode	Syntaxelemente
TrackPageView	Seiten, Bildschirme, Bereiche oder Formulare.
TrackEvent	Benutzeraktionen und andere Ereignisse. Wird zum Verfolgen des Benutzerverhaltens oder zur Leistungsüberwachung eingesetzt.
GetMetric	Nullmetriken und mehrdimensionale Metriken, zentral konfigurierte Aggregation, nur C#.
TrackMetric	Leistungsmessungen wie Warteschlangenlängen, die nicht im Zusammenhang mit bestimmten Ereignissen stehen.
TrackException	Protokollieren von Ausnahmen für die Diagnose. Verfolgen Sie, wo diese in Bezug auf andere Ereignisse auftreten, und untersuchen Sie die Stapelüberwachung.
TrackRequest	Protokollieren der Häufigkeit und Dauer der Serveranforderungen für die Leistungsanalyse.
TrackTrace	Protokollnachrichten zur Ressourcendiagnose. Sie können auch Drittanbieterprotokolle erfassen.
TrackDependency	Protokollieren der Dauer und Häufigkeit der Aufrufe von externen Komponenten, von denen Ihre Anwendung abhängt.

Sie können den meisten dieser Telemetrieaufrufe Eigenschaften und Metriken anfügen .

Vorbereitung

Gehen Sie wie folgt vor, falls Sie noch nicht über einen Verweis auf das Application Insights SDK verfügen:

• Fügen Sie Ihrem Projekt das Application Insights-SDK hinzu:

  • ASP.NET-Projekt
  • ASP.NET Core-Projekt
  • Java-Projekt
  • Node.js-Projekt
  • JavaScript auf jeder Webseite

• Schließen Sie Folgendes in den Geräte- oder Webservercode ein:

  C# : using Microsoft.ApplicationInsights;

  Visual Basic: Imports Microsoft.ApplicationInsights

  Java: import com.microsoft.applicationinsights.TelemetryClient;

  Node.js: var applicationInsights = require("applicationinsights");

Abrufen einer TelemetryClient-Instanz

Rufen Sie eine TelemetryClient-Instanz ab (gilt nicht für JavaScript auf Webseiten):

Rufen Sie für Apps vom Typ ASP.NET Core oder Nicht-HTTP/Worker für .NET/.NET Core eine Instanz von TelemetryClient aus dem Container für die Abhängigkeitsinjektion ab, wie in der jeweiligen Dokumentation erläutert.

Wenn Sie Azure Functions v2+ oder Azure WebJobs v3+ verwenden, finden Sie weitere Informationen unter Überwachen von Azure Functions.

C#

private TelemetryClient telemetry = new TelemetryClient();

Sollte eine Meldung mit dem Hinweis angezeigt werden, dass diese Methode veraltet ist, finden Sie weitere Informationen unter microsoft/ApplicationInsights-dotnet#1152.

Visual Basic

Private Dim telemetry As New TelemetryClient

Java

private TelemetryClient telemetry = new TelemetryClient();

Node.js

var telemetry = applicationInsights.defaultClient;

TelemetryClient ist threadsicher.

Bei ASP.NET- und Java-Projekten werden eingehende HTTP-Anforderungen automatisch erfasst. Es empfiehlt sich gegebenenfalls, mehr Instanzen von TelemetryClient für weitere Module Ihrer App zu erstellen. Beispielsweise können Sie eine TelemetryClient-Instanz in Ihrer Middleware-Klasse verwenden, um Geschäftslogikereignisse zu melden. Sie können Eigenschaften wie UserId und DeviceId festlegen, um den Computer zu identifizieren. Diese Informationen werden an alle Ereignissen angefügt, die von der Instanz gesendet werden.

C#

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

Java

telemetry.getContext().getUser().setId("...");
telemetry.getContext().getDevice().setId("...");

In Node.js-Projekten können Sie new applicationInsights.TelemetryClient(instrumentationKey?) verwenden, um eine neue Instanz zu erstellen. Dieser Ansatz wird nur für Szenarien empfohlen, die eine Konfiguration erfordern, die vom Singleton-Standardclient (defaultClient) isoliert ist.

TrackEvent

In Application Insights handelt es sich bei einem benutzerdefinierten Ereignis um einen Datenpunkt, den Sie als aggregierte Anzahl im Metrik-Explorer und als einzelne Vorkommen in der Diagnosesuche anzeigen können. (Er gehört nicht zu MVC oder anderen Ereignissen des Frameworks.)

Fügen Sie TrackEvent-Aufrufe in Ihrem Code ein, um verschiedene Ereignisse zu zählen – beispielsweise, um nachzuverfolgen, wie oft Benutzer ein bestimmtes Feature auswählen, oder um zu ermitteln, wie oft sie bestimmte Ziele erreichen oder bestimmte Arten von Fehlern machen.

Senden Sie z. B. in einer Spiele-App ein Ereignis, sobald ein Benutzer das Spiel gewinnt:

JavaScript

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

C#

telemetry.TrackEvent("WinGame");

Visual Basic

telemetry.TrackEvent("WinGame")

Java

telemetry.trackEvent("WinGame");

Node.js

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

Benutzerdefinierte Ereignisse in Log Analytics

Die Telemetrie ist in der Tabelle customEvents auf der Registerkarte mit Application Insights-Protokollen oder auf der Oberfläche zur Verwendungsanalyse verfügbar. Ereignisse können beispielsweise von trackEvent(..) oder vom Plug-In für die automatische Erfassung von Klickanalysen stammen.

Wenn die Stichprobenentnahme aktiv ist, wird für die Eigenschaft itemCount ein Wert größer 1 angezeigt. trackEvent() bedeutet beispielsweise, dass von der Stichprobenentnahme nur einer von zehn itemCount==10-Aufrufen übertragen wurde. Verwenden Sie Code wie customEvents | summarize sum(itemCount), um die korrekte Anzahl benutzerdefinierter Ereignisse zu erhalten.

GetMetric

Informationen zur effektiven Verwendung des Aufrufs GetMetric(), um lokal vorab aggregierte Metriken für .NET- und .NET Core-Anwendungen zu erfassen, finden Sie unter Benutzerdefinierte Sammlung von Metriken in .NET und .NET Core.

TrackMetric

In Application Insights können Metriken dargestellt werden, die keinen bestimmten Ereignissen zugeordnet sind. Beispielsweise könnten Sie die Länge einer Warteschlange in regelmäßigen Abständen überwachen. Bei vorhandenen Metriken sind die einzelnen Messwerte von geringerem Interesse als die Abwandlungen und Trends, daher sind statistische Diagramme sehr nützlich.

Zum Senden von Metriken an Application Insights können Sie die TrackMetric(..)-API verwenden. Es gibt zwei Möglichkeiten, eine Metrik zu senden:

• Einzelner Wert: Bei jeder Durchführung einer Messung in der Anwendung wird der entsprechende Wert an Application Insights gesendet.

  Angenommen, Sie verfügen über eine Metrik, die die Anzahl von Elementen in einem Container beschreibt. In einem bestimmten Zeitraum fügen Sie dem Container zunächst drei Elemente hinzu und entfernen dann zwei Elemente. TrackMetric muss also zweimal aufgerufen werden. Zuerst übergeben Sie den Wert 3 und dann den Wert -2. Application Insights speichert beide Werte für Sie.

• Aggregation. Bei der Arbeit mit Metriken ist nur selten jede einzelne Messung von Interesse. Stattdessen ist eine Zusammenfassung der Vorgänge in einem bestimmten Zeitraum wichtig. Eine solche Zusammenfassung wird als Aggregation bezeichnet.

  Im obigen Beispiel lautet die aggregierte Metriksumme für den Zeitraum 1, und die Anzahl von Metrikwerten ist 2. Bei Verwendung der Aggregation rufen Sie TrackMetric nur einmal pro Zeitraum auf und senden die aggregierten Werte. Mit dieser empfohlenen Vorgehensweise lassen sich die Kosten und die Auswirkungen auf die Leistung erheblich reduzieren, da weniger Datenpunkte an Application Insights gesendet werden. Trotzdem werden alle relevanten Informationen erfasst.

Beispiele für einzelne Werte

So senden Sie einen einzelnen Metrikwert:

JavaScript

appInsights.trackMetric({name: "queueLength", average: 42});

C#

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

Java

telemetry.trackMetric("queueLength", 42.0);

Node.js

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

Benutzerdefinierte Metriken in Log Analytics

Die Telemetrie ist in der Tabelle customMetrics in Application Insights Analytics verfügbar. Jede Zeile stellt einen Aufruf von trackMetric(..) in der App dar.

• valueSum: Die Summe der Messungen. Den Mittelwert erhalten Sie, indem Sie eine Division durch valueCount ausführen.
• valueCount: Die Anzahl von Messungen, die in diesem trackMetric(..)-Aufruf aggregiert wurden.

Seitenaufrufe

In einer Geräte- oder Webseiten-App werden die Telemetriedaten zu den Seitenaufrufen standardmäßig gesendet, wenn die einzelnen Bildschirme oder Seiten geladen werden. Diese Standardeinstellung kann jedoch geändert werden, um Seitenaufrufe öfter oder zu anderen Zeiten nachzuverfolgen. Angenommen, Sie möchten in einer App mit Registerkarten oder Bereichen eine „Seite“ nachverfolgen, sobald der Benutzer einen neuen Bereich öffnet.

Benutzer- und Sitzungsdaten werden als Eigenschaften zusammen mit Seitenaufrufen gesendet, damit die Benutzer- und Sitzungsdiagramme aktiv werden, sobald Telemetriedaten zu den Seitenaufrufen vorliegen.

Benutzerdefinierte Seitenaufrufe

JavaScript

appInsights.trackPageView("tab1");

C#

telemetry.TrackPageView("GameReviewPage");

Visual Basic

telemetry.TrackPageView("GameReviewPage")

Java

telemetry.trackPageView("GameReviewPage");

Wenn Sie mehrere Registerkarten in anderen HTML-Seiten haben, können Sie ebenfalls die URL angeben:

appInsights.trackPageView("tab1", "http://fabrikam.com/page1.htm");

Zeitliches Einteilen von Seitenaufrufen

Standardmäßig werden die gemeldeten Zeiten für Ladezeit der Seitenansicht vom Senden der Anforderung durch den Browser bis zum Aufrufen des Seitenladeereignisses des Browsers gemessen.

Sie haben stattdessen noch folgende Möglichkeiten:

• Legen Sie im trackPageView-Aufruf eine explizite Dauer fest: appInsights.trackPageView("tab1", null, null, null, durationInMilliseconds);.
• Verwenden Sie die Zeitsteuerungsaufrufe startTrackPage und stopTrackPage für die Seitenansicht.

JavaScript

// To start timing a page:
appInsights.startTrackPage("Page1");

...

// To stop timing and log the page:
appInsights.stopTrackPage("Page1", url, properties, measurements);

Mit dem Namen, den Sie für den ersten Parameter verwenden, werden die Start- und Stoppaufrufe zugeordnet. Der Standardwert ist der Name der aktuellen Seite.

Die resultierenden Zeiten für das Laden der Seite, die im Metrik-Explorer angezeigt werden, leiten sich vom Intervall zwischen den Start- und Stoppaufrufen ab. Sie können entscheiden, welches Intervall Sie tatsächlich verwenden.

Seitentelemetrie in Log Analytics

In Log Analytics werden Daten aus Browservorgängen in zwei Tabellen angezeigt:

• pageViews: Enthält Daten zu URL und Seitentitel.
• browserTimings: Enthält Daten zur Leistung des Clients – etwa die benötigte Zeit für die Verarbeitung der eingehenden Daten.

So ermitteln Sie, wie lange die Verarbeitung unterschiedlicher Seiten im Browser dauert

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

So ermitteln Sie die Beliebtheit verschiedener Browser

pageViews
| summarize count() by client_Browser

Um Seitenansichten AJAX-Aufrufen zuzuordnen, verknüpfen Sie sie mit Abhängigkeiten:

pageViews
| join (dependencies) on operation_Id

TrackRequest

TrackRequest wird vom Server-SDK zum Protokollieren von HTTP-Anforderungen verwendet.

Sie können diese Methode auch selbst aufrufen, wenn Sie Anforderungen in einem Kontext simulieren möchten, in dem das Webdienstmodul nicht ausgeführt wird.

Es wird empfohlen, Telemetrieanforderungen zu senden, bei denen die Anforderung als Vorgangskontext fungiert.

Vorgangskontext

Sie können Telemetrieelemente zusammen korrelieren, indem Sie sie dem Vorgangskontext zuordnen. Das standardmäßige Anforderungsnachverfolgungs-Modul führt dies für Ausnahmen und andere Ereignisse aus, die beim Verarbeiten einer HTTP-Anforderung gesendet werden. Unter Suche und Analyse können Sie anhand der Vorgangs-ID problemlos Ereignisse finden, die der Anforderung zugeordnet sind.

Weitere Informationen zur Korrelation finden Sie unter Telemetriekorrelation in Application Insights.

Beim manuellen Nachverfolgen von Telemetriedaten kann die Korrelation der Telemetriedaten am einfachsten mithilfe des folgenden Musters sichergestellt werden:

C#

// Establish an operation context and associated telemetry item:
using (var operation = telemetryClient.StartOperation<RequestTelemetry>("operationName"))
{
    // Telemetry sent in here will use 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.

Neben dem Festlegen eines Vorgangskontexts wird mit StartOperation ein Telemetrieelement des von Ihnen angegebenen Typs erstellt. Das Telemetrieelement wird gesendet, wenn Sie den Vorgang verwerfen oder explizit StopOperation aufrufen. Wenn Sie RequestTelemetry als Telemetrietyp verwenden, wird die Dauer („Duration“) auf das Zeitintervall zwischen Start und Stopp festgelegt.

Die Telemetrieelemente, die innerhalb eines Vorgangsbereichs gemeldet werden, werden zu untergeordneten Elementen eines entsprechenden Vorgangs. Vorgangskontexte können geschachtelt werden.

Unter Suche wird der Vorgangskontext verwendet, um die Liste Verwandte Elemente zu erstellen:

Weitere Informationen zur Nachverfolgung benutzerdefinierter Vorgänge finden Sie unter Nachverfolgen von benutzerdefinierten Vorgängen mit dem Application Insights .NET SDK.

Anforderungen in Log Analytics

In Application Insights Analytics werden Anforderungen in der Tabelle requests angezeigt.

Wenn die Stichprobenentnahme aktiv ist, wird für die Eigenschaft itemCount ein Wert größer 1 angezeigt. trackRequest() bedeutet beispielsweise, dass von der Stichprobenentnahme nur einer von zehn itemCount==10-Aufrufen übertragen wurde. Um die richtige Anzahl der Anforderungen und die durchschnittliche Dauer nach Anforderungsnamen segmentiert abzurufen, verwenden Sie beispielsweise folgenden Code:

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

TrackException

Ziele beim Senden von Ausnahmen an Application Insights:

• Durchführen einer Zählung als Hinweis auf die Häufigkeit eines Problems
• Untersuchen einzelner Vorkommen

Die Berichte enthalten die Stapelüberwachung.

C#

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

Java

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

JavaScript

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

Node.js

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

Da die SDKs viele Ausnahmen automatisch abfangen, muss nicht immer explizit TrackException aufgerufen werden:

• ASP.NET: Schreiben Sie Code zum Abfangen von Ausnahmen.
• Java EE: Ausnahmen werden automatisch abgefangen.
• JavaScript: Ausnahmen werden automatisch abgefangen. Wenn Sie die automatische Erfassung deaktivieren wollen, können Sie dem JavaScript (Web) SDK-Ladeprogrammskript, das Sie in Ihren Webseiten einfügen, eine Zeile hinzufügen:

({
    instrumentationKey: "your key",
    disableExceptionTracking: true
})

Ausnahmen in Log Analytics

In Application Insights Analytics werden Ausnahmen in der Tabelle exceptions angezeigt.

Wenn die Stichprobenentnahme aktiv ist, wird für die Eigenschaft itemCount ein Wert größer 1 angezeigt. trackException() bedeutet beispielsweise, dass von der Stichprobenentnahme nur einer von zehn itemCount==10-Aufrufen übertragen wurde. Um die richtige Anzahl der Ausnahmen segmentiert nach Ausnahmetyp abzurufen, geben Sie beispielsweise folgenden Code ein:

exceptions
| summarize sum(itemCount) by type

Die meisten wichtigen Stapelinformationen wurden bereits in separate Variablen extrahiert, Sie können jedoch die Struktur details analysieren, um weitere Informationen zu erhalten. Da es sich hierbei um eine dynamische Struktur handelt, muss das Ergebnis in den erwarteten Typ umgewandelt werden. Beispiel:

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

Verwenden Sie zum Zuordnen von Ausnahmen zu den zugehörigen Anforderungen eine Verknüpfung:

exceptions
| join (requests) on operation_Id

TrackTrace

Nutzen Sie TrackTrace bei der Diagnose von Problemen, indem Sie eine Brotkrümelnavigation an Application Insights senden. Sie können Blöcke von Diagnosedaten senden und sie in der Diagnosesuche überprüfen.

Verwenden Sie diese API in .NET-Protokolladaptern, um Drittanbieterprotokolle an das Portal zu senden.

In Java erfasst der Java-Agent von Application Insights automatisch Protokolle und sendet sie an das Portal.

C#

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

Java

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

Node.js

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

Client-/browserseitiges JavaScript

trackTrace({
    message: string,
    properties?: {[string]:string},
    severityLevel?: SeverityLevel
})

Protokollieren eines Diagnoseereignisses, z.B. Eingeben oder Beenden einer Methode

Parameter	BESCHREIBUNG
message	Diagnosedaten. Kann erheblich länger als ein Name sein.
properties	Zuordnung von Zeichenfolge zu Zeichenfolge. Weitere Daten werden zum Filtern von Ausnahmen im Portal verwendet. Ist standardmäßig leer.
severityLevel	Unterstützte Werte: SeverityLevel.ts

Sie können nach Nachrichteninhalt suchen, aber anders als bei Eigenschaftswerten nicht danach filtern.

Die Größenbeschränkung für message liegt wesentlich höher als der Grenzwert für Eigenschaften. Ein Vorteil von TrackTrace ist, dass relativ lange Daten in die Nachricht eingefügt werden können. Sie können dort beispielsweise POST-Daten codieren.

Sie können Ihrer Nachricht auch einen Schweregrad hinzufügen. Wie bei anderen Telemetriedaten auch können Sie Eigenschaftswerte hinzufügen, um zu filtern oder nach verschiedenen Ablaufverfolgungen zu suchen. Beispiel:

C#

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

Java

Map<String, Integer> properties = new HashMap<>();
properties.put("Database", db.ID);
telemetry.trackTrace("Slow Database response", SeverityLevel.Warning, properties);

Unter Search können Sie dann leicht alle Nachrichten eines bestimmten Schweregrads herausfiltern, die eine bestimmte Datenbank betreffen.

Ablaufverfolgungen in Log Analytics

In Application Insights Analytics werden Aufrufe von TrackTrace in der Tabelle traces angezeigt.

Wenn die Stichprobenentnahme aktiv ist, wird für die Eigenschaft itemCount ein Wert größer 1 angezeigt. trackTrace() bedeutet beispielsweise, dass von der Stichprobenentnahme nur einer von zehn itemCount==10-Aufrufen übertragen wurde. Verwenden Sie Code wie traces | summarize sum(itemCount), um die korrekte Anzahl von Ablaufverfolgungsaufrufen zu erhalten.

TrackDependency

Verwenden Sie den Aufruf von TrackDependency zum Nachverfolgen der Antwortzeiten und der Erfolgsraten der Aufrufe von externem Code. Die Ergebnisse werden in den Abhängigkeitsdiagrammen im Portal angezeigt. Der folgende Codeausschnitt muss immer dann hinzugefügt werden, wenn ein Abhängigkeitsaufruf ausgeführt wird.

C#

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

Java

boolean success = false;
Instant startTime = Instant.now();
try {
    success = dependency.call();
}
finally {
    Instant endTime = Instant.now();
    Duration delta = Duration.between(startTime, endTime);
    RemoteDependencyTelemetry dependencyTelemetry = new RemoteDependencyTelemetry("My Dependency", "myCall", delta, success);
    dependencyTelemetry.setTimeStamp(startTime);
    telemetry.trackDependency(dependencyTelemetry);
}

Node.js

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

Zur Erinnerung: Die Server-SDKs enthalten ein Abhängigkeitsmodul, das bestimmte Abhängigkeitsaufrufe automatisch ermittelt und nachverfolgt (z. B. für Datenbanken und REST-APIs). Sie müssen einen Agent auf dem Server installieren, damit das Modul funktioniert.

In Java können viele Abhängigkeitsaufrufe mit dem Java-Agent von Application Insights automatisch nachverfolgt werden.

Sie verwenden diesen Aufruf, um Aufrufe nachzuverfolgen, die durch die automatisierte Nachverfolgung nicht abgefangen werden.

Wenn Sie das Standardmodul zum Nachverfolgen von Abhängigkeiten in C# deaktivieren möchten, bearbeiten Sie ApplicationInsights.config, und löschen Sie den Verweis auf DependencyCollector.DependencyTrackingTelemetryModule. Informationen zu Java finden Sie unter Unterdrücken bestimmter automatisch erfasster Telemetriedaten.

Abhängigkeiten in Log Analytics

In Application Insights Analytics werden Aufrufe von trackDependency in der Tabelle dependencies angezeigt.

Wenn die Stichprobenentnahme aktiv ist, wird für die Eigenschaft itemCount ein Wert größer 1 angezeigt. trackDependency() bedeutet beispielsweise, dass von der Stichprobenentnahme nur einer von zehn itemCount==10-Aufrufen übertragen wurde. Um die richtige Anzahl der Abhängigkeiten segmentiert nach Zielkomponente abzurufen, verwenden Sie beispielsweise folgenden Code:

dependencies
| summarize sum(itemCount) by target

Verwenden Sie zum Zuordnen von Abhängigkeiten zu den zugehörigen Anforderungen eine Verknüpfung:

dependencies
| join (requests) on operation_Id

Leeren von Daten

Normalerweise sendet das SDK Daten in festen Intervallen (in der Regel alle 30 Sekunden) oder wenn der Puffer voll ist (in der Regel 500 Elemente). In einigen Fällen empfiehlt es sich aber, den Puffer zu leeren – etwa, wenn Sie das SDK in einer Anwendung verwenden, die heruntergefahren wird.

.NET

Bei Verwendung von Flush() wird das folgende Muster empfohlen:

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

Bei Verwendung von FlushAsync() wird das folgende Muster empfohlen:

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

Es wird empfohlen, beim Herunterfahren der Anwendung immer eine Leerung durchzuführen, um sicherzustellen, dass keine Telemetriedaten verloren gehen.

Java

telemetry.flush();
//Allow some time for flushing before shutting down
Thread.sleep(5000);

Node.js

telemetry.flush();

Die Funktion ist für den Servertelemetriekanal asynchron.

Authentifizierte Benutzer

In einer Web-App werden Benutzer standardmäßig anhand von Cookies identifiziert. Benutzer werden unter Umständen mehr als einmal gezählt, wenn sie über verschiedene Computer oder Browser auf Ihre App zugreifen oder Cookies löschen.

Wenn sich Benutzer bei Ihrer App anmelden, erhalten Sie einen genaueren Zählwert durch Festlegen der ID des authentifizierten Benutzers im Browsercode:

JavaScript

// Called when my app has identified the user.
function Authenticated(signInId) {
    var validatedId = signInId.replace(/[,;=| ]+/g, "_");
    appInsights.setAuthenticatedUserContext(validatedId);
    ...
}

In einer ASP.NET-MVC-Webanwendung, beispielsweise:

Razor

@if (Request.IsAuthenticated)
{
    <script>
        appInsights.setAuthenticatedUserContext("@User.Identity.Name
            .Replace("\\", "\\\\")"
            .replace(/[,;=| ]+/g, "_"));
    </script>
}

Es ist nicht notwendig, den tatsächlichen Anmeldenamen des Benutzers zu verwenden. Es muss sich lediglich um eine ID handeln, die für diesen Benutzer eindeutig ist. Sie darf keine Leerzeichen und keines der folgenden Zeichen enthalten: ,;=|.

Die Benutzer-ID wird zudem in einem Sitzungscookie festgelegt und an den Server gesendet. Wenn das Server-SDK installiert ist, wird die ID des authentifizierten Benutzers als Teil der Kontexteigenschaften der Client- und Servertelemetrie gesendet. Anschließend können Sie danach filtern und suchen.

Wenn bei Ihrer App Benutzer in Konten gruppiert werden, können Sie auch einen Bezeichner für das Konto übergeben. Es gelten die gleichen Zeicheneinschränkungen.

appInsights.setAuthenticatedUserContext(validatedId, accountId);

Im Metrik-Explorer können Sie ein Diagramm erstellen, das authentifizierte Benutzer und Benutzerkonten zählt.

Sie können auch nach Clientdatenpunkten mit bestimmten Benutzernamen und Konten suchen.

Filtern, Suchen und Segmentieren Ihrer Daten mithilfe von Eigenschaften

Sie können Eigenschaften und Messungen an Ereignisse, Metriken, Seitenaufrufe, Ausnahme und andere Telemetriedaten anfügen.

Eigenschaften sind die Zeichenfolgenwerte, die Sie zum Filtern der Telemetriedaten in den Nutzungsberichten verwenden können. Wenn die Anwendung beispielsweise mehrere Spiele bereitstellt, können Sie den Namen des Spiels an jedes Ereignis anfügen, damit Sie sehen können, welche Spiele immer populärer werden.

Die Zeichenfolgenlänge ist auf 8.192 Zeichen begrenzt. Wenn Sie große Datenblöcke senden möchten, verwenden Sie den Nachrichtenparameter von TrackTrace.

Metriken sind numerische Werte, die grafisch dargestellt werden können. Beispiel: Sie möchten überprüfen, ob die von den Spielern erreichten Punktzahlen stetig zunehmen. Die Graphen können anhand der mit dem Ereignis gesendeten Eigenschaften unterteilt werden, sodass Sie separate oder gestapelte Graphen für verschiedene Spiele erhalten.

Metrikwerte müssen größer oder gleich 0 sein, um ordnungsgemäß dargestellt zu werden.

Es gibt einige Beschränkungen hinsichtlich der Anzahl von Eigenschaften, Eigenschaftswerten und Metriken , die Sie verwenden können.

JavaScript

appInsights.trackEvent({
  name: 'some event',
  properties: { // accepts any type
    prop1: 'string',
    prop2: 123.45,
    prop3: { nested: 'objects are okay too' }
  }
});

appInsights.trackPageView({
  name: 'some page',
  properties: { // accepts any type
    prop1: 'string',
    prop2: 123.45,
    prop3: { nested: 'objects are okay too' }
  }
});

C#

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

Node.js

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

Visual Basic

' Set up some properties:
Dim properties = New Dictionary (Of String, String)
properties.Add("game", currentGame.Name)
properties.Add("difficulty", currentGame.Difficulty)

Dim metrics = New Dictionary (Of String, Double)
metrics.Add("Score", currentGame.Score)
metrics.Add("Opponents", currentGame.OpponentCount)

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

Java

Map<String, String> properties = new HashMap<String, String>();
properties.put("game", currentGame.getName());
properties.put("difficulty", currentGame.getDifficulty());

Map<String, Double> metrics = new HashMap<String, Double>();
metrics.put("Score", currentGame.getScore());
metrics.put("Opponents", currentGame.getOpponentCount());

telemetry.trackEvent("WinGame", properties, metrics);

Alternative Methode zum Festlegen von Eigenschaften und Metriken

Wenn es für Sie praktischer ist, können Sie die Parameter eines Ereignisses in einem separaten Objekt sammeln:

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

Benutzerdefinierte Messungen und Eigenschaften in Log Analytics

In Log Analytics werden benutzerdefinierte Metriken und Eigenschaften in den Attributen customMeasurements und customDimensions jedes Telemetriedatensatzes angezeigt.

Wenn Sie Ihrer Anforderungstelemetrie beispielsweise die Eigenschaft „game“ hinzufügen, werden bei dieser Abfrage die Vorkommen verschiedener Werte von „game“ gezählt, und der Durchschnitt der benutzerdefinierten Metrik „score“ wird angezeigt:

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

Beachten Sie Folgendes:

• Wenn Sie einen Wert aus dem JSON-Code customDimensions oder customMeasurements extrahieren, ist dieser dynamisch typisiert. Daher müssen Sie ihn in tostring oder todouble umwandeln.
• Verwenden Sie für eine mögliche Stichprobenentnahme nicht count(), sondern sum(itemCount).

Zeitmessung bei Ereignissen

In bestimmten Fällen möchten Sie im Diagramm vielleicht darstellen, wie lange es dauert, eine Aktion auszuführen. Beispielsweise möchten Sie wissen, wie lange Benutzer brauchen, um die Auswahl in einem Spiel zu erwägen. Verwenden Sie zum Abrufen dieser Information den Messungsparameter.

C#

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

Java

long startTime = System.currentTimeMillis();

// Perform timed action

long endTime = System.currentTimeMillis();
Map<String, Double> metrics = new HashMap<>();
metrics.put("ProcessingTime", (double)endTime-startTime);

// Setup some properties
Map<String, String> properties = new HashMap<>();
properties.put("signalSource", currentSignalSource.getName());

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

Standardeigenschaften für benutzerdefinierte Telemetriedaten

Wenn Sie für einige der benutzerdefinierten Ereignisse, die Sie schreiben, Standardeigenschaftswerte festlegen möchten, verwenden Sie dazu eine TelemetryClient-Instanz. Sie werden jedem Telemetrieelement zugeordnet, das von diesem Client gesendet wird.

C#

using Microsoft.ApplicationInsights.DataContracts;

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

Visual Basic

Dim gameTelemetry = New TelemetryClient()
gameTelemetry.Context.GlobalProperties("Game") = currentGame.Name
' Now all telemetry will automatically be sent with the context property:
gameTelemetry.TrackEvent("WinGame")

Java

import com.microsoft.applicationinsights.TelemetryClient;
import com.microsoft.applicationinsights.TelemetryContext;
...

TelemetryClient gameTelemetry = new TelemetryClient();
TelemetryContext context = gameTelemetry.getContext();
context.getProperties().put("Game", currentGame.Name);

gameTelemetry.TrackEvent("WinGame");

Node.js

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

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

Einzelne Telemetrieaufrufe können die Standardwerte in ihren Eigenschaftenwörterbüchern überschreiben.

Für JavaScript-Webclients verwenden Sie JavaScript-Telemetrieinitialisierer.

Wenn Sie allen Telemetriedaten Eigenschaften hinzufügen möchten (einschließlich Daten aus Standardsammlungsmodulen), implementieren Sie ITelemetryInitializer.

Entnehmen von Stichproben sowie Filtern und Verarbeiten von Telemetriedaten

Siehe Filtern und Vorverarbeiten von Telemetriedaten im Application Insights-SDK.

Telemetrie deaktivieren

So können Sie die Sammlung und Übermittlung von Telemetriedaten dynamisch beenden und starten :

C#

using  Microsoft.ApplicationInsights.Extensibility;

TelemetryConfiguration.Active.DisableTelemetry = true;

Java

telemetry.getConfiguration().setTrackingDisabled(true);

Wenn Sie ausgewählte Standardsammlungsmodule deaktivieren möchten (beispielsweise Leistungsindikatoren, HTTP-Anforderungen oder Abhängigkeiten), können Sie die entsprechenden Zeilen in ApplicationInsights.config löschen oder auskommentieren. Ein Beispiel wäre etwa, wenn Sie Ihre eigenen TrackRequest-Daten senden möchten.

Node.js

telemetry.config.disableAppInsights = true;

Um ausgewählte Standardsammlungsmodule zu deaktivieren (beispielsweise Leistungsindikatoren, HTTP-Anforderungen oder Abhängigkeiten), verketten Sie Konfigurationsmethoden bei der Initialisierung mit Ihrem SDK-Initialisierungscode.

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

Verwenden Sie zum Deaktivieren dieser Sammlungsmodule nach der Initialisierung das Configuration-Objekt: applicationInsights.Configuration.setAutoCollectRequests(false)

Entwicklermodus

Während des Debuggens ist es sinnvoll, die Telemetriedaten beschleunigt über die Pipeline zu senden, damit die Ergebnisse sofort angezeigt werden. Sie erhalten außerdem zusätzliche Meldungen, mit denen Sie Probleme mit der Telemetrie verfolgen können. Deaktivieren Sie den Modus in der Produktion, da er Ihre App verlangsamen kann.

C#

TelemetryConfiguration.Active.TelemetryChannel.DeveloperMode = true;

Visual Basic

TelemetryConfiguration.Active.TelemetryChannel.DeveloperMode = True

Node.js

Für Node.js können Sie den Entwicklermodus aktivieren, indem Sie die interne Protokollierung über setInternalLogging aktivieren und maxBatchSize auf 0 festlegen, wodurch Ihre Telemetriedaten gesendet werden, sobald sie gesammelt wurden.

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

Festlegen des Instrumentationsschlüssels für ausgewählte benutzerdefinierte Telemetriedaten

C#

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

Dynamischer Instrumentationsschlüssel

Um das Vermischen von Telemetriedaten aus Entwicklungs-, Test- und Produktionsumgebungen zu vermeiden, können Sie separate Application Insights-Ressourcen erstellen und ihre Schlüssel abhängig von der Umgebung ändern.

Statt den Instrumentationsschlüssel aus der Konfigurationsdatei abzurufen, können Sie ihn im Code festlegen. Legen Sie den Schlüssel in einer Initialisierungsmethode fest – beispielsweise global.aspx.cs in einem ASP.NET-Dienst:

C#

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

JavaScript

appInsights.config.instrumentationKey = myKey;

Bei Webseiten empfiehlt es sich, ihn über den Zustand des Webservers festzulegen, anstatt ihn im Skript zu codieren. Beispielsweise auf einer Webseite, die in einer ASP.NET-App generiert wird:

JavaScript in Razor

<script type="text/javascript">
// Standard Application Insights webpage script:
var appInsights = window.appInsights || function(config){ ...
// Modify this part:
}({instrumentationKey:
    // Generate from server property:
    @Microsoft.ApplicationInsights.Extensibility.
        TelemetryConfiguration.Active.InstrumentationKey;
}) // ...

    String instrumentationKey = "00000000-0000-0000-0000-000000000000";

    if (instrumentationKey != null)
    {
        TelemetryConfiguration.getActive().setInstrumentationKey(instrumentationKey);
    }

TelemetryContext

TelemetryClient verfügt über eine Kontexteigenschaft mit Werten, die zusammen mit allen Telemetriedaten gesendet werden. Sie werden normalerweise von den Standardtelemetriemodulen festgelegt, können aber auch manuell festgelegt werden. Beispiel:

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

Wenn Sie diese Werte selbst festlegen, empfiehlt es sich gegebenenfalls, die entsprechende Zeile aus ApplicationInsights.config zu entfernen, damit kein Konflikt zwischen Ihren Werten und den Standardwerten entsteht.

• Component: Die App und ihre Version.
• Device: Daten zu dem Gerät, auf dem die App ausgeführt wird. In Web-Apps ist dies das Server- oder Clientgerät, von dem die Telemetriedaten gesendet werden.
• InstrumentationKey: Die Application Insights-Ressource in Azure, in der die Telemetriedaten angezeigt werden. Sie wird in der Regel aus ApplicationInsights.config übernommen.
• Standort: Der geografische Standort des Geräts.
• Operation: In Web-Apps die aktuelle HTTP-Anforderung. Bei anderen App-Typen kann dieser Wert zum Gruppieren von Ereignissen festgelegt werden.
  • ID: Ein generierter Wert, der verschiedene Ereignisse korreliert, sodass Sie beim Untersuchen eines Ereignisses in der Diagnosesuche verwandte Elemente finden können.
  • Name: Ein Bezeichner, in der Regel die URL der HTTP-Anforderung.
  • SyntheticSource: Wenn diese Zeichenfolge nicht NULL oder leer ist, wird damit angegeben, dass die Quelle der Anforderung als Roboter oder Webtest identifiziert wurde. Standardmäßig wird sie von Berechnungen im Metrik-Explorer ausgeschlossen.
• Sitzung (Session) : Die Sitzung des Benutzers. Die ID wird auf einen generierten Wert festgelegt und ändert sich, wenn der Benutzer eine Weile nicht aktiv war.
• Benutzer: Benutzerinformationen.

Einschränkungen

Es gibt einige Grenzwerte hinsichtlich der Anzahl von Metriken und Ereignissen pro Anwendung (d. h. pro Instrumentationsschlüssel). Die Beschränkungen hängen von dem von Ihnen ausgewählten Tarif ab.

Resource	Standardlimit	Maximales Limit	Hinweise
Gesamtdaten pro Tag	100 GB	Wenden Sie sich an den Support.	Sie können eine Obergrenze festlegen, um Daten zu reduzieren. Wird eine höhere Datenmenge benötigt, können Sie den Grenzwert im Portal auf bis zu 1.000 GB erhöhen. Bei Kapazitäten über 1.000 GB senden Sie eine E-Mail an AIDataCap@microsoft.com.
Drosselung	32.000 Ereignisse/s	Wenden Sie sich an den Support.	Das Limit wird eine Minute lang gemessen.
Datenaufbewahrungsprotokolle	30 bis 730 Tage	Nach 730 Tagen	Diese Ressource ist für Protokolle vorgesehen.
Datenaufbewahrungsmetriken	90 Tage	90 Tage	Diese Ressource ist für den Metrik-Explorer vorgesehen.
Aufbewahrung ausführlicher Ergebnisse von Verfügbarkeitstests mit mehreren Schritten	90 Tage	90 Tage	Diese Ressource liefert detaillierte Ergebnisse der einzelnen Schritte.
Maximale Größe von Telemetrieelementen	64 KB	64 KB
Maximale Anzahl von Telemetrieelementen pro Batch	64.000	64.000
Eingenschaft und Länge der Namen von Metriken	150	150	Siehe Typschemas.
Zeichenfolgenlänge des Eigenschaftswerts	8\.192	8\.192	Siehe Typschemas.
Länge von Ablaufverfolgungs- und Ausnahmebenachrichtigungen	32,768	32,768	Siehe Typschemas.
Anzahl der Verfügbarkeitstests pro Application Insights-Ressource	100	100
Anzahl der Verfügbarkeitstests pro Ressourcengruppe	800	800	Weitere Informationen finden Sie unter Azure Resource Manager.
In Verfügbarkeitstests maximale Anzahl der Umleitungen pro Test	10	10
Minimale Testhäufigkeit bei Verfügbarkeitstests	300 Sekunden		Benutzerdefinierte Testhäufigkeiten oder Häufigkeiten von weniger als fünf Minuten erfordern benutzerdefinierte TrackAvailability-Implementierungen.
Profiler und Momentaufnahmedatenaufbewahrung	Zwei Wochen	Wenden Sie sich an den Support. Die maximale Aufbewahrungszeit beträgt sechs Monate.
Pro Tag gesendete Profiler-Daten	Keine Begrenzung	Keine Begrenzung
Pro Tag gesendete Momentaufnahmedaten	30 Momentaufnahmen pro Tag pro überwachte App	Keine Begrenzung	Die Anzahl der pro Anwendung erfassten Momentaufnahmen kann über die Konfiguration geändert werden.

Weitere Informationen zu Preisen und Kontingenten finden Sie unter Abrechnung für Application Insights.

Nutzen Sie die Stichprobenerstellung (Sampling), um zu vermeiden, dass Sie die Datenratengrenze erreichen.

Informationen dazu, wie lange Daten aufbewahrt werden, finden Sie unter Datenspeicherung und Datenschutz.

Referenz

• .NET-Referenz
• Java-Referenz
• JavaScript-Referenz

SDK-Code

• .NET
• Windows Server-Pakete
• Java SDK
• Node.js SDK
• JavaScript SDK

Häufig gestellte Fragen

Dieser Abschnitt enthält Antworten auf häufig gestellte Fragen.

Warum fehlen mir Telemetriedaten?

Beide TelemetryChannels verlieren gepufferte Telemetriedaten, wenn sie vor dem Herunterfahren einer Anwendung nicht geleert werden.

Um Datenverluste zu vermeiden, leeren Sie den TelemetryClient, wenn eine Anwendung heruntergefahren wird.

Weitere Informationen finden Sie unter Leeren von Daten.

Welche Ausnahmen können bei Track_()-Aufrufen ausgelöst werden?

Keine. Sie müssen sie nicht mit try/catch-Klauseln umschließen. Sollte das SDK auf Probleme stoßen, werden Meldungen in der Debugkonsolenausgabe und (sofern die Meldungen ankommen) in der Diagnosesuche protokolliert.

Gibt es eine REST-API zum Abrufen von Daten aus dem Portal?

Ja, die Datenzugriffs-API. Weitere Möglichkeiten zum Extrahieren von Daten bietet Power BI, wenn Sie zu einer arbeitsbereichsbasierten Ressource migriert haben oder den fortlaufenden Export verwenden, sofern Sie sich noch eine klassische Ressource nutzen.

Warum werden meine Aufrufe für benutzerdefinierte Ereignisse und Metrik-APIs ignoriert?

Das Application Insights SDK ist nicht mit der automatischen Instrumentierung kompatibel. Wenn die automatische Instrumentierung aktiviert ist, werden Aufrufe an Track() und andere benutzerdefinierte Ereignisse und Metrik-APIs ignoriert.

Deaktivieren Sie die automatische Instrumentierung im Azure-Portal auf der Registerkarte „Application Insights“ der App Service-Seite, oder legen Sie ApplicationInsightsAgent_EXTENSION_VERSION auf disabled fest.

Warum sind die Zahlen in den Diagrammen „Suchen“ und „Metriken“ unterschiedlich?

Durch Sampling wird die Anzahl der Telemetrieelemente (wie Anforderungen, benutzerdefinierte Ereignisse), die von der App an das Portal gesendet werden, verringert. In „Suchen“ wir die Anzahl der empfangenen Elemente angezeigt. In Metrikdiagrammen, in denen die Anzahl der Ereignisse angezeigt wird, wird die Anzahl der ursprünglich eingetretenen Ereignisse angezeigt.

Jedes übertragene Element verfügt über eine itemCount-Eigenschaft, die angibt, wie viele ursprüngliche Ereignisse das Element darstellt. Sie können die folgende Abfrage in Log Analytics ausführen, um zu sehen, wie Sampling erfolgt:

    requests | summarize original_events = sum(itemCount), transmitted_events = count()

Wie kann ich eine Warnung für ein Ereignis festlegen?

Azure-Warnungen gelten nur für Metriken. Erstellen Sie eine benutzerdefinierte Metrik, die immer einen Schwellenwert überschreitet, wenn das Ereignis eintritt. Legen Sie dann eine Warnung für die Metrik fest. Sie erhalten eine Benachrichtigung, wenn die Metrik den Schwellenwert in beide Richtungen überschreitet. Sie erhalten erst beim ersten Überschreiten eine Benachrichtigung, unabhängig davon, ob der Anfangswert hoch oder niedrig ist. Es gibt immer eine Wartezeit von einigen Minuten.

Nächste Schritte

• Durchsuchen von Ereignissen und Protokollen