Get-DbaAgRingBuffer

the dbatools team + Claude

Windows, Linux, macOS

Synopsis

Retrieves Always On availability group diagnostic data from SQL Server’s internal HADR ring buffers.

This command queries sys.dm_os_ring_buffers for HADR-specific ring buffer types to provide diagnostic
information about Always On availability groups. These ring buffers record state transitions, role changes,
commit activity, and transport state events useful for troubleshooting AG health and failover issues.

As noted in Microsoft’s documentation, the ring buffers are not officially supported, but they provide
valuable post-mortem diagnostic data, especially when SQL Server stops responding or has crashed.

Reference: https://learn.microsoft.com/en-us/sql/database-engine/availability-groups/windows/always-on-ring-buffers

Syntax

Get-DbaAgRingBuffer
    [-SqlInstance] <DbaInstanceParameter[]>
    [[-SqlCredential] <PSCredential>]
    [[-RingBufferType] <String[]>]
    [[-CollectionMinutes] <Int32>]
    [-EnableException]
    [<CommonParameters>]

Examples

Example: 1

PS C:\> Get-DbaAgRingBuffer -SqlInstance sql2019

Returns HADR ring buffer records from the last 60 minutes from the sql2019 instance.

Example: 2

PS C:\> Get-DbaAgRingBuffer -SqlInstance sql2019 -CollectionMinutes 240

Returns HADR ring buffer records from the last 240 minutes from the sql2019 instance.

Example: 3

PS C:\> Get-DbaAgRingBuffer -SqlInstance sql2019 -RingBufferType RING_BUFFER_HADRDBMGR_API

Returns only RING_BUFFER_HADRDBMGR_API records from the last 60 minutes from the sql2019 instance.

Example: 4

PS C:\> Get-DbaAgRingBuffer -SqlInstance sql2019 -RingBufferType RING_BUFFER_HADRDBMGR_API, RING_BUFFER_HADR_TRANSPORT_STATE

Returns API and transport state records from sql2019.

Example: 5

PS C:\> 'sql2019', 'sql2022' | Get-DbaAgRingBuffer

Returns all HADR ring buffer records from sql2019 and sql2022.

Required Parameters

-SqlInstance

The target SQL Server instance or instances.

Property	Value
Alias
Required	True
Pipeline	true (ByValue)
Default Value

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. To use:
$cred = Get-Credential, this pass this $cred to the param.
Windows Authentication will be used if SqlCredential is not specified. To connect as a different Windows user, run PowerShell as that user.

Property	Value
Alias
Required	False
Pipeline	false
Default Value

-RingBufferType

Specifies which HADR ring buffer types to query. Defaults to all four HADR ring buffer types.
Valid values:

RING_BUFFER_HADRDBMGR_API : State transitions at the API level
RING_BUFFER_HADRDBMGR_STATE : Database manager state change records
RING_BUFFER_HADRDBMGR_COMMIT : Commit-level activity records
RING_BUFFER_HADR_TRANSPORT_STATE: Connection and transport state transitions

Property	Value
Alias
Required	False
Pipeline	false
Default Value
Accepted Values	RING_BUFFER_HADRDBMGR_API,RING_BUFFER_HADRDBMGR_STATE,RING_BUFFER_HADRDBMGR_COMMIT,RING_BUFFER_HADR_TRANSPORT_STATE

-CollectionMinutes

Specifies how many minutes of historical data to retrieve from the ring buffer. Defaults to 60 minutes.
Use this to extend the analysis window when investigating longer-term AG issues or to focus on recent activity with shorter periods.

Property	Value
Alias
Required	False
Pipeline	false
Default Value	60

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

Property	Value
Alias
Required	False
Pipeline	false
Default Value	False

Outputs

PSCustomObject

Returns one object per ring buffer record retrieved from the SQL Server instance.

Properties:

ComputerName : The computer name of the SQL Server instance
InstanceName : The SQL Server instance name
SqlInstance : The full SQL Server instance name (computer\instance)
RingBufferType : The type of ring buffer (e.g. RING_BUFFER_HADRDBMGR_API)
RecordId : The unique record identifier from the ring buffer entry
EventTime : Approximate DateTime of the event (in local server time)
Record : The raw XML record containing event-specific diagnostic fields