API Application Insights pour les événements et les mesures personnalisésApplication Insights API for custom events and metrics

Insérez quelques lignes de code dans votre application pour découvrir ce qu’en font les utilisateurs ou pour faciliter le diagnostic des problèmes.Insert a few lines of code in your application to find out what users are doing with it, or to help diagnose issues. Vous pouvez envoyer la télémétrie depuis des applications de périphérique et de bureau, des clients web et des serveurs web.You can send telemetry from device and desktop apps, web clients, and web servers. Utilisez l’API des données de télémétrie principales Azure Application Insights pour envoyer des événements et métriques personnalisés, ainsi que vos propres versions de la télémétrie standard.Use the Azure Application Insights core telemetry API to send custom events and metrics, and your own versions of standard telemetry. Cette API est la même que celle utilisée par les collecteurs de données standard d’Application Insights.This API is the same API that the standard Application Insights data collectors use.

Résumé des APIAPI summary

L’API principale est uniforme sur toutes les plateformes, à l’exception de quelques petites variantes telles que GetMetric (.NET uniquement).The core API is uniform across all platforms, apart from a few variations like GetMetric(.NET only).

MéthodeMethod Utilisé pourUsed for
TrackPageView Pages, écrans, panneaux ou formes.Pages, screens, blades, or forms.
TrackEvent Actions de l’utilisateur et autres événements.User actions and other events. Utilisé pour suivre le comportement de l’utilisateur ou pour analyser les performances.Used to track user behavior or to monitor performance.
GetMetric Zéro métrique et métriques multidimensionnels, agrégation configurée de manière centralisée, C# uniquement.Zero and multi-dimensional metrics, centrally configured aggregation, C# only.
TrackMetric Mesures de performances telles que la longueur des files d’attente non liées à des événements spécifiques.Performance measurements such as queue lengths not related to specific events.
TrackException Exceptions de journal pour des diagnostics.Logging exceptions for diagnosis. Effectuez un suivi lorsqu’ils se produisent par rapport à d’autres événements et examinez les arborescences des appels de procédure.Trace where they occur in relation to other events and examine stack traces.
TrackRequest Notez la fréquence et la durée des requêtes du serveur pour l’analyse des performances.Logging the frequency and duration of server requests for performance analysis.
TrackTrace Messages du journal de diagnostic des ressources.Resource Diagnostic log messages. Vous pouvez également capturer des journaux d’activité tiers.You can also capture third-party logs.
TrackDependency La journalisation de la durée et de la fréquence des appels vers les composants externes dont dépend votre application.Logging the duration and frequency of calls to external components that your app depends on.

Vous pouvez associer des propriétés et des mesures à la plupart de ces appels de télémétrie.You can attach properties and metrics to most of these telemetry calls.

Avant de commencerBefore you start

Si vous n’avez pas encore de référence sur le kit SDK Application Insights :If you don't have a reference on Application Insights SDK yet:

Obtenir une instance de TelemetryClientGet a TelemetryClient instance

Obtenez une instance de TelemetryClient (sauf en JavaScript dans les pages web) :Get an instance of TelemetryClient (except in JavaScript in webpages):

Pour les applications ASP.NET Core et non HTTP/Worker pour .NET/.NET Core, nous vous recommandons d’obtenir une instance de TelemetryClient à partir du conteneur d’injection de dépendances comme expliqué dans la documentation correspondante.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.

Si vous utilisez Azure Functions v2+ ou Azure WebJobs v3+, consultez ce document : 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();

Si vous constatez que cette méthode contient des messages obsolètes, consultez microsoft/ApplicationInsights-dotnet#1152 pour plus d’informations.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 est thread-safe.TelemetryClient is thread-safe.

Dans le cas des projets ASP.NET et Java, les requêtes HTTP entrantes sont automatiquement capturées.For ASP.NET and Java projects, incoming HTTP Requests are automatically captured. Si vous le souhaitez, vous pouvez créer des instances supplémentaires de TelemetryClient pour l’autre module de votre application.You might want to create additional instances of TelemetryClient for other module of your app. Il est par exemple possible d’en avoir une dans une classe d’intergiciels pour signaler les événements de logique métier.For instance, you may have one TelemetryClient instance in your middleware class to report business logic events. Vous pouvez définir des propriétés comme UserId et DeviceId pour identifier l’ordinateur.You can set properties such as UserId and DeviceId to identify the machine. Cette information est associée à tous les événements envoyés par l'instance.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("...");

Dans les projets Node.js, vous pouvez utiliser new applicationInsights.TelemetryClient(instrumentationKey?) pour créer une instance, mais cette procédure est réservée aux scénarios qui nécessitent une configuration isolée du singleton defaultClient.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

Dans Application Insights, un événement personnalisé est un point de données que vous pouvez afficher dans Metrics Explorer en tant que nombre agrégé et dans Recherche de diagnostic en tant qu’occurrences individuelles.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. (Il n’est pas lié à des « événements » de type MVC ou autres.)(It isn't related to MVC or other framework "events.")

Insérez des appels TrackEvent dans votre code pour compter les différents événements.Insert TrackEvent calls in your code to count various events. Par exemple, la fréquence à laquelle les utilisateurs choisissent une fonctionnalité particulière, la fréquence à laquelle ils atteignent des objectifs particuliers ou à laquelle ils commettent éventuellement des types d’erreurs particuliers.How often users choose a particular feature, how often they achieve particular goals, or maybe how often they make particular types of mistakes.

Par exemple, dans une application de jeu, envoyez un événement chaque fois qu'un utilisateur gagne le jeu :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"});

Événements personnalisés dans l’analytiqueCustom events in Analytics

La télémétrie est disponible dans la table customEvents dans Application Insights - Analytique.The telemetry is available in the customEvents table in Application Insights Analytics. Chaque ligne représente un appel à trackEvent(..) dans votre application.Each row represents a call to trackEvent(..) in your app.

Si un échantillonnage est en cours, la propriété itemCount affiche une valeur supérieure à 1.If sampling is in operation, the itemCount property shows a value greater than 1. Par exemple, itemCount==10 signifie que sur 10 appels à trackEvent(), le processus d’échantillonnage n’en a transmis qu’un seul.For example itemCount==10 means that of 10 calls to trackEvent(), the sampling process only transmitted one of them. Pour obtenir un nombre correct d’événements personnalisés, vous devez donc utiliser un code similaire à customEvents | summarize sum(itemCount).To get a correct count of custom events, you should therefore use code such as customEvents | summarize sum(itemCount).

GetMetricGetMetric

Pour découvrir comment utiliser efficacement l’appel GetMetric() afin de capturer des métriques pré-agrégées localement pour les applications .NET et .NET Core, consultez la documentation de 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

Notes

La méthode Microsoft.ApplicationInsights.TelemetryClient.TrackMetric n’est pas la méthode recommandée pour l’envoi de mesures.Microsoft.ApplicationInsights.TelemetryClient.TrackMetric is not the preferred method for sending metrics. Les métriques doivent toujours être pré-agrégés au cours d’une période spécifique avant d’être envoyés.Metrics should always be pre-aggregated across a time period before being sent. Utilisez l’une des surcharges GetMetric(..) afin d’obtenir un objet de métrique pour accéder aux fonctionnalités de pré-agrégation du Kit de développement logiciel (SDK).Use one of the GetMetric(..) overloads to get a metric object for accessing SDK pre-aggregation capabilities. Si vous implémentez votre propre logique de pré-agrégation, vous pouvez utiliser la méthode TrackMetric() pour envoyer les agrégats résultants.If you are implementing your own pre-aggregation logic, you can use the TrackMetric() method to send the resulting aggregates. Si votre application requiert l’envoi systématique d’un élément de télémétrie distinct sans agrégation au fil du temps, il s’agit probablement d’un cas d’usage de télémétrie d’événement ; consultez la méthode 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).

Application Insight peut représenter des mesures qui ne sont pas associées à des événements particuliers.Application Insights can chart metrics that are not attached to particular events. Par exemple, vous pouvez analyser la longueur d’une file d'attente à des intervalles réguliers.For example, you could monitor a queue length at regular intervals. Avec les mesures, les mesures individuelles sont moins intéressantes que les variations et tendances, ainsi les graphiques statistiques sont utiles.With metrics, the individual measurements are of less interest than the variations and trends, and so statistical charts are useful.

Pour pouvoir envoyer des métriques à Application Insights, vous pouvez utiliser l’API TrackMetric(..).In order to send metrics to Application Insights, you can use the TrackMetric(..) API. Il existe deux façons d’envoyer une métrique :There are two ways to send a metric:

  • Valeur unique.Single value. Chaque fois que vous effectuez une mesure dans votre application, vous envoyez la valeur correspondante à Application Insights.Every time you perform a measurement in your application, you send the corresponding value to Application Insights. Par exemple, supposons que vous avez une mesure décrivant le nombre d’éléments dans un conteneur.For example, assume that you have a metric describing the number of items in a container. Pendant une période donnée, vous placez d’abord trois éléments dans le conteneur puis vous en supprimez deux.During a particular time period, you first put three items into the container and then you remove two items. En conséquence, vous appelez TrackMetric à deux reprises : d’abord en passant la valeur 3 puis la valeur -2.Accordingly, you would call TrackMetric twice: first passing the value 3 and then the value -2. Application Insights stocke les deux valeurs pour votre compte.Application Insights stores both values on your behalf.

  • Agrégation.Aggregation. Quand vous travaillez avec des métriques, chaque mesure individuelle est rarement intéressante.When working with metrics, every single measurement is rarely of interest. Au lieu de cela, un récapitulatif de ce qui s’est passé au cours d’une période donnée est important.Instead a summary of what happened during a particular time period is important. Un tel récapitulatif est appelé agrégation.Such a summary is called aggregation. Dans l’exemple ci-dessus, la somme totale des métriques pour cette période est 1 et le nombre de valeurs des métriques est 2.In the above example, the aggregate metric sum for that time period is 1 and the count of the metric values is 2. Quand vous utilisez l’approche par agrégation, vous appelez TrackMetric une seule fois par période et vous envoyez les valeurs agrégées.When using the aggregation approach, you only invoke TrackMetric once per time period and send the aggregate values. C’est l’approche recommandée, car elle peut réduire considérablement le coût et les problèmes de performances en envoyant moins de points de données à Application Insights, tout en collectant néanmoins toutes les informations pertinentes.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.

ExemplesExamples

Valeurs uniquesSingle values

Pour envoyer une seule valeur métrique :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});

Métriques personnalisées dans AnalyticsCustom metrics in Analytics

La télémétrie est disponible dans la table customMetrics dans Application Insights - Analytique.The telemetry is available in the customMetrics table in Application Insights Analytics. Chaque ligne représente un appel à trackMetric(..) dans votre application.Each row represents a call to trackMetric(..) in your app.

  • valueSum - Il s’agit de la somme des mesures.valueSum - This is the sum of the measurements. Pour obtenir la valeur moyenne, divisez par valueCount.To get the mean value, divide by valueCount.
  • valueCount : le nombre de mesures qui ont été agrégées dans cet appel de trackMetric(..).valueCount - The number of measurements that were aggregated into this trackMetric(..) call.

Affichages de pagePage views

Dans un périphérique ou une application de page web, la télémétrie d'affichage de page est envoyée par défaut lorsque chaque écran ou page est chargé.In a device or webpage app, page view telemetry is sent by default when each screen or page is loaded. Mais vous pouvez modifier cela pour suivre les affichages de page à différents moments.But you can change that to track page views at additional or different times. Par exemple, dans une application qui affiche les onglets ou les panneaux, vous pouvez effectuer le suivi d'une « page » chaque fois que l'utilisateur ouvre un nouveau panneau.For example, in an app that displays tabs or blades, you might want to track a page whenever the user opens a new blade.

Les données d’utilisateur et de session sont envoyées en tant que propriétés avec les affichages de page, de façon à ce que les graphiques d’utilisateur et de session soient actifs s’il existe une télémétrie de l’affichage de page.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.

Affichages de pages personnaliséesCustom page views

JavaScriptJavaScript

appInsights.trackPageView("tab1");

C#C#

telemetry.TrackPageView("GameReviewPage");

Visual BasicVisual Basic

telemetry.TrackPageView("GameReviewPage")

JavaJava

telemetry.trackPageView("GameReviewPage");

Si vous avez plusieurs onglets dans différentes pages HTML, vous pouvez aussi spécifier l'URL :If you have several tabs within different HTML pages, you can specify the URL too:

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

Affichages de la page de duréeTiming page views

Par défaut, les heures déclarées Temps de chargement de l’affichage de la page sont mesurées à partir du moment où le navigateur envoie la demande, jusqu’à ce que l’événement de chargement de la page du navigateur soit appelé.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.

Au lieu de cela, vous pouvez :Instead, you can either:

  • Définir une durée explicite dans l’appel trackPageView : appInsights.trackPageView("tab1", null, null, null, durationInMilliseconds);.Set an explicit duration in the trackPageView call: appInsights.trackPageView("tab1", null, null, null, durationInMilliseconds);.
  • Utiliser les appels de minutage d’affichage de la page startTrackPage et stopTrackPage.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);

Le nom que vous utilisez comme premier paramètre associe les appels de démarrage et d’arrêt.The name that you use as the first parameter associates the start and stop calls. Le nom de la page actuelle est utilisé par défaut.It defaults to the current page name.

Les durées de chargement de la page résultantes affichées dans Metrics Explorer sont dérivées de l’intervalle entre les appels de démarrage et d’arrêt.The resulting page load durations displayed in Metrics Explorer are derived from the interval between the start and stop calls. C’est à vous de décider quel intervalle de temps vous voulez mesurer.It's up to you what interval you actually time.

Télémétrie des pages dans AnalytiquePage telemetry in Analytics

Dans Analytique, deux tables affichent les données des opérations du navigateur :In Analytics two tables show data from browser operations:

  • La table pageViews contient des données sur l’URL et le titre de la page.The pageViews table contains data about the URL and page title
  • La table browserTimings contient des données sur les performances du client, comme le temps nécessaire pour traiter les données entrantes.The browserTimings table contains data about client performance, such as the time taken to process the incoming data

Pour trouver le temps mis par le navigateur pour traiter différentes pages :To find how long the browser takes to process different pages:

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

Pour découvrir la popularité de différents navigateurs :To discover the popularities of different browsers:

pageViews
| summarize count() by client_Browser

Pour associer des vues de pages à des appels AJAX, joindre à des dépendances :To associate page views to AJAX calls, join with dependencies:

pageViews
| join (dependencies) on operation_Id 

TrackRequestTrackRequest

Le kit de développement logiciel de serveur utilise TrackRequest pour consigner les requêtes HTTP.The server SDK uses TrackRequest to log HTTP requests.

Vous pouvez également l'appeler vous-même si vous souhaitez simuler des requêtes dans le cas où le module du service web n’est pas en cours d'exécution.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.

Toutefois, le moyen recommandé d’envoyer la télémétrie de la demande est là où la demande agit comme un contexte d’opération.However, the recommended way to send request telemetry is where the request acts as an operation context.

Contexte de l’opérationOperation context

Vous pouvez associer des éléments de télémétrie en les associant à un contexte d’opération.You can correlate telemetry items together by associating them with operation context. Le module de suivi de requête standard effectue cette opération pour les exceptions et les autres événements envoyés lors du traitement d’une requête HTTP.The standard request-tracking module does this for exceptions and other events that are sent while an HTTP request is being processed. Dans Recherche et Analytique, vous pouvez trouver facilement tous les événements associés à la requête avec son ID d’opération.In Search and Analytics, you can easily find any events associated with the request using its operation ID.

Consultez Corrélation de télémétrie dans Application Insights pour plus d’informations sur la corrélation.See Telemetry correlation in Application Insights for more details on correlation.

Lors du suivi manuel des données de télémétrie, le moyen le plus simple pour vous assurer de la corrélation des données de télémétrie en utilisant ce modèle :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.

Outre la définition d’un contexte d’opération, StartOperation crée un élément de télémétrie du type que vous spécifiez.Along with setting an operation context, StartOperation creates a telemetry item of the type that you specify. Il envoie l’élément de télémétrie lorsque vous libérez l’opération, ou si vous appelez explicitement StopOperation.It sends the telemetry item when you dispose the operation, or if you explicitly call StopOperation. Si vous utilisez RequestTelemetry comme type de télémétrie, alors sa durée est définie sur l’intervalle compris entre le début et la fin.If you use RequestTelemetry as the telemetry type, its duration is set to the timed interval between start and stop.

Les éléments de télémétrie signalés dans une étendue de l’opération deviennent « enfants » de cette opération.Telemetry items reported within a scope of operation become 'children' of such operation. Les contextes de l’opération ne peuvent pas être imbriqués.Operation contexts could be nested.

Dans Recherche, le contexte d’opération est utilisé pour créer la liste Éléments connexes :In Search, the operation context is used to create the Related Items list:

Éléments connexes

Consultez Suivi des opérations personnalisées avec le kit SDK .NET d’Application Insights pour plus d’informations sur le suivi des opérations personnalisées.See Track custom operations with Application Insights .NET SDK for more information on custom operations tracking.

Requêtes dans AnalytiqueRequests in Analytics

Dans Application Insights - Analytique, les demandes s’affichent dans la table requests.In Application Insights Analytics, requests show up in the requests table.

Si l’échantillonnage est en cours, la propriété itemCount affiche une valeur supérieure à 1.If sampling is in operation, the itemCount property will show a value greater than 1. Par exemple, itemCount==10 signifie que sur 10 appels à trackRequest(), le processus d’échantillonnage n’en a transmis qu’un seul.For example itemCount==10 means that of 10 calls to trackRequest(), the sampling process only transmitted one of them. Pour obtenir un nombre correct de demandes et une durée moyenne segmentée par nom des demandes, utilisez un code similaire à celui-ci :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

Envoi d’exceptions à Application Insights :Send exceptions to Application Insights:

Les rapports incluent des arborescences des appels de procédure.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});
}

Les Kits de développement logiciel (SDK) interceptent de nombreuses exceptions automatiquement, ce qui vous évite ainsi d’avoir toujours à appeler TrackException explicitement.The SDKs catch many exceptions automatically, so you don't always have to call TrackException explicitly.

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

Exceptions dans AnalytiqueExceptions in Analytics

Dans Application Insights - Analytique, les exceptions s’affichent dans la table exceptions.In Application Insights Analytics, exceptions show up in the exceptions table.

Si un échantillonnage est en cours, la propriété itemCount affiche une valeur supérieure à 1.If sampling is in operation, the itemCount property shows a value greater than 1. Par exemple, itemCount==10 signifie que sur 10 appels à trackException(), le processus d’échantillonnage n’en a transmis qu’un seul.For example itemCount==10 means that of 10 calls to trackException(), the sampling process only transmitted one of them. Pour obtenir un nombre correct d’exceptions segmentées par type d’exception, utilisez un code similaire à celui-ci :To get a correct count of exceptions segmented by type of exception, use code such as:

exceptions
| summarize sum(itemCount) by type

La plupart des informations importantes sur la pile sont déjà extraites dans des variables distinctes, mais vous pouvez extraire séparément la structure details pour en savoir plus.Most of the important stack information is already extracted into separate variables, but you can pull apart the details structure to get more. Comme cette structure est dynamique, vous devez effectuer une conversion de type (transtypage) du résultat vers le type attendu.Since this structure is dynamic, you should cast the result to the type you expect. Par exemple :For example:

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

Pour associer des exceptions aux demandes qui s’y rapportent, utilisez une jointure :To associate exceptions with their related requests, use a join:

exceptions
| join (requests) on operation_Id

TrackTraceTrackTrace

Utilisez TrackTrace pour diagnostiquer des problèmes en envoyant une « piste de navigation » à Application Insights.Use TrackTrace to help diagnose problems by sending a "breadcrumb trail" to Application Insights. Vous pouvez envoyer des blocs de données de diagnostic et les examiner dans la Recherche de diagnostic.You can send chunks of diagnostic data and inspect them in Diagnostic Search.

Dans .NET, les Adaptateurs de journaux d’activité utilisent cette API pour envoyer des journaux d’activité tiers au portail.In .NET Log adapters use this API to send third-party logs to the portal.

En Java, pour les Enregistreurs d’événements standard, comme Log4J ou Logback, utilisez les appenders Application Insights Log4j ou Logback afin d’envoyer des journaux d’activité tiers au portail.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
});

JavaScript côté client/navigateurClient/Browser-side JavaScript

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

Enregistrer un événement de diagnostic comme l'utilisation ou la non-utilisation d'une méthode.Log a diagnostic event such as entering or leaving a method.

ParamètreParameter DescriptionDescription
message Données de diagnostic.Diagnostic data. Peut être plus longue qu'un nom.Can be much longer than a name.
properties Mappage de chaîne à chaîne : Données supplémentaires utilisées pour filtrer les exceptions dans le portail.Map of string to string: Additional data used to filter exceptions in the portal. Vide par défaut.Defaults to empty.
severityLevel Valeurs prises en charge : SeverityLevel.tsSupported values: SeverityLevel.ts

Vous pouvez effectuer une recherche dans le contenu du message, mais (contrairement aux valeurs de propriété), vous ne pouvez pas les filtrer.You can search on message content, but (unlike property values) you can't filter on it.

La limite de taille sur message est plus importante que la limite des propriétés.The size limit on message is much higher than the limit on properties. l’un des avantages de TrackTrace est que vous pouvez insérer des données relativement longues dans le message.An advantage of TrackTrace is that you can put relatively long data in the message. Par exemple, vous pourriez y encoder des données POST.For example, you can encode POST data there.

Par ailleurs, vous pouvez ajouter un niveau de gravité à votre message.In addition, you can add a severity level to your message. Comme pour les autres données de télémétrie, vous pouvez également ajouter des valeurs de propriété qui permettent de filtrer ou rechercher différents jeux de traces.And, like other telemetry, you can add property values to help you filter or search for different sets of traces. Par exemple :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);

Dans Recherche, vous pouvez filtrer facilement tous les messages d’un niveau de gravité particulier portant sur une certaine base de données.In Search, you can then easily filter out all the messages of a particular severity level that relate to a particular database.

Traces dans AnalytiqueTraces in Analytics

Dans Application Insights - Analytique, les appels à TrackTrace s’affichent dans la table traces.In Application Insights Analytics, calls to TrackTrace show up in the traces table.

Si un échantillonnage est en cours, la propriété itemCount affiche une valeur supérieure à 1.If sampling is in operation, the itemCount property shows a value greater than 1. Par exemple, itemCount==10 signifie que sur 10 appels à trackTrace(), le processus d’échantillonnage n’en a transmis qu’un seul.For example itemCount==10 means that of 10 calls to trackTrace(), the sampling process only transmitted one of them. Pour obtenir un nombre correct d’appels de trace, vous devez utiliser un code similaire à traces | summarize sum(itemCount).To get a correct count of trace calls, you should use therefore code such as traces | summarize sum(itemCount).

TrackDependencyTrackDependency

Utilisez l’appel à TrackDependency pour suivre les temps de réponse et les taux de réussite des appels vers un bloc de code externe.Use the TrackDependency call to track the response times and success rates of calls to an external piece of code. Les résultats s'affichent dans les graphiques de dépendance sur le portail.The results appear in the dependency charts in the portal. L’extrait de code ci-dessous doit être ajouté chaque fois qu’un appel de dépendance est effectué.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
    });
}

N’oubliez pas que les kits SDK de serveur incluent un module de dépendance qui détecte certains appels de dépendance et en effectue le suivi automatiquement. C’est notamment le cas des bases de données et des API REST.Remember that the server SDKs include a dependency module that discovers and tracks certain dependency calls automatically--for example, to databases and REST APIs. Vous devez installer un agent sur votre serveur pour que le module fonctionne.You have to install an agent on your server to make the module work.

En Java, l’Agent Java permet de suivre automatiquement certains appels de dépendance.In Java, certain dependency calls can be automatically tracked using Java Agent.

Vous utiliserez cet appel si vous souhaitez effectuer le suivi des appels qui ne sont pas interceptés par le système de suivi automatisé, ou si vous ne souhaitez pas installer l'agent.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.

Pour désactiver le module de suivi des dépendances standard en C#, modifiez ApplicationInsights.config et supprimez la référence à DependencyCollector.DependencyTrackingTelemetryModule.To turn off the standard dependency-tracking module in C#, edit ApplicationInsights.config and delete the reference to DependencyCollector.DependencyTrackingTelemetryModule. En Java, n’installez pas l’agent Java si vous ne souhaitez pas collecter automatiquement les dépendances standards.In Java, please do not install java agent if you do not want to collect standard dependencies automatically.

Dépendances dans AnalytiqueDependencies in Analytics

Dans Application Insights - Analytique, les appels de trackDependency s’affichent dans la table dependencies.In Application Insights Analytics, trackDependency calls show up in the dependencies table.

Si un échantillonnage est en cours, la propriété itemCount affiche une valeur supérieure à 1.If sampling is in operation, the itemCount property shows a value greater than 1. Par exemple, itemCount==10 signifie que sur 10 appels à trackDependency(), le processus d’échantillonnage n’en a transmis qu’un seul.For example itemCount==10 means that of 10 calls to trackDependency(), the sampling process only transmitted one of them. Pour obtenir un nombre correct de dépendances segmentées par composant cible, utilisez un code similaire à celui-ci :To get a correct count of dependencies segmented by target component, use code such as:

dependencies
| summarize sum(itemCount) by target

Pour associer des dépendances aux demandes qui s’y rapportent, utilisez une jointure :To associate dependencies with their related requests, use a join:

dependencies
| join (requests) on operation_Id

Vidage des donnéesFlushing data

Normalement, le Kit de développement logiciel (SDK) envoie des données à intervalles réguliers (généralement 30 secondes), ou chaque fois que la mémoire tampon est saturée (en général, lorsqu’elle inclut plus de 500 éléments).Normally, the SDK sends data at fixed intervals (typically 30 secs) or whenever buffer is full (typically 500 items). Toutefois, dans certains cas vous pouvez vider la mémoire tampon - par exemple, si vous utilisez le kit SDK dans une application qui s'arrête.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();

La fonction est asynchrone pour le canal de télémétrie du serveur.The function is asynchronous for the server telemetry channel.

Dans l’idéal, il est recommandé d’utiliser la méthode flush() dans l’activité d’arrêt de l’application.Ideally, flush() method should be used in the shutdown activity of the Application.

Utilisateurs authentifiésAuthenticated users

Dans une application web, les utilisateurs sont identifiés par des cookies (par défaut).In a web app, users are (by default) identified by cookies. Un utilisateur peut être compté plusieurs fois s’il accède à votre application à partir d’un autre ordinateur ou navigateur, ou s’il supprime des cookies.A user might be counted more than once if they access your app from a different machine or browser, or if they delete cookies.

Mais si les utilisateurs se connectent à votre application, vous pouvez obtenir un nombre plus précis en définissant l’ID de l’utilisateur authentifié dans le code du navigateur :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);
    ...
}

Dans une application MVC Web ASP.NET, par exemple :In an ASP.NET web MVC application, for example:

RazorRazor

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

Il n’est pas nécessaire d’utiliser le nom de connexion réel de l’utilisateur.It isn't necessary to use the user's actual sign-in name. Il doit uniquement s’agir d’un ID unique pour cet utilisateur.It only has to be an ID that is unique to that user. Il ne doit pas inclure d'espaces ni l'un des caractères suivants : ,;=|.It must not include spaces or any of the characters ,;=|.

L’ID d’utilisateur est également défini dans un cookie de session et envoyé au serveur.The user ID is also set in a session cookie and sent to the server. Si le kit SDK de serveur est installé, l’ID d’utilisateur authentifié est envoyé dans le cadre des propriétés de contexte de télémétrie client et serveur.If the server SDK is installed, the authenticated user ID is sent as part of the context properties of both client and server telemetry. Vous pouvez ensuite filtrer et rechercher dessus.You can then filter and search on it.

Si votre application regroupe les utilisateurs par comptes, vous pouvez également fournir un identificateur pour ce compte (avec les mêmes restrictions de caractères).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);

Dans Metrics Explorer, vous pouvez créer un graphique qui compte les Utilisateurs authentifiés et les Comptes d’utilisateur.In Metrics Explorer, you can create a chart that counts Users, Authenticated, and User accounts.

Vous pouvez également rechercher les points de données client avec des comptes et des noms d’utilisateur spécifiques.You can also Search for client data points with specific user names and accounts.

Filtrage, recherche et segmentation de vos données à l’aide des propriétésFiltering, searching, and segmenting your data by using properties

Vous pouvez associer des propriétés et des mesures à vos événements (et également à des mesures, des affichages de page, des exceptions et d'autres données de télémétrie).You can attach properties and measurements to your events (and also to metrics, page views, exceptions, and other telemetry data).

propriétés sont des valeurs de chaîne que vous pouvez utiliser pour filtrer votre télémétrie dans les rapports d'utilisation.Properties are string values that you can use to filter your telemetry in the usage reports. Par exemple, si votre application fournit plusieurs jeux, vous pouvez attacher le nom du jeu à chaque événement pour vous permettre de savoir quels sont les jeux les plus populaires.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.

Il existe une limite de 8192 sur la longueur de chaîne.There's a limit of 8192 on the string length. (Si vous souhaitez envoyer d’importants blocs de données, utilisez le paramètre de message de TrackTrace.)(If you want to send large chunks of data, use the message parameter of TrackTrace.)

mesures sont des valeurs numériques qui peuvent être représentées sous forme graphique.Metrics are numeric values that can be presented graphically. Par exemple, observez s'il existe une augmentation progressive des scores atteints par vos joueurs.For example, you might want to see if there's a gradual increase in the scores that your gamers achieve. Les graphes peuvent être segmentés par les propriétés envoyées avec l'événement pour vous permettre d’obtenir des graphes distincts ou empilés pour différents jeux.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.

Pour que les valeurs de mesure s’affichent correctement, elles doivent être supérieures ou égales à 0.For metric values to be correctly displayed, they should be greater than or equal to 0.

Il existe certaines limites au nombre de propriétés, de valeurs de propriété et de mesures que vous pouvez utiliser.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);

Notes

Veillez à ne pas journaliser des informations personnelles dans les propriétés.Take care not to log personally identifiable information in properties.

Autre façon de définir des propriétés et des mesuresAlternative way to set properties and metrics

Si cela est plus pratique, vous pouvez collecter les paramètres d'un événement dans un objet séparé :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);

Avertissement

Ne réutilisez pas la même instance d’élément de télémétrie (event dans cet exemple) pour appeler Track*() plusieurs fois.Don't reuse the same telemetry item instance (event in this example) to call Track*() multiple times. Cela peut provoquer un envoi de données de télémétrie configurées de façon incorrecte.This may cause telemetry to be sent with incorrect configuration.

Mesures et propriétés personnalisées dans AnalytiqueCustom measurements and properties in Analytics

Dans Analytique, les mesures et les propriétés personnalisées s’affichent dans les attributs customMeasurements et customDimensions de chaque enregistrement de télémétrie.In Analytics, custom metrics and properties show in the customMeasurements and customDimensions attributes of each telemetry record.

Par exemple, si vous avez ajouté une propriété nommée « game » à votre télémétrie des demandes, cette requête compte les occurrences des différentes valeurs de « game » et affiche la moyenne de la métrique personnalisée « score » :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)

Notez que :Notice that:

  • Quand vous extrayez une valeur du JSON la customDimensions ou customMeasurements, elle est de type dynamique et par conséquent, vous devez la transtyper en tostring ou todouble.When you extract a value from the customDimensions or customMeasurements JSON, it has dynamic type, and so you must cast it tostring or todouble.
  • Pour tenir compte de la possibilité d’échantillonnage, vous devez utiliser sum(itemCount), et non pas count().To take account of the possibility of sampling, you should use sum(itemCount), not count().

Événements de duréeTiming events

Vous avez parfois besoin d’obtenir une représentation graphique de la durée nécessaire à la réalisation d’une action.Sometimes you want to chart how long it takes to perform an action. Par exemple, vous souhaitez savoir de combien de temps les utilisateurs ont besoin pour évaluer leurs choix dans un jeu.For example, you might want to know how long users take to consider choices in a game. Vous pouvez utiliser le paramètre de mesure pour cela.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);

Propriétés par défaut pour la télémétrie personnaliséeDefault properties for custom telemetry

Si vous souhaitez définir des valeurs de propriété par défaut pour certains des événements personnalisés que vous écrivez, vous pouvez les définir dans une instance de TelemetryClient.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. Ils sont associés à chaque élément de télémétrie envoyée à partir de ce client.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"});

Les appels de télémétrie individuels peuvent remplacer les valeurs par défaut dans leurs dictionnaires de propriété.Individual telemetry calls can override the default values in their property dictionaries.

Pour les clients Web JavaScript, utilisez des initialiseurs de télémétrie JavaScript.For JavaScript web clients, use JavaScript telemetry initializers.

Pour ajouter des propriétés à toutes les données de télémétrie, notamment les données des modules de collecte standard, implémentez ITelemetryInitializer.To add properties to all telemetry, including the data from standard collection modules, implement ITelemetryInitializer.

Échantillonnage, filtrage et traitement de la télémétrieSampling, filtering, and processing telemetry

Vous pouvez écrire du code pour traiter votre télémétrie avant de l’envoyer à partir du Kit de développement logiciel (SDK).You can write code to process your telemetry before it's sent from the SDK. Le traitement inclut les données envoyées par les modules de télémétrie standard, telles que la collection de requêtes HTTP et la collection de dépendances.The processing includes data that's sent from the standard telemetry modules, such as HTTP request collection and dependency collection.

Ajoutez des propriétés à la télémétrie en implémentant ITelemetryInitializer.Add properties to telemetry by implementing ITelemetryInitializer. Par exemple, vous pouvez ajouter des numéros de version ou des valeurs calculées à partir d'autres propriétés.For example, you can add version numbers or values that are calculated from other properties.

Le filtrage peut modifier ou abandonner des données de télémétrie avant leur envoi depuis le SDK en implémentant ITelemetryProcessor.Filtering can modify or discard telemetry before it's sent from the SDK by implementing ITelemetryProcessor. Vous contrôlez ce qui est envoyé ou rejeté, mais vous devez prendre en compte l’impact sur vos mesures.You control what is sent or discarded, but you have to account for the effect on your metrics. Suivant la façon dont vous ignorez les éléments, vous risquez de ne plus pouvoir naviguer entre des éléments connexes.Depending on how you discard items, you might lose the ability to navigate between related items.

L’échantillonnage est une solution intégrée pour réduire le volume des données envoyées à partir de votre application vers le portail.Sampling is a packaged solution to reduce the volume of data that's sent from your app to the portal. Cela n’affecte pas les mesures affichées.It does so without affecting the displayed metrics. Et il n’affecte pas votre capacité à diagnostiquer les problèmes en navigant entre des éléments connexes, tels que les exceptions, les requêtes et les affichages de page.And it does so without affecting your ability to diagnose problems by navigating between related items such as exceptions, requests, and page views.

Plus d’informationsLearn more.

Désactivation de la télémétrieDisabling telemetry

Pour arrêter et démarrer dynamiquement la collecte et la transmission de la télémétrie :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);

Pour désactiver les collecteurs standard sélectionnés (par exemple, les compteurs de performances, les requêtes HTTP ou les dépendances), supprimez ou commentez les lignes correspondantes dans ApplicationInsights.config. Par exemple, vous pouvez faire cela si vous souhaitez envoyer vos propres données TrackRequest.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;

Pour désactiver les collecteurs standard sélectionnés (par exemple, les compteurs de performances, les requêtes HTTP ou les dépendances) lors de l’initialisation, enchaînez plusieurs méthodes de configuration dans votre code d’initialisation SDK.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();

Pour désactiver ces collecteurs après l’initialisation, utilisez l’objet de configuration : applicationInsights.Configuration.setAutoCollectRequests(false)To disable these collectors after initialization, use the Configuration object: applicationInsights.Configuration.setAutoCollectRequests(false)

Mode Développeur :Developer mode

Pendant le débogage, il est utile d'avoir votre télémétrie envoyée par le pipeline afin que vous puissiez voir immédiatement les résultats.During debugging, it's useful to have your telemetry expedited through the pipeline so that you can see results immediately. Vous obtenez également des messages supplémentaires qui vous permettent de suivre tout problème relatif à la télémétrie.You also get additional messages that help you trace any problems with the telemetry. Désactivez-les lors de la production, car ils peuvent ralentir votre application.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

Pour Node.js, vous pouvez activer le mode développeur en activant la journalisation interne via setInternalLogging et en définissant le paramètre maxBatchSize sur 0, ce qui entraîne l’envoi de votre télémétrie dès qu’elle est collectée.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;

Définition de la touche d’instrumentation pour la télémétrie personnalisée sélectionnéeSetting the instrumentation key for selected custom telemetry

C#C#

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

Clé d'instrumentation dynamiqueDynamic instrumentation key

Pour éviter de mélanger la télémétrie fournie par les environnements de développement, de test et de production, vous pouvez créer des ressources Application Insights distinctes et modifier leurs clés en fonction de l’environnement.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.

Au lieu de récupérer la clé d'instrumentation à partir du fichier de configuration, vous pouvez la définir dans votre code.Instead of getting the instrumentation key from the configuration file, you can set it in your code. Définissez la clé dans une méthode d'initialisation, par exemple global.aspx.cs dans un service ASP.NET :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;

Dans les pages web, vous pouvez la définir depuis l'état du serveur web au lieu de la coder littéralement dans le script.In webpages, you might want to set it from the web server's state, rather than coding it literally into the script. Par exemple, dans une page web générée dans une application ASP.NET :For example, in a webpage generated in an ASP.NET app:

JavaScript dans 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 a une propriété de contexte contenant les valeurs qui sont envoyées avec toutes les données de télémétrie.TelemetryClient has a Context property, which contains values that are sent along with all telemetry data. Elles sont normalement définies par les modules de télémétrie standard, mais vous pouvez également les définir vous-même.They are normally set by the standard telemetry modules, but you can also set them yourself. Par exemple :For example:

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

Si vous définissez une de ces valeurs vous-même, supprimez la ligne appropriée dans ApplicationInsights.config, pour ne pas mélanger vos valeurs et les valeurs standard.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.

  • Composant : l’application et sa version.Component: The app and its version.
  • Appareil : données concernant l’appareil sur lequel l’application s’exécute.Device: Data about the device where the app is running. (dans les applications web, il s’agit du serveur ou de l’appareil client depuis lequel la télémétrie est envoyée.)(In web apps, this is the server or client device that the telemetry is sent from.)
  • InstrumentationKey : la ressource Application Insights dans Azure dans laquelle la télémétrie s’affiche.InstrumentationKey: The Application Insights resource in Azure where the telemetry appears. Elle est généralement récupérée dans ApplicationInsights.config.It's usually picked up from ApplicationInsights.config.
  • Emplacement : emplacement géographique de l’appareil.Location: The geographic location of the device.
  • Opération : dans les applications web, il s’agit de la requête HTTP actuelle.Operation: In web apps, the current HTTP request. Dans d'autres types d'application, vous pouvez définir celle-ci sur les événements regroupés.In other app types, you can set this to group events together.
    • ID : une valeur générée qui met en relation différents événements de manière à ce que vous trouviez les « Éléments associés » quand vous inspectez un événement dans la Recherche de diagnostic.ID: A generated value that correlates different events, so that when you inspect any event in Diagnostic Search, you can find related items.
    • Name : un identificateur, généralement l’URL de la requête HTTP.Name: An identifier, usually the URL of the HTTP request.
    • SyntheticSource : si elle est non nulle ou vide, cette chaîne indique que la source de la requête a été identifiée en tant que robot ou test web.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. Par défaut, elle est exclue des calculs dans Metrics Explorer.By default, it is excluded from calculations in Metrics Explorer.
  • Propriétés : ce sont les propriétés qui sont envoyées avec toutes les données de télémétrie.Properties: Properties that are sent with all telemetry data. Elles peuvent être remplacées dans les appels Track* individuels.It can be overridden in individual Track* calls.
  • Session: la session utilisateur.Session: The user's session. L'ID est définie sur une valeur générée qui est modifiée lorsque l'utilisateur n'a pas été actif pendant un certain temps.The ID is set to a generated value, which is changed when the user has not been active for a while.
  • Utilisateur : informations utilisateur.User: User information.

limitesLimits

Il existe certaines limites au nombre de métriques et d’événements par application, c’est-à-dire, par clé d’instrumentation.There are some limits on the number of metrics and events per application, that is, per instrumentation key. Les limites varient selon le plan de tarification que vous choisissez.Limits depend on the pricing plan that you choose.

RessourceResource Limite par défautDefault limit RemarqueNote
Total des données par jourTotal data per day 100 Go100 GB Vous pouvez réduire les données en définissant une limite.You can reduce data by setting a cap. Si vous avez besoin de davantage de données, vous pouvez augmenter la limite dans le portail, jusqu’à 1 000 Go.If you need more data, you can increase the limit in the portal, up to 1,000 GB. Pour une capacité supérieure à 1 000 Go, envoyez un e-mail à AIDataCap@microsoft.com.For capacities greater than 1,000 GB, send email to AIDataCap@microsoft.com.
LimitationThrottling 32 000 événements/seconde32,000 events/second La limite est mesurée par minute.The limit is measured over a minute.
Conservation des donnéesData retention 30 à 730 jours30 - 730 days Cette ressource est pour Recherche, Analytics et Metrics Explorer.This resource is for Search, Analytics, and Metrics Explorer.
Rétention des résultats détaillés du test de disponibilité à plusieurs étapesAvailability multi-step test detailed results retention 90 jours90 days Cette ressource fournit des résultats détaillés de chaque étape.This resource provides detailed results of each step.
Taille maximale des éléments de télémétrieMaximum telemetry item size 64 Ko64 kB
Nombre maximal d’éléments de télémétrie par lotMaximum telemetry items per batch 64 K64 K
Longueur des noms de propriétés et de mesuresProperty and metric name length 150150 Consultez les schémas par type.See type schemas.
Longueur de chaîne de valeur de propriétéProperty value string length 8 1928,192 Consultez les schémas par type.See type schemas.
Longueur des messages de trace et d’exceptionTrace and exception message length 32,76832,768 Consultez les schémas par type.See type schemas.
Nombre de tests de disponibilité par applicationAvailability tests count per app 100100
Rétention de données ProfileurProfiler data retention 5 jours5 days
Données Profileur envoyées par jourProfiler data sent per day 10 Go10 GB

Pour plus d’informations, consultez Tarification et quotas dans Application Insights.For more information, see About pricing and quotas in Application Insights.

Pour éviter d'atteindre la limite de débit de données, utilisez l’échantillonnage.To avoid hitting the data rate limit, use sampling.

Pour déterminer la durée de conservation des données, consultez Rétention des données et confidentialité.To determine how long data is kept, see Data retention and privacy.

Documents de référenceReference docs

Code de Kit de développement logiciel (SDK)SDK code

QuestionsQuestions

  • Quelles exceptions peuvent être lancées par les appels Track_() ?What exceptions might Track_() calls throw?

    Aucun.None. Vous n’avez pas besoin de les inclure dans des clauses try-catch.You don't need to wrap them in try-catch clauses. Si le Kit de développement logiciel (SDK) rencontre des problèmes, il enregistrera des messages dans la sortie de la console de débogage et, si les messages aboutissent, dans la recherche de diagnostic.If the SDK encounters problems, it will log messages in the debug console output and--if the messages get through--in Diagnostic Search.

  • Existe-t-il une API REST pour obtenir des données à partir du portail ?Is there a REST API to get data from the portal?

    Oui, l’API d’accès aux données.Yes, the data access API. Les autres méthodes d’extraction des données sont l’exportation d’Analytics vers Power BI et l’exportation continue.Other ways to extract data include export from Analytics to Power BI and continuous export.

Étapes suivantesNext steps