src/go/plugin/go.d/modules/portcheck/metadata.yaml
plugin_name: go.d.plugin
modules:
- meta:
id: collector-go.d.plugin-portcheck
plugin_name: go.d.plugin
module_name: portcheck
monitored_instance:
name: TCP/UDP Endpoints
link: ""
icon_filename: globe.svg
categories:
- data-collection.synthetic-checks
keywords: []
related_resources:
integrations:
list: []
info_provided_to_referring_integrations:
description: ""
most_popular: false
overview:
data_collection:
metrics_description: |
Collector for monitoring service availability and response time. It can be used to check if specific ports are open or reachable on a target system.
It supports both TCP and UDP protocols over IPv4 and IPv6 networks.
| Protocol | Check Description |
|----------|-----------------------------------------------------------------------------------------------------------------------------|
| TCP | Attempts to establish a TCP connection to the specified ports on the target system. |
| UDP | Sends a 0-byte UDP packet to the specified ports on the target system and analyzes ICMP responses to determine port status. |
Possible TCP statuses:
| TCP Status | Description |
|------------|-------------------------------------------------------------|
| success | Connection established successfully. |
| timeout | Connection timed out after waiting for configured duration. |
| failed | An error occurred during the connection attempt. |
Possible UDP statuses:
| UDP Status | Description |
|---------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| open/filtered | No response received within the configured timeout. This status indicates the port is either open or filtered, but the exact state cannot be determined definitively. |
| closed | Received an ICMP Destination Unreachable message, indicating the port is closed. |
method_description: ""
supported_platforms:
include: []
exclude: []
multi_instance: true
additional_permissions:
description: ""
default_behavior:
auto_detection:
description: ""
limits:
description: ""
performance_impact:
description: ""
setup:
prerequisites:
list: []
configuration:
file:
name: go.d/portcheck.conf
options:
description: |
The following options can be defined globally: update_every, autodetection_retry.
folding:
title: Config options
enabled: true
list:
- name: update_every
description: Data collection frequency.
default_value: 5
required: false
- name: autodetection_retry
description: Recheck interval in seconds. Zero means no recheck will be scheduled.
default_value: 0
required: false
- name: host
description: Remote host address in IPv4, IPv6 format, or DNS name.
default_value: ""
required: true
- name: ports
description: Target TCP ports. Must be specified in numeric format.
default_value: ""
required: false
- name: udp_ports
description: Target UDP ports. Must be specified in numeric format.
default_value: ""
required: false
- name: timeout
description: HTTP request timeout.
default_value: 2
required: false
examples:
folding:
title: Config
enabled: true
list:
- name: Check TCP ports (IPv4)
description: An example configuration.
config: |
jobs:
- name: local
host: 127.0.0.1
ports:
- 22
- 23
- name: Check TCP ports (IPv6)
description: An example configuration.
config: |
jobs:
- name: local
host: "[2001:DB8::1]"
ports:
- 80
- 8080
- name: Check UDP ports (IPv4)
description: An example configuration.
config: |
jobs:
- name: local
host: 127.0.0.1
udp_ports:
- 3120
- 3121
- name: Check UDP ports (IPv6)
description: An example configuration.
config: |
jobs:
- name: local
host: [::1]
udp_ports:
- 3120
- 3121
- name: Multi-instance
description: |
> **Note**: When you define multiple jobs, their names must be unique.
Multiple instances.
config: |
jobs:
- name: server1
host: 127.0.0.1
ports:
- 22
- 23
- name: server2
host: 203.0.113.10
ports:
- 22
- 23
troubleshooting:
problems:
list: []
alerts:
- name: portcheck_service_reachable
metric: portcheck.status
info: "TCP host ${label:host} port ${label:port} liveness status"
link: https://github.com/netdata/netdata/blob/master/src/health/health.d/portcheck.conf
- name: portcheck_connection_timeouts
metric: portcheck.status
info: "percentage of timed-out TCP connections to host ${label:host} port ${label:port} in the last 5 minutes"
link: https://github.com/netdata/netdata/blob/master/src/health/health.d/portcheck.conf
- name: portcheck_connection_fails
metric: portcheck.status
info: "percentage of failed TCP connections to host ${label:host} port ${label:port} in the last 5 minutes"
link: https://github.com/netdata/netdata/blob/master/src/health/health.d/portcheck.conf
metrics:
folding:
title: Metrics
enabled: false
description: ""
availability: []
scopes:
- name: TCP endpoint
description: These metrics refer to the TCP endpoint.
labels:
- name: host
description: The hostname or IP address of the target system, as specified in the configuration.
- name: port
description: The TCP port being monitored, as defined in the 'ports' configuration parameter.
metrics:
- name: portcheck.status
description: TCP Check Status
unit: boolean
chart_type: line
dimensions:
- name: success
- name: failed
- name: timeout
- name: portcheck.state_duration
description: Current State Duration
unit: seconds
chart_type: line
dimensions:
- name: time
- name: portcheck.latency
description: TCP Connection Latency
unit: ms
chart_type: line
dimensions:
- name: time
- name: UDP endpoint
description: These metrics refer to the UDP endpoint.
labels:
- name: host
description: The hostname or IP address of the target system, as specified in the configuration.
- name: port
description: The UDP port being monitored, as defined in the 'udp_ports' configuration parameter.
metrics:
- name: portcheck.udp_port_status
description: UDP Port Check Status
unit: status
chart_type: line
dimensions:
- name: open/filtered
- name: closed
- name: portcheck.udp_port_status_duration
description: UDP Port Current Status Duration
unit: seconds
chart_type: line
dimensions:
- name: time