Read-DbaXEFile

Synopsis

Parses Extended Events trace files (.xel/.xem) into structured PowerShell objects for analysis

Description

Converts Extended Events trace files into PowerShell objects so you can analyze captured SQL Server events without needing SQL Server Management Studio. This function takes the raw XEvent data from .xel or .xem files and transforms it into structured objects with properties for each field and action in the trace.

Perfect for post-incident analysis of deadlocks, performance issues, or security events that were captured by your Extended Events sessions. You can pipe the results to other PowerShell cmdlets for filtering, sorting, exporting to CSV, or building reports.

When using pipeline input from Get-DbaXESession, the function automatically skips the file currently being written to avoid access conflicts, and can read files from remote servers via admin shares.

Syntax

Read-DbaXEFile
    [-Path] <Object[]>
    [-Raw]
    [-EnableException]
    [<CommonParameters>]

Examples

Example: 1

PS C:\> Read-DbaXEFile -Path C:\temp\deadocks.xel

Returns events from C:\temp\deadocks.xel.

Example: 2

PS C:\> Get-ChildItem C:\temp\xe\*.xel | Read-DbaXEFile

Returns events from all .xel files in C:\temp\xe.

Example: 3

PS C:\> Get-DbaXESession -SqlInstance sql2019 -Session deadlocks | Read-DbaXEFile

Reads remote XEvents by accessing the file over the admin UNC share.

Required Parameters

-Path

Specifies the Extended Events file path (.xel or .xem), file objects, or XEvent session objects to read from. Supports local paths, UNC paths for remote files, and pipeline input from Get-ChildItem
or Get-DbaXESession.
When using session objects from Get-DbaXESession, automatically accesses files via admin shares and skips the current file being written to prevent access conflicts.

Optional Parameters

-Raw

Returns the native Microsoft.SqlServer.XEvent.XELite.XEvent objects instead of structured PowerShell objects. Use this when you need direct access to the XEvent object properties and methods for
advanced programmatic processing.
By default, events are converted to PSCustomObjects with all fields and actions as individual properties for easier analysis and reporting.

-EnableException

By default, when something goes wrong we try to catch it, interpret it and give you a friendly warning message.
This avoids overwhelming you with “sea of red” exceptions, but is inconvenient because it basically disables advanced scripting.
Using this switch turns this “nice by default” feature off and enables you to catch exceptions with your own try/catch.

Outputs

Microsoft.SqlServer.XEvent.XELite.XEvent[] (when -Raw is specified)

Returns the native XEvent objects from the XELite reader with full access to XEvent properties and methods for advanced programmatic processing. PSCustomObject[] (default)

Returns one object per event in the trace file with dynamic properties based on the captured fields and actions. All objects include standard properties plus event-specific fields:

Standard properties:

• name: The name of the Extended Event
• timestamp: The timestamp when the event was captured

Dynamic properties vary based on the Extended Events session configuration and captured actions:

• All unique field names from the XEvent.Fields collection appear as individual properties
• All unique action names from the XEvent.Actions collection appear as individual properties (action names are normalized to remove the leading package.action prefix) For example, a deadlock trace might include properties like: database_id, duration, cpu_time, physical_reads, logical_reads, writes, priority, transaction_id, client_app_name, etc. A security audit trace might include: client_principal_name, server_principal_name, statement, etc. Use Select-Object * to see all properties returned in the results.