Share via

StartKernelTrace

  • Article

Cette fonction inscrit et démarre une session de suivi d’événements du noyau. Vous pouvez également activer le stackwalking pour certains événements de noyau à l’aide de cette fonction.

ULONG
WINAPI
StartKernelTrace(
__out PTRACEHANDLE TraceHandle,
__inout PEVENT_TRACE_PROPERTIES Properties,
__in ULONG cStackTracingEventIds
);

Paramètres

TraceHandle [out]
Stocke un handle dans une session de suivi d’événements. Ce paramètre est défini sur zéro si le handle n’est pas valide. Ce paramètre ne doit pas être comparé à INVALID_HANDLE_VALUE. N’utilisez pas ce handle si la fonction échoue.

Propriétés [in, out]
Stocke un pointeur vers une structure EVENT_TRACE_PROPERTIES. EVENT_TRACE_PROPERTIES configure certains aspects du comportement de session.

Le premier membre de la structure EVENT_TRACE_PROPERTIES est une structure WNODE_HEADER, appelée ici Wnode.

Le EVENT_TRACE_PROPERTIES suivant. Les membres Wnode doivent être définis pour configurer le contrôle de trace du noyau.

BufferSize
Ce membre contient la taille totale, en octets, de la mémoire allouée pour les propriétés de session de suivi d’événements. La taille de la mémoire doit inclure suffisamment d’espace pour stocker les données suivantes :

  • Structure EVENT_TRACE_PROPERTIES.

  • Chaîne de nom de session.

  • Chaîne de nom de fichier journal.

Guid
Chaque session de suivi doit avoir un GUID défini pour référencer la session.

Pour une session d’enregistreur d’événements du noyau NT, ce membre doit être défini sur SystemTraceControlGuid. Pour plus d’informations sur les constantes en mode journalisation, consultez Constantes d’enregistreur d’événements du noyau NT.

Clientcontext
Ce membre définit la résolution d’horloge utilisée lors du calcul de l’horodatage de journalisation pour chaque événement. La valeur par défaut de ce membre est un compteur de performances de requête.

Vous pouvez spécifier l'une des valeurs suivantes :

  • 1 : Compteur de performances de requête (QPC). Le QPC fournit un horodatage haute résolution (100 nanosecondes), mais il est comparativement plus coûteux à récupérer. Utilisez cette résolution si vous avez des taux d’événements élevés ou si le consommateur fusionne des événements à partir de différentes mémoires tampons. Sur les ordinateurs plus anciens, l’horodatage peut ne pas être précis, car le compteur passe parfois à l’avant en raison d’erreurs matérielles.

  • 2 : Heure système. L’heure système fournit un horodatage basse résolution (10 millisecondes), mais est comparativement moins coûteux à récupérer. Si le volume d’événements est élevé, la résolution du temps système peut ne pas être suffisante pour déterminer la séquence des événements. Dans ce cas, un ensemble d’événements aura le même horodatage, mais l’ordre dans lequel ETW livre les événements peut ne pas être correct.

  • 3 : Compteur de cycle du processeur. Le compteur processeur fournit l’horodatage de résolution la plus élevée et est le moins coûteux à récupérer. Toutefois, le compteur processeur n’est pas fiable et ne doit pas être utilisé en production. Par exemple, sur certains ordinateurs, le minuteur change de fréquence en raison de changements thermiques et d’alimentation, en plus de s’arrêter dans certains états. Si votre matériel ne prend pas en charge ce type d’horloge, ETW utilise l’heure système. Dans Windows Server 2003, Windows XP avec SP1 et Windows XP, cette valeur n’est pas prise en charge. Il a été introduit dans Windows Server 2003 avec SP1 et Windows XP avec SP2.

Drapeaux
Ce membre doit contenir des WNODE_FLAG_TRACED_GUID pour indiquer que la structure contient des informations de suivi d’événements et que les informations sont envoyées à un enregistreur d’événements. WNODE_FLAG_TRACED_GUID est défini dans Evntrace.h.

Les membres EVENT_TRACE_PROPERTIES suivants doivent également être définis :

LogFileMode
Indique les modes de journalisation à utiliser dans la session de suivi des événements du noyau. Vous pouvez utiliser ce membre pour spécifier que les événements doivent être écrits dans un fichier journal, un consommateur en temps réel ou les deux.

Ce membre peut également être utilisé pour spécifier que la session est une session d’enregistreur d’événements privé. Un ou plusieurs modes peuvent être spécifiés. Pour obtenir la liste des modes possibles, consultez Constantes du mode de journalisation.

Note Ne spécifiez pas la journalisation en temps réel, sauf s’il existe des consommateurs en temps réel prêts à consommer les événements. S’il n’existe aucun consommateur en temps réel, les événements sont écrits dans un fichier de lecture. La taille du fichier de lecture est limitée. Si la limite est atteinte, aucun nouvel événement n’est enregistré dans le fichier journal ou le fichier de lecture. Les fonctions de journalisation échouent avec STATUS_LOG_FILE_FULL.

EnableFlags
Ce membre est utilisé uniquement pour les sessions d’enregistreur d’événements du noyau NT. Il identifie au journal du noyau les événements à suivre. En utilisant or logique, ce membre peut contenir une ou plusieurs valeurs. En plus des événements spécifiés, l’enregistreur d’événements du noyau journalise également les événements de configuration matérielle.

Les indicateurs de contrôle de trace suivants sont disponibles en plus de ceux fournis par EVENT_TRACE_PROPERTIES :

LogFileNameOffset
Ce nombre représente le décalage entre le début de la mémoire allouée à la structure et le début de la chaîne null qui contient le nom du fichier journal.

Les considérations suivantes s'appliquent :

  • L’extension de nom de fichier doit être .etl.

  • Tous les dossiers du chemin d’accès doivent exister.

  • Le chemin peut être relatif, absolu, local ou distant.

  • Le chemin d’accès ne doit pas contenir de variables d’environnement, car ces variables ne sont pas développées.

  • L’utilisateur qui lance la trace doit disposer de l’autorisation d’écriture sur le dossier.

  • Le nom du fichier journal est limité à 1 024 caractères.

  • Si vous définissez LogFileMode sur EVENT_TRACE_PRIVATE_LOGGER_MODE ou EVENT_TRACE_FILE_MODE_NEWFILE, veillez à allouer suffisamment de mémoire pour inclure l’identificateur de processus ajouté au nom de fichier pour les sessions d’enregistreur d’événements privés et le numéro séquentiel ajouté aux fichiers journaux créés à l’aide du nouveau mode journal des fichiers.

  • Si vous ne souhaitez pas journaliser les événements dans un fichier journal (par exemple, vous spécifiez EVENT_TRACE_REAL_TIME_MODE uniquement), définissez LogFileNameOffset sur zéro. Si vous spécifiez uniquement la journalisation en temps réel et que vous fournissez également un décalage avec un nom de fichier journal valide, le nom du fichier journal est utilisé pour créer un fichier journal séquentiel et des événements de journalisation dans le fichier journal. Le fichier journal séquentiel est également créé si LogFileMode est égal à zéro et que vous fournissez un décalage avec un nom de fichier journal valide.

  • Si vous souhaitez journaliser des événements dans un fichier journal, vous devez allouer suffisamment de mémoire pour que cette structure inclue le nom du fichier journal et le nom de session suivant la structure. Le nom du fichier journal doit suivre le nom de session en mémoire.

  • Les fichiers de trace sont créés à l’aide du descripteur de sécurité par défaut, ce qui signifie que le fichier journal aura la même liste de contrôle d’accès que le répertoire parent. Si vous souhaitez restreindre l’accès aux fichiers, créez un répertoire parent avec les listes de contrôle d’accès appropriées.

LoggerNameOffset
Ce membre représente le décalage entre le début de la mémoire allouée à la structure et le début de la chaîne null qui contient le nom de session.

Les considérations suivantes s'appliquent :

  • Le nom de session est limité à 1 024 caractères.

  • Le nom de session ne respecte pas la casse et doit être unique.

  • Lors de l’allocation de mémoire pour cette structure, une mémoire suffisante doit être réservée pour inclure le nom de session et le nom du fichier journal qui suit la structure.

  • Le nom de session doit être antérieur au nom du fichier journal en mémoire. Le nom du fichier journal doit être copié dans la zone de décalage. Cette fonction écrit le nom de session défini par KERNEL_LOGGER_NAME.

Selon le type de fichier journal choisi, il peut être nécessaire de définir le membre MaximumFileSize .

Note Il n’est pas nécessaire de définir le nom de l’enregistreur d’événements dans LoggerNameOffset , car cette fonction utilise toujours la valeur KERNEL_LOGGER_NAME pour appeler StartKernelTrace. Cette fonction vérifie si Wnode.Guid correspond à SystemTraceControlGuid ; si ce n’est pas le cas, elle retourne ERROR_INVALID_PARAMETER. Si Wnode.Guid correspond à KernelRundownGuid, le nom de l’enregistreur d’événements doit être spécifié. KernelRundownGuid est le GUID de contrôle utilisé pour journaliser les événements tels que les informations de processus existantes, les informations de thread, les images chargées par processus et la configuration matérielle comme le processeur, la vidéo, le disque, les cartes réseau, les services, l’alimentation, les Plug-and-Play et les canaux IDE de disque.

Valeur de retour

ERROR_SUCCESS indique la réussite.

Les valeurs d’erreur possibles sont décrites dans le tableau suivant.

Valeur d’erreur Description

ERROR_ALREADY_EXISTS

Un seul instance du journal du noyau s’exécute sur le système. Si cette fonction tente de démarrer après qu’un autre composant a démarré la journalisation du noyau, cette erreur est probablement retournée.

ERROR_INVALID_FLAGS

Indique peut-être qu’il existe des indicateurs de trace non valides dans Properties.EnableFlags.

ERROR_OUT_OF_MEMORY

Indique éventuellement un échec d’allocation de mémoire pour EVENT_TRACE_PROPERTIES.

Si la fonction échoue pour une raison autre que celles répertoriées, un code d’erreur système est retourné.

Notes

Si StackTracingEventIds contiennent des événements qui ne sont pas activés dans le EVENT_TRACE_PROPERTIES. Champ EnableFlags ou n’a pas pu être décodé par le contrôle de trace du noyau, ces indicateurs sont ignorés et aucun code d’erreur n’est retourné.

Conditions requises :

Versions: Disponible à partir de Windows Vista. Cette structure est distribuée avec windows Analyseur de performances.

En-têtes: Déclaré dans KernelTraceControl.h. Incluez KernelTraceControl.h.

Bibliothèque: Contenu dans KernelTraceControl.dll.

Fonctions

Injection personnalisée d’informations système