Поделиться через

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

  • Статья

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

Важно!

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

Синтаксис

ULONG WMIAPI StartTraceA(
            CONTROLTRACE_ID         *TraceId,
  [in]      LPCSTR                  InstanceName,
  [in, out] PEVENT_TRACE_PROPERTIES Properties
);

Параметры

TraceId

[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 любые системные средства ведения журнала могут одновременно использовать не более 2 различных типов часов. Например, если одно активное средство ведения журнала системы использует тип часов "Счетчик циклов ЦП", а другое активное средство ведения журнала системы использует тип часов "Счетчик производительности запросов", любая попытка запустить системное средство ведения журнала с использованием типа "Системное время" будет завершатся ошибкой, так как потребует активации третьего типа часов. Из-за этого ограничения корпорация Майкрософт настоятельно рекомендует, чтобы системные средства ведения журнала не использовали тип часов "Системное время".
  • Начиная с Windows 10 версии 1703 ограничение типа часов было удалено. Все три типа часов теперь могут одновременно использоваться системными средствами ведения журнала.

Чтобы указать сеанс nt kernel Logger (не рекомендуется), задайте для 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