Start-DbaXESession

Synopsis

Starts Extended Events sessions on SQL Server instances for monitoring and troubleshooting.

Description

Activates Extended Events sessions that have been created but are not currently running. Extended Events sessions are SQL Server’s lightweight monitoring framework used for troubleshooting performance issues, security auditing, and capturing specific database activity patterns.

The function can start individual sessions by name, all user-created sessions at once, or sessions scheduled to start and stop at specific times. When using -AllSessions, it automatically excludes built-in system sessions (AlwaysOn_health, system_health, telemetry_xevents) so you don’t accidentally interfere with SQL Server’s internal monitoring.

For scheduled operations, the function creates temporary SQL Agent jobs that execute at the specified times and then delete themselves. This is particularly useful for capturing data during specific time windows or off-hours troubleshooting sessions.

Syntax

Start-DbaXESession
    [-SqlInstance] <DbaInstanceParameter[]>
    [-SqlCredential <PSCredential>]
    -Session <Object[]>
    [-StartAt <DateTime>]
    [-StopAt <DateTime>]
    [-EnableException]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

Start-DbaXESession
    [-SqlInstance] <DbaInstanceParameter[]>
    [-SqlCredential <PSCredential>]
    [-StartAt <DateTime>]
    [-StopAt <DateTime>]
    -AllSessions
    [-EnableException]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

Start-DbaXESession
    [-StartAt <DateTime>]
    [-StopAt <DateTime>]
    -InputObject <Session[]>
    [-EnableException]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

Examples

Example: 1

PS C:\> Start-DbaXESession -SqlInstance sqlserver2012 -AllSessions

Starts all Extended Event Session on the sqlserver2014 instance.

Example: 2

PS C:\> Start-DbaXESession -SqlInstance sqlserver2012 -Session xesession1,xesession2

Starts the xesession1 and xesession2 Extended Event sessions.

Example: 3

PS C:\> Start-DbaXESession -SqlInstance sqlserver2012 -Session xesession1,xesession2 -StopAt (Get-Date).AddMinutes(30)

Starts the xesession1 and xesession2 Extended Event sessions and stops them in 30 minutes.

Example: 4

PS C:\> Start-DbaXESession -SqlInstance sqlserver2012 -Session AlwaysOn_health -StartAt (Get-Date).AddMinutes(1)

Starts the AlwaysOn_health Extended Event sessions in 1 minute. The command will return immediately.

Example: 5

PS C:\> Get-DbaXESession -SqlInstance sqlserver2012 -Session xesession1 | Start-DbaXESession

Starts the sessions returned from the Get-DbaXESession function.

Required Parameters

-SqlInstance

The target SQL Server instance or instances. You must have sysadmin access and server version must be SQL Server version 2008 or higher.

-Session

Specifies the names of specific Extended Events sessions to start. Accepts multiple session names as an array.
Use this when you need to start only certain sessions rather than all user-created sessions on the instance.

-AllSessions

Starts all user-created Extended Events sessions on the instance while excluding system sessions (AlwaysOn_health, system_health, telemetry_xevents).
Use this when you want to activate all custom monitoring sessions without interfering with SQL Server’s built-in diagnostics.

-InputObject

Accepts Extended Events session objects from Get-DbaXESession for pipeline operations.
Use this when you need to filter sessions with Get-DbaXESession first, then start only the matching sessions.

Optional Parameters

-SqlCredential

Login to the target instance using alternative credentials. Accepts PowerShell credentials (Get-Credential).
Windows Authentication, SQL Server Authentication, Active Directory - Password, and Active Directory - Integrated are all supported.
For MFA support, please use Connect-DbaInstance.

-StartAt

Schedules the Extended Events sessions to start at a specific date and time using a temporary SQL Agent job.
The command returns immediately while the job handles starting sessions at the scheduled time, useful for capturing activity during specific time windows.

-StopAt

Schedules the Extended Events sessions to stop at a specific date and time using a temporary SQL Agent job.
Use this with StartAt or on already running sessions to create time-bounded monitoring windows for troubleshooting specific issues.

-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.

-WhatIf

If this switch is enabled, no actions are performed but informational messages will be displayed that explain what would happen if the command were to run.

-Confirm

If this switch is enabled, you will be prompted for confirmation before executing any operations that change state.

Outputs

Microsoft.SqlServer.Management.XEvent.Session

Returns one Session object for each Extended Events session that was started or would be started (if -WhatIf is specified).

Default display properties (via Select-DefaultView):

• ComputerName: The computer name of the SQL Server instance
• InstanceName: The SQL Server instance name
• SqlInstance: The full SQL Server instance name (computer\instance)
• Name: The name of the Extended Events session
• Status: Current session status - either “Running” or “Stopped”
• StartTime: DateTime when the session was started (null if stopped)
• AutoStart: Boolean indicating if the session starts automatically when SQL Server starts
• State: SMO object state (Existing, Creating, Pending, etc.)
• Targets: Collection of target objects configured for this session
• TargetFile: Array of resolved file paths for all event_file targets (includes UNC paths for network access)
• Events: Collection of Extended Events configured in this session
• MaxMemory: Maximum memory allocation for the session in KB
• MaxEventSize: Maximum event size the session will capture in KB

Additional properties added as NoteProperties:

• Session: The session name (alias for Name property)
• RemoteTargetFile: Array of UNC paths for all target files (for remote file access)
• Parent: Reference to the parent Microsoft.SqlServer.Management.Smo.Server object
• Store: Reference to the Microsoft.SqlServer.Management.XEvent.XEStore object When -StartAt is specified, jobs are created but the session objects are returned immediately without waiting for scheduled execution.