icmp datasource

The icmp datasource uses ICMP to send packets (pings) to the hosts you specify and creates metric data points, entities, and events. Both IPv4 and IPv6 host addresses are supported.

Metrics

Most of the following metrics rely on the round-trip time of a ping. A round-trip time starts when Zenoss Cloud agent sends a ping to a target host and ends when Zenoss Cloud agent receives the target host's acknowledgement of the ping, if the target can send one.

Name	Units	Description
ping.icmp.up	boolean	1 if target is up, 0 if down (see Availability metric)
ping.icmp.min_rtt	ms	The minimum round-trip time among all performed pings per cycle
ping.icmp.max_rtt	ms	The maximum round-trip time among all performed pings per cycle
ping.icmp.mean_rtt	ms	The average round-trip time of all performed pings per cycle
ping.icmp.std_dev	ms	The average variance of each ping's round-trip time from the mean round-trip time
ping.icmp.packet_loss	percentage	The percentage of sent packets that did not reach the destination
ping.icmp.packet_loss_count	packets	The count of sent packets that did not reach the destination
ping.icmp.jitter	ms	The variation among round-trip times (see Jitter metric)

Availability metric

Either value of ping.icmp.up generates an event:

When ping.icmp.up is 1 (true), an icmpAvailability UP event is sent.
When ping.icmp.up is 0 (false), an icmpAvailability DOWN event is sent, and only ping.icmp.packet_loss and ping.icmp.packet_loss_count are gathered. All other metrics are set to 0.

The value is 0 in the following circumstances:

When the Zenoss Cloud agent or its inbound gateway determine that the destination is unreachable.
When the value of ping.icmp.packet_loss_count is greater than the value of the packets_loss_critical_amount configuration property.

Jitter metric

Jitter is the average time between successive round-trip times divided by the number of computed values. For example, five successive round-trip times (136, 184, 115, 148, 125) are computed four times:

136 - 184 = 48
184 - 115 = 69
115 - 148 = 33
148 - 125 = 23

Then, the sum of the computed values (48+69+33+23) is divided by the number of computed values (4) for a jitter value of 43.25.

Entities

This datasource either creates one entity for each monitoring target or uses existing entities. Specify the properties of each target's entity in the configuration file. Zenoss Cloud associates metrics and events with each target's entity.

Events

Health event

This datasource sends an icmpHealth event of severity WARNING in the following circumstances:

(Degraded) The value of ping.icmp.packet_loss_count is greater than 0 but less than the value of the packets_loss_critical_amount configuration property.
(Degraded) The value of ping.icmp.mean_rtt grows abnormally.
The previous ping attempt resulted in one of the preceding events, but the current ping attempt passes all health checks, so a new event is sent to clear the previous event.

Availability event

This datasource sends an icmpAvailability event of severity CRITICAL in the following circumstances:

(UP) All health checks pass.
(DOWN) The value of ping.icmp.packet_loss_count is greater than the value of the packets_loss_critical_amount configuration property.
(DOWN) The target is unreachable (ping.icmp.packet_loss is equal to 100%).

Configuration

If you specify the icmp datasource during installation, its configuration file is placed in the following location:

/etc/zendatamon-configs/configs/icmp.config.yaml

Otherwise, you must copy it from the templates directory:

cp /etc/zendatamon-configs/.templates/.configs/icmp.config.yaml \
  /etc/zendatamon-configs/configs/icmp.config.yaml

The Zenoss Cloud agent service monitors the /etc/zendatamon-configs/configs directory and loads any new or changed configuration files immediately.

Properties

Datasource properties

max_concurrent_pings (number)

The maximum number of target hosts to ping concurrently.

use_target_dimensions_only (boolean, default = false)

Whether entities include a common set of dimension attributes.

When this property is false, entities include the attributes defined in the common dimensions and target dimensions fields.
When this property is true, the target attributes (dimensions) identify an existing entity for the metrics and events the datasource creates.

For more information about entity attributes, see Using entities.

collector_interval (string)

The frequency of ping cycles, in seconds.

one_ping_timeout (string)

The duration of a ping cycle, in seconds.

pings_per_cycle (number)

The number of pings per cycle.

packets_loss_critical_amount (number)

The number of missed packets to use when determining whether to send an event. The minimum value is 1 and the maximum cannot exceed the value of pings_per_cycle.

avg_rtt_deviation_warning (string)

The amount of time over the average round-trip time that triggers a health event.

payload_size_bytes (number)

The size of the variable-length field to append to each ICMP packet header, in bytes. For Windows targets, the valid range is 24-65500 bytes. For Linux or Darwin targets, the valid range is 24-65507 bytes.

probing_target (string)

The fully-qualified domain name of a host to test before beginning a collection cycle.

dimensions (object)

Dimension attributes to include in new entities. See use_target_dimensions_only.

metadata (object)

Metadata attributes to include in new entities. See use_target_dimensions_only.

Target properties

The following properties specify one target host. You may specify as many target hosts as you wish, although larger numbers of targets may require additional hardware resources.

<TARGET-ID> (string): A unique identifier for a target host. Often, this is the FQDN of the host.
address (string): The IPv4/IPv6 address or FQDN of a target host.
send_metrics (boolean, default = false): Whether to send metrics for this target.
dimensions (object): Dimension attributes to include in new entities or to identify existing entities. See use_target_dimensions_only in datasource properties.
metadata (object): Metadata attributes to include in new entities or to identify existing entities. In particular, the name field should be specified. See use_target_dimensions_only in datasource properties.

Example

apiVersion: v1
kind: datasource
name: icmp
spec:
  type: icmp
  datasource:
    config:
      max_concurrent_pings: 20
      use_target_dimensions_only: false
      collector_interval: 30s
      one_ping_timeout: 1s
      pings_per_cycle: 4
      packets_loss_critical_amount: 3
      avg_rtt_deviation_warning: 300ms
      payload_size_bytes: 24
      probing_target: zenoss.com
    targets:
      server.example.com:
        address: 198.51.100.12
        send_metrics: true
        dimensions:
          type: icmp.target.host
        metadata:
          name: server.example.com

Configuring ICMP traffic

To support availability monitoring of IPv4 hosts with the icmp datasource, your Zenoss Cloud agent host must be configured to allow ICMP traffic from userland services.

Before you begin

Make sure you meet the following requirements:

Zenoss Cloud agent is installed and running.
The icmp datasource is configured with at least one monitoring target.

Configure ICMP traffic

Perform the following steps:

Log in to the Zenoss Cloud agent host.
Check the security setting.
```
sudo sysctl net.ipv4.ping_group_range
```
- If the result is net.ipv4.ping_group_range = 1 2147483647, stop. Your host is configured to allow ICMP traffic from userland services.
- If the result is net.ipv4.ping_group_range = 1 0, proceed to the next step.

Enable outgoing ICMP traffic.

sudo sysctl -w net.ipv4.ping_group_range="0 2147483647"