Émission de suivis dans du code utilisateur

Outre l’activation du suivi dans la configuration pour collecter les données d’instrumentation générées par Windows Communication Foundation (WCF), vous pouvez également émettre des traces par programmation dans le code utilisateur. De cette façon, vous pouvez créer de manière proactive des données d’instrumentation que vous pouvez utiliser ultérieurement à des fins de diagnostic. Cette rubrique explique comment procéder.

En outre, l’exemple Extending Tracing inclut tout le code démontré dans les sections suivantes.

Création d’une source de trace

Vous pouvez utiliser le code suivant pour créer une source de trace utilisateur.

TraceSource ts = new TraceSource("myUserTraceSource");

Création d’activités

Les activités sont une unité logique de traitement. Vous pouvez créer une activité pour chaque unité de traitement majeure dans laquelle vous souhaitez regrouper les traces. Par exemple, vous pouvez créer une activité pour chaque demande adressée au service. Pour ce faire, procédez comme suit.

1. Enregistrez l'ID d'activité dans la portée.

2. Créez un ID d’activité.

3. Transférez depuis l'activité dans la portée vers la nouvelle, définissez la nouvelle activité dans la portée et émettez un suivi de démarrage pour cette activité.

Le code suivant montre comment procéder.

Guid oldID = Trace.CorrelationManager.ActivityId;
Guid traceID = Guid.NewGuid();
ts.TraceTransfer(0, "transfer", traceID);
Trace.CorrelationManager.ActivityId = traceID; // Trace is static
ts.TraceEvent(TraceEventType.Start, 0, "Add request");

Émission de traces au sein d’une activité utilisateur

Le code suivant émet des traces au sein d’une activité utilisateur.

double value1 = 100.00D;
double value2 = 15.99D;
ts.TraceInformation("Client sends message to Add " + value1 + ", " + value2);
double result = client.Add(value1, value2);
ts.TraceInformation("Client receives Add response '" + result + "'");

Arrêt des activités

Pour arrêter les activités, transférez en retour vers l'ancienne activité, arrêtez l'ID d'activité actuel et réinitialisez l'ID de l'ancienne activité dans la portée.

Le code suivant montre comment procéder.

ts.TraceTransfer(0, "transfer", oldID);
ts.TraceEvent(TraceEventType.Stop, 0, "Add request");
Trace.CorrelationManager.ActivityId = oldID;

Propager l'ID d'activité à un service

Si vous affectez à l'attribut propagateActivity la valeur true pour la source de suivi System.ServiceModel dans les fichiers de configuration de client et de service, le traitement de service pour la demande Ajouter se produit dans la même activité que celle définie dans le client. Si le service définit ses propres activités et transferts, les traces de service n’apparaissent pas dans l’activité propagée par le client. À la place, ils apparaissent dans une activité corrélée par les suivis de transfert à l'activité dont l'ID est propagé par le client.

Vous pouvez utiliser le code suivant pour vérifier si une activité a été définie dans la portée par WCF.

// Check if an activity was set in scope by WCF, if it was
// propagated from the client. If not, ( ambient activity is
// equal to Guid.Empty), create a new one.
if(Trace.CorrelationManager.ActivityId == Guid.Empty)
{
    Guid newGuid = Guid.NewGuid();
    Trace.CorrelationManager.ActivityId = newGuid;
}
// Emit your Start trace.
ts.TraceEvent(TraceEventType.Start, 0, "Add Activity");

// Emit the processing traces for that request.
serviceTs.TraceInformation("Service receives Add "
                            + n1 + ", " + n2);
// double result = n1 + n2;
serviceTs.TraceInformation("Service sends Add result" + result);

// Emit the Stop trace and exit the method scope.
ts.TraceEvent(TraceEventType.Stop, 0, "Add Activity");
// return result;

Exceptions de suivi levées dans le code

Lorsque vous levez une exception dans le code, vous pouvez également tracer l'exception au niveau avertissement ou au niveau supérieur à l'aide du code suivant.

ts.TraceEvent(TraceEventType.Warning, 0, "Throwing exception " + "exceptionMessage");

Consultation des suivis d'utilisateur dans l'outil Service Trace Viewer

Cette section contient des captures d’écran des traces générées en exécutant l’exemple Extension du suivi , lors de l’affichage à l’aide de l’outil Service Trace Viewer (SvcTraceViewer.exe).

Dans le diagramme suivant, l’activité « Ajouter une demande » créée précédemment est sélectionnée dans le volet gauche. Elle est répertoriée avec trois autres activités d’opération mathématiques (Diviser, Soustraire, Multiplier) qui constituent le programme client de l’application. Le code utilisateur a défini une nouvelle activité pour chaque opération afin d’isoler les occurrences d’erreurs potentielles dans différentes requêtes.

Pour illustrer l’utilisation des transferts dans l’exemple Extending Tracing, une activité de calculatrice qui regroupe les quatre requêtes d'opération est également créée. Pour chaque demande, il s'opère un transfert aller/retour depuis l'activité de calculatrice à l'activité de demande (le suivi est mis en surbrillance dans le volet supérieur droit dans l'illustration).

Lorsque vous sélectionnez une activité dans le volet gauche, les traces incluses par cette activité sont affichées dans le volet supérieur droit. Si propagateActivity est true à chaque point de terminaison du chemin de requête, les traces de l'activité de requête proviennent de tous les processus participant à la demande. Dans cet exemple, vous pouvez voir les traces du client et du service dans la 4e colonne du panneau.

Cette activité affiche l’ordre de traitement suivant :

1. Le client envoie un message à Ajouter.

2. Le service reçoit le message Ajouter une demande.

3. Le service envoie la réponse Ajouter.

4. Le client reçoit la réponse Ajouter.

Tous ces suivis ont été émis au niveau des informations. Le fait de cliquer sur une trace dans le volet supérieur droit affiche les détails de cette trace dans le panneau inférieur droit.

Dans le diagramme suivant, nous voyons également des traces de transfert depuis et vers l'activité Calculatrice, ainsi que deux paires de traces de démarrage et d'arrêt pour chaque activité de requête, une paire pour le client et une paire pour le service (une par source de trace).

Liste des activités par heure de création (volet gauche) et leurs activités imbriquées (volet supérieur droit)

Si le code de service lève une exception qui amène le client à lever également une exception (par exemple, lorsque le client n’a pas obtenu la réponse à sa demande), les messages d’avertissement ou d’erreur du service et du client se produisent dans la même activité pour une corrélation directe. Dans l’image suivante, le service lève une exception indiquant « Le service refuse de traiter cette demande dans le code utilisateur ». Le client lève également une exception indiquant « Le serveur n’a pas pu traiter la demande en raison d’une erreur interne ».

Les images suivantes montrent que les erreurs entre les points de terminaison d’une requête donnée apparaissent dans la même activité si l’ID d’activité de la demande a été propagé :

Le double-clic sur l’activité Multiplier dans le volet gauche affiche le graphique suivant, avec les traces de l’activité Multiplier pour chaque processus impliqué. Nous pouvons voir qu’un avertissement s’est d’abord produit au niveau du service (exception levée), suivi d’avertissements et d’erreurs sur le client, car la demande n’a pas pu être traitée. Par conséquent, nous pouvons impliquer la relation d’erreur causale entre les points de terminaison et dériver la cause racine de l’erreur.

L’image suivante montre une vue graphique de corrélation d’erreur :

Pour obtenir les traces précédentes, nous définissons ActivityTracing pour les sources de trace utilisateur et propagateActivity=true pour la source de trace System.ServiceModel. Nous n'avons pas défini ActivityTracing pour la source de suivi System.ServiceModel pour permettre la propagation d'activité du code utilisateur au code utilisateur. (Lorsque le suivi d’activité ServiceModel est activé, l’ID d’activité défini dans le client n’est pas propagé jusqu’au code utilisateur du service ; les transferts, toutefois, corrèlent les activités de code utilisateur client et de service à toutes les activités WCF intermédiaires.)

La définition des activités et la propagation de l’ID d’activité nous permet d’effectuer une corrélation d’erreur directe entre les points de terminaison. De cette façon, nous pouvons localiser plus rapidement la cause racine d’une erreur.

Voir aussi

• Extension du traçage