INF AddAutoLogger 和 UpdateAutoLogger 指令

AddAutoLoggerUpdateAutoLogger 指令在 INF DDInstall 中使用。“事件”部分。 它们为Windows事件跟踪 (ETW) AutoLogger 会话指定特征,这些会话记录在操作系统启动过程中早期发生的事件。 从 Windows 11 开始支持这些指令。

[DDInstall.Events] 

AddAutoLogger=session-name,{SessionGUID},add-autologger-install-section 
UpdateAutoLogger=session-name,update-autologger-install-section 
... 

session-name
指定要添加的 AutoLogger 会话的名称。 此名称需要在计算机上的 AutoLogger 会话集中唯一。 建议会话名称包括公司的名称或公司名称的缩写,因此它与另一家公司的会话名称不冲突。

SessionGUID
指定标识 AutoLogger 会话的 GUID 值。 这可以表示为窗体{nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn}的显式 GUID 值,也可以表示为 INF 文件的 Strings 节中定义的 {nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn} %strkey% 标记。

add-autologger-install-section
引用 INF 编写器定义的节,其中包含注册 AutoLogger 的信息。 有关详细信息,请参阅以下 “备注” 部分。

update-autologger-install-section
引用 INF 编写器定义的节,其中包含用于将提供程序添加到现有 AutoLogger 的信息。 有关详细信息,请参阅以下 “备注” 部分。

注解

有关 AutoLoggers 的详细信息,请参阅 配置和启动 AutoLogger 会话

每个 INF 编写器创建的节名称必须在 INF 文件中是唯一的,并且必须遵循定义节名称的一般规则。 有关这些规则的详细信息,请参阅 INF 文件的一般语法规则

AddAutoLogger 指令必须引用 INF 文件中其他位置的名称 add-autologger-install-section。 每个部分都有以下格式:

[add-autologger-install-section] 

Start=<0 | 1> 
[BufferSize=buffer-size] 
[ClockType=clock-type] 
[DisableRealtimePersistence= <0 | 1>] 
[FileName=path-to-file] 
[FileMax=file-max]
[FlushTimer=flush-timer] 
[LogFileMode=log-file-mode] 
[MaxFileSize=max-file-size] 
[MaximumBuffers=max-buffers] 
[MinimumBuffers=min-buffers] 

(AddAutoLoggerProvider={ProviderGUID},autologger-provider-install-section) 
… 

每个 add-autologger-install-section 都必须提供"开始"菜单。 (可选)使用 AddAutoLoggerProvider 为 AutoLogger 指定一个或多个 AutoLogger 提供程序,每个提供程序位于单独的行上。 有关 INF 文件中的 AutoLogger 提供程序的详细信息,请参阅下面的 “添加 AutoLogger 提供程序 ”。

UpdateAutoLogger 指令必须引用 INF 文件中其他位置的命名 update-autologger-install-section。 每个此类部分都有以下格式:

[update-autologger-install-section] 

(AddAutoLoggerProvider={ProviderGUID},autologger-provider-install-section) 
… 

每个 update-autologger-install-section 都可以使用 AddAutoLoggerProvider 指定一个或多个 AutoLogger 提供程序,每个提供程序位于单独的行上。 有关 INF 文件中的 AutoLogger 提供程序的详细信息,请参阅下面的 “添加 AutoLogger 提供程序 ”。

Add-AutoLogger-Install-Section 条目和值

="开始"菜单0 | 1
指定自动记录程序是否下次重启计算机时启动。 若要启动 AutoLogger,请将此值设置为 1,否则请将此值设置为 0。

BufferSize=buffer-size
(可选)以 KB 为单位指定每个缓冲区的大小。 BufferSize 应小于 1 兆字节。 ETW 使用物理内存的大小来计算此值(如果未设置)。

ClockType=clock-type
(可选)指定在使用以下数值记录每个事件的时间戳时要使用的计时器,这些数字值以十进制表示形式表示,或者,如以下列表所示,以十六进制表示法表示。 如果省略,则默认0x1 ( 性能计数器值) 。

0x1 性能计数器值 ()

0x2 (系统计时器)

0x3 (CPU 周期计数器)

有关每个时钟类型的说明,请参阅 WNODE_HEADER 的 ClientContext 成员。

DisableRealtimePersistence=0 | 1
(可选)通过将值设置为 1,允许禁用实时持久性。 默认值为启用 0 () 。 如果启用了实时持久性,则计算机关闭时未传递的实时事件将持久保存。 然后,下次使用者连接到会话时,事件将传递到使用者。

文件名=file-name
(可选)指定日志文件的完全限定路径。 如果路径不存在,则首次启动 AutoLogger 时,将尽最大努力创建。 FileName 的长度限制为 1024 个字符。 该文件是一个顺序日志文件。 默认文件路径为 %DriverData%\<SessionName.etl>。

FileMax=file-max
(可选)指定 ETW 创建的日志文件的最大实例数。 创建最大文件数后,ETW 将覆盖第一个文件(如果存在)。 支持的日志文件的最大实例数为 16。 请勿将此功能与 EVENT_TRACE_FILE_MODE_NEWLINE LogFileMode 配合使用。

FlushTimer=flush-timer
(可选)指定强制刷新跟踪缓冲区的频率(以秒为单位)。 最小刷新时间为 1 秒。 默认值为 0。 默认情况下,仅当缓冲区已满时才会刷新。

LogFileMode=log-file-mode
(可选)指定一个或多个日志模式。 有关可能的值,请参阅 日志记录模式常量。 默认值 为0x1 (EVENT_TRACE_FILE_MODE_SEQUENTIAL) 。

MaxFileSize=max-file-size
(可选)指定日志文件的最大文件大小(以 MB 为单位)。 达到最大大小时,会话将关闭,除非在 LogFileMode 中指定了EVENT_TRACE_FILE_MODE_CIRCULAR。 若要指定无限制,请将值设置为 0。 默认值为 100 mb。 达到最大文件大小时发生的行为取决于 LogFileMode 的值。

MaximumBuffers=maximum-buffers
(可选)指定要分配的最大缓冲区数,通常是最小缓冲区数加上 20。 此值必须大于或等于 MinimumBuffers 的值。

MinimumBuffers=minimum-buffers
(可选)指定要在启动时分配的最小缓冲区数。 可以指定的最小缓冲区数是每个处理器的两个缓冲区。

AddAutoLoggerProvider={ProviderGUID}autologger-provider-install-section
(可选)使用子指令指定提供程序,该指令引用 INF 文件中其他位置的 INF-writer-defined autologger-provider-install-section。 有关详细信息,请参阅以下 “添加 AutoLogger 提供程序” 部分。

添加 AutoLogger 提供程序

add-autologger-install-sectionupdate-autologger-install-section 部分中 ,可以使用 AddAutoLoggerProvider 指令指定要在会话中启用的提供程序。

ProviderGUID 必须是标识 AutoLogger 提供程序的 GUID 值。 这可以表示为 {nnnn-nnnn-nn} 形式的显式 GUID 值,也可以表示为 INF 文件的 Strings 节中定义为 {nn-nn} 的 %strkey% 令牌。

AddAutoLoggerProvider 子指令还必须引用文件中其他位置的 autologger-provider-install-section 。 每个此类部分都有以下格式:

[autologger-provider-install-section] 

[Enabled=<0 | 1>] 
[EnableFlags=enable-flags] 
[EnableLevel=enable-level] 
[EnablePropety=enable-property] 
[MatchAnyKeyword=match-any-keyword] 
[MatchAllKeyword=match-all-keyword] 

AutoLogger-Provider-Install-Section 条目和值

启用=0 | 1
(可选)提供是否启用提供程序。 若要启用提供程序,请将此值设置为 1。 若要禁用,请将值设置为 0。 默认值为 0。

EnableFlags=enable-flags
(可选)指定提供程序为其生成事件的事件的类。 有关详细信息,请参阅 EnableTraceEx 函数的 EnableFlags 参数。 如果提供程序不支持 MatchAnyKeywordMatchAllKeyword,请指定此值名称。

EnableLevel=enable-level
(可选)提供事件中包含的详细信息级别。 有关预定义级别的列表,请参阅 EnableTraceEx 函数的 Level 参数。

EnableProperty=enable-property
(可选)提供日志文件中包含一个或多个以下项:

0x00000001 (EVENT_ENABLE_PROPERTY_SID) = 在扩展数据中包含用户的安全标识符 (SID) 。

0x00000002 (EVENT_ENABLE_PROPERTY_TS_ID) = 包含在终端会话标识符的扩展数据中。

0x00000004 (EVENT_ENABLE_PROPERTY_STACK_TRACE) = 在扩展数据中包含使用 EventWrite 编写的事件的调用堆栈跟踪。

0x00000010 (EVENT_ENABLE_PROPERTY_IGNORE_KEYWORD_0) = 筛选出未指定非零关键字的所有事件。

0x00000020 (EVENT_ENABLE_PROPERTY_PROVIDER_GROUP) = 指示对 EnableTraceEx2 的此调用应启用 提供程序组 而不是单个事件提供程序。

0x00000080 (EVENT_ENABLE_PROPERTY_PROCESS_START_KEY) = 在扩展数据中包含进程"开始"菜单密钥。

0x00000100 (EVENT_ENABLE_PROPERTY_EVENT_KEY) = 在扩展数据中包含事件密钥。

0x00000200 (EVENT_ENABLE_PROPERTY_EXCLUDE_INPRIVATE) = 筛选出标记为 InPrivate 事件或来自标记为 InPrivate 的进程的所有事件。

MatchAnyKeyword=match-any-keyword
(可选)提供关键字的位掩码,用于确定你希望提供程序写入的事件类别。 如果事件的任何关键字位与此掩码中设置的任何位匹配,提供程序将写入该事件。 若要指定提供程序写入所有事件,请将此值设置为零。 有关示例,请参阅 EnableTraceEx 函数的“备注”部分。

MatchAllKeyword=match-all-keyword
(可选)限制希望提供程序写入的事件类别。 如果事件的关键字满足 MatchAnyKeyword 条件,则仅当此掩码中的所有位都存在于事件的关键字中时,提供程序才会写入该事件。 如果 MatchAnyKeyword 为零,则不使用此掩码。 有关示例,请参阅 EnableTraceEx 函数的“备注”部分。

示例

[Contoso_Add_AutoLogger_Inst] 
Start = 1 
FileName = %%DriverData%%\Contoso\AutoLoggerLogFile.etl  
AddAutoLoggerProvider = {4b8b1947-ae4d-54e2-826a-1aee78ef05b2}, Contoso_Provider_1_Inst

[Contoso_Update_AutoLogger_Inst] 
AddAutoLoggerProvider= {a55d5a23-1a5b-580a-2be5-d7188f43fae1}, Contoso_Provider_2_Inst

[Contoso_Provider_1_Inst] 
Enabled = 1
EnableProperty = 0x00000001

[Contoso_Provider_2_Inst] 
Enabled = 1 

传统兼容性

从 Windows 11 开始,支持 AddAutoLogger 和 UpdateAutoLogger 指令。 若要在下层 OS 上配置 AutoLogger,请使用 AddReg 指令。

[Contoso_AutoLogger_AddReg] 
HKLM,SYSTEM\CurrentControlSet\Control\WMI\Autologger\<autologger-session-name>,Start,0x00010001,1 
HKLM,SYSTEM\CurrentControlSet\Control\WMI\Autologger\<autologger-session-name>,GUID,,{autologger-guid} 
HKLM,SYSTEM\CurrentControlSet\Control\WMI\Autologger\<autologger-session-name>\{autologger-provider-guid},Enabled,0x00010001,1 

另请参阅

DDInstall。事件