DOC-5567 RS: Added lag-aware checks to DB availability doc

Author: rrelledge

content/operate/rs/monitoring/db-availability.md

@@ -45,6 +45,56 @@ Returns HTTP status code 200 OK if all primary (master) shards are reachable fro
 
 If the local database endpoint is unavailable, returns an error status code and a JSON object that contains [`error_code` and `description` fields]({{<relref "/operate/rs/references/rest-api/requests/bdbs/availability#get-endpoint-error-codes">}}).
 
+## Use lag-aware availability checks for disaster recovery {#lag-aware}
+
+The database availability API supports lag-aware availability checks that consider replication lag tolerance. You can reduce the risk of data inconsistencies during disaster recovery by incorporating lag-aware availability checks into your disaster recovery solution and ensuring failover-failback flows only occur when databases are accessible and sufficiently synchronized.
+
+### Adjust availability lag tolerance threshold
+
+The lag tolerance threshold is 100 milliseconds by default. Depending on factors such as workload, network conditions, and throughput, you might want to adjust the lag tolerance threshold using one of the following methods:
+
+- Change the default threshold for the entire cluster by setting `availability_lag_tolerance_ms` with an [update cluster]({{<relref "/operate/rs/references/rest-api/requests/cluster#put-cluster">}}) request.
+
+    ```sh
+    PUT /v1/cluster
+    { "availability_lag_tolerance_ms": 100 }
+    ```
+
+- Override the default threshold by adding the `availability_lag_tolerance_ms` query parameter to specific lag-aware [availability checks]({{<relref "/operate/rs/references/rest-api/requests/bdbs/availability">}}).
+
+    ```sh
+    GET /v1/bdbs/<database_id>/availability?extend_check=lag&availability_lag_tolerance_ms=100
+    ```
+
+### Lag-aware database availability checks
+
+To perform a lag-aware database availability check using the cluster's default lag tolerance threshold:
+
+```sh
+GET /v1/bdbs/<database_id>/availability?extend_check=lag
+```
+
+To perform a lag-aware database availability check and override the cluster's default lag tolerance threshold:
+
+```sh
+GET /v1/bdbs/<database_id>/availability?extend_check=lag&availability_lag_tolerance_ms=100
+```
+
+### Lag-aware endpoint availability checks
+
+To perform a lag-aware database endpoint availability check using the cluster's default lag tolerance threshold:
+
+```sh
+GET /v1/local/bdbs/<database_id>/endpoint/availability?extend_check=lag
+```
+
+To perform a lag-aware database endpoint availability check and override the cluster's default lag tolerance threshold:
+
+```sh
+GET /v1/local/bdbs/<database_id>/endpoint/availability?extend_check=lag&availability_lag_tolerance_ms=100
+```
+
+
 ## Availability by database status
 
 The following table shows the relationship between a database's status and availability. For more details about the database status values, see [BDB status field]({{<relref "/operate/rs/references/rest-api/objects/bdb/status">}}).

content/operate/rs/references/rest-api/objects/cluster/_index.md

@@ -16,7 +16,7 @@ An API object that represents the cluster.
 | Name | Type/Value | Description |
 |------|------------|-------------|
 | alert_settings | [alert_settings]({{< relref "/operate/rs/references/rest-api/objects/cluster/alert_settings" >}}) object | Cluster and node alert settings |
-| <span class="break-all">availability_lag_tolerance_ms</span> | integer (default: 100) | The maximum replication lag in milliseconds tolerated between source and replicas during lag-aware [database availability checks]({{<relref "/operate/rs/monitoring/db-availability">}}). |
+| <span class="break-all">availability_lag_tolerance_ms</span> | integer (default: 100) | The maximum replication lag in milliseconds tolerated between source and replicas during [lag-aware database availability checks]({{<relref "/operate/rs/monitoring/db-availability#lag-aware">}}). |
 | bigstore_driver | 'speedb'<br />'rocksdb' | Storage engine for [Auto Tiering]({{<relref "/operate/rs/databases/auto-tiering">}}) |
 | <span class="break-all">cluster_ssh_public_key</span> | string | Cluster's autogenerated SSH public key |
 | cm_port | integer, (range: 1024-65535) | UI HTTPS listening port |