Функция StartTraceA (evntrace.h)

  • Статья

Функция StartTrace регистрирует и запускает сеанс трассировки событий.

Важно!

Сеансы трассировки событий между процессами являются ограниченным системным ресурсом. Разработчикам следует избегать запуска сеансов трассировки событий на компьютерах клиентов. Если требуются сеансы трассировки событий, они должны быть ограничены минимально возможной областью: используйте как можно меньше сеансов, по возможности используйте сеанс только внутри процесса (EVENT_TRACE_PRIVATE_LOGGER_MODE | EVENT_TRACE_PRIVATE_IN_PROC), запускать трассировку только тогда, когда сбор данных требуется для сценария, остановить трассировку сразу после завершения сценария, ограничить объем памяти, используемой сеансом. и используют строгие фильтры событий, чтобы не собирать ненужные события.

Синтаксис

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

Параметры

[out] TraceHandle

Получает дескриптор сеанса трассировки событий для последующего использования с ТАКИМИ API, как ControlTrace.

Не используйте этот дескриптор, если функция завершается сбоем. Не сравнивайте дескриптор сеанса с INVALID_HANDLE_VALUE. Дескриптор сеанса равен 0, если дескриптор недопустим.

[in] InstanceName

Строка, завершающаяся значением NULL, содержащая имя сеанса трассировки событий. Имя сеанса ограничено 1024 символами, не учитывает регистр и должно быть уникальным.

Важно!

Используйте описательное имя сеанса, чтобы его владение и использование можно было определить по имени сеанса. Не используйте GUID или другое недетерминированное или описательное значение. Не добавляйте случайные цифры, чтобы сделать имя сеанса уникальным. Сеансы трассировки событий Windows — это ограниченный ресурс, поэтому компонент не должен запускать несколько сеансов. Если сеанс компонента уже запущен при запуске компонента, компонент должен очистить потерянный сеанс, а не создавать второй сеанс.

Эта функция копирует указанное имя сеанса в смещение, на которое указывает элемент LoggerNameOffsetсвойства .

[in, out] Properties

Указатель на структуру EVENT_TRACE_PROPERTIES , указывающую поведение сеанса. Ниже приведены ключевые элементы устанавливаемой структуры.

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

В зависимости от типа создаваемого файла журнала может потребоваться также указать значение параметра MaximumFileSize. Дополнительные сведения о настройке параметра Properties и поведении сеанса см. в разделе Примечания.

Начиная с Windows 10 версии 1703: для повышения производительности в сценариях между процессами теперь можно передать фильтрацию в StartTrace при запуске системных частных средств ведения журнала. Вам потребуется передать новую структуру EVENT_TRACE_PROPERTIES_V2 , чтобы включить сведения о фильтрации. Дополнительные сведения см. в разделе Настройка и запуск сеанса частного средства ведения журнала .

Возвращаемое значение

Если функция выполняется успешно, возвращаемое значение будет ERROR_SUCCESS.

Если функция завершается сбоем, возвращаемое значение является одним из кодов системных ошибок. Ниже приведены некоторые распространенные ошибки и их причины.

  • ERROR_BAD_LENGTH

    Выполняется одно из следующих условий.

    • Элемент Wnode.BufferSizeсвойства указывает неправильный размер.
    • В свойствах недостаточно места, выделенного для хранения копии InstanceName.

  • ERROR_INVALID_PARAMETER

    Выполняется одно из следующих условий.

    • Свойство имеет значение NULL.
    • TraceHandle имеет значение NULL.
    • Недопустимый элемент LogFileNameOffsetсвойства.
    • Недопустимый элемент LoggerNameOffsetсвойства .
    • Элемент LogFileModeсвойства задает недопустимое сочетание флагов.
    • Элементом Wnode.Guid является SystemTraceControlGuid, но параметр InstanceName не KERNEL_LOGGER_NAME.

  • ERROR_ALREADY_EXISTS

    Сеанс с тем же именем или идентификатором GUID уже выполняется.

  • ERROR_BAD_PATHNAME

    Эта ошибка может возникнуть по одной из следующих причин:

    • В другом сеансе уже используется имя файла, указанное в элементе LogFileNameOffset структуры Properties .
    • Параметры LogFileMode и LogFileNameOffset равны нулю.

  • ERROR_DISK_FULL

    На диске недостаточно свободного места для файла журнала. Это происходит в следующих случаях:

    • Параметр MaximumFileSize не равен нулю, и для файла журнала нет байтов MaximumFileSize .
    • диск является системным, и дополнительных доступных 200 МБ нет
    • MaximumFileSize равен нулю, и нет дополнительных доступных 200 МБ

    Выберите диск с большим пространством или уменьшите размер, указанный в параметре MaximumFileSize (если используется).

  • ERROR_ACCESS_DENIED

    Только пользователи с правами администратора, пользователи в группе Пользователи журнала производительности и службы, работающие под управлением LocalSystem, LocalService, NetworkService, могут управлять сеансами трассировки событий. Чтобы предоставить ограниченному пользователю возможность управлять сеансами трассировки, добавьте его в группу Пользователи журнала производительности. Только пользователи с правами администратора и службами, работающими под управлением LocalSystem, могут управлять сеансом средства ведения журнала ядра NT.

    Если пользователь является членом группы Пользователи журнала производительности, у него может не быть разрешения на создание файла журнала в указанной папке.

  • ERROR_NO_SYSTEM_RESOURCES

    Выполняется одно из следующих условий.

    • В сеансе ведения журнала используется флаг EVENT_TRACE_SYSTEM_LOGGER_MODE , и достигнуто максимальное количество системных средств ведения журнала (8).

    • Достигнуто максимальное количество сеансов ведения журнала в системе. Новые средства ведения журнала не могут быть созданы до остановки сеанса ведения журнала. В большинстве систем максимальное число сеансов ведения журнала составляет 64.

      Вы можете изменить максимальное число сеансов ведения журнала для системы, изменив ключ REG_DWORD по адресу HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\WMI@EtwMaxLoggers. Допустимые значения: от 32 до 256 включительно. Для того, чтобы любое изменение вступило в силу, требуется перезагрузка.

      Обратите внимание, что средства ведения журнала используют системные ресурсы. Увеличение количества средств ведения журнала в системе будет стоить за производительность, если эти слоты заполнены. Это ограничение существует для предотвращения чрезмерного использования системных ресурсов.

      Важно!

      Ограничение должно быть настроено только вручную системным администратором для включения определенных сценариев. Параметр EtwMaxLoggers не должен автоматически изменяться программой или драйвером.

      До Windows 10 версии 1709 это фиксированное ограничение — 64 средства ведения журнала для не закрытых средств ведения журнала.

Комментарии

Контроллеры трассировки событий вызывают эту функцию.

Сеанс остается активным до тех пор, пока сеанс не будет остановлен, компьютер не будет перезапущен, не возникнет ошибка ввода-вывода или достигнут максимальный размер файла для не циклических журналов. Чтобы остановить сеанс трассировки событий, вызовите функцию ControlTrace и задайте для параметра ControlCodeзначение EVENT_TRACE_CONTROL_STOP.

Нельзя запустить несколько сеансов с одним и тем же GUID сеанса (как указано в параметре Properties.Wnode.Guid). В большинстве случаев вы устанавливаете значение Properties.Wnode.Guid all-zero (т. е. GUID_NULL), чтобы система трассировки событий Windows создавала новый GUID для сеанса.

Чтобы указать закрытый сеанс средства ведения журнала, задайте в элементе Wnode.Guid свойства GUID элемента управления поставщика, а не GUID элемента управления частного сеанса средства ведения журнала. Поставщик должен зарегистрировать GUID перед вызовом StartTrace.

Эта функция не используется для запуска глобального сеанса средства ведения журнала (не рекомендуется). Дополнительные сведения о запуске сеанса глобального средства ведения журнала см. в разделе Настройка и запуск сеанса глобального средства ведения журнала.

Системные средства ведения журнала

Чтобы средство ведения журнала было системным и получало события от SystemTraceProvider или других системных поставщиков, должно выполняться любое из следующих действий:

  • Элемент СвойстваLogFileMode содержит флаг EVENT_TRACE_SYSTEM_LOGGER_MODE (предпочтительный).
  • Для элемента PropertiesWnode.Guid задано значение SystemTraceControlGuid или GlobalLoggerGuid (не рекомендуется— не следует использовать для нового кода, так как он будет конфликтовать с другими компонентами, которые также пытаются использовать эти GUID).
  • Для instanceName задано значение KERNEL_LOGGER_NAME (нерекомендуемый — не следует использовать для нового кода, так как он будет конфликтовать с другими компонентами, которые также пытаются использовать это имя).

Примечание

 Средство ведения журнала системы должно задать элемент EnableFlags структуры EVENT_TRACE_PROPERTIES , чтобы указать, какие события SystemTraceProvider следует включить в трассировку.

Так как системные средства ведения журнала получают специальные события ядра, на них распространяются дополнительные ограничения:

  • В одной системе может быть не более 8 активных средств ведения журнала.
  • Системные средства ведения журнала не могут быть созданы в контейнере Windows Server.
  • Системные средства ведения журнала не могут использовать флаг EVENT_TRACE_USE_PAGED_MEMORY .
  • До Windows 10 версии 1703 любые системные средства ведения журнала могут одновременно использовать не более двух различных типов часов. Например, если одно активное средство ведения журнала системы использует тип часов "Счетчик циклов ЦП", а другое активное средство ведения журнала системы использует тип часов "Счетчик производительности запросов", то любая попытка запустить системное средство ведения журнала с типом часов "Системное время" завершится ошибкой, так как для этого потребуется активация третьего типа часов. Из-за этого ограничения корпорация Майкрософт настоятельно рекомендует, чтобы системные средства ведения журнала не использовали тип часов "Системное время".
  • Начиная с Windows 10 версии 1703 ограничение типа часов было удалено. Все три типа часов теперь могут одновременно использоваться системными средствами ведения журнала.

Чтобы указать сеанс ведения журнала ядра NT (не рекомендуется), задайте для instanceNameзначение KERNEL_LOGGER_NAME , а для элемента Wnode.Guidсвойства — SystemTraceControlGuid. Если идентификатор GUID не указан как SystemTraceControlGuid, трассировка событий Windows переопределит значение GUID и присвоит ему значение SystemTraceControlGuid.

Примеры

Пример использования StartTrace см. в разделе Настройка и запуск сеанса трассировки событий.

Примечание

Заголовок evntrace.h определяет StartTrace как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Использование псевдонима, не зависящий от кодирования, с кодом, который не является нейтральным для кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или времени выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования

   
Минимальная версия клиента Windows Vista [классические приложения | Приложения UWP]
Минимальная версия сервера Windows Server 2008 [классические приложения | Приложения UWP]
Целевая платформа Windows
Header evntrace.h
Библиотека Sechost.lib в Windows 8.1 и Windows Server 2012 R2; Advapi32.lib в Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista
DLL Sechost.dll в Windows 8.1 и Windows Server 2012 R2; Advapi32.dll в Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista

См. также раздел

ControlTrace

EVENT_TRACE_PROPERTIES