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

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

Синтаксис

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

Параметры

TraceId

[in] InstanceName

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

Эта функция копирует указанное имя сеанса в смещение, на которое указывает элемент 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 (не рекомендуется — не следует использовать для нового кода, так как он будет конфликтовать с другими компонентами, которые также пытаются использовать это имя).

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

• В одной системе может быть не более 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 см. в разделе Настройка и запуск сеанса трассировки событий.

Требования

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

ControlTrace

EVENT_TRACE_PROPERTIES