API Application Insights pour les événements et les mesures personnalisés

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. 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. Utilisez l’API de télémétrie principale d’Application Insights pour envoyer des événements et métriques personnalisés, ainsi que vos propres versions de la télémétrie standard. Cette API est la même que celle utilisée par les collecteurs de données standard d’Application Insights.

Résumé des API

L’API principale est uniforme sur toutes les plateformes, à l’exception de quelques petites variantes telles que GetMetric (.NET uniquement).

Méthode	Utilisé pour
TrackPageView	Pages, écrans, volets ou formulaires.
TrackEvent	Actions de l’utilisateur et autres événements. Utilisé pour suivre le comportement de l’utilisateur ou pour analyser les performances.
GetMetric	Zéro métrique et métriques multidimensionnelles, agrégation configurée de manière centralisée, C# uniquement.
TrackMetric	Mesures de performances telles que la longueur des files d’attente non liées à des événements spécifiques.
TrackException	Exceptions de journal pour des diagnostics. Effectuez un suivi lorsqu’ils se produisent par rapport à d’autres événements et examinez les arborescences des appels de procédure.
TrackRequest	Notez la fréquence et la durée des requêtes du serveur pour l’analyse des performances.
TrackTrace	Messages du journal de diagnostic des ressources. Vous pouvez également capturer des journaux d’activité tiers.
TrackDependency	La journalisation de la durée et de la fréquence des appels vers les composants externes dont dépend votre application.

Vous pouvez associer des propriétés et des mesures à la plupart de ces appels de télémétrie.

Avant de commencer

Si vous n’avez pas encore de référence sur le kit SDK Application Insights :

• Ajoutez le Kit de développement logiciel (SDK) Application Insights à votre projet :

  • Projet ASP.NET
  • ASP.NET Core project
  • Projet Java
  • Projet Node.js
  • JavaScript dans chaque page web

• Ajoutez au code de votre périphérique ou de votre serveur web :

  C# :using Microsoft.ApplicationInsights;

  Visual Basic :Imports Microsoft.ApplicationInsights

  Java:import com.microsoft.applicationinsights.TelemetryClient;

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

Obtenir une instance de TelemetryClient

Obtenez une instance de TelemetryClient (sauf en JavaScript dans les pages web) :

Pour les applications ASP.NET Core et non HTTP/Worker pour .NET/.NET Core, obtenez une instance de TelemetryClient à partir du conteneur d’injection de dépendances comme expliqué dans la documentation correspondante.

Si vous utilisez Azure Functions v2+ ou Azure WebJobs v3+, consultez Superviser Azure Functions.

C#

private TelemetryClient telemetry = new TelemetryClient();

Si vous voyez un message qui vous indique que cette méthode est obsolète, consultez microsoft/ApplicationInsights-dotnet#1152 pour plus d’informations.

Visual Basic

Private Dim telemetry As New TelemetryClient

Java

private TelemetryClient telemetry = new TelemetryClient();

Node.JS

var telemetry = applicationInsights.defaultClient;

TelemetryClient est thread-safe.

Dans le cas des projets ASP.NET et Java, les requêtes HTTP entrantes sont automatiquement capturées. Vous pouvez créer d’autres instances de TelemetryClient pour d’autres modules de votre application. Par exemple, vous pouvez avoir une instance TelemetryClient dans votre classe d’intergiciels pour signaler les événements de logique métier. Vous pouvez définir des propriétés comme UserId et DeviceId pour identifier l’ordinateur. Cette information est associée à tous les événements envoyés par l'instance.

C#

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

Java

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. Nous recommandons cette approche uniquement pour les scénarios qui nécessitent une configuration isolée du singleton defaultClient.

TrackEvent

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. (Il n’est pas lié à des « événements » de type MVC ou autres.)

Insérez des appels TrackEvent dans votre code pour compter les différents événements. Par exemple, vous pouvez suivre la fréquence à laquelle les utilisateurs choisissent une fonctionnalité particulière. Vous pouvez également savoir combien de fois ils atteignent certains objectifs ou commettent des erreurs d’un type spécifique.

Par exemple, dans une application de jeu, envoyez un événement chaque fois qu'un utilisateur gagne le jeu :

JavaScript

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

C#

telemetry.TrackEvent("WinGame");

Visual Basic

telemetry.TrackEvent("WinGame")

Java

telemetry.trackEvent("WinGame");

Node.JS

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

Événements personnalisés dans Log Analytics

La télémétrie est disponible dans la table customEvents sous l’onglet Journaux Application Insights ou l’expérience d’utilisation. Les événements peuvent provenir de trackEvent(..) ou du plug-in Click Analytics Auto-collection.

Si un échantillonnage est en cours, la propriété itemCount affiche une valeur supérieure à 1. Par exemple, itemCount==10 signifie que sur 10 appels à trackEvent(), le processus d’échantillonnage n’en a transmis qu’un seul. Pour obtenir un nombre correct d’événements personnalisés, utilisez un code similaire à customEvents | summarize sum(itemCount).

GetMetric

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 Collecte de métriques personnalisées dans .NET et .NET Core.

TrackMetric

Application Insight peut représenter des métriques qui ne sont pas associées à des événements particuliers. Par exemple, vous pouvez analyser la longueur d’une file d'attente à des intervalles réguliers. Avec les mesures, les mesures individuelles sont moins intéressantes que les variations et tendances, ainsi les graphiques statistiques sont utiles.

Pour pouvoir envoyer des métriques à Application Insights, vous pouvez utiliser l’API TrackMetric(..). Il existe deux façons d’envoyer une métrique :

• Valeur unique. Chaque fois que vous effectuez une mesure dans votre application, vous envoyez la valeur correspondante à Application Insights.

  Par exemple, supposons que vous avez une métrique décrivant le nombre d’éléments dans un conteneur. Pendant une période donnée, vous placez d’abord trois éléments dans le conteneur puis vous en supprimez deux. En conséquence, vous appelez TrackMetric deux fois. Tout d’abord, vous passez la valeur 3, puis la valeur -2. Application Insights stocke les deux valeurs pour vous.

• Agrégation. Quand vous travaillez avec des métriques, chaque mesure individuelle est rarement intéressante. En revanche, un récapitulatif de ce qui s’est passé au cours d’une période donnée est important. Un tel récapitulatif est appelé agrégation.

  Dans l’exemple précédent, la somme totale des métriques pour cette période est 1 et le nombre de valeurs des métriques est 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. Nous vous recommandons cette approche, 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.

Exemples de valeurs uniques

Pour envoyer une seule valeur métrique :

JavaScript

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

C#

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

Java

telemetry.trackMetric("queueLength", 42.0);

Node.JS

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

Métriques personnalisées dans Log Analytics

La télémétrie est disponible dans la table customMetrics dans Application Insights - Analytique. Chaque ligne représente un appel à trackMetric(..) dans votre application.

• valueSum : somme des mesures. Pour obtenir la valeur moyenne, divisez par valueCount.
• valueCount : nombre de mesures qui ont été agrégées dans cet appel de trackMetric(..).

Affichages de page

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é. Mais vous pouvez modifier le comportement par défaut pour suivre les affichages de page à d’autres moments ou à des moments différents. Par exemple, dans une application qui affiche les onglets ou les volets, vous pouvez effectuer le suivi d’une « page » chaque fois que l’utilisateur ouvre un nouveau volet.

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.

Affichages de pages personnalisées

JavaScript

appInsights.trackPageView("tab1");

C#

telemetry.TrackPageView("GameReviewPage");

Visual Basic

telemetry.TrackPageView("GameReviewPage")

Java

telemetry.trackPageView("GameReviewPage");

Si vous avez plusieurs onglets dans différentes pages HTML, vous pouvez aussi spécifier l'URL :

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

Affichages de la page de durée

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é.

Au lieu de cela, vous pouvez :

• Définir une durée explicite dans l’appel trackPageView : appInsights.trackPageView("tab1", null, null, null, durationInMilliseconds);.
• Utiliser les appels de minutage d’affichage de la page startTrackPage et stopTrackPage.

JavaScript

// 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. Le nom de la page actuelle est utilisé par défaut.

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. C’est à vous de décider quel intervalle de temps vous voulez mesurer.

Télémétrie des pages dans Log Analytics

Dans Log Analytics, deux tables affichent les données des opérations du navigateur :

• pageViews : contient des données sur l’URL et le titre de la page.
• browserTimings : contient des données sur les performances du client, comme le temps nécessaire pour traiter les données entrantes.

Pour trouver le temps mis par le navigateur pour traiter différentes pages :

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

Pour découvrir la popularité de différents navigateurs :

pageViews
| summarize count() by client_Browser

Pour associer des vues de pages à des appels AJAX, joindre à des dépendances :

pageViews
| join (dependencies) on operation_Id

TrackRequest

Le kit SDK du serveur utilise TrackRequest pour consigner les requêtes HTTP.

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.

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.

Contexte de l’opération

Vous pouvez associer des éléments de télémétrie en les associant à un contexte d’opération. 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. Dans Recherche et Analytique, vous pouvez trouver facilement tous les événements associés à la requête avec son ID d’opération.

Pour plus d’informations sur la corrélation, consultez l’article Corrélation de télémétrie dans Application Insights.

Quand vous suivez manuellement la télémétrie, le moyen le plus simple pour vous assurer de la corrélation des données de télémétrie est d’utiliser ce modèle :

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. Il envoie l’élément de télémétrie lorsque vous libérez l’opération ou si vous appelez explicitement 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.

Les éléments de télémétrie signalés dans une étendue de l’opération deviennent « enfants » d’une telle opération. Les contextes de l’opération ne peuvent pas être imbriqués.

Dans Recherche, le contexte d’opération est utilisé pour créer la liste Éléments connexes.

Pour plus d’informations sur le suivi des opérations personnalisées, consultez Suivi des opérations personnalisées avec le kit SDK .NET Application Insights.

Demandes dans Log Analytics

Dans Application Insights - Analytique, les demandes s’affichent dans la table requests.

Si un échantillonnage est en cours, la propriété itemCount affiche une valeur supérieure à 1. Par exemple, itemCount==10 signifie que sur 10 appels à trackRequest(), le processus d’échantillonnage n’en a transmis qu’un seul. Pour obtenir un nombre correct de demandes et une durée moyenne segmentée par nom des demandes, utilisez un code similaire à celui-ci :

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

TrackException

Envoi d’exceptions à Application Insights :

• Pour les compter, comme une indication de la fréquence d’un problème.
• Pour inspecter les occurrences individuelles.

Les rapports incluent des arborescences des appels de procédure.

C#

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

Java

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

JavaScript

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

Node.JS

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

Les kits SDK interceptent de nombreuses exceptions automatiquement, ce qui vous évite ainsi d’avoir toujours à appeler TrackException explicitement :

• ASP.NET : écrivez du code pour intercepter les exceptions.
• Java EE : les exceptions sont interceptées automatiquement.
• JavaScript : les exceptions sont interceptées automatiquement. Si vous souhaitez désactiver la collecte automatique, ajoutez une ligne au script de chargement du kit de développement logiciel (SDK) JavaScript (web) que vous insérez dans vos pages web :

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

Exceptions dans Log Analytics

Dans Application Insights - Analytique, les exceptions s’affichent dans la table exceptions.

Si un échantillonnage est en cours, la propriété itemCount affiche une valeur supérieure à 1. Par exemple, itemCount==10 signifie que sur 10 appels à trackException(), le processus d’échantillonnage n’en a transmis qu’un seul. Pour obtenir un nombre correct d’exceptions segmentées par type d’exception, utilisez un code similaire à celui-ci :

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. Cette structure étant dynamique, vous devez caster le résultat avec le type attendu. Par exemple :

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

Pour associer des exceptions aux demandes qui s’y rapportent, utilisez une jointure :

exceptions
| join (requests) on operation_Id

TrackTrace

Utilisez TrackTrace pour diagnostiquer des problèmes en envoyant une « piste de navigation » à Application Insights. Vous pouvez envoyer des blocs de données de diagnostic et les examiner dans la Recherche de diagnostic.

Dans .NET, les Adaptateurs de journaux utilisent cette API pour envoyer des journaux tiers au portail.

En Java, l’agent Application Insights Java collecte et envoie automatiquement les journaux au portail.

C#

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

Java

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

Node.JS

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

JavaScript côté client/navigateur

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.

Paramètre	Description
message	Données de diagnostic. Peut être plus longue qu'un nom.
properties	Mappage de chaîne à chaîne. Des données supplémentaires sont utilisées pour filtrer les exceptions dans le portail. Vide par défaut.
severityLevel	Valeurs prises en charge : SeverityLevel.ts.

Vous pouvez effectuer une recherche dans le contenu du message, mais contrairement aux valeurs de propriété, vous ne pouvez pas le filtrer.

La limite de taille sur message est plus importante que la limite des propriétés. L’un des avantages de TrackTrace est que vous pouvez insérer des données relativement longues dans le message. Par exemple, vous pourriez y encoder des données POST.

Vous pouvez également ajouter un niveau de gravité à votre 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. Par exemple :

C#

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

Java

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

Dans Recherche, vous pouvez filtrer facilement tous les messages d’un niveau de gravité particulier portant sur une certaine base de données.

Traces dans Log Analytics

Dans Analytique Application Insights, les appels à TrackTrace apparaissent dans la table traces.

Si un échantillonnage est en cours, la propriété itemCount affiche une valeur supérieure à 1. Par exemple, itemCount==10 signifie que sur 10 appels à trackTrace(), le processus d’échantillonnage n’en a transmis qu’un seul. Pour obtenir un nombre correct d’appels de trace, utilisez un code similaire à traces | summarize sum(itemCount).

TrackDependency

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. Les résultats s'affichent dans les graphiques de dépendance sur le portail. L’extrait de code suivant doit être ajouté chaque fois qu’un appel de dépendance est effectué.

C#

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

Java

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

Node.JS

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

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. Vous devez installer un agent sur votre serveur pour que le module fonctionne.

En Java, de nombreux appels de dépendance peuvent être suivis automatiquement à l’aide de l’agent Application Insights Java.

Vous utilisez cet appel si vous souhaitez suivre les appels que le suivi automatisé n’intercepte pas.

Pour désactiver le module de suivi des dépendances standard en C#, modifiez ApplicationInsights.config et supprimez la référence à DependencyCollector.DependencyTrackingTelemetryModule. Pour Java, consultez Suppression d’une télémétrie collectée automatiquement spécifique.

Dépendances dans Log Analytics

Dans Analytique Application Insights, les appels à trackDependency apparaissent dans la table dependencies.

Si un échantillonnage est en cours, la propriété itemCount affiche une valeur supérieure à 1. Par exemple, itemCount==10 signifie que sur 10 appels à trackDependency(), le processus d’échantillonnage n’en a transmis qu’un seul. Pour obtenir un nombre correct de dépendances segmentées par composant cible, utilisez un code similaire à celui-ci :

dependencies
| summarize sum(itemCount) by target

Pour associer des dépendances aux demandes qui s’y rapportent, utilisez une jointure :

dependencies
| join (requests) on operation_Id

Vidage des données

Normalement, le kit SDK envoie des données à intervalles réguliers (en général, 30 secondes) ou chaque fois que la mémoire tampon est saturée (en général, 500 éléments). Dans certains cas, vous souhaiterez peut-être vider la mémoire tampon. Par exemple, si vous utilisez le kit SDK dans une application qui s’arrête.

.NET

Quand vous utilisez Flush(), nous vous recommandons ce modèle :

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

Quand vous utilisez FlushAsync(), nous vous recommandons ce modèle :

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

Nous vous recommandons de toujours le vider dans le cadre de l’arrêt de l’application afin de ne pas perdre la télémétrie.

Java

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

Node.JS

telemetry.flush();

La fonction est asynchrone pour le canal de télémétrie du serveur.

Utilisateurs authentifiés

Dans une application web, les utilisateurs sont identifiés par des cookies par défaut. 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.

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 :

JavaScript

// 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 :

Razor

@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. Il doit uniquement s’agir d’un ID unique pour cet utilisateur. Il ne doit pas inclure d'espaces ni l'un des caractères suivants : ,;=|.

L’ID d’utilisateur est également défini dans un cookie de session et envoyé au serveur. 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. Vous pouvez ensuite filtrer et rechercher dessus.

Si votre application regroupe les utilisateurs par comptes, vous pouvez également fournir un identificateur pour ce compte. Les mêmes restrictions de caractères s’appliquent.

appInsights.setAuthenticatedUserContext(validatedId, accountId);

Dans Metrics Explorer, vous pouvez créer un graphique qui compte les Utilisateurs authentifiés et les Comptes d’utilisateur.

Vous pouvez également rechercher les points de données client avec des comptes et des noms d'utilisateur spécifiques.

Filtrez, recherchez et segmentez vos données avec des propriétés

Vous pouvez attacher des propriétés et des mesures à vos événements, métriques, affichages de page, exceptions et autres données de télémétrie.

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. 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.

Il existe une limite de 8 192 sur la longueur de chaîne. Si vous souhaitez envoyer d’importants blocs de données, utilisez le paramètre message de TrackTrace.

mesures sont des valeurs numériques qui peuvent être représentées sous forme graphique. Par exemple, observez s'il existe une augmentation progressive des scores atteints par vos joueurs. 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.

Les valeurs des métriques doivent être supérieures ou égales à 0 pour s’afficher correctement.

Il existe certaines limites au nombre de propriétés, de valeurs de propriété et de mesures que vous pouvez utiliser.

JavaScript

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

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

C#

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

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

Node.JS

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

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

Visual Basic

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

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

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

Java

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

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

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

Autre façon de définir des propriétés et des mesures

Si cela est plus pratique, vous pouvez collecter les paramètres d'un événement dans un objet séparé :

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

Mesures et propriétés personnalisées dans Log Analytics

Dans Log Analytics, les métriques et les propriétés personnalisées s’affichent dans les attributs customMeasurements et customDimensions de chaque enregistrement de télémétrie.

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 » :

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

Notez que :

• Quand vous extrayez une valeur de customDimensions ou customMeasurements en JSON, elle a un type dynamique. Vous devez donc la caster en tostring ou todouble.
• Pour tenir compte de la possibilité d’échantillonnage, utilisez sum(itemCount), et non count().

Événements de durée

Vous avez parfois besoin d’obtenir une représentation graphique de la durée nécessaire à la réalisation d’une action. Par exemple, vous souhaitez savoir de combien de temps les utilisateurs ont besoin pour évaluer leurs choix dans un jeu. Pour obtenir ces informations, utilisez le paramètre de mesure.

C#

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

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

stopwatch.Stop();

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

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

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

Java

long startTime = System.currentTimeMillis();

// Perform timed action

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

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

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

Propriétés par défaut pour la télémétrie personnalisée

Si vous souhaitez définir des valeurs de propriété par défaut pour certains des événements personnalisés que vous écrivez, définissez-les dans une instance TelemetryClient. Ils sont associés à chaque élément de télémétrie envoyé à partir de ce client.

C#

using Microsoft.ApplicationInsights.DataContracts;

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

Visual Basic

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

Java

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

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

gameTelemetry.TrackEvent("WinGame");

Node.JS

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

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

Les appels de télémétrie individuels peuvent remplacer les valeurs par défaut dans leurs dictionnaires de propriété.

Pour les clients Web JavaScript, utilisez des initialiseurs de télémétrie JavaScript.

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.

Échantillonner, filtrer et traiter la télémétrie

Consultez Filtrage et pré-traitement de la télémétrie dans le Kit de développement logiciel (SDK) Application Insights.

Désactiver la télémétrie

Pour arrêter et démarrer dynamiquement la collecte et la transmission de la télémétrie :

C#

using  Microsoft.ApplicationInsights.Extensibility;

TelemetryConfiguration.Active.DisableTelemetry = true;

Java

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. C’est le cas par exemple si vous souhaitez envoyer vos propres données TrackRequest.

Node.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) au moment de l’initialisation, enchaînez plusieurs méthodes de configuration dans votre code d’initialisation SDK.

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

Mode Développeur :

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. Vous obtenez également d’autres messages qui vous permettent de suivre tout problème relatif à la télémétrie. Désactivez-les lors de la production, car ils peuvent ralentir votre application.

C#

TelemetryConfiguration.Active.TelemetryChannel.DeveloperMode = true;

Visual Basic

TelemetryConfiguration.Active.TelemetryChannel.DeveloperMode = True

Node.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.

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

Définir la clé d'instrumentation pour la télémétrie personnalisée sélectionnée

C#

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

Clé d'instrumentation dynamique

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.

Au lieu de récupérer la clé d'instrumentation à partir du fichier de configuration, vous pouvez la définir dans votre code. Définissez la clé dans une méthode d’initialisation, par exemple global.aspx.cs dans un service ASP.NET :

C#

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

JavaScript

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. Par exemple, dans une page web générée dans une application ASP.NET :

JavaScript dans Razor

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

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

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

TelemetryContext

TelemetryClient a une propriété de contexte contenant les valeurs qui sont envoyées avec toutes les données de télémétrie. Elles sont normalement définies par les modules de télémétrie standard, mais vous pouvez également les définir vous-même. Par exemple :

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.

• Composant : l’application et sa version.
• Appareil : données concernant l’appareil sur lequel l’application s’exécute. Dans les applications web, il s’agit du serveur ou de l’appareil client à partir duquel la télémétrie est envoyée.
• InstrumentationKey : la ressource Application Insights dans Azure dans laquelle la télémétrie s’affiche. Elle est généralement récupérée à partir de ApplicationInsights.config.
• Emplacement : emplacement géographique de l’appareil.
• Opération : dans les applications web, il s’agit de la requête HTTP actuelle. Dans d’autres types d’application, vous pouvez définir cette valeur pour regrouper des événements.
  • 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.
  • Name : un identificateur, généralement l’URL de la requête HTTP.
  • 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. Par défaut, elle est exclue des calculs dans Metrics Explorer.
• Session: la session utilisateur. L’ID est définie avec une valeur générée qui est modifiée lorsque l’utilisateur n’a pas été actif pendant un certain temps.
• Utilisateur : informations utilisateur.

limites

Il existe certaines limites au nombre de métriques et d’événements par application, c’est-à-dire, par clé d’instrumentation. Les limites varient selon le plan de tarification que vous choisissez.

Ressource	Limite par défaut	Limite maximale	Notes
Total des données par jour	100 Go	Contactez le support technique.	Vous pouvez définir une limite pour réduire les données. Si vous avez besoin de davantage de données, vous pouvez augmenter la limite dans le portail, jusqu’à 1 000 Go. Pour une capacité supérieure à 1 000 Go, envoyez un e-mail à AIDataCap@microsoft.com.
Limitation	32 000 événements/seconde	Contactez le support technique.	La limite est mesurée par minute.
Journaux de conservation des données	30 à 730 jours	730 jours	Cette ressource est destiné aux journaux.
Métriques de conservation des données	90 jours	90 jours	Cette ressource est destinée à Metrics Explorer.
Conservation des résultats détaillés du test de disponibilité à plusieurs étapes	90 jours	90 jours	Cette ressource fournit des résultats détaillés de chaque étape.
Taille maximale des éléments de télémétrie	64 Ko	64 Ko
Nombre maximal d’éléments de télémétrie par lot	64 000	64 000
Longueur des noms de propriétés et de mesures	150	150	Consultez les schémas par type.
Longueur de chaîne de valeur de propriété	8 192	8 192	Consultez les schémas par type.
Longueur des messages de trace et d’exception	32,768	32,768	Consultez les schémas par type.
Nombre de tests de disponibilité par ressource Application Insights	100	100
Conservation des données Profileur et Instantané	Deux semaines	Contactez le support technique. La limite maximale de conservation est de six mois.
Données Profileur envoyées par jour	Aucune limite	Aucune limite.
Données Instantané envoyées par jour	30 instantanés par jour par application monitorée	Aucune limite.	Le nombre d’instantanés collectés par application peut être modifié dans la configuration.

Pour plus d’informations sur la tarification et les quotas, consultez Facturation d’Application Insights.

Pour éviter d'atteindre la limite de débit de données, utilisez l’échantillonnage.

Pour déterminer la durée de conservation des données, consultez Rétention des données et confidentialité.

Documents de référence

• Information de référence sur .NET
• Référence Java
• Référence JavaScript

Code de Kit de développement logiciel (SDK)

• .NET
• Packages Windows Server
• Kit SDK Java
• Kit de développement logiciel (SDK) Node.js
• Kit de développement logiciel (SDK) JavaScript

Forum aux questions

Cette section fournit des réponses aux questions fréquentes.

Pourquoi me manque-t-il des données de télémétrie ?

Les deux canaux de télémétrie (TelemetryChannels) perdent la télémétrie mise en mémoire tampon s’ils ne sont pas vidés avant qu’une application s’arrête.

Pour éviter toute perte de données, videz TelemetryClient lorsqu’une application s’arrête.

Pour plus d’informations, consultez Vidage des données.

Quelles exceptions peuvent être lancées par les appels Track_() ?

Aucun. Vous n’avez pas besoin de les inclure dans des clauses try-catch. Si le kit SDK rencontre des problèmes, il enregistre des messages dans la sortie de la console de débogage et, si les messages aboutissent, dans la recherche de diagnostic.

Existe-t-il une API REST pour obtenir des données à partir du portail ?

Oui, l’API d’accès aux données. Voici d’autres façons d’extraire des données : Power BI si vous avez migré vers une ressource basée sur un espace de travail ou l’exportation continue si vous utilisez toujours une ressource classique.

Pourquoi mes appels aux événements personnalisés et aux API de métriques sont-ils ignorés ?

Le Kit de développement logiciel (SDK) Application Insights n’est pas compatible avec l’instrumentation automatique. Si l’instrumentation automatique est activée, les appels à Track() et aux autres événements personnalisés et API de métriques sont ignorés.

Désactivez l’instrumentation automatique sur le Portail Azure, sous l’onglet Application Insights de la page App Service, ou définissez ApplicationInsightsAgent_EXTENSION_VERSION sur disabled.

Pourquoi les graphiques de recherche et de mesures contiennent-ils des valeurs différentes ?

L’échantillonnage réduit le nombre d’éléments de télémétrie (comme les demandes et les événements personnalisés) qui sont envoyés à partir de votre application vers le portail. Dans la Recherche, vous pouvez voir le nombre d’éléments reçus. Dans les graphiques de mesure qui affichent un nombre d’événements, vous obtenez le nombre d’événements d’origine qui se sont produits.

Chaque élément transmis comporte une propriété itemCount qui indique le nombre d’événements d’origine qu’il représente. Pour observer l’échantillonnage en action, vous pouvez exécuter cette requête dans Log Analytics :

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

Comment puis-je définir une alerte sur un événement ?

Les alertes Azure portent uniquement sur les mesures. Créez une mesure personnalisée qui dépasse un seuil de valeur chaque fois que l’événement se produit. Puis définissez une alerte sur la mesure. Vous recevez une notification chaque fois que la métrique franchit le seuil dans un sens ou dans l’autre. Vous ne recevrez pas de notification avant le premier franchissement, quelle que soit la valeur initiale (haute ou basse). Il y a toujours une latence de quelques minutes.

Étapes suivantes

• Recherche d’événements et de journaux d’activité