Fix tedge watchdog timeout misalignment with monitored services

1 files changed, 32 insertions, 22 deletions

diff --git a/docs/src/howto-guides/021_enable_tedge_watchdog_using_systemd.md b/docs/src/howto-guides/021_enable_tedge_watchdog_using_systemd.md
index 50c39967..c7a188fa 100644
--- a/docs/src/howto-guides/021_enable_tedge_watchdog_using_systemd.md
+++ b/docs/src/howto-guides/021_enable_tedge_watchdog_using_systemd.md
@@ -2,24 +2,31 @@
 
 ## Introduction
 
-The systemd watchdog feature enables systemd to detect when a service is unhealthy or unresponsive and attempt to fix it by restarting that service.
+The systemd watchdog feature enables systemd to detect when a service is unhealthy or unresponsive and 
+attempt to fix it by restarting that service.
 To detect if a service is healthy or not, systemd relies on periodic health notifications from that service at regular intervals.
-If the service fails to send that notification within a time threshold, then systemd will assume that service to be unhealthy and restart it.
+If the service fails to send that notification within a time threshold,
+then systemd will assume that service to be unhealthy and restart it.
 
 This document describes how the systemd watchdog mechanism can be enabled for thin-edge services.
 
-## Enabling the `watchdog` feature in `systemd`
+## Enabling the systemd watchdog feature for a tedge service
 
-Enabling systemd `watchdog` for a `thin-edge.io` service (tedge_agent, tedge_mapper_c8y/az/collectd)
-using the `systemd` is a two-step process.
+Enabling systemd watchdog for a `thin-edge.io` service (tedge-agent, tedge-mapper-c8y/az/collectd) is a two-step process.
 
-### Step 1: Enable the `watchdog` feature in the `systemd` service file
-For example to enable the `watchdog` feature for `tedge-mapper-c8y` service, update systemd service file as shown below.
+### Step 1: Enable the watchdog feature in the systemd service file
 
-Add `tedge-watchdog.service` in  `After` under `[Unit]` section.
-Add `WatchdogSec=5` under `[Service]` section.
+For example, to enable the watchdog feature for `tedge-mapper-c8y` service,
+update the systemd service file as shown below:
 
-The sample service file after updating looks as below.
+> Note: The systemd service file for tedge services are usually present in `/lib/systemd/system` directory, 
+> like `/lib/systemd/system/tedge-mapper-c8y.service`.
+
+Add `tedge-watchdog.service` as an `After` service dependency under `[Unit]` section.
+Add the watchdog interval as `WatchdogSec=30` under `[Service]` section.
+Update the restart condition as `Restart=always` under `[Service]` section.
+
+Here is the updated service file for `tedge-mapper-c8y` service:
 
 ```shell
 [Unit]
@@ -29,19 +36,16 @@ After=syslog.target network.target mosquitto.service tedge-watchdog.service
 [Service]
 User=tedge-mapper
 ExecStart=/usr/bin/tedge_mapper c8y
-Restart=on-failure
+Restart=always
 RestartPreventExitStatus=255
-WatchdogSec=5
+WatchdogSec=30
 ```
 
-> Note: The systemd service file for tedge services are usually present
-in `/lib/systemd/system` directory, like `/lib/systemd/system/tedge-mapper-c8y.service`.
-
 ### Step 2: Start the `tedge-watchdog` service
 
 The `tedge-watchdog` service is responsible for periodically checking the health of
-all tedge services for which the watchdog feature is enabled, and send systemd
-watchdog notifications on their behalf to systemd.
+all tedge services for which the watchdog feature is enabled,
+and send systemd watchdog notifications on their behalf to systemd.
 
 Start and enable the `tedge-watchdog` service as follows:
 	
@@ -50,16 +54,22 @@ systemctl start tedge-watchdog.service
 systemctl enable tedge-watchdog.service
 ``` 
 
-Now, the `tedge-watchdog` service will be keep sending health check messages to the monitored services periodically within their configured `WatchdogSec` interval.
+Once started, the `tedge-watchdog` service will keep checking the health of the monitored tedge services
+by periodically sending health check messages to them within their configured `WatchdogSec` interval.
 
-The health check request for service is published to `tedge/health-check/<service-name>` topic and the health status response from that service is expected on `tedge/health/<service-name>` topic.
+The health check request for service is published to `tedge/health-check/<service-name>` topic and
+the health status response from that service is expected on `tedge/health/<service-name>` topic.
 
-Once the health status response is received from a particular service, the `tedge-watchdog` service will send the watchdog notification on behalf of that service to systemd.
+Once the health status response is received from a particular service,
+the `tedge-watchdog` service will send the [systemd notification](https://www.freedesktop.org/software/systemd/man/sd_notify.html#) to systemd on behalf of that monitored service.
 
 ## Debugging
-One can observe the message exchange between the `service` and the `watchdog` by subscribing to `tedge/health/#` and `tedge/health-check/#` topics.
+
+One can observe the message exchange between the `service` and the `watchdog`
+by subscribing to `tedge/health/#` and `tedge/health-check/#` topics.
 For more info check [here](./020_monitor_tedge_health.md)
 
-> Note: If the watchdog service did not send the notification to the systemd within `WatchdogSec`, then the systemd will kill the existing service process and restarts it.
+> Note: If the watchdog service does not send the notification to the systemd within `WatchdogSec` interval for a service,
+> then systemd restarts that service by killing the old process and spawning a new one to replace it.
 
 > Note: [Here](https://www.medo64.com/2019/01/systemd-watchdog-for-any-service/) is an example about using `systemd watchdog` feature.