[Microsoft SQL Server] metrics for Always On Availability Groups

packages/microsoft_sqlserver/_dev/build/docs/README.md

@@ -19,6 +19,7 @@ Find more details in [Logs](#logs).
 
 * `performance`: Comprehensive performance counters and objects available on the server.
 * `transaction_log`: Usage statistics and space utilization metrics for transaction logs.
+* `availability_groups`: Health and synchronization metrics for Always On Availability Groups.
 
 Find more details in [Metrics](#metrics).
 
@@ -39,6 +40,9 @@ If you browse Microsoft Developer Network (MSDN) for the following tables, you w
     - [sys.dm_db_log_stats (DB_ID)](https://learn.microsoft.com/en-us/sql/relational-databases/system-dynamic-management-views/sys-dm-db-log-stats-transact-sql?view=sql-server-ver16) (Available on SQL Server (MSSQL) 2016 (13.x) SP 2 and later)
 2. `performance`:
     - [sys.dm_os_performance_counters](https://learn.microsoft.com/en-us/sql/relational-databases/system-dynamic-management-views/sys-dm-os-performance-counters-transact-sql?view=sql-server-ver16)
+3. `availability_groups`:
+    - [sys.availability_groups](https://learn.microsoft.com/en-us/sql/relational-databases/system-catalog-views/sys-availability-groups-transact-sql?view=sql-server-ver16)
+    - [sys.dm_hadr_availability_group_states](https://learn.microsoft.com/en-us/sql/relational-databases/system-dynamic-management-views/sys-dm-hadr-availability-group-states-transact-sql)
 
 Please make sure the user has the permissions to system as well as user-defined databases. For the particular user used in the integration, the following requirements are met:
 
@@ -85,8 +89,6 @@ As part of the input configuration, you need to provide the user name, password
 * `host/instance_name`          (e.g. `localhost/namedinstance_01`)
 * `host:named_instance_port`    (e.g. `localhost:60873`)
 
-
-
 ### Configuration
 
 #### Audit
@@ -137,6 +139,22 @@ Keep in mind that this feature is disabled by default and needs to be manually e
 
 When the password contains special characters, pass these special characters using URL encoding.
 
+### Availability Groups Metrics
+
+Collects metrics related to Always On Availability Groups, including replica status and synchronization health. This dataset queries the following SQL Server tables:
+
+- `sys.availability_groups`
+- `sys.dm_hadr_availability_group_states`
+
+**Note:** Always On Availability Groups must be enabled on your SQL Server instance for this dataset to collect metrics. This feature is available in SQL Server Enterprise and Standard editions (with limitations in Standard).
+
+**Prerequisites**: To collect Availability Groups metrics, ensure the following:
+
+1. Always On Availability Groups feature is enabled on the SQL Server instance.
+2. The user account configured for the integration has `VIEW SERVER STATE` and `VIEW ANY DEFINITION` permissions. *Additionaly look at secion [Microsoft SQL Server permissions](#microsoft-sql-server-permissions)*.
+
+Read more in [Monitor Availability Groups](https://learn.microsoft.com/en-us/sql/database-engine/availability-groups/windows/monitoring-of-availability-groups-sql-server?view=sql-server-ver16) and [Always On Availability Groups](https://learn.microsoft.com/en-us/sql/database-engine/availability-groups/windows/overview-of-always-on-availability-groups-sql-server?view=sql-server-ver16) overview.
+
 ## Logs
 
 ### audit
@@ -187,5 +205,17 @@ Please refer to the following [document](https://www.elastic.co/guide/en/ecs/cur
 
 {{fields "transaction_log"}}
 
+### availability_groups
+
+The Microsoft SQL Server `availability_groups` dataset provides metrics from the Always On Availability Groups DMVs (Dynamic Management Views). All availability_groups metrics will be available in the `sqlserver.metrics` field group.
+
+{{event "availability_groups"}}
+
+**ECS Field Reference**
+
+Please refer to the following [document](https://www.elastic.co/guide/en/ecs/current/ecs-field-reference.html) for detailed information on ECS fields.
+
+{{fields "availability_groups"}}
+
 ## Alerting Rule Template
 {{alertRuleTemplates}}

packages/microsoft_sqlserver/changelog.yml

@@ -1,4 +1,9 @@
 # newer versions go on top
+- version: "2.15.1":
+  changes:
+    - description: Add health metrics for Always On Availability Groups.  
+      type: enhancement
+      link: https://github.com/elastic/integrations/pull/16759
 - version: "2.15.0"
   changes:
     - description: Update README with Alerting Rule Template.

packages/microsoft_sqlserver/data_stream/availability_groups/agent/stream/stream.yml.hbs

@@ -0,0 +1,31 @@
+metricsets: ["query"]
+# Specify hosts in the below format. TODO: hosts need to be updated to support multiple entries.
+hosts: 
+  - sqlserver://{{username}}:{{password}}@{{hosts}}
+period: {{period}}
+raw_data.enabled: true
+merge_results: false
+driver: "mssql"
+sql_queries:
+  # Availability groups metrics
+  - query: "SELECT
+    @@servername AS server_name,
+    ag.name,
+    CONVERT(NVARCHAR(36), ag.group_id) AS group_id,
+    ags.primary_replica,
+    ags.synchronization_health,
+    ags.synchronization_health_desc,
+    ags.primary_recovery_health,
+    ags.secondary_recovery_health
+FROM sys.dm_hadr_availability_group_states ags
+JOIN sys.availability_groups ag 
+    ON ags.group_id = ag.group_id;"
+    response_format: table
+{{#if processors}}
+processors:
+{{processors}}
+{{/if}}
+tags:
+{{#if preserve_sql_queries}}
+- preserve_sql_queries
+{{/if}}

packages/microsoft_sqlserver/data_stream/availability_groups/elasticsearch/ingest_pipeline/default.yml

@@ -0,0 +1,21 @@
+---
+description: Pipeline for processing mssql always on availability group metrics
+processors:
+- remove:
+    field: sql.driver
+    ignore_missing: true
+    ignore_failure: true
+- rename:
+    field: sql
+    target_field: mssql
+    ignore_missing: true
+    ignore_failure: true
+- remove:
+    field: mssql.query
+    if: "ctx?.tags == null || !(ctx.tags.contains('preserve_sql_queries'))"
+    ignore_missing: true
+    ignore_failure: true
+on_failure:
+- set:
+    field: error.message
+    value: "{{ _ingest.on_failure_message }}"

packages/microsoft_sqlserver/data_stream/availability_groups/fields/agent.yml

@@ -0,0 +1,33 @@
+- name: cloud
+  title: Cloud
+  group: 2
+  description: Fields related to the cloud or infrastructure the events are coming from.
+  footnote: 'Examples: If Metricbeat is running on an EC2 host and fetches data from its host, the cloud info contains the data about this machine. If Metricbeat runs on a remote machine outside the cloud and fetches data from a service running in the cloud, the field contains cloud data from the machine the service is running on.'
+  type: group
+  fields:
+    - name: image.id
+      type: keyword
+      description: Image ID for the cloud instance.
+- name: host
+  title: Host
+  group: 2
+  description: 'A host is defined as a general computing instance.  ECS host.* fields should be populated with details about the host on which the event happened, or from which the measurement was taken. Host types include hardware, virtual machines, Docker containers, and Kubernetes nodes.'
+  type: group
+  fields:
+    - name: containerized
+      type: boolean
+      description: >
+        If the host is a container.
+
+    - name: os.build
+      type: keyword
+      example: "18D109"
+      description: >
+        OS build information.
+
+    - name: os.codename
+      type: keyword
+      example: "stretch"
+      description: >
+        OS codename, if any.
+

packages/microsoft_sqlserver/data_stream/availability_groups/fields/base-fields.yml

@@ -0,0 +1,12 @@
+- name: data_stream.type
+  type: constant_keyword
+  description: Data stream type.
+- name: data_stream.dataset
+  type: constant_keyword
+  description: Data stream dataset.
+- name: data_stream.namespace
+  type: constant_keyword
+  description: Data stream namespace.
+- name: '@timestamp'
+  type: date
+  description: Event timestamp.

packages/microsoft_sqlserver/data_stream/availability_groups/fields/ecs.yml

@@ -0,0 +1,27 @@
+- external: ecs
+  name: service.address
+  dimension: true
+- external: ecs
+  name: host.name
+  dimension: true
+- external: ecs
+  name: agent.id
+  dimension: true
+- external: ecs
+  name: cloud.instance.id
+  dimension: true
+- external: ecs
+  name: cloud.provider
+  dimension: true
+- external: ecs
+  name: container.id
+  dimension: true
+- external: ecs
+  name: cloud.account.id
+  dimension: true
+- external: ecs
+  name: cloud.region
+  dimension: true
+- external: ecs
+  name: cloud.availability_zone
+  dimension: true

packages/microsoft_sqlserver/data_stream/availability_groups/fields/fields.yml

@@ -0,0 +1,33 @@
+- name: mssql
+  type: group
+  fields:
+    - name: metrics
+      type: group
+      fields:
+        - name: server_name
+          type: keyword
+          description: SQL Server instance name where metrics were collected.
+        - name: name
+          type: keyword
+          description: Availability group name.
+        - name: group_id
+          type: keyword
+          description: Unique identifier (GUID) of the availability group.
+        - name: primary_replica
+          type: keyword
+          description: Server name of the current primary replica.
+        - name: synchronization_health
+          type: keyword
+          description: AG synchronization health status (0 = NOT_HEALTHY, 1 = PARTIALLY_HEALTHY, 2 = HEALTHY).
+        - name: synchronization_health_desc
+          type: keyword
+          description: Text description of AG synchronization health.
+        - name: primary_recovery_health
+          type: keyword
+          description: Primary replica recovery health (0 = ONLINE_IN_PROGRESS, 1 = ONLINE. NULL on secondary replicas).
+        - name: secondary_recovery_health
+          type: keyword
+          description: Secondary replica recovery health (0 = ONLINE_IN_PROGRESS, 1 = ONLINE. NULL on primary replicas).
+    - name: query
+      type: keyword
+      description: The SQL queries executed.

packages/microsoft_sqlserver/data_stream/availability_groups/manifest.yml

@@ -0,0 +1,33 @@
+title: "Microsoft SQL Server Always On Availability Groups metrics"
+type: metrics
+streams:
+  - input: sql/metrics
+    vars:
+      - name: period
+        type: text
+        title: Period
+        multi: false
+        required: true
+        show_user: true
+        default: 5m
+      - name: preserve_sql_queries
+        required: true
+        show_user: false
+        title: Preserve SQL Queries
+        description: Preserves SQL queries for debugging purposes. This feature is available in Elastic stack version 8.18 and later.
+        type: bool
+        multi: false
+        default: false
+      - name: processors
+        type: yaml
+        title: Processors
+        multi: false
+        required: false
+        show_user: false
+        description: >
+          Processors are used to reduce the number of fields in the exported event or to enhance the event with metadata. This executes in the agent before the events are shipped. See [Processors](https://www.elastic.co/guide/en/fleet/current/elastic-agent-processor-configuration.html) for details.
+
+    title: Microsoft SQL Server Always On Availability Groups metrics
+    description: Collect Microsoft SQL Server Always On Availability Groups metrics. Monitors overall AG health, synchronization status, and primary/secondary recovery state.
+elasticsearch:
+  index_mode: "time_series"

packages/microsoft_sqlserver/data_stream/availability_groups/sample_event.json

@@ -0,0 +1,72 @@
+{
+    "@timestamp": "2026-01-09T13:26:41.427Z",
+    "agent": {
+        "ephemeral_id": "9879229c-2cb1-4082-a6e7-289de62de193",
+        "id": "819a1c28-7fc6-4490-8456-c04d37abce3d",
+        "name": "elastic-agent-12312",
+        "type": "metricbeat",
+        "version": "8.19.8"
+    },
+    "data_stream": {
+        "dataset": "microsoft_sqlserver.availability_groups",
+        "namespace": "default",
+        "type": "metrics"
+    },
+    "ecs": {
+        "version": "8.0.0"
+    },
+    "elastic_agent": {
+        "id": "819a1c28-7fc6-4490-8456-c04d37abce3d",
+        "snapshot": false,
+        "version": "8.19.8"
+    },
+    "event": {
+        "agent_id_status": "verified",
+        "dataset": "microsoft_sqlserver.availability_groups",
+        "duration": 797064208,
+        "ingested": "2026-01-09T13:26:43Z",
+        "module": "sql"
+    },
+    "host": {
+        "architecture": "arm64",
+        "hostname": "localhost",
+        "id": "11111-8ABC-59B6-95BC-11111111",
+        "ip": [
+            "192.168.242.2",
+            "192.168.255.6"
+        ],
+        "mac": [
+            "02-42-C0-A8-F2-02",
+            "02-42-C0-A8-FF-06"
+        ],
+        "name": "elastic-agent-12312",
+        "os": {
+            "build": "24G84",
+            "family": "darwin",
+            "kernel": "24.6.0",
+            "name": "macOS",
+            "platform": "darwin",
+            "type": "macos",
+            "version": "15.6"
+        }
+    },
+    "metricset": {
+        "name": "query",
+        "period": 300000
+    },
+    "mssql": {
+        "metrics": {
+            "group_id": "13495A5F-460C-4D93-BFA2-477E9F555A5A",
+            "name": "ag_test",
+            "primary_recovery_health": 1,
+            "primary_replica": "myVm-1",
+            "server_name": "myVm-1",
+            "synchronization_health": 2,
+            "synchronization_health_desc": "HEALTHY"
+        }
+    },
+    "service": {
+        "address": "microsoft_sqlserver",
+        "type": "sql"
+    }
+}