Application Insights-API für benutzerdefinierte Ereignisse und MetrikenApplication Insights API for custom events and metrics

Fügen Sie einige Codezeilen in Ihre Anwendung ein, um herauszufinden, wie sie von Benutzern eingesetzt wird, oder um Probleme zu diagnostizieren.Insert a few lines of code in your application to find out what users are doing with it, or to help diagnose issues. Sie können Telemetriedaten von Geräte- und Desktop-Apps, Webclients und Webservern senden.You can send telemetry from device and desktop apps, web clients, and web servers. Verwenden Sie die Azure Application Insights-Kerntelemetrie-API, um benutzerdefinierte Ereignisse und Metriken und Ihre eigenen Versionen der standardmäßigen Telemetrie zu senden.Use the Azure Application Insights core telemetry API to send custom events and metrics, and your own versions of standard telemetry. Dies ist die gleiche API, die von den standardmäßigen Application Insights-Datensammlern verwendet wird.This API is the same API that the standard Application Insights data collectors use.

API-ZusammenfassungAPI summary

Die Haupt-API ist, abgesehen von einigen Abweichungen wie GetMetric (nur .NET), auf allen Plattformen einheitlich.The core API is uniform across all platforms, apart from a few variations like GetMetric(.NET only).

MethodeMethod SyntaxelementeUsed for
TrackPageView Seiten, Bildschirme, Blätter oder Formulare.Pages, screens, blades, or forms.
TrackEvent Benutzeraktionen und andere Ereignisse.User actions and other events. Wird zum Verfolgen des Benutzerverhaltens oder zur Leistungsüberwachung eingesetzt.Used to track user behavior or to monitor performance.
GetMetric Nullmetriken und mehrdimensionale Metriken, zentral konfigurierte Aggregation, nur C#.Zero and multi-dimensional metrics, centrally configured aggregation, C# only.
TrackMetric Leistungsmessungen wie Warteschlangenlängen, die nicht im Zusammenhang mit bestimmten Ereignissen stehen.Performance measurements such as queue lengths not related to specific events.
TrackException Protokollieren von Ausnahmen für die Diagnose.Logging exceptions for diagnosis. Verfolgen Sie, wo diese in Bezug auf andere Ereignisse auftreten, und untersuchen Sie die Stapelüberwachung.Trace where they occur in relation to other events and examine stack traces.
TrackRequest Protokollieren der Häufigkeit und Dauer der Serveranforderungen für die Leistungsanalyse.Logging the frequency and duration of server requests for performance analysis.
TrackTrace Protokollnachrichten zur Ressourcendiagnose.Resource Diagnostic log messages. Sie können auch Drittanbieterprotokolle erfassen.You can also capture third-party logs.
TrackDependency Protokollieren der Dauer und Häufigkeit der Aufrufe von externen Komponenten, von denen Ihre Anwendung abhängt.Logging the duration and frequency of calls to external components that your app depends on.

Sie können den meisten dieser Telemetrieaufrufe Eigenschaften und Metriken anfügen .You can attach properties and metrics to most of these telemetry calls.

VorbereitungBefore you start

Gehen Sie wie folgt vor, falls Sie noch nicht über einen Verweis auf das Application Insights SDK verfügen:If you don't have a reference on Application Insights SDK yet:

Abrufen einer TelemetryClient-InstanzGet a TelemetryClient instance

Rufen Sie eine TelemetryClient-Instanz ab (gilt nicht für JavaScript auf Webseiten):Get an instance of TelemetryClient (except in JavaScript in webpages):

Für ASP.NET Core-Apps und Nicht-HTTP/Worker für .NET/.NET Core-Apps empfiehlt es sich, eine Instanz von TelemetryClient aus dem Container für die Abhängigkeitsinjektion abzurufen, wie in der entsprechenden Dokumentation erläutert.For ASP.NET Core apps and Non HTTP/Worker for .NET/.NET Core apps, it is recommended to get an instance of TelemetryClient from the dependency injection container as explained in their respective documentation.

Halten Sie sich bei Verwendung von AzureFunctions v2 (oder höher) oder Azure WebJobs v3 (oder höher) an folgendes Dokument: https://docs.microsoft.com/azure/azure-functions/functions-monitoring#version-2x-and-higherIf you use AzureFunctions v2+ or Azure WebJobs v3+ - follow this document: https://docs.microsoft.com/azure/azure-functions/functions-monitoring#version-2x-and-higher

C#C#

private TelemetryClient telemetry = new TelemetryClient();

Sollten Meldungen mit dem Hinweis angezeigt werden, dass diese Methode veraltet ist, besuchen Sie microsoft/ApplicationInsights-dotnet#1152, um weitere Informationen zu erhalten.For anyone seeing this method is obsolete messages please visit microsoft/ApplicationInsights-dotnet#1152 for further details.

Visual BasicVisual Basic

Private Dim telemetry As New TelemetryClient

JavaJava

private TelemetryClient telemetry = new TelemetryClient();

Node.jsNode.js

var telemetry = applicationInsights.defaultClient;

TelemetryClient ist threadsicher.TelemetryClient is thread-safe.

Bei ASP.NET- und Java-Projekten werden eingehende HTTP-Anforderungen automatisch erfasst.For ASP.NET and Java projects, incoming HTTP Requests are automatically captured. Es empfiehlt sich unter Umständen, zusätzliche TelemetryClient-Instanzen für weitere Module Ihrer App zu erstellen.You might want to create additional instances of TelemetryClient for other module of your app. So können Sie beispielsweise eine TelemetryClient-Instanz in Ihrer Middleware-Klasse verwenden, um Geschäftslogikereignisse zu melden.For instance, you may have one TelemetryClient instance in your middleware class to report business logic events. Sie können Eigenschaften wie „UserId“ und „DeviceId“ festlegen, um den Computer zu identifizieren.You can set properties such as UserId and DeviceId to identify the machine. Diese Informationen werden an alle Ereignissen angefügt, die von der Instanz gesendet werden.This information is attached to all events that the instance sends.

C#C#

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

JavaJava

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, aber diese Empfehlung gilt nur für Szenarien, die eine vom Singleton-defaultClient isolierte Konfiguration erfordern.In Node.js projects, you can use new applicationInsights.TelemetryClient(instrumentationKey?) to create a new instance, but this is recommended only for scenarios that require isolated configuration from the singleton defaultClient.

TrackEventTrackEvent

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.In Application Insights, a custom event is a data point that you can display in Metrics Explorer as an aggregated count, and in Diagnostic Search as individual occurrences. (Er gehört nicht zu MVC oder anderen Ereignissen des Frameworks.)(It isn't related to MVC or other framework "events.")

Fügen Sie TrackEvent-Aufrufe in Ihrem Code ein, um verschiedene Ereignisse zu zählen –Insert TrackEvent calls in your code to count various events. beispielsweise, wie oft Benutzer ein bestimmtes Feature auswählen, bestimmte Ziele erreichen oder bestimmte Arten von Fehlern machen.How often users choose a particular feature, how often they achieve particular goals, or maybe how often they make particular types of mistakes.

Senden Sie z. B. in einer Spiele-App ein Ereignis, sobald ein Benutzer das Spiel gewinnt:For example, in a game app, send an event whenever a user wins the game:

JavaScriptJavaScript

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

C#C#

telemetry.TrackEvent("WinGame");

Visual BasicVisual Basic

telemetry.TrackEvent("WinGame")

JavaJava

telemetry.trackEvent("WinGame");

Node.jsNode.js

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

Benutzerdefinierte Ereignisse in AnalyticsCustom events in Analytics

Die Telemetrie ist in der Tabelle customEvents in Application Insights Analytics verfügbar.The telemetry is available in the customEvents table in Application Insights Analytics. Jede Zeile stellt einen Aufruf von trackEvent(..) in der App dar.Each row represents a call to trackEvent(..) in your app.

Wenn die Stichprobenentnahme aktiv ist, wird für die itemCount-Eigenschaft ein Wert größer 1 angezeigt.If sampling is in operation, the itemCount property shows a value greater than 1. itemCount==10 bedeutet beispielsweise, dass bei der Stichprobenentnahme von 10 Aufrufen von trackEvent() nur einer übertragen wurde.For example itemCount==10 means that of 10 calls to trackEvent(), the sampling process only transmitted one of them. Zum Abrufen der richtigen Anzahl benutzerdefinierter Ereignisse sollten Sie daher Code wie customEvents | summarize sum(itemCount) verwenden.To get a correct count of custom events, you should therefore use code such as customEvents | summarize sum(itemCount).

GetMetricGetMetric

Informationen zur effektiven Verwendung des GetMetric()-Aufrufs zum Erfassen lokal vorab aggregierter Metriken für .NET- und .NET Core-Anwendungen finden Sie in der Dokumentation zu GetMetric.To learn how to effectively use the GetMetric() call to capture locally pre-aggregated metrics for .NET and .NET Core applications visit the GetMetric documentation.

TrackMetricTrackMetric

Hinweis

2Microsoft.ApplicationInsights.TelemetryClient.TrackMetric“ ist nicht die bevorzugte Methode für das Senden von Metriken.Microsoft.ApplicationInsights.TelemetryClient.TrackMetric is not the preferred method for sending metrics. Metriken sollten immer für einen bestimmten Zeitraum vorab aggregiert werden, bevor sie gesendet werden.Metrics should always be pre-aggregated across a time period before being sent. Verwenden Sie eine der GetMetric(..)-Überladungen, um ein Metrikobjekt für den Zugriff auf Funktionen für die SDK-Vorabaggregation zu erhalten.Use one of the GetMetric(..) overloads to get a metric object for accessing SDK pre-aggregation capabilities. Wenn Sie Ihre eigene Logik für die Vorabaggregation implementieren, können Sie die TrackMetric()-Methode zum Senden der sich ergebenden Aggregate verwenden.If you are implementing your own pre-aggregation logic, you can use the TrackMetric() method to send the resulting aggregates. Falls für Ihre Anwendung das Senden eines separaten Telemetrieelements immer erforderlich ist (ohne zeitabhängige Aggregation), verfügen Sie wahrscheinlich über einen Anwendungsfall für eine Ereignistelemetrie. Weitere Informationen finden Sie unter „TelemetryClient.TrackEvent (Microsoft.Applicationlnsights.DataContracts.EventTelemetry)“.If your application requires sending a separate telemetry item at every occasion without aggregation across time, you likely have a use case for event telemetry; see TelemetryClient.TrackEvent (Microsoft.ApplicationInsights.DataContracts.EventTelemetry).

In Application Insights können Metriken dargestellt werden, die keinen bestimmten Ereignissen zugeordnet sind.Application Insights can chart metrics that are not attached to particular events. Beispielsweise könnten Sie die Länge einer Warteschlange in regelmäßigen Abständen überwachen.For example, you could monitor a queue length at regular intervals. Bei vorhandenen Metriken sind die einzelnen Messwerte von geringerem Interesse als die Abwandlungen und Trends, daher sind statistische Diagramme sehr nützlich.With metrics, the individual measurements are of less interest than the variations and trends, and so statistical charts are useful.

Zum Senden von Metriken an Application Insights können Sie die TrackMetric(..)-API verwenden.In order to send metrics to Application Insights, you can use the TrackMetric(..) API. Es gibt zwei Möglichkeiten, eine Metrik zu senden:There are two ways to send a metric:

  • Einzelner Wert:Single value. Bei jeder Durchführung einer Messung in der Anwendung wird der entsprechende Wert an Application Insights gesendet.Every time you perform a measurement in your application, you send the corresponding value to Application Insights. Angenommen, Sie haben eine Metrik für die Anzahl der Elemente in einem Container festgelegt.For example, assume that you have a metric describing the number of items in a container. In einem bestimmten Zeitraum fügen Sie dem Container zunächst drei Elemente hinzu und entfernen dann zwei Elemente.During a particular time period, you first put three items into the container and then you remove two items. Dementsprechend rufen Sie TrackMetric zweimal auf: zuerst zum Übergeben des Werts 3 und anschließend zum Übergeben des Werts -2.Accordingly, you would call TrackMetric twice: first passing the value 3 and then the value -2. Application Insights speichert beide Werte für Sie.Application Insights stores both values on your behalf.

  • Aggregation:Aggregation. Bei der Arbeit mit Metriken ist nur selten jede einzelne Messung von Interesse.When working with metrics, every single measurement is rarely of interest. Stattdessen ist eine Zusammenfassung der Vorgänge in einem bestimmten Zeitraum wichtig.Instead a summary of what happened during a particular time period is important. Eine solche Zusammenfassung wird als Aggregation bezeichnet.Such a summary is called aggregation. Im obigen Beispiel lautet die aggregierte Metriksumme für den Zeitraum 1, und die Anzahl von Metrikwerten ist 2.In the above example, the aggregate metric sum for that time period is 1 and the count of the metric values is 2. Bei Verwendung der Aggregation rufen Sie TrackMetric nur einmal pro Zeitraum auf und senden die aggregierten Werte.When using the aggregation approach, you only invoke TrackMetric once per time period and send the aggregate values. Diese Vorgehensweise empfiehlt sich, um die Kosten und den Leistungsaufwand erheblich zu reduzieren, da weniger Datenpunkte an Application Insights gesendet, aber dennoch alle relevanten Informationen erfasst werden.This is the recommended approach since it can significantly reduce the cost and performance overhead by sending fewer data points to Application Insights, while still collecting all relevant information.

BeispieleExamples

Einzelne WerteSingle values

So senden Sie einen einzelnen Metrikwert:To send a single metric value:

JavaScriptJavaScript

appInsights.trackMetric("queueLength", 42.0);

C#C#

var sample = new MetricTelemetry();
sample.Name = "metric name";
sample.Value = 42.3;
telemetryClient.TrackMetric(sample);

JavaJava

telemetry.trackMetric("queueLength", 42.0);

Node.jsNode.js

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

Benutzerdefinierte Metriken in der AnalyseCustom metrics in Analytics

Die Telemetrie ist in der Tabelle customMetrics in Application Insights Analytics verfügbar.The telemetry is available in the customMetrics table in Application Insights Analytics. Jede Zeile stellt einen Aufruf von trackMetric(..) in der App dar.Each row represents a call to trackMetric(..) in your app.

  • valueSum: Dies ist die Summe der Messwerte.valueSum - This is the sum of the measurements. Den Mittelwert erhalten Sie, indem Sie eine Division durch valueCount ausführen.To get the mean value, divide by valueCount.
  • valueCount: Die Anzahl der Messwerte, die in diesem trackMetric(..)-Aufruf aggregiert wurden.valueCount - The number of measurements that were aggregated into this trackMetric(..) call.

SeitenaufrufePage views

In einer Geräte- oder Webseiten-App werden die Telemetriedaten zu den Seitenaufrufen standardmäßig gesendet, wenn die einzelnen Bildschirme oder Seiten geladen werden.In a device or webpage app, page view telemetry is sent by default when each screen or page is loaded. Sie können dies jedoch so ändern, dass Seitenaufrufe zu zusätzlichen oder anderen verfolgt werden.But you can change that to track page views at additional or different times. Angenommen, Sie möchten in einer App mit Registerkarten oder Blättern eine „Seite“ nachverfolgen, sobald der Benutzer ein neues Blatt öffnet.For example, in an app that displays tabs or blades, you might want to track a page whenever the user opens a new blade.

Benutzer- und Sitzungsdaten werden als Eigenschaften zusammen mit Seitenaufrufen gesendet, damit die Benutzer- und Sitzungsdiagramme aktiv werden, sobald Telemetriedaten zu den Seitenaufrufen vorliegen.User and session data is sent as properties along with page views, so the user and session charts come alive when there is page view telemetry.

Benutzerdefinierte SeitenaufrufeCustom page views

JavaScriptJavaScript

appInsights.trackPageView("tab1");

C#C#

telemetry.TrackPageView("GameReviewPage");

Visual BasicVisual Basic

telemetry.TrackPageView("GameReviewPage")

JavaJava

telemetry.trackPageView("GameReviewPage");

Wenn Sie mehrere Registerkarten in anderen HTML-Seiten haben, können Sie ebenfalls die URL angeben:If you have several tabs within different HTML pages, you can specify the URL too:

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

Zeitliches Einteilen von SeitenaufrufenTiming page views

In der Standardeinstellung werden die gemeldeten Zeiten für Ladezeit der Seitenansicht von dem Zeitpunkt, zu dem der Browser die Anforderung sendet, bis zum Aufruf des Seitenladeereignisses im Browser gemessen.By default, the times reported as Page view load time are measured from when the browser sends the request, until the browser's page load event is called.

Sie haben stattdessen noch folgende Möglichkeiten:Instead, you can either:

  • Legen Sie im trackPageView-Aufruf eine explizite Dauer fest: appInsights.trackPageView("tab1", null, null, null, durationInMilliseconds);.Set an explicit duration in the trackPageView call: appInsights.trackPageView("tab1", null, null, null, durationInMilliseconds);.
  • Verwenden Sie die Zeitsteuerungsaufrufe startTrackPage und stopTrackPage für die Seitenansicht.Use the page view timing calls startTrackPage and stopTrackPage.

JavaScriptJavaScript

// 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.The name that you use as the first parameter associates the start and stop calls. Der Standardwert ist der Name der aktuellen Seite.It defaults to the current page name.

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.The resulting page load durations displayed in Metrics Explorer are derived from the interval between the start and stop calls. Sie können entscheiden, welches Intervall Sie tatsächlich verwenden.It's up to you what interval you actually time.

Seitentelemetrie in AnalyticsPage telemetry in Analytics

In Analytics werden Daten aus Browservorgängen in zwei Tabellen angezeigt:In Analytics two tables show data from browser operations:

  • Die Tabelle pageViews enthält Daten über die URL und den Seitentitel.The pageViews table contains data about the URL and page title
  • Die Tabelle browserTimings enthält Daten über die Leistung des Clients, z.B. die angefallene Zeit zum Verarbeiten der eingehenden Daten.The browserTimings table contains data about client performance, such as the time taken to process the incoming data

So ermitteln Sie, wie lange die Verarbeitung unterschiedlicher Seiten im Browser dauertTo find how long the browser takes to process different pages:

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

So ermitteln Sie die Beliebtheit verschiedener BrowserTo discover the popularities of different browsers:

pageViews
| summarize count() by client_Browser

Um Seitenansichten AJAX-Aufrufen zuzuordnen, verknüpfen Sie sie mit Abhängigkeiten:To associate page views to AJAX calls, join with dependencies:

pageViews
| join (dependencies) on operation_Id 

TrackRequestTrackRequest

Für das Server-SDK wird TrackRequest zum Protokollieren von HTTP-Anforderungen verwendet.The server SDK uses TrackRequest to log HTTP requests.

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.You can also call it yourself if you want to simulate requests in a context where you don't have the web service module running.

Es wird jedoch empfohlen, Telemetrieanforderungen zu senden, bei denen die Anforderung als Vorgangskontext fungiert.However, the recommended way to send request telemetry is where the request acts as an operation context.

VorgangskontextOperation context

Sie können Telemetrieelemente zusammen korrelieren, indem Sie sie dem Vorgangskontext zuordnen.You can correlate telemetry items together by associating them with operation context. Das standardmäßige Anforderungsnachverfolgungs-Modul führt dies für Ausnahmen und andere Ereignisse aus, die beim Verarbeiten einer HTTP-Anforderung gesendet werden.The standard request-tracking module does this for exceptions and other events that are sent while an HTTP request is being processed. Unter Suche und Analyse können Sie anhand der Vorgangs-ID leicht Ereignisse finden, die der Anforderung zugeordnet sind.In Search and Analytics, you can easily find any events associated with the request using its operation ID.

Ausführlichere Informationen zur Korrelation finden Sie unter Telemetriekorrelation in Application Insights.See Telemetry correlation in Application Insights for more details on correlation.

Beim manuellen Nachverfolgen der Telemetriedaten besteht die einfachste Vorgehensweise darin, die Korrelation der Telemetriedaten sicherzustellen, indem das folgende Muster verwendet wird:When tracking telemetry manually, the easiest way to ensure telemetry correlation by using this pattern:

C#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.Along with setting an operation context, StartOperation creates a telemetry item of the type that you specify. Das Telemetrieelement wird gesendet, wenn Sie den Vorgang verwerfen oder wenn Sie StopOperation explizit aufrufen.It sends the telemetry item when you dispose the operation, or if you explicitly call StopOperation. Wenn Sie RequestTelemetry als Telemetrietyp verwenden, wird die Dauer („Duration“) auf das Zeitintervall zwischen Start und Stopp festgelegt.If you use RequestTelemetry as the telemetry type, its duration is set to the timed interval between start and stop.

Die Telemetrieelemente, die innerhalb eines Vorgangsbereichs gemeldet werden, werden zu den untergeordneten Elementen des Vorgangs.Telemetry items reported within a scope of operation become 'children' of such operation. Vorgangskontexte können geschachtelt werden.Operation contexts could be nested.

In der Suche wird mit dem Vorgangskontext die Liste Verwandte Elemente erstellt:In Search, the operation context is used to create the Related Items list:

Verwandte Elemente

Weitere Informationen zur Nachverfolgung benutzerdefinierter Vorgänge finden Sie unter Nachverfolgen von benutzerdefinierten Vorgängen mit dem Application Insights .NET SDK.See Track custom operations with Application Insights .NET SDK for more information on custom operations tracking.

Anforderungen in AnalyticsRequests in Analytics

In Application Insights Analytics werden Anforderungen in der Tabelle requests angezeigt.In Application Insights Analytics, requests show up in the requests table.

Wenn die Stichprobenentnahme aktiv ist, wird für die itemCount-Eigenschaft ein Wert größer 1 angezeigt.If sampling is in operation, the itemCount property will show a value greater than 1. itemCount==10 bedeutet beispielsweise, dass bei der Stichprobenentnahme von 10 Aufrufen von trackRequest() nur einer übertragen wurde.For example itemCount==10 means that of 10 calls to trackRequest(), the sampling process only transmitted one of them. Um die richtige Anzahl der Anforderungen und die durchschnittliche Dauer nach Anforderungsnamen segmentiert abzurufen, verwenden Sie beispielsweise folgenden Code:To get a correct count of requests and average duration segmented by request names, use code such as:

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

TrackExceptionTrackException

Ziele beim Senden von Ausnahmen an Application Insights:Send exceptions to Application Insights:

Die Berichte enthalten die Stapelüberwachung.The reports include the stack traces.

C#C#

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

JavaJava

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

JavaScriptJavaScript

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

Node.jsNode.js

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

Die SDKs viele Ausnahmen automatisch abfangen, müssen Sie TrackException nicht immer explizit aufrufen.The SDKs catch many exceptions automatically, so you don't always have to call TrackException explicitly.

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

Ausnahmen in AnalyticsExceptions in Analytics

In Application Insights Analytics werden Ausnahmen in der Tabelle exceptions angezeigt.In Application Insights Analytics, exceptions show up in the exceptions table.

Wenn die Stichprobenentnahme aktiv ist, wird für die Eigenschaft itemCount ein Wert größer 1 angezeigt.If sampling is in operation, the itemCount property shows a value greater than 1. itemCount==10 bedeutet beispielsweise, dass bei der Stichprobenentnahme von 10 Aufrufen von trackException() nur einer übertragen wurde.For example itemCount==10 means that of 10 calls to trackException(), the sampling process only transmitted one of them. Um die richtige Anzahl der Ausnahmen segmentiert nach Ausnahmetyp abzurufen, geben Sie beispielsweise folgenden Code ein:To get a correct count of exceptions segmented by type of exception, use code such as:

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.Most of the important stack information is already extracted into separate variables, but you can pull apart the details structure to get more. Da es sich hierbei um eine dynamische Struktur handelt, muss das Ergebnis in den erwarteten Typ umgewandelt werden.Since this structure is dynamic, you should cast the result to the type you expect. Beispiel:For example:

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

Verwenden Sie zum Zuordnen von Ausnahmen zu den zugehörigen Anforderungen eine Verknüpfung:To associate exceptions with their related requests, use a join:

exceptions
| join (requests) on operation_Id

TrackTraceTrackTrace

Verwenden Sie TrackTrace zum Diagnostizieren von Problemen, indem Sie eine „Brotkrümelnavigation“ an Application Insights senden.Use TrackTrace to help diagnose problems by sending a "breadcrumb trail" to Application Insights. Sie können Blöcke von Diagnosedaten senden und sie in der Diagnosesuche überprüfen.You can send chunks of diagnostic data and inspect them in Diagnostic Search.

Verwenden Sie diese API in .NET-Protokolladaptern, um Drittanbieterprotokolle an das Portal zu senden.In .NET Log adapters use this API to send third-party logs to the portal.

Verwenden Sie in Java für Standardprotokollierungen wie Log4J und Logback Application Insights-Log4J- oder Logback-Appender, um Drittanbieterprotokolle an das Portal zu senden.In Java for Standard loggers like Log4J, Logback use Application Insights Log4j or Logback Appenders to send third-party logs to the portal.

C#C#

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

JavaJava

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

Node.jsNode.js

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

Client-/browserseitiges JavaScriptClient/Browser-side JavaScript

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

Protokollieren eines Diagnoseereignisses, z.B. Eingeben oder Beenden einer MethodeLog a diagnostic event such as entering or leaving a method.

ParameterParameter BESCHREIBUNGDescription
message Diagnosedaten.Diagnostic data. Kann erheblich länger als ein Name sein.Can be much longer than a name.
properties Zuordnen einer Zeichenfolge zu einer Zeichenfolge: Zusätzlich zum Filtern von Ausnahmen im Portal verwendete Daten.Map of string to string: Additional data used to filter exceptions in the portal. Ist standardmäßig leer.Defaults to empty.
severityLevel Unterstützte Werte: SeverityLevel.tsSupported values: SeverityLevel.ts

Sie können nach Nachrichteninhalt suchen, aber (anders als bei Eigenschaftswerten) nicht danach filtern.You can search on message content, but (unlike property values) you can't filter on it.

Die Größenbeschränkung für message liegt wesentlich höher als der Grenzwert für Eigenschaften.The size limit on message is much higher than the limit on properties. Ein Vorteil von TrackTrace ist, dass relativ lange Daten in die Nachricht eingefügt werden können.An advantage of TrackTrace is that you can put relatively long data in the message. Sie können dort beispielsweise POST-Daten codieren.For example, you can encode POST data there.

Darüber hinaus können Sie Ihrer Nachricht einen Schweregrad hinzufügen.In addition, you can add a severity level to your message. Wie bei anderen Telemetriedaten auch können Sie Eigenschaftswerte hinzufügen, um zu filtern oder nach verschiedenen Ablaufverfolgungen zu suchen.And, like other telemetry, you can add property values to help you filter or search for different sets of traces. Beispiel:For example:

C#C#

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

JavaJava

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.In Search, you can then easily filter out all the messages of a particular severity level that relate to a particular database.

Ablaufverfolgungen in AnalyticsTraces in Analytics

In Application Insights Analytics werden Aufrufe von TrackTrace in der Tabelle traces angezeigt.In Application Insights Analytics, calls to TrackTrace show up in the traces table.

Wenn die Stichprobenentnahme aktiv ist, wird für die itemCount-Eigenschaft ein Wert größer 1 angezeigt.If sampling is in operation, the itemCount property shows a value greater than 1. „itemCount==10“ bedeutet beispielsweise, dass bei der Stichprobenentnahme von zehn trackTrace()-Aufrufen nur einer übertragen wurde.For example itemCount==10 means that of 10 calls to trackTrace(), the sampling process only transmitted one of them. Zum Abrufen der richtigen Anzahl von Ablaufverfolgungsaufrufen sollten Sie daher Code wie traces | summarize sum(itemCount) verwenden.To get a correct count of trace calls, you should use therefore code such as traces | summarize sum(itemCount).

TrackDependencyTrackDependency

Verwenden Sie den TrackDependency-Aufruf zum Nachverfolgen der Antwortzeiten und der Erfolgsraten beim Aufrufen einer externen Codepassage.Use the TrackDependency call to track the response times and success rates of calls to an external piece of code. Die Ergebnisse werden in den Abhängigkeitsdiagrammen im Portal angezeigt.The results appear in the dependency charts in the portal. Der folgende Codeausschnitt muss immer dann hinzugefügt werden, wenn ein Abhängigkeitsaufruf ausgeführt wird.The code snippet below needs to be added wherever a dependency call is made.

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

JavaJava

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);
    RemoteDependencyTelemetry.setTimeStamp(startTime);
    RemoteDependencyTelemetry.trackDependency(dependencyTelemetry);
}

Node.jsNode.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
    });
}

Beachten Sie, dass die Server-SDKs ein Abhängigkeitsmodul enthalten, das bestimmte Abhängigkeitsaufrufe automatisch ermittelt und nachverfolgt (z.B. zu Datenbanken und REST-APIs).Remember that the server SDKs include a dependency module that discovers and tracks certain dependency calls automatically--for example, to databases and REST APIs. Sie müssen einen Agent auf dem Server installieren, damit das Modul funktioniert.You have to install an agent on your server to make the module work.

In Java können bestimmte Abhängigkeitsaufrufe per Java-Agent automatisch nachverfolgt werden.In Java, certain dependency calls can be automatically tracked using Java Agent.

Sie verwenden diesen Aufruf, um Aufrufe nachzuverfolgen, die durch die automatisierte Nachverfolgung nicht abgefangen werden, oder wenn Sie den Agent nicht installieren möchten.You use this call if you want to track calls that the automated tracking doesn't catch, or if you don't want to install the agent.

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.To turn off the standard dependency-tracking module in C#, edit ApplicationInsights.config and delete the reference to DependencyCollector.DependencyTrackingTelemetryModule. Installieren Sie in Java keinen Java-Agent, wenn Standardabhängigkeiten nicht automatisch gesammelt werden sollen.In Java, please do not install java agent if you do not want to collect standard dependencies automatically.

Abhängigkeiten in AnalyticsDependencies in Analytics

In Application Insights Analytics werden trackDependency-Aufrufe in der Tabelle dependencies angezeigt.In Application Insights Analytics, trackDependency calls show up in the dependencies table.

Wenn die Stichprobenentnahme aktiv ist, wird für die itemCount-Eigenschaft ein Wert größer 1 angezeigt.If sampling is in operation, the itemCount property shows a value greater than 1. itemCount==10 bedeutet beispielsweise, dass bei der Stichprobenentnahme von 10 Aufrufen von trackDependency() nur einer übertragen wurde.For example itemCount==10 means that of 10 calls to trackDependency(), the sampling process only transmitted one of them. Um die richtige Anzahl der Abhängigkeiten segmentiert nach Zielkomponente abzurufen, verwenden Sie beispielsweise folgenden Code:To get a correct count of dependencies segmented by target component, use code such as:

dependencies
| summarize sum(itemCount) by target

Verwenden Sie zum Zuordnen von Abhängigkeiten zu den zugehörigen Anforderungen eine Verknüpfung:To associate dependencies with their related requests, use a join:

dependencies
| join (requests) on operation_Id

Leeren von DatenFlushing data

Normalerweise sendet das SDK Daten in festen Intervallen (in der Regel 30 Sekunden) oder wenn der Puffer voll ist (in der Regel 500 Elemente).Normally, the SDK sends data at fixed intervals (typically 30 secs) or whenever buffer is full (typically 500 items). In einigen Fällen empfiehlt es sich aber, den Puffer zu leeren – beispielsweise bei der Verwendung des SDK in einer Anwendung, die heruntergefahren wird.However, in some cases, you might want to flush the buffer--for example, if you are using the SDK in an application that shuts down.

C#C#

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

JavaJava

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

Node.jsNode.js

telemetry.flush();

Die Funktion ist für den Servertelemetriekanal asynchron.The function is asynchronous for the server telemetry channel.

Die flush()-Methode wird idealerweise in der Aktivität zum Herunterfahren der Anwendung verwendet.Ideally, flush() method should be used in the shutdown activity of the Application.

Authentifizierte BenutzerAuthenticated users

In einer Web-App werden Benutzer (standardmäßig) anhand von Cookies identifiziert.In a web app, users are (by default) identified by cookies. 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.A user might be counted more than once if they access your app from a different machine or browser, or if they delete cookies.

Wenn sich Benutzer bei Ihrer App anmelden, erhalten Sie einen genaueren Zählwert durch Festlegen der ID des authentifizierten Benutzers im Browsercode:If users sign in to your app, you can get a more accurate count by setting the authenticated user ID in the browser code:

JavaScriptJavaScript

// 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:In an ASP.NET web MVC application, for example:

RazorRazor

@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.It isn't necessary to use the user's actual sign-in name. Es muss sich lediglich um eine ID handeln, die für diesen Benutzer eindeutig ist.It only has to be an ID that is unique to that user. Sie darf keine Leerzeichen und keines der folgenden Zeichen enthalten: ,;=|.It must not include spaces or any of the characters ,;=|.

Die Benutzer-ID wird zudem in einem Sitzungscookie festgelegt und an den Server gesendet.The user ID is also set in a session cookie and sent to the server. Wenn das Server-SDK installiert ist, wird die ID des authentifizierten Benutzers als Teil der Kontexteigenschaften der Client- und Servertelemetrie gesendet.If the server SDK is installed, the authenticated user ID is sent as part of the context properties of both client and server telemetry. Anschließend können Sie danach filtern und suchen.You can then filter and search on it.

Wenn bei Ihrer App Benutzer in Konten gruppiert werden, können Sie auch einen Bezeichner für das Konto (mit den gleichen Zeicheneinschränkungen) übergeben.If your app groups users into accounts, you can also pass an identifier for the account (with the same character restrictions).

appInsights.setAuthenticatedUserContext(validatedId, accountId);

Im Metrik-Explorer können Sie ein Diagramm erstellen, das authentifizierte Benutzer und Benutzerkonten zählt.In Metrics Explorer, you can create a chart that counts Users, Authenticated, and User accounts.

Sie können auch nach Clientdatenpunkten mit bestimmten Benutzernamen und Konten suchen.You can also Search for client data points with specific user names and accounts.

Filtern, Durchsuchen und Segmentieren von Daten mithilfe von EigenschaftenFiltering, searching, and segmenting your data by using properties

Sie können Ihren Ereignissen (und auch Metriken, Seitenaufrufen, Ausnahmen und anderen Telemetriedaten) Eigenschaften und Messungen anfügen.You can attach properties and measurements to your events (and also to metrics, page views, exceptions, and other telemetry data).

Eigenschaften sind die Zeichenfolgenwerte, die Sie zum Filtern der Telemetriedaten in den Nutzungsberichten verwenden können.Properties are string values that you can use to filter your telemetry in the usage reports. 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.For example, if your app provides several games, you can attach the name of the game to each event so that you can see which games are more popular.

Die Zeichenfolgenlänge ist auf 8192 Zeichen begrenzt.There's a limit of 8192 on the string length. (Wenn Sie große Datenblöcke senden möchten, verwenden Sie den message-Parameter von TrackTrace.)(If you want to send large chunks of data, use the message parameter of TrackTrace.)

Metriken sind numerische Werte, die grafisch dargestellt werden können.Metrics are numeric values that can be presented graphically. Beispiel: Sie möchten überprüfen, ob die von den Spielern erreichten Punktzahlen stetig zunehmen.For example, you might want to see if there's a gradual increase in the scores that your gamers achieve. Die Diagramme können anhand der mit dem Ereignis gesendeten Eigenschaften unterteilt werden, sodass Sie für verschiedene Spiele separate oder gestapelte Diagramme erhalten.The graphs can be segmented by the properties that are sent with the event, so that you can get separate or stacked graphs for different games.

Damit die Metrikwerte richtig angezeigt werden, sollten sie größer als oder gleich 0 sein.For metric values to be correctly displayed, they should be greater than or equal to 0.

Es gibt einige Beschränkungen hinsichtlich der Anzahl von Eigenschaften, Eigenschaftswerten und Metriken , die Sie verwenden können.There are some limits on the number of properties, property values, and metrics that you can use.

JavaScriptJavaScript

appInsights.trackEvent
    ("WinGame",
        // String properties:
        {Game: currentGame.name, Difficulty: currentGame.difficulty},
        // Numeric metrics:
        {Score: currentGame.score, Opponents: currentGame.opponentCount}
        );

appInsights.trackPageView
    ("page name", "http://fabrikam.com/pageurl.html",
        // String properties:
        {Game: currentGame.name, Difficulty: currentGame.difficulty},
        // Numeric metrics:
        {Score: currentGame.score, Opponents: currentGame.opponentCount}
        );

C#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.jsNode.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 BasicVisual 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)

JavaJava

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

Hinweis

Achten Sie darauf, keine persönlich identifizierbaren Informationen in den Eigenschaften zu protokollieren.Take care not to log personally identifiable information in properties.

Alternative Methode zum Festlegen von Eigenschaften und MetrikenAlternative way to set properties and metrics

Wenn es für Sie praktischer ist, können Sie die Parameter eines Ereignisses in einem separaten Objekt sammeln:If it's more convenient, you can collect the parameters of an event in a separate object:

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

Warnung

Verwenden Sie nicht dieselbe Telemetrieelementinstanz (in diesem Beispiel event), um „Track*()“ mehrfach aufzurufen.Don't reuse the same telemetry item instance (event in this example) to call Track*() multiple times. Dies kann dazu führen, dass Telemetriedaten mit einer falschen Konfiguration gesendet werden.This may cause telemetry to be sent with incorrect configuration.

Benutzerdefinierte Messungen und Eigenschaften in AnalyticsCustom measurements and properties in Analytics

In Analytics werden benutzerdefinierte Metriken und Eigenschaften in den Attributen customMeasurements und customDimensions jedes Telemetriedatensatzes angezeigt.In Analytics, custom metrics and properties show in the customMeasurements and customDimensions attributes of each telemetry record.

Wenn Sie der Anforderungstelemetrie beispielsweise die Eigenschaft „game“ hinzugefügt haben, werden bei dieser Abfrage die Vorkommen verschiedener Werte von „game“ gezählt, und der Durchschnitt der benutzerdefinierten Metrik „score“ wird angezeigt:For example, if you have added a property named "game" to your request telemetry, this query counts the occurrences of different values of "game", and show the average of the custom metric "score":

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

Beachten Sie Folgendes:Notice that:

  • Wenn Sie einen Wert aus dem customDimensions- oder customMeasurements-JSON-Code extrahieren, ist dieser dynamisch typisiert. Daher müssen Sie ihn in tostring oder todouble umwandeln.When you extract a value from the customDimensions or customMeasurements JSON, it has dynamic type, and so you must cast it tostring or todouble.
  • Um die Möglichkeit der Stichprobenentnahme zu berücksichtigen, müssen Sie sum(itemCount) statt count() verwenden.To take account of the possibility of sampling, you should use sum(itemCount), not count().

Zeitmessung bei EreignissenTiming events

In bestimmten Fällen möchten Sie im Diagramm vielleicht darstellen, wie lange es dauert, eine Aktion auszuführen.Sometimes you want to chart how long it takes to perform an action. Beispielsweise möchten Sie wissen, wie lange Benutzer brauchen, um die Auswahl in einem Spiel zu erwägen.For example, you might want to know how long users take to consider choices in a game. Hierfür können Sie den Messparameter verwenden.You can use the measurement parameter for this.

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

JavaJava

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 TelemetriedatenDefault properties for custom telemetry

Wenn Sie die Standardeigenschaftswerte für einige Ihrer benutzerdefinierten Ereignisse festlegen möchten, können Sie diese in einer TelemetryClient-Instanz festlegen.If you want to set default property values for some of the custom events that you write, you can set them in a TelemetryClient instance. Sie werden jedem Telemetrieelement zugeordnet, das von diesem Client gesendet wird.They are attached to every telemetry item that's sent from that client.

C#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 BasicVisual 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")

JavaJava

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.jsNode.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.Individual telemetry calls can override the default values in their property dictionaries.

Für JavaScript-Webclients verwenden Sie JavaScript-Telemetrieinitialisierer.For JavaScript web clients, use JavaScript telemetry initializers.

Wenn Sie allen Telemetriedaten Eigenschaften hinzufügen möchten (einschließlich Daten aus Standardsammlungsmodulen), implementieren Sie ITelemetryInitializer.To add properties to all telemetry, including the data from standard collection modules, implement ITelemetryInitializer.

Stichprobenerstellung, Filterung und Verarbeitung von TelemetriedatenSampling, filtering, and processing telemetry

Sie können Code zum Verarbeiten Ihrer Telemetriedaten schreiben, bevor diese vom SDK gesendet werden.You can write code to process your telemetry before it's sent from the SDK. Die Verarbeitung umfasst Daten, die von den standardmäßigen Telemetriemodulen gesendet werden, z.B. die HTTP-Anforderungsauflistung und Abhängigkeitsauflistung.The processing includes data that's sent from the standard telemetry modules, such as HTTP request collection and dependency collection.

Fügen Sie der Telemetrie Eigenschaften hinzu, indem Sie ITelemetryInitializer implementieren.Add properties to telemetry by implementing ITelemetryInitializer. Beispielsweise können Sie Versionsnummern oder Werte hinzufügen, die anhand von anderen Eigenschaften berechnet werden.For example, you can add version numbers or values that are calculated from other properties.

Mittels Filterung können Sie Telemetriedaten ändern oder verwerfen, bevor sie vom SDK gesendet werden. Implementieren Sie hierzu ITelemetryProcessor.Filtering can modify or discard telemetry before it's sent from the SDK by implementing ITelemetryProcessor. Sie steuern, was gesendet oder verworfen wird, aber Sie müssen die Auswirkung auf Ihre Metriken im Auge behalten.You control what is sent or discarded, but you have to account for the effect on your metrics. Je nach Vorgehensweise beim Verwerfen der Elemente kann es sein, dass Sie nicht mehr zwischen verwandten Elementen navigieren können.Depending on how you discard items, you might lose the ability to navigate between related items.

Erstellung von Stichproben ist eine sofort einsetzbare Methode, um das von Ihrer App an das Portal gesendete Datenvolumen zu reduzieren.Sampling is a packaged solution to reduce the volume of data that's sent from your app to the portal. Dies erfolgt ohne Auswirkung auf die angezeigten Metriken.It does so without affecting the displayed metrics. Außerdem hat dies keinerlei Auswirkungen auf die Fähigkeit, Probleme durch Navigieren zwischen verwandten Elementen wie Ausnahmen, Anforderungen und Seitenansichten zu diagnostizieren.And it does so without affecting your ability to diagnose problems by navigating between related items such as exceptions, requests, and page views.

Weitere InformationenLearn more.

Deaktivieren der TelemetrieDisabling telemetry

So können Sie die Sammlung und Übermittlung von Telemetriedaten dynamisch beenden und starten :To dynamically stop and start the collection and transmission of telemetry:

C#C#

using  Microsoft.ApplicationInsights.Extensibility;

TelemetryConfiguration.Active.DisableTelemetry = true;

JavaJava

telemetry.getConfiguration().setTrackingDisabled(true);

Um ausgewählte Standardsammlungsmodule zu deaktivieren, beispielsweise Leistungsindikatoren, HTTP-Anforderungen oder Abhängigkeiten, löschen Sie die entsprechenden Zeilen in ApplicationInsights.config oder kommentieren sie aus. Diese Vorgehensweise bietet sich beispielsweise an, wenn Sie Ihre eigenen TrackRequest-Daten senden möchten.To disable selected standard collectors--for example, performance counters, HTTP requests, or dependencies--delete or comment out the relevant lines in ApplicationInsights.config. You can do this, for example, if you want to send your own TrackRequest data.

Node.jsNode.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:To disable selected standard collectors--for example, performance counters, HTTP requests, or dependencies--at initialization time, chain configuration methods to your SDK initialization code:

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).To disable these collectors after initialization, use the Configuration object: applicationInsights.Configuration.setAutoCollectRequests(false)

EntwicklermodusDeveloper mode

Während des Debuggens ist es sinnvoll, die Telemetriedaten beschleunigt über die Pipeline zu senden, damit die Ergebnisse sofort angezeigt werden.During debugging, it's useful to have your telemetry expedited through the pipeline so that you can see results immediately. Sie erhalten außerdem zusätzliche Meldungen, mit denen Sie alle Probleme mit der Telemetrie verfolgen können.You also get additional messages that help you trace any problems with the telemetry. Schalten Sie ihn in der Produktion aus, da er Ihre App beeinträchtigen kann.Switch it off in production, because it may slow down your app.

C#C#

TelemetryConfiguration.Active.TelemetryChannel.DeveloperMode = true;

Visual BasicVisual Basic

TelemetryConfiguration.Active.TelemetryChannel.DeveloperMode = True

Node.jsNode.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.For Node.js, you can enable developer mode by enabling internal logging via setInternalLogging and setting maxBatchSize to 0, which causes your telemetry to be sent as soon as it is collected.

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

Festlegen des Instrumentationsschlüssels für ausgewählte benutzerdefinierte TelemetriedatenSetting the instrumentation key for selected custom telemetry

C#C#

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

Dynamischer InstrumentationsschlüsselDynamic instrumentation key

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.To avoid mixing up telemetry from development, test, and production environments, you can create separate Application Insights resources and change their keys, depending on the environment.

Statt den Instrumentationsschlüssel aus der Konfigurationsdatei abzurufen, können Sie ihn im Code festlegen.Instead of getting the instrumentation key from the configuration file, you can set it in your code. Legen Sie den Schlüssel in einer Initialisierungsmethode fest, wie z. B. "global.aspx.cs" in einem ASP.NET-Dienst:Set the key in an initialization method, such as global.aspx.cs in an ASP.NET service:

C#C#

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

JavaScriptJavaScript

appInsights.config.instrumentationKey = myKey;

Auf Webseiten empfiehlt es sich, ihn über den Zustand des Webservers festzulegen, anstatt ihn im Skript zu codieren.In webpages, you might want to set it from the web server's state, rather than coding it literally into the script. Beispielsweise auf einer Webseite, die in einer ASP.NET-App generiert wird:For example, in a webpage generated in an ASP.NET app:

JavaScript in RazorJavaScript 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);
    }

TelemetryContextTelemetryContext

TelemetryClient besitzt eine Context-Eigenschaft mit Werten, die zusammen mit allen Telemetriedaten gesendet werden.TelemetryClient has a Context property, which contains values that are sent along with all telemetry data. Sie werden normalerweise von den Standardtelemetriemodulen festgelegt, aber Sie können sie auch selbst einstellen.They are normally set by the standard telemetry modules, but you can also set them yourself. Beispiel:For example:

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

Wenn Sie diese Werte selbst festlegen, empfiehlt es sich, die entsprechende Zeile aus ApplicationInsights.config zu entfernen, damit kein Konflikt zwischen Ihren Werten und den Standardwerten entsteht.If you set any of these values yourself, consider removing the relevant line from ApplicationInsights.config, so that your values and the standard values don't get confused.

  • Component: Die App und ihre Version.Component: The app and its version.
  • Device: Daten zu dem Gerät, auf dem die App ausgeführt wird.Device: Data about the device where the app is running. (In Web-Apps ist dies das Server- oder Clientgerät, von dem die Telemetriedaten gesendet werden.)(In web apps, this is the server or client device that the telemetry is sent from.)
  • InstrumentationKey: Die Application Insights-Ressource in Azure, in der die Telemetriedaten angezeigt werden.InstrumentationKey: The Application Insights resource in Azure where the telemetry appears. In der Regel wird diese aus der Datei „ApplicationInsights.config“ übernommen.It's usually picked up from ApplicationInsights.config.
  • Standort: Der geografische Standort des Geräts.Location: The geographic location of the device.
  • Operation: In Web-Apps die aktuelle HTTP-Anforderung.Operation: In web apps, the current HTTP request. In anderen App-Typen können Sie dies zur Gruppierung von Ereignissen festlegen.In other app types, you can set this to group events together.
    • ID: Ein generierter Wert, der verschiedene Ereignisse korreliert, sodass Sie beim Untersuchen eines Ereignisses in der Diagnosesuche verwandte Elemente finden können.ID: A generated value that correlates different events, so that when you inspect any event in Diagnostic Search, you can find related items.
    • Name: Ein Bezeichner, in der Regel die URL der HTTP-Anforderung.Name: An identifier, usually the URL of the HTTP request.
    • SyntheticSource: Wenn diese Zeichenfolge nicht NULL oder leer ist, wird damit angegeben, dass die Quelle der Anforderung als Roboter oder Webtest identifiziert wurde.SyntheticSource: If not null or empty, a string that indicates that the source of the request has been identified as a robot or web test. Standardmäßig wird sie von Berechnungen im Metrik-Explorer ausgeschlossen.By default, it is excluded from calculations in Metrics Explorer.
  • Properties: Eigenschaften, die mit allen Telemetriedaten gesendet werden.Properties: Properties that are sent with all telemetry data. Kann in einzelnen Track*-Aufrufen außer Kraft gesetzt werden.It can be overridden in individual Track* calls.
  • Sitzung (Session) : Die Sitzung des Benutzers.Session: The user's session. Die ID wird auf einen generierten Wert festgelegt, der geändert wird, wenn der Benutzer für eine Weile nicht aktiv ist.The ID is set to a generated value, which is changed when the user has not been active for a while.
  • Benutzer: Benutzerinformationen.User: User information.

EinschränkungenLimits

Es gibt einige Grenzwerte hinsichtlich der Anzahl von Metriken und Ereignissen pro Anwendung (d. h. pro Instrumentationsschlüssel).There are some limits on the number of metrics and events per application, that is, per instrumentation key. Die Beschränkungen hängen von dem von Ihnen ausgewählten Tarif ab.Limits depend on the pricing plan that you choose.

ResourceResource StandardlimitDefault limit HinweisNote
Gesamtdaten pro TagTotal data per day 100 GB100 GB Die Datenmenge kann durch Festlegen einer Obergrenze reduziert werden.You can reduce data by setting a cap. Wird eine höhere Datenmenge benötigt, können Sie den Grenzwert im Portal auf bis zu 1.000 GB erhöhen.If you need more data, you can increase the limit in the portal, up to 1,000 GB. Bei Kapazitäten über 1.000 GB senden Sie eine E-Mail an AIDataCap@microsoft.com.For capacities greater than 1,000 GB, send email to AIDataCap@microsoft.com.
DrosselungThrottling 32.000 Ereignisse/s32,000 events/second Das Limit wird eine Minute lang gemessen.The limit is measured over a minute.
Beibehaltung von DatenData retention 30 – 730 Tage30 - 730 days Hierbei handelt es sich um eine Ressource für Suche, Analyse und Metrik-Explorer.This resource is for Search, Analytics, and Metrics Explorer.
Webtests in mehreren Schritten mit detaillierter ErgebnisaufbewahrungAvailability multi-step test detailed results retention 90 Tage90 days Diese Ressource liefert detaillierte Ergebnisse der einzelnen Schritte.This resource provides detailed results of each step.
Maximale Größe von TelemetrieelementenMaximum telemetry item size 64 KB64 kB
Maximale Anzahl von Telemetrieelementen pro BatchMaximum telemetry items per batch 64 K64 K
Eingenschaft und Länge der Namen von MetrikenProperty and metric name length 150150 Siehe Typschemas.See type schemas.
Zeichenfolgenlänge des EigenschaftswertsProperty value string length 8.1928,192 Siehe Typschemas.See type schemas.
Länge von Ablaufverfolgungs- und AusnahmebenachrichtigungenTrace and exception message length 32,76832,768 Siehe Typschemas.See type schemas.
Verfügbarkeitstests Anzahl pro AppAvailability tests count per app 100100
Vermerkdauer von Profiler-DatenProfiler data retention 5 Tage5 days
Pro Tag gesendete Profiler-DatenProfiler data sent per day 10 GB10 GB

Weitere Informationen zu Preisen und Kontingenten für Application Insights finden Sie hier.For more information, see About pricing and quotas in Application Insights.

Nutzen Sie die Stichprobenerstellung (Sampling), um zu vermeiden, dass Sie die Datenratengrenze erreichen.To avoid hitting the data rate limit, use sampling.

Informationen dazu, wie lange Daten aufbewahrt werden, finden Sie unter Datenspeicherung und Datenschutz.To determine how long data is kept, see Data retention and privacy.

ReferenzReference docs

SDK-CodeSDK code

FragenQuestions

  • Welche Ausnahmen werden möglicherweise von Aufrufen vom Typ „Track_()“ ausgelöst?What exceptions might Track_() calls throw?

    Keine.None. Sie müssen sie nicht mit try/catch-Klauseln umschließen.You don't need to wrap them in try-catch clauses. Wenn beim SDK Probleme auftreten, werden Meldungen in der Debugkonsolenausgabe und – sofern die Meldungen ankommen – in der Diagnosesuche protokolliert.If the SDK encounters problems, it will log messages in the debug console output and--if the messages get through--in Diagnostic Search.

  • Gibt es eine REST-API zum Abrufen von Daten aus dem Portal?Is there a REST API to get data from the portal?

    Ja, die Datenzugriffs-API.Yes, the data access API. Weitere Methoden zum Extrahieren von Daten stellen das Exportieren aus Analytics in Power BI und der fortlaufende Export dar.Other ways to extract data include export from Analytics to Power BI and continuous export.

Nächste SchritteNext steps