en-US/PSEtw.dll-Help.xml
|
<?xml version="1.0" encoding="utf-8"?> <helpItems schema="maml" xmlns="http://msh"> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>New-PSEtwEventInfo</command:name> <command:verb>New</command:verb> <command:noun>PSEtwEventInfo</command:noun> <maml:description> <maml:para>Create a trace info object used for filtering traces with an ETW event.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>This cmdlet is used to create a trace info object that can be used to filter ETW trace events started with Register-PSEtwEvent (./Register-PSEtwEvent.md) or [Trace-PSEtwEvent](./Trace-PSEtwEvent.md). It describes the provider to trace as well as any keywords or levels to filter by in the trace itself.</maml:para> <maml:para>Multiple trace info objects can be provided to a trace event loop allowing the caller to capture traces using multiple criteria values.</maml:para> <maml:para>This cmdlet supports tab completion to autocomplete and list the available values for each parameter. The default value for Windows PSReadLine to list all parameters and a description is to use `ctrl + space` after the parameter name like `New-PSEtwEventInfo -Provider <ctrl + space>`. Each parameter matches with a simple wildcard pattern to filter the available options further. The `-KeywordsAll`, `-KeywordsAny`, and `-Level` parameters can display provider specific values if `-Provider` is already set in the call when tab completing those values.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>New-PSEtwEventInfo</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none"> <maml:name>KeywordsAll</maml:name> <maml:description> <maml:para>Restrict the events for the specified provider to only the ones that match all the keywords specified here. This filter does not apply to events that do not have a keyword associated with it.</maml:para> <maml:para>The keyword can either be specified as a 64-bit integer value which are combined together or as a string representing the keyword. The keyword strings are dependent on the provider that was specified and what keywords it defines through its manifest. Trace Logging providers that aren't registered on the system cannot be filtered by name, the integer value must be specified for these providers. This parameter supports tab completion to retrieve the keywords for a registered provider if one is set by `-Provider`. The value `*` represents the numeric value `0xFFFFFFFFFFFFFFFF` which is all keywords set.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">KeywordsStringOrLong[]</command:parameterValue> <dev:type> <maml:name>KeywordsStringOrLong[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none"> <maml:name>KeywordsAny</maml:name> <maml:description> <maml:para>Restrict the events for the specified provider to only the ones that match any of the keywords specified here. This filter does not apply to events that do not have a keyword associated with it.</maml:para> <maml:para>The keyword can either be specified as a 64-bit integer value which are combined together or as a string representing the keyword. The keyword strings are dependent on the provider that was specified and what keywords it defines through its manifest. Trace Logging providers that aren't registered on the system cannot be filtered by name, the integer value must be specified for these providers. This parameter supports tab completion to retrieve the keywords for a registered provider if one is set by `-Provider`. The value `*` represents the numeric value `0xFFFFFFFFFFFFFFFF` which is all keywords set.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">KeywordsStringOrLong[]</command:parameterValue> <dev:type> <maml:name>KeywordsStringOrLong[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none"> <maml:name>Level</maml:name> <maml:description> <maml:para>Restricts the events to only ones with a level that is equal to or less than the level specified. Builtin levels are:</maml:para> <maml:para>+ `0` - `LogAlways` - only events with `LogAlways` will be emitted + `1` - `Critical` + `2` - `Error` + `3` - `Warning` + `4` - `Info` + `5` - `Verbose` + `0xFF` - `*`</maml:para> <maml:para>Some providers may implement custom levels which can be specified by the numeric value or by name. Use tab completion with `-Provider` set to see the known levels for the provider in use. The level `*` or `0xFF` is set then all levels will be captured. If no level is set then the default is `4 (Info)`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">LevelStringOrInt</command:parameterValue> <dev:type> <maml:name>LevelStringOrInt</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="proga"> <maml:name>ProgressAction</maml:name> <maml:description> <maml:para>New common parameter introduced in PowerShell 7.4.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ActionPreference</command:parameterValue> <dev:type> <maml:name>ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none"> <maml:name>Provider</maml:name> <maml:description> <maml:para>The provider name or guid to retrieve events for. This parameter supports tab completion to retrieve all available providers that have been registered on the system. Trace Logger providers can be specified by name but as they are not registered on the system by name they cannot be validated when creating the filter. If set to a registered provider, other parameters tab completion can retrieve values specific to that provider for example `New-PSEtwEventInfo -Provider PowerShellCore -KeywordsAny <ctrl+space>`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ProviderStringOrGuid</command:parameterValue> <dev:type> <maml:name>ProviderStringOrGuid</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none"> <maml:name>KeywordsAll</maml:name> <maml:description> <maml:para>Restrict the events for the specified provider to only the ones that match all the keywords specified here. This filter does not apply to events that do not have a keyword associated with it.</maml:para> <maml:para>The keyword can either be specified as a 64-bit integer value which are combined together or as a string representing the keyword. The keyword strings are dependent on the provider that was specified and what keywords it defines through its manifest. Trace Logging providers that aren't registered on the system cannot be filtered by name, the integer value must be specified for these providers. This parameter supports tab completion to retrieve the keywords for a registered provider if one is set by `-Provider`. The value `*` represents the numeric value `0xFFFFFFFFFFFFFFFF` which is all keywords set.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">KeywordsStringOrLong[]</command:parameterValue> <dev:type> <maml:name>KeywordsStringOrLong[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none"> <maml:name>KeywordsAny</maml:name> <maml:description> <maml:para>Restrict the events for the specified provider to only the ones that match any of the keywords specified here. This filter does not apply to events that do not have a keyword associated with it.</maml:para> <maml:para>The keyword can either be specified as a 64-bit integer value which are combined together or as a string representing the keyword. The keyword strings are dependent on the provider that was specified and what keywords it defines through its manifest. Trace Logging providers that aren't registered on the system cannot be filtered by name, the integer value must be specified for these providers. This parameter supports tab completion to retrieve the keywords for a registered provider if one is set by `-Provider`. The value `*` represents the numeric value `0xFFFFFFFFFFFFFFFF` which is all keywords set.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">KeywordsStringOrLong[]</command:parameterValue> <dev:type> <maml:name>KeywordsStringOrLong[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none"> <maml:name>Level</maml:name> <maml:description> <maml:para>Restricts the events to only ones with a level that is equal to or less than the level specified. Builtin levels are:</maml:para> <maml:para>+ `0` - `LogAlways` - only events with `LogAlways` will be emitted + `1` - `Critical` + `2` - `Error` + `3` - `Warning` + `4` - `Info` + `5` - `Verbose` + `0xFF` - `*`</maml:para> <maml:para>Some providers may implement custom levels which can be specified by the numeric value or by name. Use tab completion with `-Provider` set to see the known levels for the provider in use. The level `*` or `0xFF` is set then all levels will be captured. If no level is set then the default is `4 (Info)`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">LevelStringOrInt</command:parameterValue> <dev:type> <maml:name>LevelStringOrInt</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="proga"> <maml:name>ProgressAction</maml:name> <maml:description> <maml:para>New common parameter introduced in PowerShell 7.4.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ActionPreference</command:parameterValue> <dev:type> <maml:name>ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none"> <maml:name>Provider</maml:name> <maml:description> <maml:para>The provider name or guid to retrieve events for. This parameter supports tab completion to retrieve all available providers that have been registered on the system. Trace Logger providers can be specified by name but as they are not registered on the system by name they cannot be validated when creating the filter. If set to a registered provider, other parameters tab completion can retrieve values specific to that provider for example `New-PSEtwEventInfo -Provider PowerShellCore -KeywordsAny <ctrl+space>`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ProviderStringOrGuid</command:parameterValue> <dev:type> <maml:name>ProviderStringOrGuid</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>PSEtw.Shared.ProviderStringOrGuid</maml:name> </dev:type> <maml:description> <maml:para>The provider string or guid can be passed as input using the property name `Provider`.</maml:para> </maml:description> </command:inputType> <command:inputType> <dev:type> <maml:name>PSEtw.Shared.KeywordsStringOrLong[]</maml:name> </dev:type> <maml:description> <maml:para>The keywords all/any string or numeric flag value can be passed as input using the property name `KeywordsAll` or `KeywordsAny`.</maml:para> </maml:description> </command:inputType> <command:inputType> <dev:type> <maml:name>PSEtw.Shared.LevelStringOrInt[]</maml:name> </dev:type> <maml:description> <maml:para>The level name or numeric flag value can be passed as input using the property name `Level`.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>PSEtw.Shared.EtwTraceInfo</maml:name> </dev:type> <maml:description> <maml:para>This cmdlet outputs an `EtwTraceInfo` that contains trace details to use when starting a trace. It can be provided using the `-TraceInfo` cmdlet or piped into the Register-PSEtwEvent (./Register-PSEtwEvent.md) or Trace-PSEtwEvent (./Trace-PSEtwEvent.md)cmdlets.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- Example 1 --------------------------</maml:title> <dev:code>PS C:\> $eventParams = @{ Provider = 'PowerShellCore' KeywordsAny = 'Runspace', 'Pipeline' Level = 'Verbose' } PS C:\> $info = New-PSEtwEventInfo @eventParams PS C:\> $info | Trace-PSEtwEvent</dev:code> <dev:remarks> <maml:para>Creates a event info that can be used to filter events for the `PowerShellCore` provider, the keywords `Runspace`, `Pipeline`, and all events lower than the `Verbose` level.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>https://www.github.com/jborean93/PSEtw/blob/main/docs/en-US/New-PSEtwEventInfo.md</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>EnableTraceEx2</maml:linkText> <maml:uri>https://learn.microsoft.com/en-us/windows/win32/api/evntrace/nf-evntrace-enabletraceex2</maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>New-PSEtwSession</command:name> <command:verb>New</command:verb> <command:noun>PSEtwSession</command:noun> <maml:description> <maml:para>Creates a new ETW Trace Session.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Creates a new ETW Trace Session that can be used by other cmdlets in this module to perform real time tracing. This is a cut down cmdlet of Start-EtwTraceSession (https://learn.microsoft.com/en-us/powershell/module/eventtracingmanagement/start-etwtracesession?view=windowsserver2022-ps) provided by this module to create a new session that is usable with [Register-PSEtwEvent](./Register-PSEtwEvent.md) or [Trace-PSEtwEvent](./Trace-PSEtwEvent.md).</maml:para> <maml:para>A session is global to the host and will persist even after the current process has ended. Use Remove-PSEtwSession (./Remove-PSEtwSession.md) or [Stop-EtwTraceSession](https://learn.microsoft.com/en-us/powershell/module/eventtracingmanagement/stop-etwtracesession?view=windowsserver2022-ps)to remove a trace session on the host.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>New-PSEtwSession</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Default</maml:name> <maml:description> <maml:para>Creates the default ETW Trace Session used by this module called `PSEtw`. Always implies `-SystemLogger` is set to ensure the trace session can trace other processes. The default Trace Session is used if no `-SessionName` is specified with Registser-PSEtwEvent (./Register-PSEtwEvent.md) or [Trace-PSEtwEvent](./Trace-PSEtwEvent.md).</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="proga"> <maml:name>ProgressAction</maml:name> <maml:description> <maml:para>New common parameter introduced in PowerShell 7.4.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ActionPreference</command:parameterValue> <dev:type> <maml:name>ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="cf"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="wi"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>New-PSEtwSession</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="0" aliases="Name"> <maml:name>SessionName</maml:name> <maml:description> <maml:para>The name of the session to be created. A session name cannot exceed 1024 characters, is case insensitive, and must be unique.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">TraceSessionOrString[]</command:parameterValue> <dev:type> <maml:name>TraceSessionOrString[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="proga"> <maml:name>ProgressAction</maml:name> <maml:description> <maml:para>New common parameter introduced in PowerShell 7.4.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ActionPreference</command:parameterValue> <dev:type> <maml:name>ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SystemLogger</maml:name> <maml:description> <maml:para>Will create the trace session with the `EVENT_TRACE_SYSTEM_LOGGER_MODE` flag. This flag allows the trace session to trace other processes and not just the current process. This requires the current user to be a member of the local Administrators group.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="cf"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="wi"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Default</maml:name> <maml:description> <maml:para>Creates the default ETW Trace Session used by this module called `PSEtw`. Always implies `-SystemLogger` is set to ensure the trace session can trace other processes. The default Trace Session is used if no `-SessionName` is specified with Registser-PSEtwEvent (./Register-PSEtwEvent.md) or [Trace-PSEtwEvent](./Trace-PSEtwEvent.md).</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="proga"> <maml:name>ProgressAction</maml:name> <maml:description> <maml:para>New common parameter introduced in PowerShell 7.4.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ActionPreference</command:parameterValue> <dev:type> <maml:name>ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="0" aliases="Name"> <maml:name>SessionName</maml:name> <maml:description> <maml:para>The name of the session to be created. A session name cannot exceed 1024 characters, is case insensitive, and must be unique.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">TraceSessionOrString[]</command:parameterValue> <dev:type> <maml:name>TraceSessionOrString[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SystemLogger</maml:name> <maml:description> <maml:para>Will create the trace session with the `EVENT_TRACE_SYSTEM_LOGGER_MODE` flag. This flag allows the trace session to trace other processes and not just the current process. This requires the current user to be a member of the local Administrators group.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="cf"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="wi"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.String[]</maml:name> </dev:type> <maml:description> <maml:para>The names of the session to create.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>PSEtw.Shared.EtwTraceSession</maml:name> </dev:type> <maml:description> <maml:para>An `EtwTraceSession` object that can be used with other cmdlets in this module. Disposing this object will dispose the handle but the session will still persist unless removed with Remove-PSEtwSession (./Remove-PSEtwSession.md).</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>--------- Example 1 - Create and remove Trace Session ---------</maml:title> <dev:code>PS C:\> $session = New-PSEtwSession -Name MySession PS C:\> $session | Remove-PSEtwSession</dev:code> <dev:remarks> <maml:para>Creates a new ETW Trace Session called `MySession` then removes it.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------- Example 2 - Creates the default PSEtw Session --------</maml:title> <dev:code>PS C:\> New-PSEtwSession -Default</dev:code> <dev:remarks> <maml:para>Creates the default ETW Trace Session used by this module when no explicit session was specified. This requires admin access to perform as it is created as a System logger.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>----------- Example 3 - Create system logger session -----------</maml:title> <dev:code>PS C:\> New-PSEtwSession -Name MySession -SystemLogger</dev:code> <dev:remarks> <maml:para>Creates a new ETW Trace Session called `MySession` with the flag `EVENT_TRACE_SYSTEM_LOGGER_MODE` set. A system logger session can trace other processes but requires admin access to create.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>https://www.github.com/jborean93/PSEtw/blob/main/docs/en-US/New-PSEtwSession.md</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>StartTraceW</maml:linkText> <maml:uri>https://learn.microsoft.com/en-us/windows/win32/api/evntrace/nf-evntrace-starttracew</maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Register-PSEtwEvent</command:name> <command:verb>Register</command:verb> <command:noun>PSEtwEvent</command:noun> <maml:description> <maml:para>Subscribes to the events generated by an ETW Trace Session.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>This cmdlet can be used to subscribe ETW traces as PowerShell events similar to how Register-ObjectEvent (https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/register-objectevent?view=powershell-7.4)works for .NET object events. When a subscribed trace event is raised, it is added to the event queue in your session. Events in the queue can be retrieved by Get-Event (https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/get-event?view=powershell-7.4) and/or [Wait-Event](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/wait-event?view=powershell-7.4).</maml:para> <maml:para>The parameters for this cmdlet define what ETW providers to register to, the keywords, and levels for that provider to subscribe to. It is possible to use New-PSEtwEventInfo (./New-PSEtwEventInfo.md)to define multiple filters when creating an ETW trace.</maml:para> <maml:para>When an ETW event is registered, an event subscriber is added to your session. To get the event subscribers in the session, use the Get-EventSubscriber (https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/get-eventsubscriber?view=powershell-7.4)cmdlet. To cancel/stop the subscription, use the Unregister-Event (https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/unregister-event?view=powershell-7.4)cmdlet. It is important that any registered subscribers are unregistered when no longer needed so that the trace session is no longer using any system resources.</maml:para> <maml:para>The Trace-PSEtwEvent (./Trace-PSEtwEvent.md)cmdlet can be used to retrieve ETW events in realtime without having to go through PowerShell's eventing system. See about_PSEtwEventArgs (./about_PSEtwEventArgs.md)for more information on the structure of the event data that is set in `SourceEventArgs`.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Register-PSEtwEvent</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Action</maml:name> <maml:description> <maml:para>Specifies the commands to handle the ETW trace. The commands in the Action run when an event is raised, instead of sending the event to the event queue. Enclose the commands in braces `{ }` to create a script block.</maml:para> <maml:para>The value of the Action parameter can include the following automatic variables:</maml:para> <maml:para>+ `$Event` - The full event details, includes `SourceEventArgs`, `Sender`, and other PowerShell event data</maml:para> <maml:para>+ `$EventSubscriber` - The PowerShell event subscriber for the current event</maml:para> <maml:para>+ `$Sender` - The event sender (same as `$Event.Sender`), this currently has no use</maml:para> <maml:para>+ `$EventArgs` - The event data (same as `$Event.SourceEventArgs`), see about_PSEtwEventArgs (./about_PSEtwEventArgs.md)to see more information on this object</maml:para> <maml:para>+ `$Args` - The `$Sender` and `$EventArgs` value that can be provided through params as positional arguments</maml:para> <maml:para>As `$Args` are supplied positionally, the script block can be run with a param block that accepts two arguments. The first being the `$Sender` and the second being `$EventArgs`. Typically the `$EventArgs` is the variable of most interest to a user as it contains the ETW trace information.</maml:para> <maml:para>These variables provide information about the event to the Action script block. For more information, see about_Automatic_Variables (https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_automatic_variables?view=powershell-7.4).</maml:para> <maml:para>When you specify an action, `Register-PSEtwEvent` returns an event job object that represents that action. You can use the Job cmdlets to manage the event job.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ScriptBlock</command:parameterValue> <dev:type> <maml:name>ScriptBlock</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Forward</maml:name> <maml:description> <maml:para>Indicates that the cmdlet sends events for this subscription to a remote session. Use this parameter when you are registering for events on a remote computer or in a remote session.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>IncludeRawData</maml:name> <maml:description> <maml:para>Stores the raw event data as part of the `EventData` property of the returned event arg object. If not set this property will be an empty array. This is useful when needing to debug the event data if the parser failed to extract the event information.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>KeywordsAll</maml:name> <maml:description> <maml:para>Restrict the events for the specified provider to only the ones that match all the keywords specified here. This filter does not apply to events that do not have a keyword associated with it.</maml:para> <maml:para>The keyword can either be specified as a 64-bit integer value which are combined together or as a string representing the keyword. The keyword strings are dependent on the provider that was specified and what keywords it defines through its manifest. Trace Logging providers that aren't registered on the system cannot be filtered by name, the integer value must be specified for these providers. This parameter supports tab completion to retrieve the keywords for a registered provider if one is set by `-Provider`. The value `*` represents the numeric value `0xFFFFFFFFFFFFFFFF` which is all keywords set.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">KeywordsStringOrLong[]</command:parameterValue> <dev:type> <maml:name>KeywordsStringOrLong[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>KeywordsAny</maml:name> <maml:description> <maml:para>Restrict the events for the specified provider to only the ones that match any of the keywords specified here. This filter does not apply to events that do not have a keyword associated with it.</maml:para> <maml:para>The keyword can either be specified as a 64-bit integer value which are combined together or as a string representing the keyword. The keyword strings are dependent on the provider that was specified and what keywords it defines through its manifest. Trace Logging providers that aren't registered on the system cannot be filtered by name, the integer value must be specified for these providers. This parameter supports tab completion to retrieve the keywords for a registered provider if one is set by `-Provider`. The value `*` represents the numeric value `0xFFFFFFFFFFFFFFFF` which is all keywords set.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">KeywordsStringOrLong[]</command:parameterValue> <dev:type> <maml:name>KeywordsStringOrLong[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Level</maml:name> <maml:description> <maml:para>Restricts the events to only ones with a level that is equal to or less than the level specified. Builtin levels are:</maml:para> <maml:para>+ `0` - `LogAlways` - only events with `LogAlways` will be emitted + `1` - `Critical` + `2` - `Error` + `3` - `Warning` + `4` - `Info` + `5` - `Verbose` + `0xFF` - `*`</maml:para> <maml:para>Some providers may implement custom levels which can be specified by the numeric value or by name. Use tab completion with `-Provider` set to see the known levels for the provider in use. The level `*` or `0xFF` is set then all levels will be captured. If no level is set then the default is `4 (Info)`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">LevelStringOrInt</command:parameterValue> <dev:type> <maml:name>LevelStringOrInt</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>MaxTriggerCount</maml:name> <maml:description> <maml:para>Specifies the maximum number of times an event can be triggered.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>MessageData</maml:name> <maml:description> <maml:para>Specifies any additional data to be associated with this event subscription. The value of this parameter appears in the MessageData property of all events associated with this subscription.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PSObject</command:parameterValue> <dev:type> <maml:name>PSObject</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="proga"> <maml:name>ProgressAction</maml:name> <maml:description> <maml:para>New common parameter introduced in PowerShell 7.4.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ActionPreference</command:parameterValue> <dev:type> <maml:name>ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Provider</maml:name> <maml:description> <maml:para>The provider name or guid to retrieve events for. This parameter supports tab completion to retrieve all available providers that have been registered on the system. Trace Logger providers can be specified by name but as they are not registered on the system by name they cannot be validated when creating the filter. If set to a registered provider, other parameters tab completion can retrieve values specific to that provider for example `Register-PSEtwEvent -Provider PowerShellCore -KeywordsAny <ctrl+space>`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ProviderStringOrGuid</command:parameterValue> <dev:type> <maml:name>ProviderStringOrGuid</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="Name"> <maml:name>SessionName</maml:name> <maml:description> <maml:para>Register the events on the ETW trace session specified. A trace session can be created with New-PSEtwSession (./New-PSEtwSession.md). When running the process as an administrator, a default ETW Trace Session called `PSEtw` will be created and used. Non-administrative sessions will attempt to open this session which may work depending on the permissions applied to the trace session and what groups the user is a member of.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SourceIdentifier</maml:name> <maml:description> <maml:para>Specifies a name that you select for the subscription. The name that you select must be unique in the current session. The default value is the GUID that PowerShell assigns.</maml:para> <maml:para>The value of this parameter appears in the value of the SourceIdentifier property of the subscriber object and all event objects associated with this subscription.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SupportEvent</maml:name> <maml:description> <maml:para>Indicates that the cmdlet hides the event subscription. Use this parameter when the current subscription is part of a more complex event registration mechanism and should not be discovered independently.</maml:para> <maml:para>To view or cancel a subscription that was created with the SupportEvent parameter, use the Force parameter of the `Get-EventSubscriber` and `Unregister-Event` cmdlets.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Register-PSEtwEvent</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Action</maml:name> <maml:description> <maml:para>Specifies the commands to handle the ETW trace. The commands in the Action run when an event is raised, instead of sending the event to the event queue. Enclose the commands in braces `{ }` to create a script block.</maml:para> <maml:para>The value of the Action parameter can include the following automatic variables:</maml:para> <maml:para>+ `$Event` - The full event details, includes `SourceEventArgs`, `Sender`, and other PowerShell event data</maml:para> <maml:para>+ `$EventSubscriber` - The PowerShell event subscriber for the current event</maml:para> <maml:para>+ `$Sender` - The event sender (same as `$Event.Sender`), this currently has no use</maml:para> <maml:para>+ `$EventArgs` - The event data (same as `$Event.SourceEventArgs`), see about_PSEtwEventArgs (./about_PSEtwEventArgs.md)to see more information on this object</maml:para> <maml:para>+ `$Args` - The `$Sender` and `$EventArgs` value that can be provided through params as positional arguments</maml:para> <maml:para>As `$Args` are supplied positionally, the script block can be run with a param block that accepts two arguments. The first being the `$Sender` and the second being `$EventArgs`. Typically the `$EventArgs` is the variable of most interest to a user as it contains the ETW trace information.</maml:para> <maml:para>These variables provide information about the event to the Action script block. For more information, see about_Automatic_Variables (https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_automatic_variables?view=powershell-7.4).</maml:para> <maml:para>When you specify an action, `Register-PSEtwEvent` returns an event job object that represents that action. You can use the Job cmdlets to manage the event job.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ScriptBlock</command:parameterValue> <dev:type> <maml:name>ScriptBlock</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Forward</maml:name> <maml:description> <maml:para>Indicates that the cmdlet sends events for this subscription to a remote session. Use this parameter when you are registering for events on a remote computer or in a remote session.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>IncludeRawData</maml:name> <maml:description> <maml:para>Stores the raw event data as part of the `EventData` property of the returned event arg object. If not set this property will be an empty array. This is useful when needing to debug the event data if the parser failed to extract the event information.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>MaxTriggerCount</maml:name> <maml:description> <maml:para>Specifies the maximum number of times an event can be triggered.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>MessageData</maml:name> <maml:description> <maml:para>Specifies any additional data to be associated with this event subscription. The value of this parameter appears in the MessageData property of all events associated with this subscription.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PSObject</command:parameterValue> <dev:type> <maml:name>PSObject</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="proga"> <maml:name>ProgressAction</maml:name> <maml:description> <maml:para>New common parameter introduced in PowerShell 7.4.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ActionPreference</command:parameterValue> <dev:type> <maml:name>ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="Name"> <maml:name>SessionName</maml:name> <maml:description> <maml:para>Register the events on the ETW trace session specified. A trace session can be created with New-PSEtwSession (./New-PSEtwSession.md). When running the process as an administrator, a default ETW Trace Session called `PSEtw` will be created and used. Non-administrative sessions will attempt to open this session which may work depending on the permissions applied to the trace session and what groups the user is a member of.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SourceIdentifier</maml:name> <maml:description> <maml:para>Specifies a name that you select for the subscription. The name that you select must be unique in the current session. The default value is the GUID that PowerShell assigns.</maml:para> <maml:para>The value of this parameter appears in the value of the SourceIdentifier property of the subscriber object and all event objects associated with this subscription.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SupportEvent</maml:name> <maml:description> <maml:para>Indicates that the cmdlet hides the event subscription. Use this parameter when the current subscription is part of a more complex event registration mechanism and should not be discovered independently.</maml:para> <maml:para>To view or cancel a subscription that was created with the SupportEvent parameter, use the Force parameter of the `Get-EventSubscriber` and `Unregister-Event` cmdlets.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="named" aliases="none"> <maml:name>TraceInfo</maml:name> <maml:description> <maml:para>Specifies the trace info objects to filter by. These objects can be created by New-PSEtwEventInfo (./New-PSEtwEventInfo.md). Each trace info object specifies what traces to register with.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">EtwEventInfo[]</command:parameterValue> <dev:type> <maml:name>EtwEventInfo[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Action</maml:name> <maml:description> <maml:para>Specifies the commands to handle the ETW trace. The commands in the Action run when an event is raised, instead of sending the event to the event queue. Enclose the commands in braces `{ }` to create a script block.</maml:para> <maml:para>The value of the Action parameter can include the following automatic variables:</maml:para> <maml:para>+ `$Event` - The full event details, includes `SourceEventArgs`, `Sender`, and other PowerShell event data</maml:para> <maml:para>+ `$EventSubscriber` - The PowerShell event subscriber for the current event</maml:para> <maml:para>+ `$Sender` - The event sender (same as `$Event.Sender`), this currently has no use</maml:para> <maml:para>+ `$EventArgs` - The event data (same as `$Event.SourceEventArgs`), see about_PSEtwEventArgs (./about_PSEtwEventArgs.md)to see more information on this object</maml:para> <maml:para>+ `$Args` - The `$Sender` and `$EventArgs` value that can be provided through params as positional arguments</maml:para> <maml:para>As `$Args` are supplied positionally, the script block can be run with a param block that accepts two arguments. The first being the `$Sender` and the second being `$EventArgs`. Typically the `$EventArgs` is the variable of most interest to a user as it contains the ETW trace information.</maml:para> <maml:para>These variables provide information about the event to the Action script block. For more information, see about_Automatic_Variables (https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_automatic_variables?view=powershell-7.4).</maml:para> <maml:para>When you specify an action, `Register-PSEtwEvent` returns an event job object that represents that action. You can use the Job cmdlets to manage the event job.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ScriptBlock</command:parameterValue> <dev:type> <maml:name>ScriptBlock</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Forward</maml:name> <maml:description> <maml:para>Indicates that the cmdlet sends events for this subscription to a remote session. Use this parameter when you are registering for events on a remote computer or in a remote session.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>IncludeRawData</maml:name> <maml:description> <maml:para>Stores the raw event data as part of the `EventData` property of the returned event arg object. If not set this property will be an empty array. This is useful when needing to debug the event data if the parser failed to extract the event information.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>KeywordsAll</maml:name> <maml:description> <maml:para>Restrict the events for the specified provider to only the ones that match all the keywords specified here. This filter does not apply to events that do not have a keyword associated with it.</maml:para> <maml:para>The keyword can either be specified as a 64-bit integer value which are combined together or as a string representing the keyword. The keyword strings are dependent on the provider that was specified and what keywords it defines through its manifest. Trace Logging providers that aren't registered on the system cannot be filtered by name, the integer value must be specified for these providers. This parameter supports tab completion to retrieve the keywords for a registered provider if one is set by `-Provider`. The value `*` represents the numeric value `0xFFFFFFFFFFFFFFFF` which is all keywords set.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">KeywordsStringOrLong[]</command:parameterValue> <dev:type> <maml:name>KeywordsStringOrLong[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>KeywordsAny</maml:name> <maml:description> <maml:para>Restrict the events for the specified provider to only the ones that match any of the keywords specified here. This filter does not apply to events that do not have a keyword associated with it.</maml:para> <maml:para>The keyword can either be specified as a 64-bit integer value which are combined together or as a string representing the keyword. The keyword strings are dependent on the provider that was specified and what keywords it defines through its manifest. Trace Logging providers that aren't registered on the system cannot be filtered by name, the integer value must be specified for these providers. This parameter supports tab completion to retrieve the keywords for a registered provider if one is set by `-Provider`. The value `*` represents the numeric value `0xFFFFFFFFFFFFFFFF` which is all keywords set.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">KeywordsStringOrLong[]</command:parameterValue> <dev:type> <maml:name>KeywordsStringOrLong[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Level</maml:name> <maml:description> <maml:para>Restricts the events to only ones with a level that is equal to or less than the level specified. Builtin levels are:</maml:para> <maml:para>+ `0` - `LogAlways` - only events with `LogAlways` will be emitted + `1` - `Critical` + `2` - `Error` + `3` - `Warning` + `4` - `Info` + `5` - `Verbose` + `0xFF` - `*`</maml:para> <maml:para>Some providers may implement custom levels which can be specified by the numeric value or by name. Use tab completion with `-Provider` set to see the known levels for the provider in use. The level `*` or `0xFF` is set then all levels will be captured. If no level is set then the default is `4 (Info)`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">LevelStringOrInt</command:parameterValue> <dev:type> <maml:name>LevelStringOrInt</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>MaxTriggerCount</maml:name> <maml:description> <maml:para>Specifies the maximum number of times an event can be triggered.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>MessageData</maml:name> <maml:description> <maml:para>Specifies any additional data to be associated with this event subscription. The value of this parameter appears in the MessageData property of all events associated with this subscription.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PSObject</command:parameterValue> <dev:type> <maml:name>PSObject</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="proga"> <maml:name>ProgressAction</maml:name> <maml:description> <maml:para>New common parameter introduced in PowerShell 7.4.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ActionPreference</command:parameterValue> <dev:type> <maml:name>ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Provider</maml:name> <maml:description> <maml:para>The provider name or guid to retrieve events for. This parameter supports tab completion to retrieve all available providers that have been registered on the system. Trace Logger providers can be specified by name but as they are not registered on the system by name they cannot be validated when creating the filter. If set to a registered provider, other parameters tab completion can retrieve values specific to that provider for example `Register-PSEtwEvent -Provider PowerShellCore -KeywordsAny <ctrl+space>`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ProviderStringOrGuid</command:parameterValue> <dev:type> <maml:name>ProviderStringOrGuid</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="Name"> <maml:name>SessionName</maml:name> <maml:description> <maml:para>Register the events on the ETW trace session specified. A trace session can be created with New-PSEtwSession (./New-PSEtwSession.md). When running the process as an administrator, a default ETW Trace Session called `PSEtw` will be created and used. Non-administrative sessions will attempt to open this session which may work depending on the permissions applied to the trace session and what groups the user is a member of.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SourceIdentifier</maml:name> <maml:description> <maml:para>Specifies a name that you select for the subscription. The name that you select must be unique in the current session. The default value is the GUID that PowerShell assigns.</maml:para> <maml:para>The value of this parameter appears in the value of the SourceIdentifier property of the subscriber object and all event objects associated with this subscription.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SupportEvent</maml:name> <maml:description> <maml:para>Indicates that the cmdlet hides the event subscription. Use this parameter when the current subscription is part of a more complex event registration mechanism and should not be discovered independently.</maml:para> <maml:para>To view or cancel a subscription that was created with the SupportEvent parameter, use the Force parameter of the `Get-EventSubscriber` and `Unregister-Event` cmdlets.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="named" aliases="none"> <maml:name>TraceInfo</maml:name> <maml:description> <maml:para>Specifies the trace info objects to filter by. These objects can be created by New-PSEtwEventInfo (./New-PSEtwEventInfo.md). Each trace info object specifies what traces to register with.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">EtwEventInfo[]</command:parameterValue> <dev:type> <maml:name>EtwEventInfo[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>PSEtw.Shared.EtwEventInfo</maml:name> </dev:type> <maml:description> <maml:para>This cmdlet accepts an `EtwEventInfo` object through the pipeline as part of the `-TraceInfo` parameter.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>None</maml:name> </dev:type> <maml:description> <maml:para>By default, this cmdlet returns no output.</maml:para> </maml:description> </command:returnValue> <command:returnValue> <dev:type> <maml:name>PSEventJob</maml:name> </dev:type> <maml:description> <maml:para>When you use the Action parameter, this cmdlet returns a PSEventJob object.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para>Events, event subscriptions, and the event queue exist only in the current session. If you close the current session, the event queue is discarded and the event subscription is canceled. The underlying ETW trace session exists beyond the current session, failing to call `Unregister-Event` for the event subscription will mean the ETW trace session will continue to run.</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>----- Example 1 - Register PowerShellCore pipeline events -----</maml:title> <dev:code>PS C:\> $sourceId = [Guid]::NewGuid() PS C:\> Register-PSEtwEvent -Provider PowerShellCore -KeywordsAll Pipeline -SourceIdentifier $sourceId PS C:\> $event = Wait-Event -SourceIdentifier $sourceId PS C:\> $event.SourceEventArgs | ConvertTo-Json PS C:\> $event | Remove-Event PS C:\> Unregister-Event -SourceIdentifier $sourceId</dev:code> <dev:remarks> <maml:para>Registers an event subscriber for the `PowerShellCore` provider with the keyword `Pipeline`. It then waits for the first event and prints the event data under `SourceEventArgs` as a Json string. This data contains the `Header` being the event descriptor info and the `Info` property being the event data. Once done the event is removed from the queue with `Remove-Event` and then the event subscriber is unregistered.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>------- Example 2 - Use an Action to process each event -------</maml:title> <dev:code>PS C:\> $etwEvent = Register-PSEtwEvent -Provider PowerShellCore -KeywordsAll Pipeline -Action { $EventArgs | ConvertTo-Json -WarningAction SilentlyContinue | Out-Host } PS C:\> ... # The pipeline must be free for the events to be processed PS C:\> Unregister-Event -SourceIdentifier $etwEvent.Name</dev:code> <dev:remarks> <maml:para>Register an event and runs the action for each received event. This action will output the event data as a Json string to the host when received. As PowerShell events only run when the pipeline is free, the action will only run when nothing else is running or a cmdlet like `Start-Sleep`, `Wait-Event` has freed the pipeline. The event subscription still needs to be unregistered to ensure the ETW trace session is no longer processing these events.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>------ Example 3 - Register ETW event on remote PSSession ------</maml:title> <dev:code>PS C:\> $session = New-PSSession -ComputerName remote-host PS C:\> $eventParams = @{ InputObject = $session.Runspace.Events.ReceivedEvents EventName = 'PSEventReceived' SourceIdentifier = [Guid]::NewGuid() } PS C:\> Register-ObjectEvent @eventParams PS C:\> $remoteSourceId = Invoke-Command -Session $session -ScriptBlock { Import-Module -Name PSEtw $sourceId = [Guid]::NewGuid() Register-PSEtwEvent -Provider PowerShellCore -KeywordsAll Runspace -Forward -SourceIdentifier $sourceId $sourceId } PS C:\> while ($true) { $e = Wait-Event -SourceIdentifier $eventParams.SourceIdentifier $e | Remove-Event $e.SourceEventArgs.SourceEventArgs.SerializedRemoteEventArgs } PS C:\> Invoke-Command -Session $session -ScriptBlock { Unregister-Event -SourceIdentifier $args[0] } -ArgumentList $remoteSourceId PS C:\> Unregister-Event -SourceIdentifier $eventParams.SourceIdentifier PS C:\> $session | Remove-PSSession</dev:code> <dev:remarks> <maml:para>Creates a PSSession to the host `remote-host` and starts a trace for the `PowerShellCore` provider with the keyword `Runspace`. These events will be forwarded to the local machine as they are received. Each event is then picked up to the `PSEventReceived` event and the event details under the `SerializedRemoteEventArgs`. Once the event is no longer needed the remote event subscriber is unregistered, the local event subscriber is also registered, and the PSSession closed.</maml:para> <maml:para>It is important to note that the remote data values will be deserialized and any deep objects lost as part of the deserialization process. To get a richer object more complex code is needed. The target host must have the `PSEtw` module installed for this to work, it is not needed on the local computer.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>https://www.github.com/jborean93/PSEtw/blob/main/docs/en-US/Register-PSEtwEvent.md</maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Remove-PSEtwSession</command:name> <command:verb>Remove</command:verb> <command:noun>PSEtwSession</command:noun> <maml:description> <maml:para>Removes an existing ETW Trace Session.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Removes an existing ETW Trace Session on the current host. This is a cut down cmdlet of Stop-EtwTraceSession (https://learn.microsoft.com/en-us/powershell/module/eventtracingmanagement/stop-etwtracesession?view=windowsserver2022-ps)which can also be used to remove an ETW Trace Session.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Remove-PSEtwSession</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Default</maml:name> <maml:description> <maml:para>Removes the default Trace Session used by `PSEtw`. The default Trace Session is used if no `-SessionName` is specified with Registser-PSEtwEvent (./Register-PSEtwEvent.md) or [Trace-PSEtwEvent](./Trace-PSEtwEvent.md).</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="proga"> <maml:name>ProgressAction</maml:name> <maml:description> <maml:para>New common parameter introduced in PowerShell 7.4.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ActionPreference</command:parameterValue> <dev:type> <maml:name>ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="cf"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="wi"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Remove-PSEtwSession</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="0" aliases="Name"> <maml:name>SessionName</maml:name> <maml:description> <maml:para>The ETW Trace Session name to remove.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">TraceSessionOrString[]</command:parameterValue> <dev:type> <maml:name>TraceSessionOrString[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="proga"> <maml:name>ProgressAction</maml:name> <maml:description> <maml:para>New common parameter introduced in PowerShell 7.4.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ActionPreference</command:parameterValue> <dev:type> <maml:name>ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="cf"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="wi"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Default</maml:name> <maml:description> <maml:para>Removes the default Trace Session used by `PSEtw`. The default Trace Session is used if no `-SessionName` is specified with Registser-PSEtwEvent (./Register-PSEtwEvent.md) or [Trace-PSEtwEvent](./Trace-PSEtwEvent.md).</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="proga"> <maml:name>ProgressAction</maml:name> <maml:description> <maml:para>New common parameter introduced in PowerShell 7.4.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ActionPreference</command:parameterValue> <dev:type> <maml:name>ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="0" aliases="Name"> <maml:name>SessionName</maml:name> <maml:description> <maml:para>The ETW Trace Session name to remove.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">TraceSessionOrString[]</command:parameterValue> <dev:type> <maml:name>TraceSessionOrString[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="cf"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="wi"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.String[]</maml:name> </dev:type> <maml:description> <maml:para>The session names to remove.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>None</maml:name> </dev:type> <maml:description> <maml:para>This cmdlet does not output any objects.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>--------- Example 1 - Create and remove Trace Session ---------</maml:title> <dev:code>PS C:\> $session = New-PSEtwSession -Name MySession PS C:\> $session | Remove-PSEtwSession</dev:code> <dev:remarks> <maml:para>Creates a new ETW Trace Session called `MySession` then removes it.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>https://www.github.com/jborean93/PSEtw/blob/main/docs/en-US/Remove-PSEtwSession.md</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>ControlTraceW</maml:linkText> <maml:uri>https://learn.microsoft.com/en-us/windows/win32/api/evntrace/nf-evntrace-controltracew</maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Stop-PSEtwTrace</command:name> <command:verb>Stop</command:verb> <command:noun>PSEtwTrace</command:noun> <maml:description> <maml:para>Stops an active PSEtw trace session.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Stops a PSEtw trace session started by Trace-PSEtwEvent (./Trace-PSEtwEvent.md). The trace session associated with the event provided to this cmdlet is the one that will be stopped.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Stop-PSEtwTrace</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="0" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>The event object that was created by the trace session that should be stopped.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">EtwEventArgs</command:parameterValue> <dev:type> <maml:name>EtwEventArgs</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="proga"> <maml:name>ProgressAction</maml:name> <maml:description> <maml:para>New common parameter introduced in PowerShell 7.4.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ActionPreference</command:parameterValue> <dev:type> <maml:name>ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="0" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>The event object that was created by the trace session that should be stopped.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">EtwEventArgs</command:parameterValue> <dev:type> <maml:name>EtwEventArgs</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="proga"> <maml:name>ProgressAction</maml:name> <maml:description> <maml:para>New common parameter introduced in PowerShell 7.4.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ActionPreference</command:parameterValue> <dev:type> <maml:name>ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>PSEtw.Shared.EtwEventArgs</maml:name> </dev:type> <maml:description> <maml:para>The trace event can be provided as pipeline input.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>None</maml:name> </dev:type> <maml:description> <maml:para>This cmdlet does not output anything.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>------ Example 1 - Stop a trace after receiving an event ------</maml:title> <dev:code>PS C:\> Trace-PSEtwEvent -Provider MyProvider | ForEach-Object { $_ if ($_.Header.Descriptor.Id -eq 10) { $_ | Stop-PSEtwTrace } }</dev:code> <dev:remarks> <maml:para>Will capture events for the provider `MyProvider` until an event with the `Id` of `10` is received. The trace is stopped by piping the event into `Stop-PSEtwTrace`.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>https://www.github.com/jborean93/PSEtw/blob/main/docs/en-US/Stop-PSEtwTrace.md</maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Test-PSEtwSession</command:name> <command:verb>Test</command:verb> <command:noun>PSEtwSession</command:noun> <maml:description> <maml:para>Tests if an ETW Trace Session exists or not.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Tests whether the ETW Trace Session specified exists or not on the current host.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Test-PSEtwSession</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Default</maml:name> <maml:description> <maml:para>Tests whether the default Trace Session used by PSEtw exists or not. The default Trace Session is used if no `-SessionName` is specified with Register-PSEtwEvent (./Register-PSEtwEvent.md) or [Trace-PSEtwEvent](./Trace-PSEtwEvent.md).</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="proga"> <maml:name>ProgressAction</maml:name> <maml:description> <maml:para>New common parameter introduced in PowerShell 7.4.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ActionPreference</command:parameterValue> <dev:type> <maml:name>ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Test-PSEtwSession</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="0" aliases="Name"> <maml:name>SessionName</maml:name> <maml:description> <maml:para>The name of the ETW Trace Session to check.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">TraceSessionOrString[]</command:parameterValue> <dev:type> <maml:name>TraceSessionOrString[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="proga"> <maml:name>ProgressAction</maml:name> <maml:description> <maml:para>New common parameter introduced in PowerShell 7.4.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ActionPreference</command:parameterValue> <dev:type> <maml:name>ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Default</maml:name> <maml:description> <maml:para>Tests whether the default Trace Session used by PSEtw exists or not. The default Trace Session is used if no `-SessionName` is specified with Register-PSEtwEvent (./Register-PSEtwEvent.md) or [Trace-PSEtwEvent](./Trace-PSEtwEvent.md).</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="proga"> <maml:name>ProgressAction</maml:name> <maml:description> <maml:para>New common parameter introduced in PowerShell 7.4.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ActionPreference</command:parameterValue> <dev:type> <maml:name>ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="0" aliases="Name"> <maml:name>SessionName</maml:name> <maml:description> <maml:para>The name of the ETW Trace Session to check.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">TraceSessionOrString[]</command:parameterValue> <dev:type> <maml:name>TraceSessionOrString[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.String[]</maml:name> </dev:type> <maml:description> <maml:para>The name(s) of the ETW Trace Session to check.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.Boolean</maml:name> </dev:type> <maml:description> <maml:para>A boolean value representing whether the ETW Trace Session exists or not.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>Example 1 - Checks if a trace session exists before removing it</maml:title> <dev:code>PS C:\> if (Test-PSEtwSession -SessionName MySession) { Remove-PSEtwSession -SessionName MySession }</dev:code> <dev:remarks> <maml:para>Checks if the session specified exists before removing it.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>https://www.github.com/jborean93/PSEtw/blob/main/docs/en-US/Test-PSEtwSession.md</maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Trace-PSEtwEvent</command:name> <command:verb>Trace</command:verb> <command:noun>PSEtwEvent</command:noun> <maml:description> <maml:para>Starts an ETW Trace for the provider specified.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Starts an ETW trace which outputs trace events as they are received as object outputs. This like Register-PSEtwEvent (./Register-PSEtwEvent.md)except that the events are outputted from the cmdlet rather than requiring `Get-Event` or `Wait-Event`. A trace will continue to run indefinitely until either the pipeline has been stopped with `ctrl+c` or an event outputted by this cmdlet is piped into Stop-PSEtwTrace (./Stop-PSEtwTrace.md).</maml:para> <maml:para>The parameters for this cmdlet define what ETW providers to register to, the keywords, and levels for that provider to subscribe to. It is possible to use New-PSEtwEventInfo (./New-PSEtwEventInfo.md)to define multiple filters when creating an ETW trace. See about_PSEtwEventArgs (./about_PSEtwEventArgs.md)for more information on the structure of the event data that is set in `SourceEventArgs`.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Trace-PSEtwEvent</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>IncludeRawData</maml:name> <maml:description> <maml:para>Stores the raw event data as part of the `EventData` property of the returned event arg object. If not set this property will be an empty array. This is useful when needing to debug the event data if the parser failed to extract the event information.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>KeywordsAll</maml:name> <maml:description> <maml:para>Restrict the events for the specified provider to only the ones that match all the keywords specified here. This filter does not apply to events that do not have a keyword associated with it.</maml:para> <maml:para>The keyword can either be specified as a 64-bit integer value which are combined together or as a string representing the keyword. The keyword strings are dependent on the provider that was specified and what keywords it defines through its manifest. Trace Logging providers that aren't registered on the system cannot be filtered by name, the integer value must be specified for these providers. This parameter supports tab completion to retrieve the keywords for a registered provider if one is set by `-Provider`. The value `*` represents the numeric value `0xFFFFFFFFFFFFFFFF` which is all keywords set.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">KeywordsStringOrLong[]</command:parameterValue> <dev:type> <maml:name>KeywordsStringOrLong[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>KeywordsAny</maml:name> <maml:description> <maml:para>Restrict the events for the specified provider to only the ones that match any of the keywords specified here. This filter does not apply to events that do not have a keyword associated with it.</maml:para> <maml:para>The keyword can either be specified as a 64-bit integer value which are combined together or as a string representing the keyword. The keyword strings are dependent on the provider that was specified and what keywords it defines through its manifest. Trace Logging providers that aren't registered on the system cannot be filtered by name, the integer value must be specified for these providers. This parameter supports tab completion to retrieve the keywords for a registered provider if one is set by `-Provider`. The value `*` represents the numeric value `0xFFFFFFFFFFFFFFFF` which is all keywords set.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">KeywordsStringOrLong[]</command:parameterValue> <dev:type> <maml:name>KeywordsStringOrLong[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Level</maml:name> <maml:description> <maml:para>Restricts the events to only ones with a level that is equal to or less than the level specified. Builtin levels are:</maml:para> <maml:para>+ `0` - `LogAlways` - only events with `LogAlways` will be emitted + `1` - `Critical` + `2` - `Error` + `3` - `Warning` + `4` - `Info` + `5` - `Verbose` + `0xFF` - `*`</maml:para> <maml:para>Some providers may implement custom levels which can be specified by the numeric value or by name. Use tab completion with `-Provider` set to see the known levels for the provider in use. The level `*` or `0xFF` is set then all levels will be captured. If no level is set then the default is `4 (Info)`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">LevelStringOrInt</command:parameterValue> <dev:type> <maml:name>LevelStringOrInt</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="proga"> <maml:name>ProgressAction</maml:name> <maml:description> <maml:para>New common parameter introduced in PowerShell 7.4.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ActionPreference</command:parameterValue> <dev:type> <maml:name>ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Provider</maml:name> <maml:description> <maml:para>The provider name or guid to retrieve events for. This parameter supports tab completion to retrieve all available providers that have been registered on the system. Trace Logger providers can be specified by name but as they are not registered on the system by name they cannot be validated when creating the filter. If set to a registered provider, other parameters tab completion can retrieve values specific to that provider for example `Trace-PSEtwEvent -Provider PowerShellCore -KeywordsAny <ctrl+space>`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ProviderStringOrGuid</command:parameterValue> <dev:type> <maml:name>ProviderStringOrGuid</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="Name"> <maml:name>SessionName</maml:name> <maml:description> <maml:para>Register the events on the ETW trace session specified. A trace session can be created with New-PStwSession (./New-PSEtwSession.md). When running the process as an administrator, a default ETW Trace Session called `PSEtw` will be created and used. Non-administrative sessions will attempt to open this session which may work depending on the permissions applied to the trace session and what groups the user is a member of.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Trace-PSEtwEvent</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>IncludeRawData</maml:name> <maml:description> <maml:para>Stores the raw event data as part of the `EventData` property of the returned event arg object. If not set this property will be an empty array. This is useful when needing to debug the event data if the parser failed to extract the event information.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="proga"> <maml:name>ProgressAction</maml:name> <maml:description> <maml:para>New common parameter introduced in PowerShell 7.4.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ActionPreference</command:parameterValue> <dev:type> <maml:name>ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="Name"> <maml:name>SessionName</maml:name> <maml:description> <maml:para>Register the events on the ETW trace session specified. A trace session can be created with New-PStwSession (./New-PSEtwSession.md). When running the process as an administrator, a default ETW Trace Session called `PSEtw` will be created and used. Non-administrative sessions will attempt to open this session which may work depending on the permissions applied to the trace session and what groups the user is a member of.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="named" aliases="none"> <maml:name>TraceInfo</maml:name> <maml:description> <maml:para>Specifies the trace info objects to filter by. These objects can be created by New-PSEtwEventInfo (./New-PSEtwEventInfo.md). Each trace info object specifies what traces to register with.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">EtwEventInfo[]</command:parameterValue> <dev:type> <maml:name>EtwEventInfo[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>IncludeRawData</maml:name> <maml:description> <maml:para>Stores the raw event data as part of the `EventData` property of the returned event arg object. If not set this property will be an empty array. This is useful when needing to debug the event data if the parser failed to extract the event information.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>KeywordsAll</maml:name> <maml:description> <maml:para>Restrict the events for the specified provider to only the ones that match all the keywords specified here. This filter does not apply to events that do not have a keyword associated with it.</maml:para> <maml:para>The keyword can either be specified as a 64-bit integer value which are combined together or as a string representing the keyword. The keyword strings are dependent on the provider that was specified and what keywords it defines through its manifest. Trace Logging providers that aren't registered on the system cannot be filtered by name, the integer value must be specified for these providers. This parameter supports tab completion to retrieve the keywords for a registered provider if one is set by `-Provider`. The value `*` represents the numeric value `0xFFFFFFFFFFFFFFFF` which is all keywords set.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">KeywordsStringOrLong[]</command:parameterValue> <dev:type> <maml:name>KeywordsStringOrLong[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>KeywordsAny</maml:name> <maml:description> <maml:para>Restrict the events for the specified provider to only the ones that match any of the keywords specified here. This filter does not apply to events that do not have a keyword associated with it.</maml:para> <maml:para>The keyword can either be specified as a 64-bit integer value which are combined together or as a string representing the keyword. The keyword strings are dependent on the provider that was specified and what keywords it defines through its manifest. Trace Logging providers that aren't registered on the system cannot be filtered by name, the integer value must be specified for these providers. This parameter supports tab completion to retrieve the keywords for a registered provider if one is set by `-Provider`. The value `*` represents the numeric value `0xFFFFFFFFFFFFFFFF` which is all keywords set.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">KeywordsStringOrLong[]</command:parameterValue> <dev:type> <maml:name>KeywordsStringOrLong[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Level</maml:name> <maml:description> <maml:para>Restricts the events to only ones with a level that is equal to or less than the level specified. Builtin levels are:</maml:para> <maml:para>+ `0` - `LogAlways` - only events with `LogAlways` will be emitted + `1` - `Critical` + `2` - `Error` + `3` - `Warning` + `4` - `Info` + `5` - `Verbose` + `0xFF` - `*`</maml:para> <maml:para>Some providers may implement custom levels which can be specified by the numeric value or by name. Use tab completion with `-Provider` set to see the known levels for the provider in use. The level `*` or `0xFF` is set then all levels will be captured. If no level is set then the default is `4 (Info)`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">LevelStringOrInt</command:parameterValue> <dev:type> <maml:name>LevelStringOrInt</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="proga"> <maml:name>ProgressAction</maml:name> <maml:description> <maml:para>New common parameter introduced in PowerShell 7.4.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ActionPreference</command:parameterValue> <dev:type> <maml:name>ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Provider</maml:name> <maml:description> <maml:para>The provider name or guid to retrieve events for. This parameter supports tab completion to retrieve all available providers that have been registered on the system. Trace Logger providers can be specified by name but as they are not registered on the system by name they cannot be validated when creating the filter. If set to a registered provider, other parameters tab completion can retrieve values specific to that provider for example `Trace-PSEtwEvent -Provider PowerShellCore -KeywordsAny <ctrl+space>`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ProviderStringOrGuid</command:parameterValue> <dev:type> <maml:name>ProviderStringOrGuid</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="Name"> <maml:name>SessionName</maml:name> <maml:description> <maml:para>Register the events on the ETW trace session specified. A trace session can be created with New-PStwSession (./New-PSEtwSession.md). When running the process as an administrator, a default ETW Trace Session called `PSEtw` will be created and used. Non-administrative sessions will attempt to open this session which may work depending on the permissions applied to the trace session and what groups the user is a member of.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="named" aliases="none"> <maml:name>TraceInfo</maml:name> <maml:description> <maml:para>Specifies the trace info objects to filter by. These objects can be created by New-PSEtwEventInfo (./New-PSEtwEventInfo.md). Each trace info object specifies what traces to register with.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">EtwEventInfo[]</command:parameterValue> <dev:type> <maml:name>EtwEventInfo[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>PSEtw.Shared.EtwEventInfo</maml:name> </dev:type> <maml:description> <maml:para>This cmdlet accepts an `EtwEventInfo` object through the pipeline as part of the `-TraceInfo` parameter.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>PSEtw.Shared.EtwEventArgs</maml:name> </dev:type> <maml:description> <maml:para>This cmdlet outputs each event as an output object. It can be used with other cmdlets like `ForEach-Object` to process the event in realtime. The event can be passed into `Stop-PSEtwTrace` to stop the current trace. See `about_PSEtwEventArgs` for more information on the structure of the event data that is set in `SourceEventArgs`.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>------- Example 1 - Trace PowerShellCore Runspace events -------</maml:title> <dev:code>PS C:\> Trace-PSEtwEvent -Provider PowerShellCore -KeywordsAll Runspace</dev:code> <dev:remarks> <maml:para>Starts an interactive trace that outputs the events for `PowerShellCore` with the keyword `Runspace`. This will continue to run until the caller stops the pipeline with `ctrl+c`.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>Example 2 - Trace WSMan Authentication events and output as JSON</maml:title> <dev:code>PS C:\> Trace-PSEtwEvent -Provider Microsoft-Windows-WinRM -KeywordsAll Keyword.Server, Keyword.Security | ForEach-Object { $_ | ConvertTo-Json -Depth 3 }</dev:code> <dev:remarks> <maml:para>Captures authentication trace events for the WinRM listener and outputs the event data as a Json string. The `Keyword.Server` and `Keyword.Security` keywords are used when filtering the events. Note that the `Keyword.` prefix is how the `WinRM` provider has registered its keyword names, not all providers follow this standard. Use tab completion with the `-KeywordsAll` or `-KeywordsAny` parameters with a registered provider set to view the available keywords.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>Example 3 - Trace events and stop the trace when an event is received</maml:title> <dev:code>PS C:\> Trace-PSEtwEvent -Provider PowerShellCore -KeywordsAll Runspace | ForEach-Object { $_ if ($_.Id -eq -24574) { $_ | Stop-PSEtwTrace } }</dev:code> <dev:remarks> <maml:para>Captures all `Runspace` traces for `PowerShellCore` and will stop the trace when the event with the ID `-24574` is received. This event is the `PowerShell Console Startup` event.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>https://www.github.com/jborean93/PSEtw/blob/main/docs/en-US/Trace-PSEtwEvent.md</maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> </helpItems> |