diff options
Diffstat (limited to 'src/collectors/ioping.plugin')
| l--------- | src/collectors/ioping.plugin/README.md | 1 | ||||
| -rw-r--r-- | src/collectors/ioping.plugin/integrations/ioping.md | 133 | ||||
| -rw-r--r-- | src/collectors/ioping.plugin/ioping.conf | 40 | ||||
| -rwxr-xr-x | src/collectors/ioping.plugin/ioping.plugin.in | 272 | ||||
| -rw-r--r-- | src/collectors/ioping.plugin/metadata.yaml | 101 |
5 files changed, 547 insertions, 0 deletions
diff --git a/src/collectors/ioping.plugin/README.md b/src/collectors/ioping.plugin/README.md new file mode 120000 index 00000000..cb660f13 --- /dev/null +++ b/src/collectors/ioping.plugin/README.md @@ -0,0 +1 @@ +integrations/ioping.md
\ No newline at end of file diff --git a/src/collectors/ioping.plugin/integrations/ioping.md b/src/collectors/ioping.plugin/integrations/ioping.md new file mode 100644 index 00000000..24630ae3 --- /dev/null +++ b/src/collectors/ioping.plugin/integrations/ioping.md @@ -0,0 +1,133 @@ +<!--startmeta +custom_edit_url: "https://github.com/netdata/netdata/edit/master/src/collectors/ioping.plugin/README.md" +meta_yaml: "https://github.com/netdata/netdata/edit/master/src/collectors/ioping.plugin/metadata.yaml" +sidebar_label: "IOPing" +learn_status: "Published" +learn_rel_path: "Collecting Metrics/Synthetic Checks" +most_popular: False +message: "DO NOT EDIT THIS FILE DIRECTLY, IT IS GENERATED BY THE COLLECTOR'S metadata.yaml FILE" +endmeta--> + +# IOPing + + +<img src="https://netdata.cloud/img/syslog.png" width="150"/> + + +Plugin: ioping.plugin +Module: ioping.plugin + +<img src="https://img.shields.io/badge/maintained%20by-Netdata-%2300ab44" /> + +## Overview + +Monitor IOPing metrics for efficient disk I/O latency tracking. Keep track of read/write speeds, latency, and error rates for optimized disk operations. + +Plugin uses `ioping` command. + +This collector is supported on all platforms. + +This collector supports collecting metrics from multiple instances of this integration, including remote instances. + + +### Default Behavior + +#### Auto-Detection + +This integration doesn't support auto-detection. + +#### Limits + +The default configuration for this integration does not impose any limits on data collection. + +#### Performance Impact + +The default configuration for this integration is not expected to impose a significant performance impact on the system. + + +## Metrics + +Metrics grouped by *scope*. + +The scope defines the instance that the metric belongs to. An instance is uniquely identified by a set of labels. + + + +### Per disk + + + +This scope has no labels. + +Metrics: + +| Metric | Dimensions | Unit | +|:------|:----------|:----| +| ioping.latency | latency | microseconds | + + + +## Alerts + + +The following alerts are available: + +| Alert name | On metric | Description | +|:------------|:----------|:------------| +| [ ioping_disk_latency ](https://github.com/netdata/netdata/blob/master/src/health/health.d/ioping.conf) | ioping.latency | average I/O latency over the last 10 seconds | + + +## Setup + +### Prerequisites + +#### Install ioping + +You can install the command by passing the argument `install` to the plugin (`/usr/libexec/netdata/plugins.d/ioping.plugin install`). + + + +### Configuration + +#### File + +The configuration file name for this integration is `ioping.conf`. + + +You can edit the configuration file using the `edit-config` script from the +Netdata [config directory](/docs/netdata-agent/configuration/README.md#the-netdata-config-directory). + +```bash +cd /etc/netdata 2>/dev/null || cd /opt/netdata/etc/netdata +sudo ./edit-config ioping.conf +``` +#### Options + + + +<details open><summary>Config options</summary> + +| Name | Description | Default | Required | +|:----|:-----------|:-------|:--------:| +| update_every | Data collection frequency. | 1s | no | +| destination | The directory/file/device to ioping. | | yes | +| request_size | The request size in bytes to ioping the destination (symbolic modifiers are supported) | 4k | no | +| ioping_opts | Options passed to `ioping` commands. | -T 1000000 | no | + +</details> + +#### Examples + +##### Basic Configuration + +This example has the minimum configuration necessary to have the plugin running. + +<details open><summary>Config</summary> + +```yaml +destination="/dev/sda" + +``` +</details> + + diff --git a/src/collectors/ioping.plugin/ioping.conf b/src/collectors/ioping.plugin/ioping.conf new file mode 100644 index 00000000..86f0de7f --- /dev/null +++ b/src/collectors/ioping.plugin/ioping.conf @@ -0,0 +1,40 @@ +# no need for shebang - this file is sourced from ioping.plugin + +# ioping.plugin requires a recent version of ioping. +# +# You can get it on your system, by running: +# +# /usr/libexec/netdata/plugins.d/ioping.plugin install + +# ----------------------------------------------------------------------------- +# configuration options + +# The ioping binary to use. We need one that can output netdata friendly info +# (supporting: -N). If you have multiple versions, put here the full filename +# of the right one + +#ioping="/usr/libexec/netdata/plugins.d/ioping" + + +# The directory/file/device to ioping + +destination="" + + +# The update frequency of the chart in seconds (symbolic modifiers are supported) +# the default is inherited from netdata + +#update_every="1s" + + +# The request size in bytes to ioping the destination (symbolic modifiers are supported) +# by default 4k chunks are used + +#request_size="4k" + + +# Other ioping options +# the defaults: +# -T 1000000 = maximum valid request time (us) + +#ioping_opts="-T 1000000" diff --git a/src/collectors/ioping.plugin/ioping.plugin.in b/src/collectors/ioping.plugin/ioping.plugin.in new file mode 100755 index 00000000..171e384d --- /dev/null +++ b/src/collectors/ioping.plugin/ioping.plugin.in @@ -0,0 +1,272 @@ +#!/usr/bin/env bash +# SPDX-License-Identifier: GPL-3.0-or-later + +# netdata +# real-time performance and health monitoring, done right! +# (C) 2017 Costa Tsaousis <costa@tsaousis.gr> +# GPL v3+ +# +# This plugin requires a latest version of ioping. +# You can compile it from source, by running me with option: install + +export PATH="${PATH}:/sbin:/usr/sbin:/usr/local/sbin:@sbindir_POST@" +export LC_ALL=C + +usage="$(basename "$0") [install] [-h] [-e] + +where: + install install ioping binary + -e, --env path to environment file (defaults to '/etc/netdata/.environment' + -h show this help text" + +INSTALL=0 +ENVIRONMENT_FILE="/etc/netdata/.environment" + +while :; do + case "$1" in + -h | --help) + echo "$usage" >&2 + exit 1 + ;; + install) + INSTALL=1 + shift + ;; + -e | --env) + ENVIRONMENT_FILE="$2" + shift 2 + ;; + -*) + echo "$usage" >&2 + exit 1 + ;; + *) break ;; + esac +done + +if [ "$INSTALL" == "1" ] + then + [ "${UID}" != 0 ] && echo >&2 "Please run me as root. This will install a single binary file: /usr/libexec/netdata/plugins.d/ioping." && exit 1 + + source "${ENVIRONMENT_FILE}" || exit 1 + + run() { + printf >&2 " > " + printf >&2 "%q " "${@}" + printf >&2 "\n" + "${@}" || exit 1 + } + + download() { + local git="$(which git 2>/dev/null || command -v git 2>/dev/null)" + [ ! -z "${git}" ] && run git clone "${1}" "${2}" && return 0 + + echo >&2 "Cannot find 'git' in this system." && exit 1 + } + + tmp=$(mktemp -d /tmp/netdata-ioping-XXXXXX) + [ ! -d "${NETDATA_PREFIX}/usr/libexec/netdata" ] && run mkdir -p "${NETDATA_PREFIX}/usr/libexec/netdata" + + run cd "${tmp}" + + if [ -d ioping-netdata ] + then + run rm -rf ioping-netdata || exit 1 + fi + + download 'https://github.com/netdata/ioping.git' 'ioping-netdata' + [ $? -ne 0 ] && exit 1 + run cd ioping-netdata || exit 1 + + INSTALL_PATH="${NETDATA_PREFIX}/usr/libexec/netdata/plugins.d/ioping" + + run make clean + run make + run mv ioping "${INSTALL_PATH}" + run chown root:"${NETDATA_GROUP}" "${INSTALL_PATH}" + run chmod 4750 "${INSTALL_PATH}" + echo >&2 + echo >&2 "All done, you have a compatible ioping now at ${INSTALL_PATH}." + echo >&2 + + exit 0 +fi + +# ----------------------------------------------------------------------------- +# logging + +PROGRAM_NAME="$(basename "${0}")" + +# these should be the same with syslog() priorities +NDLP_EMERG=0 # system is unusable +NDLP_ALERT=1 # action must be taken immediately +NDLP_CRIT=2 # critical conditions +NDLP_ERR=3 # error conditions +NDLP_WARN=4 # warning conditions +NDLP_NOTICE=5 # normal but significant condition +NDLP_INFO=6 # informational +NDLP_DEBUG=7 # debug-level messages + +# the max (numerically) log level we will log +LOG_LEVEL=$NDLP_INFO + +set_log_min_priority() { + case "${NETDATA_LOG_LEVEL,,}" in + "emerg" | "emergency") + LOG_LEVEL=$NDLP_EMERG + ;; + + "alert") + LOG_LEVEL=$NDLP_ALERT + ;; + + "crit" | "critical") + LOG_LEVEL=$NDLP_CRIT + ;; + + "err" | "error") + LOG_LEVEL=$NDLP_ERR + ;; + + "warn" | "warning") + LOG_LEVEL=$NDLP_WARN + ;; + + "notice") + LOG_LEVEL=$NDLP_NOTICE + ;; + + "info") + LOG_LEVEL=$NDLP_INFO + ;; + + "debug") + LOG_LEVEL=$NDLP_DEBUG + ;; + esac +} + +set_log_min_priority + +log() { + local level="${1}" + shift 1 + + [[ -n "$level" && -n "$LOG_LEVEL" && "$level" -gt "$LOG_LEVEL" ]] && return + + systemd-cat-native --log-as-netdata --newline="--NEWLINE--" <<EOFLOG +INVOCATION_ID=${NETDATA_INVOCATION_ID} +SYSLOG_IDENTIFIER=${PROGRAM_NAME} +PRIORITY=${level} +THREAD_TAG=ioping.plugin +ND_LOG_SOURCE=collector +MESSAGE=${MODULE_NAME}: ${*//\\n/--NEWLINE--} + +EOFLOG + # AN EMPTY LINE IS NEEDED ABOVE +} + +info() { + log "$NDLP_INFO" "${@}" +} + +warning() { + log "$NDLP_WARN" "${@}" +} + +error() { + log "$NDLP_ERR" "${@}" +} + +disable() { + log "${@}" + echo "DISABLE" + exit 1 +} + +fatal() { + disable "$NDLP_ALERT" "${@}" +} + +debug() { + log "$NDLP_DEBUG" "${@}" +} + +# ----------------------------------------------------------------------------- + +# store in ${plugin} the name we run under +# this allows us to copy/link ioping.plugin under a different name +# to have multiple ioping plugins running with different settings +plugin="${PROGRAM_NAME/.plugin/}" + + +# ----------------------------------------------------------------------------- + +# the frequency to send info to netdata +# passed by netdata as the first parameter +update_every="${1-1}" + +# the netdata configuration directory +# passed by netdata as an environment variable +[ -z "${NETDATA_USER_CONFIG_DIR}" ] && NETDATA_USER_CONFIG_DIR="@configdir_POST@" +[ -z "${NETDATA_STOCK_CONFIG_DIR}" ] && NETDATA_STOCK_CONFIG_DIR="@libconfigdir_POST@" + +# the netdata directory for internal binaries +[ -z "${NETDATA_PLUGINS_DIR}" ] && NETDATA_PLUGINS_DIR="@pluginsdir_POST@" + +# ----------------------------------------------------------------------------- +# configuration options +# can be overwritten at /etc/netdata/ioping.conf + +# the ioping binary to use +# we need one that can output netdata friendly info (supporting: -N) +# if you have multiple versions, put here the full filename of the right one +ioping="${NETDATA_PLUGINS_DIR}/ioping" + +# the destination to ioping +destination="" + +# the request size in bytes to ping the disk +request_size="4k" + +# ioping options +ioping_opts="-T 1000000" + +# ----------------------------------------------------------------------------- +# load the configuration files + +for CONFIG in "${NETDATA_STOCK_CONFIG_DIR}/${plugin}.conf" "${NETDATA_USER_CONFIG_DIR}/${plugin}.conf"; do + if [ -f "${CONFIG}" ]; then + debug "Loading config file '${CONFIG}'..." + source "${CONFIG}" + [ $? -ne 0 ] && warn "Failed to load config file '${CONFIG}'." + elif [[ $CONFIG =~ ^$NETDATA_USER_CONFIG_DIR ]]; then + debug "Cannot find file '${CONFIG}'." + fi +done + +if [ -z "${destination}" ] +then + disable $NDLP_DEBUG "destination is not configured - nothing to do." +fi + +if [ ! -f "${ioping}" ] +then + disable $NDLP_ERR "ioping command is not found. Please set its full path in '${NETDATA_USER_CONFIG_DIR}/${plugin}.conf'" +fi + +if [ ! -x "${ioping}" ] +then + disable $NDLP_ERR "ioping command '${ioping}' is not executable - cannot proceed." +fi + +# the ioping options we will use +options=( -N -i ${update_every} -s ${request_size} ${ioping_opts} ${destination} ) + +# execute ioping +debug "starting ioping: ${ioping} ${options[*]}" + +exec "${ioping}" "${options[@]}" + +# if we cannot execute ioping, stop +error "command '${ioping} ${options[*]}' failed to be executed (returned code $?)." diff --git a/src/collectors/ioping.plugin/metadata.yaml b/src/collectors/ioping.plugin/metadata.yaml new file mode 100644 index 00000000..e6ca8c22 --- /dev/null +++ b/src/collectors/ioping.plugin/metadata.yaml @@ -0,0 +1,101 @@ +plugin_name: ioping.plugin +modules: + - meta: + plugin_name: ioping.plugin + module_name: ioping.plugin + monitored_instance: + name: IOPing + link: "https://github.com/koct9i/ioping" + categories: + - data-collection.synthetic-checks + icon_filename: "syslog.png" + related_resources: + integrations: + list: [] + info_provided_to_referring_integrations: + description: "" + keywords: [] + most_popular: false + overview: + data_collection: + metrics_description: "Monitor IOPing metrics for efficient disk I/O latency tracking. Keep track of read/write speeds, latency, and error rates for optimized disk operations." + method_description: "Plugin uses `ioping` command." + supported_platforms: + include: [] + exclude: [] + multi_instance: true + additional_permissions: + description: "" + default_behavior: + auto_detection: + description: "" + limits: + description: "" + performance_impact: + description: "" + setup: + prerequisites: + list: + - title: Install ioping + description: | + You can install the command by passing the argument `install` to the plugin (`/usr/libexec/netdata/plugins.d/ioping.plugin install`). + configuration: + file: + name: "ioping.conf" + description: "File with options to specify hardware to monitor and arguments for ioping command." + options: + description: "" + folding: + title: "Config options" + enabled: true + list: + - name: update_every + description: Data collection frequency. + default_value: 1s + required: false + - name: destination + description: The directory/file/device to ioping. + default_value: "" + required: true + - name: request_size + description: The request size in bytes to ioping the destination (symbolic modifiers are supported) + default_value: 4k + required: false + - name: ioping_opts + description: Options passed to `ioping` commands. + default_value: -T 1000000 + required: false + examples: + folding: + enabled: true + title: "Config" + list: + - name: Basic Configuration + description: This example has the minimum configuration necessary to have the plugin running. + config: | + destination="/dev/sda" + troubleshooting: + problems: + list: [] + alerts: + - name: ioping_disk_latency + link: https://github.com/netdata/netdata/blob/master/src/health/health.d/ioping.conf + metric: ioping.latency + info: average I/O latency over the last 10 seconds + metrics: + folding: + title: Metrics + enabled: false + description: "" + availability: [] + scopes: + - name: disk + description: "" + labels: [] + metrics: + - name: ioping.latency + description: Read Latency + unit: "microseconds" + chart_type: line + dimensions: + - name: latency |