StartTraceA, fonction (evntrace.h)

  • Article

La fonction StartTrace inscrit et démarre une session de suivi d’événements.

Important

Les sessions de suivi d’événements interprocesseur sont une ressource système limitée. Les développeurs doivent éviter de démarrer des sessions de suivi d’événements sur les ordinateurs des clients. Lorsque des sessions de suivi d’événements sont nécessaires, elles doivent être limitées à l’étendue la plus petite possible : utilisez le moins de sessions possible, utilisez une session in-process uniquement si possible (EVENT_TRACE_PRIVATE_LOGGER_MODE | EVENT_TRACE_PRIVATE_IN_PROC), démarrez la trace uniquement lorsque la collecte est spécifiquement nécessaire pour un scénario, arrêtez la trace dès que le scénario est terminé, limitez la quantité de mémoire utilisée par la session, et utilisent des filtres d’événements stricts afin de ne pas collecter d’événements inutiles.

Syntaxe

ULONG WMIAPI StartTraceA(
  [out]     PTRACEHANDLE            TraceHandle,
  [in]      LPCSTR                  InstanceName,
  [in, out] PEVENT_TRACE_PROPERTIES Properties
);

Paramètres

[out] TraceHandle

Reçoit le handle de la session de suivi d’événements pour une utilisation ultérieure avec des API telles que ControlTrace.

N’utilisez pas ce handle en cas d’échec de la fonction. Ne comparez pas le handle de session à INVALID_HANDLE_VALUE. Le handle de session est 0 si le handle n’est pas valide.

[in] InstanceName

Chaîne terminée par null qui contient le nom de la session de suivi d’événements. Le nom de session est limité à 1 024 caractères, ne respecte pas la casse et doit être unique.

Important

Utilisez un nom descriptif pour votre session afin que la propriété et l’utilisation de la session puissent être déterminées à partir du nom de la session. N’utilisez pas de GUID ou d’autre valeur non déterministe ou non descriptive. N’ajoutez pas de chiffres aléatoires pour rendre votre nom de session unique. Les sessions ETW étant une ressource limitée, votre composant ne doit pas démarrer plusieurs sessions. Si la session de votre composant est déjà en cours d’exécution au démarrage de votre composant, il doit nettoyer la session orpheline au lieu de créer une deuxième session.

Cette fonction copie le nom de session que vous fournissez dans le décalage vers lequel pointe le membre LoggerNameOffset de Properties .

[in, out] Properties

Pointeur vers une structure EVENT_TRACE_PROPERTIES qui spécifie le comportement de la session. Voici les membres clés de la structure à définir :

  • Wnode.BufferSize
  • Wnode.Guid
  • Wnode.ClientContext
  • Wnode.Flags
  • LogFileMode
  • LogFileNameOffset
  • LoggerNameOffset

Selon le type de fichier journal que vous choisissez de créer, vous devrez peut-être également spécifier une valeur pour MaximumFileSize. Consultez la section Remarques pour plus d’informations sur la définition du paramètre Properties et le comportement de la session.

À compter de Windows 10, version 1703 : pour de meilleures performances dans les scénarios inter-processus, vous pouvez maintenant passer le filtrage à StartTrace lors du démarrage des enregistreurs d’événements privés à l’échelle du système. Vous devez transmettre la nouvelle structure de EVENT_TRACE_PROPERTIES_V2 pour inclure les informations de filtrage. Pour plus d’informations, consultez Configuration et démarrage d’une session d’enregistreur d’événements privés .

Valeur retournée

Si la fonction réussit, la valeur de retour est ERROR_SUCCESS.

Si la fonction échoue, la valeur de retour est l’un des codes d’erreur système. Voici quelques erreurs courantes et leurs causes.

  • ERROR_BAD_LENGTH

    Une des conditions suivantes est vraie :

    • Le membre Wnode.BufferSize de Properties spécifie une taille incorrecte.
    • Les propriétés n’ont pas suffisamment d’espace alloué pour contenir une copie de InstanceName.

  • ERROR_INVALID_PARAMETER

    Une des conditions suivantes est vraie :

    • Les propriétés ont la valeur NULL.
    • TraceHandle a la valeur NULL.
    • Le membre LogFileNameOffset de Properties n’est pas valide.
    • Le membre LoggerNameOffset de Properties n’est pas valide.
    • Le membre LogFileMode de Properties spécifie une combinaison d’indicateurs qui n’est pas valide.
    • Le membre Wnode.Guid est SystemTraceControlGuid, mais le paramètre InstanceName n’est pas KERNEL_LOGGER_NAME.

  • ERROR_ALREADY_EXISTS

    Une session portant le même nom ou guid est déjà en cours d’exécution.

  • ERROR_BAD_PATHNAME

    Vous pouvez recevoir cette erreur pour l’une des raisons suivantes :

    • Une autre session utilise déjà le nom de fichier spécifié par le membre LogFileNameOffset de la structure Properties .
    • LogFileMode et LogFileNameOffset sont tous deux zéro.

  • ERROR_DISK_FULL

    Il n’y a pas suffisamment d’espace libre sur le lecteur pour le fichier journal. Cela se produit si :

    • MaximumFileSize est différent de zéro et il n’y a pas d’octets MaximumFileSize disponibles pour le fichier journal
    • le lecteur est un lecteur système et il n’y a pas de 200 Mo supplémentaires disponibles
    • MaximumFileSize est égal à zéro et il n’y a pas de 200 Mo supplémentaires disponibles

    Choisissez un lecteur avec plus d’espace ou réduisez la taille spécifiée dans MaximumFileSize (si elle est utilisée).

  • ERROR_ACCESS_DENIED

    Seuls les utilisateurs disposant de privilèges d’administration, les utilisateurs du groupe Utilisateurs du journal des performances et les services exécutés en tant que LocalSystem, LocalService, NetworkService peuvent contrôler les sessions de suivi d’événements. Pour accorder à un utilisateur restreint la possibilité de contrôler les sessions de suivi, ajoutez-les au groupe Utilisateurs du journal de performances. Seuls les utilisateurs disposant de privilèges d’administration et de services s’exécutant en tant que LocalSystem peuvent contrôler une session d’enregistreur d’événements du noyau NT.

    Si l’utilisateur est membre du groupe Utilisateurs du journal de performances, il n’est peut-être pas autorisé à créer le fichier journal dans le dossier spécifié.

  • ERROR_NO_SYSTEM_RESOURCES

    Une des conditions suivantes est vraie :

    • La session de journalisation utilise l’indicateur EVENT_TRACE_SYSTEM_LOGGER_MODE et le nombre maximal d’enregistreurs d’événements système (8) a été atteint.

    • Le nombre maximal de sessions de journalisation sur le système a été atteint. Aucun nouvel enregistreur d’événements ne peut être créé tant qu’une session de journalisation n’a pas été arrêtée. Sur la plupart des systèmes, le nombre maximal de sessions de journalisation est de 64.

      Vous pouvez modifier le nombre maximal de sessions de journalisation pour un système en modifiant la clé REG_DWORD à l’adresse HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\WMI@EtwMaxLoggers. Les valeurs autorisées sont comprises entre 32 et 256, inclus. Un redémarrage est nécessaire pour que toute modification prenne effet.

      Notez que les enregistreurs d’événements utilisent des ressources système. L’augmentation du nombre d’enregistreurs d’événements sur le système aura un coût de performances si ces emplacements sont remplis. Cette limite existe pour éviter une utilisation excessive des ressources système.

      Important

      La limite doit uniquement être ajustée manuellement par un administrateur système pour activer des scénarios spécifiques. Le paramètre EtwMaxLoggers ne doit pas être automatiquement modifié par un programme ou un pilote.

      Avant Windows 10 version 1709, il s’agit d’un plafond fixe de 64 enregistreurs d’événements pour les enregistreurs d’événements non privés.

Notes

Les contrôleurs de trace d’événements appellent cette fonction.

La session reste active jusqu’à ce que la session soit arrêtée, que l’ordinateur soit redémarré, qu’une erreur d’E/S se produise ou que la taille de fichier maximale soit atteinte pour les journaux non circulaires. Pour arrêter une session de suivi d’événements, appelez la fonction ControlTrace et définissez le paramètre ControlCodesur EVENT_TRACE_CONTROL_STOP.

Vous ne pouvez pas démarrer plusieurs sessions avec le même GUID de session (comme spécifié par Properties.Wnode.Guid). Dans la plupart des cas, vous définissez Properties.Wnode.Guid sur zéro (c’est-à-dire GUID_NULL) pour permettre au système ETW de générer un nouveau GUID pour la session.

Pour spécifier une session d’enregistreur d’événements privé, définissez le membre Wnode.Guid de Propriétés sur le GUID de contrôle du fournisseur, et non sur le GUID de contrôle de la session d’enregistreur d’événements privés. Le fournisseur doit avoir inscrit le GUID avant d’appeler StartTrace.

Vous n’utilisez pas cette fonction pour démarrer une session d’enregistreur d’événements global (déconseillée). Pour plus d’informations sur le démarrage d’une session d’enregistreur d’événements global, consultez Configuration et démarrage de la session d’enregistreur d’événements globaux.

Enregistreurs d’événements système

Pour que l’enregistreur d’événements soit un enregistreur d’événements système et reçoive des événements de SystemTraceProvider ou d’autres fournisseurs système, l’une des conditions suivantes doit être vraie :

  • Le membre Propriétés LogFileMode inclut l’indicateur EVENT_TRACE_SYSTEM_LOGGER_MODE (préféré).
  • Le membre Properties Wnode.Guid est défini sur SystemTraceControlGuid ou GlobalLoggerGuid (déprécié - ne doit pas être utilisé pour le nouveau code, car il entrera en conflit avec d’autres composants qui essaient également d’utiliser ces GUID).
  • InstanceName est défini sur KERNEL_LOGGER_NAME (déconseillé : ne doit pas être utilisé pour le nouveau code, car il entre en conflit avec d’autres composants qui essaient également d’utiliser ce nom).

Notes

 Un enregistreur d’événements système doit définir le membre EnableFlags de la structure EVENT_TRACE_PROPERTIES pour indiquer quels événements SystemTraceProvider doivent être inclus dans la trace.

Étant donné que les enregistreurs d’événements système reçoivent des événements de noyau spéciaux, ils sont soumis à des restrictions supplémentaires :

  • Il ne peut pas y avoir plus de 8 enregistreurs d’événements système actifs sur le même système.
  • Les enregistreurs d’événements système ne peuvent pas être créés dans un conteneur Windows Server.
  • Les enregistreurs d’événements système ne peuvent pas utiliser l’indicateur EVENT_TRACE_USE_PAGED_MEMORY .
  • Avant Windows 10 version 1703, pas plus de 2 types d’horloges distincts peuvent être utilisés simultanément par tous les enregistreurs d’événements système. Par exemple, si un enregistreur d’événements système actif utilise le type d’horloge « Compteur de cycle du processeur » et qu’un autre enregistreur d’événements système actif utilise le type d’horloge « Compteur de performances de requête », toute tentative de démarrage d’un enregistreur d’événements système à l’aide du type d’horloge « Heure système » échouera, car elle nécessiterait l’activation d’un troisième type d’horloge. En raison de cette limitation, Microsoft recommande vivement que les enregistreurs d’événements système n’utilisent pas le type d’horloge « Heure système ».
  • À compter de Windows 10, version 1703, la restriction de type d’horloge a été supprimée. Les trois types d’horloge peuvent désormais être utilisés simultanément par les enregistreurs d’événements système.

Pour spécifier une session d’enregistreur d’événements du noyau NT (déconseillée), définissez InstanceNamesur KERNEL_LOGGER_NAME et le membre Wnode.Guid des propriétés sur SystemTraceControlGuid. Si vous ne spécifiez pas le GUID comme SystemTraceControlGuid, ETW remplace la valeur GUID et la définit sur SystemTraceControlGuid.

Exemples

Pour obtenir un exemple qui utilise StartTrace, consultez Configuration et démarrage d’une session de suivi d’événements.

Notes

L’en-tête evntrace.h définit StartTrace en tant qu’alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. La combinaison de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.

Spécifications

   
Client minimal pris en charge Windows Vista [applications de bureau | Applications UWP]
Serveur minimal pris en charge Windows Server 2008 [applications de bureau | Applications UWP]
Plateforme cible Windows
En-tête evntrace.h
Bibliothèque Sechost.lib sur Windows 8.1 et Windows Server 2012 R2 ; Advapi32.lib sur Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista
DLL Sechost.dll sur Windows 8.1 et Windows Server 2012 R2 ; Advapi32.dll sur Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista

Voir aussi

ControlTrace

EVENT_TRACE_PROPERTIES