action.skip

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 Data Monitor sends a ping to a target host and ends when Zenoss Data Monitor 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 Zenoss Data Monitor 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 Data Monitor service monitors the /etc/zendatamon-configs/configs directory and loads any new or changed configuration files immediately.

Properties

Datasource properties

The following properties are in spec.datasource.config:

max_concurrent_pings
The maximum number of target hosts to ping concurrently.
use_target_dimensions_only

Whether entities include a common set of dimension attributes.

  • When this property is false, entities include the dimension attributes defined in both spec.datasource.config.dimensions and spec.datasource.targets.<target-ID>.dimensions.

  • When this property is true, the dimension attributes in spec.datasource.targets.<target-ID>.dimensions identify an existing entity for the metrics and events the datasource creates.

For more information about entity attributes, see Using entities.

collector_interval
The frequency of ping cycles, in seconds.
one_ping_timeout
The duration of a ping cycle, in seconds.
pings_per_cycle
The number of pings per cycle.
packets_loss_critical_amount
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
The amount of time over the average round-trip time that triggers a health event.
payload_size_bytes
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
The fully-qualified domain name of a host to test before beginning a collection cycle.
dimensions
Dimension attributes to include in new entities. See use_target_dimensions_only.
metadata
Metadata attributes to include in new entities. See use_target_dimensions_only.

Target properties

The following properties in spec.datasource.targets 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>
A unique identifier for a target host. Often, this is the FQDN of the host.
address
The IPv4/IPv6 address or FQDN of a target host.
send_metrics
Whether to send metrics for this target.
dimensions
Dimension attributes to include in new entities or to identify existing entities. See use_target_dimensions_only.
metadata
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.

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