| external help file | Module Name | online version | schema |
|---|---|---|---|
PSEtw.dll-Help.xml |
PSEtw |
2.0.0 |
Starts an ETW Trace for the provider specified.
Trace-PSEtwEvent [-SessionName <String>] -Provider <ProviderStringOrGuid>
[-KeywordsAny <KeywordsStringOrLong[]>] [-KeywordsAll <KeywordsStringOrLong[]>] [-Level <LevelStringOrInt>]
[-IncludeRawData] [-ProgressAction <ActionPreference>] [<CommonParameters>]
Trace-PSEtwEvent [-SessionName <String>] -TraceInfo <EtwEventInfo[]> [-IncludeRawData]
[-ProgressAction <ActionPreference>] [<CommonParameters>]
Starts an ETW trace which outputs trace events as they are received as object outputs.
This like Register-PSEtwEvent 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.
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 to define multiple filters when creating an ETW trace.
See about_PSEtwEventArgs for more information on the structure of the event data that is set in SourceEventArgs.
PS C:\> Trace-PSEtwEvent -Provider PowerShellCore -KeywordsAll RunspaceStarts 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.
PS C:\> Trace-PSEtwEvent -Provider Microsoft-Windows-WinRM -KeywordsAll Keyword.Server, Keyword.Security |
ForEach-Object { $_ | ConvertTo-Json -Depth 3 }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.
PS C:\> Trace-PSEtwEvent -Provider PowerShellCore -KeywordsAll Runspace | ForEach-Object {
$_
if ($_.Id -eq -24574) {
$_ | Stop-PSEtwTrace
}
}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.
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.
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: FalseRestrict 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.
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.
Type: KeywordsStringOrLong[]
Parameter Sets: Single
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: FalseRestrict 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.
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.
Type: KeywordsStringOrLong[]
Parameter Sets: Single
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: FalseRestricts the events to only ones with a level that is equal to or less than the level specified. Builtin levels are:
0-LogAlways- only events withLogAlwayswill be emitted1-Critical2-Error3-Warning4-Info5-Verbose0xFF-*
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).
Type: LevelStringOrInt
Parameter Sets: Single
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: FalseNew common parameter introduced in PowerShell 7.4.
Type: ActionPreference
Parameter Sets: (All)
Aliases: proga
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: FalseThe 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>.
Type: ProviderStringOrGuid
Parameter Sets: Single
Aliases:
Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: FalseRegister the events on the ETW trace session specified.
A trace session can be created with New-PStwSession.
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.
Type: String
Parameter Sets: (All)
Aliases: Name
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: FalseSpecifies the trace info objects to filter by. These objects can be created by New-PSEtwEventInfo. Each trace info object specifies what traces to register with.
Type: EtwEventInfo[]
Parameter Sets: Multi
Aliases:
Required: True
Position: Named
Default value: None
Accept pipeline input: True (ByPropertyName, ByValue)
Accept wildcard characters: FalseThis cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.
This cmdlet accepts an EtwEventInfo object through the pipeline as part of the -TraceInfo parameter.
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.