[Heartbeat][Docs] Consistently use id/name in all examples (#17694) (#…

…17697)

We should always include these optional config values, as not using them
creates continuity issues in the Uptime app. The `id` attribute is the
only way we can consistently identify a monitor over time when its
config changes, and the `name` attribute is used for display purposes in
the Uptime app.

This change makes our docs examples reflect best practices.

(cherry picked from commit 4bb189d)

heartbeat/docs/heartbeat-options.asciidoc

@@ -24,17 +24,23 @@ and HTTP response verification:
 # heartbeat.yml
 heartbeat.monitors:
 - type: icmp
-  schedule: '*/5 * * * * * *'
+  id: ping-myhost
+  name: My Host Ping
   hosts: ["myhost"]
+  schedule: '*/5 * * * * * *'
 - type: tcp
-  schedule: '@every 5s'
-  hosts: ["myhost:7"]  # default TCP Echo Protocol
+  id: myhost-tcp-echo
+  name: My Host TCP Echo
+  hosts: ["myhost:777"]  # default TCP Echo Protocol
   check.send: "Check"
   check.receive: "Check"
-- type: http
   schedule: '@every 5s'
+- type: http
+  id: service-status
+  name: Service Status
   hosts: ["http://localhost:80/service/status"]
   check.response.status: [200]
+  schedule: '@every 5s'
 heartbeat.scheduler:
   limit: 10
 ----------------------------------------------------------------------
@@ -67,9 +73,11 @@ monitor definitions only, e.g. what is normally under the `heartbeat.monitors` s
 ----------------------------------------------------------------------
 # /path/to/my/monitors.d/localhost_service_check.yml
 - type: http
-  schedule: '@every 5s'
+  id: service-status
+  name: Service Status
   hosts: ["http://localhost:80/service/status"]
   check.response.status: [200]
+  schedule: '@every 5s'
 ----------------------------------------------------------------------
 
 [float]
@@ -291,16 +299,21 @@ system defaults are used (currently not supported on Windows).
 ==== `ports`
 
 A list of ports to ping if the host specified in <<monitor-tcp-hosts,`hosts`>>
-does not contain a port number.
+does not contain a port number. It is generally preferable to use a single value here,
+since each port will be monitored using a separate `id`, with the given `id` value,
+used as a prefix in the Heartbeat data, and the configured `name` shared across events
+sent via this check.
 
 Example configuration:
 
 [source,yaml]
 -------------------------------------------------------------------------------
 - type: tcp
-  schedule: '@every 5s'
+  id: my-host-services
+  name: My Host Services
   hosts: ["myhost"]
   ports: [80, 9200, 5044]
+  schedule: '@every 5s'
 -------------------------------------------------------------------------------
 
 [float]
@@ -319,11 +332,13 @@ Example configuration:
 [source,yaml]
 -------------------------------------------------------------------------------
 - type: tcp
-  schedule: '@every 5s'
+  id: echo-service
+  name: Echo Service
   hosts: ["myhost"]
   ports: [7]
   check.send: 'Hello World'
   check.receive: 'Hello World'
+  schedule: '@every 5s'
 -------------------------------------------------------------------------------
 
 
@@ -369,9 +384,11 @@ Example configuration:
 [source,yaml]
 -------------------------------------------------------------------------------
 - type: tcp
+  id: tls-mail
+  name: TLS Mail
+  hosts: ["mail.example.net"]
+  ports: [465]
   schedule: '@every 5s'
-  hosts: ["myhost"]
-  ports: [80, 9200, 5044]
   ssl:
     certificate_authorities: ['/etc/ca.crt']
     supported_protocols: ["TLSv1.0", "TLSv1.1", "TLSv1.2"]
@@ -399,6 +416,8 @@ Example configuration:
 [source,yaml]
 -------------------------------------------------------------------------------
 - type: http
+  id: myhost
+  name: My HTTP Host
   schedule: '@every 5s'
   hosts: ["http://myhost:80"]
 -------------------------------------------------------------------------------
@@ -451,14 +470,15 @@ Example configuration:
 [source,yaml]
 -------------------------------------------------------------------------------
 - type: http
-  schedule: '@every 5s'
+  id: my-http-service
+  name: My HTTP Service
   hosts: ["https://myhost:443"]
+  schedule: '@every 5s'
   ssl:
     certificate_authorities: ['/etc/ca.crt']
     supported_protocols: ["TLSv1.0", "TLSv1.1", "TLSv1.2"]
 -------------------------------------------------------------------------------
 
-
 Also see <<configuration-ssl>> for a full description of the `ssl` options.
 
 [float]
@@ -486,10 +506,12 @@ Example configuration:
 [source,yaml]
 -------------------------------------------------------------------------------
 - type: http
-  schedule: '@every 5s'
+  id: my-http-host
+  name: My HTTP Service
   hosts: ["http://myhost:80"]
   check.request.method: HEAD
   check.response.status: [200]
+  schedule: '@every 5s'
 -------------------------------------------------------------------------------
 
 
@@ -508,6 +530,8 @@ to the endpoint `/demo/add`
 [source,yaml]
 -------------------------------------------------------------------------------
 - type: http
+  id: demo-service
+  name: Demo Service
   schedule: '@every 5s'
   urls: ["http://localhost:8080/demo/add"]
   check.request:
@@ -537,6 +561,8 @@ response body for the strings `saved` or `Saved` and expects 200 or 201 status c
 [source,yaml]
 -------------------------------------------------------------------------------
 - type: http
+  id: demo-service
+  name: Demo Service
   schedule: '@every 5s'
   urls: ["http://localhost:8080/demo/add"]
   check.request:
@@ -561,6 +587,8 @@ contains JSON:
 [source,yaml]
 -------------------------------------------------------------------------------
 - type: http
+  id: demo-service
+  name: Demo Service
   schedule: '@every 5s'
   hosts: ["https://myhost:80"]
   check.request:
@@ -582,6 +610,8 @@ patterns:
 [source,yaml]
 -------------------------------------------------------------------------------
 - type: http
+  id: demo-service
+  name: Demo Service
   schedule: '@every 5s'
   hosts: ["https://myhost:80"]
   check.request:
@@ -601,6 +631,8 @@ regex:
 [source,yaml]
 -------------------------------------------------------------------------------
 - type: http
+  id: demo-service
+  name: Demo Service
   schedule: '@every 5s'
   hosts: ["https://myhost:80"]
   check.request:
@@ -683,6 +715,8 @@ Example configuration:
 -------------------------------------------------------------------------------
 heartbeat.monitors:
 - type: tcp
+  id: demo-service
+  name: Demo Service
   schedule: '*/5 * * * * * *'
   hosts: ["myhost"]
   watch.poll_file: