happyDomain/checker-ping
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Initial commit

Browse source
This commit is contained in:
nemunaire 2026-04-08 01:46:37 +07:00
commit a2ebf17774
15 changed files with 1041 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

159
checker/collect.go Normal file
View file

@ -0,0 +1,159 @@
// This file is part of the happyDomain (R) project.
// Copyright (c) 2020-2026 happyDomain
// Authors: Pierre-Olivier Mercier, et al.
//
// This program is offered under a commercial and under the AGPL license.
// For commercial licensing, contact us at <contact@happydomain.org>.
//
// For AGPL licensing:
// This program is free software: you can redistribute it and/or modify
// it under the terms of the GNU Affero General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU Affero General Public License for more details.
//
// You should have received a copy of the GNU Affero General Public License
// along with this program. If not, see <https://www.gnu.org/licenses/>.
package checker
import (
"context"
"encoding/json"
"fmt"
"net"
"strings"
"time"
probing "github.com/prometheus-community/pro-bing"
sdk "git.happydns.org/checker-sdk-go/checker"
happydns "git.happydns.org/happyDomain/model"
"git.happydns.org/happyDomain/services/abstract"
)
// Collect performs ICMP ping and returns PingData.
// Addresses are resolved from opts: "addresses" ([]string), "address" (string),
// or "service" (*ServiceMessage of type abstract.Server).
func (p *pingProvider) Collect(ctx context.Context, opts sdk.CheckerOptions) (any, error) {
addresses, err := resolveAddresses(opts)
if err != nil {
return nil, err
}
count := sdk.GetIntOption(opts, "count", 5)
if count < 1 {
count = 1
}
if count > 20 {
count = 20
}
data := &PingData{}
var errs []string
for _, addr := range addresses {
pinger, err := probing.NewPinger(addr)
if err != nil {
errs = append(errs, fmt.Sprintf("failed to create pinger for %s: %v", addr, err))
continue
}
pinger.Count = count
pinger.Timeout = time.Duration(count)*time.Second + 5*time.Second
if p.Privileged {
pinger.SetPrivileged(true)
}
if err = pinger.RunWithContext(ctx); err != nil {
errs = append(errs, fmt.Sprintf("ping failed for %s: %v", addr, err))
continue
}
stats := pinger.Statistics()
data.Targets = append(data.Targets, PingTargetResult{
Address: addr,
RTTMin: float64(stats.MinRtt.Microseconds()) / 1000.0,
RTTAvg: float64(stats.AvgRtt.Microseconds()) / 1000.0,
RTTMax: float64(stats.MaxRtt.Microseconds()) / 1000.0,
PacketLoss: stats.PacketLoss,
Sent: stats.PacketsSent,
Received: stats.PacketsRecv,
})
}
if len(data.Targets) == 0 {
return nil, fmt.Errorf("all pings failed: %s", strings.Join(errs, "; "))
}
return data, nil
}
// resolveAddresses extracts target IP addresses from the options.
func resolveAddresses(opts sdk.CheckerOptions) ([]string, error) {
// Direct addresses (from HTTP server).
if v, ok := opts["addresses"]; ok {
switch addrs := v.(type) {
case []any:
var result []string
for _, a := range addrs {
if s, ok := a.(string); ok && s != "" {
result = append(result, s)
}
}
if len(result) > 0 {
return result, nil
}
case []string:
if len(addrs) > 0 {
return addrs, nil
}
}
}
// Single address.
if v, ok := opts["address"]; ok {
if s, ok := v.(string); ok && s != "" {
return []string{s}, nil
}
}
// From auto-filled service (plugin provider path or HTTP JSON).
if svc, ok := sdk.GetOption[happydns.ServiceMessage](opts, "service"); ok {
if svc.Type != "abstract.Server" {
return nil, fmt.Errorf("service is %s, expected abstract.Server", svc.Type)
}
ips := ipsFromService(&svc)
if len(ips) > 0 {
addrs := make([]string, len(ips))
for i, ip := range ips {
addrs[i] = ip.String()
}
return addrs, nil
}
return nil, fmt.Errorf("no IP addresses found in the service")
}
return nil, fmt.Errorf("no addresses provided: set 'addresses', 'address', or 'service' in options")
}
func ipsFromService(svc *happydns.ServiceMessage) []net.IP {
var server abstract.Server
if err := json.Unmarshal(svc.Service, &server); err != nil {
return nil
}
var ips []net.IP
if server.A != nil && len(server.A.A) > 0 {
ips = append(ips, server.A.A)
}
if server.AAAA != nil && len(server.AAAA.AAAA) > 0 {
ips = append(ips, server.AAAA.AAAA)
}
return ips
}

102
checker/definition.go Normal file
View file

@ -0,0 +1,102 @@
// This file is part of the happyDomain (R) project.
// Copyright (c) 2020-2026 happyDomain
// Authors: Pierre-Olivier Mercier, et al.
//
// This program is offered under a commercial and under the AGPL license.
// For commercial licensing, contact us at <contact@happydomain.org>.
//
// For AGPL licensing:
// This program is free software: you can redistribute it and/or modify
// it under the terms of the GNU Affero General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU Affero General Public License for more details.
//
// You should have received a copy of the GNU Affero General Public License
// along with this program. If not, see <https://www.gnu.org/licenses/>.
package checker
import (
"time"
happydns "git.happydns.org/checker-sdk-go/checker"
)
// Version is the checker version reported in CheckerDefinition.Version.
//
// It defaults to "built-in", which is appropriate when the checker package is
// imported directly (built-in or plugin mode). Standalone binaries (like
// main.go) should override this from their own Version variable at the start
// of main(), which makes it easy for CI to inject a version with a single
// -ldflags "-X main.Version=..." flag instead of targeting the nested
// package path.
var Version = "built-in"
// Definition returns the CheckerDefinition for the ping checker.
func Definition() *happydns.CheckerDefinition {
return &happydns.CheckerDefinition{
ID: "ping",
Name: "Ping (ICMP)",
Version: Version,
Availability: happydns.CheckerAvailability{
ApplyToService: true,
LimitToServices: []string{"abstract.Server"},
},
ObservationKeys: []happydns.ObservationKey{ObservationKeyPing},
Options: happydns.CheckerOptionsDocumentation{
UserOpts: []happydns.CheckerOptionDocumentation{
{
Id: "warningRTT",
Type: "number",
Label: "Warning RTT threshold (ms)",
Default: float64(100),
},
{
Id: "criticalRTT",
Type: "number",
Label: "Critical RTT threshold (ms)",
Default: float64(500),
},
{
Id: "warningPacketLoss",
Type: "number",
Label: "Warning packet loss threshold (%)",
Default: float64(10),
},
{
Id: "criticalPacketLoss",
Type: "number",
Label: "Critical packet loss threshold (%)",
Default: float64(50),
},
{
Id: "count",
Type: "uint",
Label: "Number of pings to send",
Default: float64(5),
},
},
ServiceOpts: []happydns.CheckerOptionDocumentation{
{
Id: "service",
Label: "Service",
AutoFill: happydns.AutoFillService,
},
},
},
Rules: []happydns.CheckRule{
Rule(),
},
Interval: &happydns.CheckIntervalSpec{
Min: 1 * time.Minute,
Max: 1 * time.Hour,
Default: 5 * time.Minute,
},
HasMetrics: true,
}
}

89
checker/evaluate.go Normal file
View file

@ -0,0 +1,89 @@
// This file is part of the happyDomain (R) project.
// Copyright (c) 2020-2026 happyDomain
// Authors: Pierre-Olivier Mercier, et al.
//
// This program is offered under a commercial and under the AGPL license.
// For commercial licensing, contact us at <contact@happydomain.org>.
//
// For AGPL licensing:
// This program is free software: you can redistribute it and/or modify
// it under the terms of the GNU Affero General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU Affero General Public License for more details.
//
// You should have received a copy of the GNU Affero General Public License
// along with this program. If not, see <https://www.gnu.org/licenses/>.
package checker
import (
"fmt"
"strings"
"time"
)
// Metrics extracts time-series metrics from ping data.
func Metrics(data *PingData, collectedAt time.Time) []Metric {
var metrics []Metric
for _, t := range data.Targets {
labels := map[string]string{"address": t.Address}
metrics = append(metrics,
Metric{Name: "ping_rtt_avg", Value: t.RTTAvg, Unit: "ms", Labels: labels, Timestamp: collectedAt},
Metric{Name: "ping_rtt_min", Value: t.RTTMin, Unit: "ms", Labels: labels, Timestamp: collectedAt},
Metric{Name: "ping_rtt_max", Value: t.RTTMax, Unit: "ms", Labels: labels, Timestamp: collectedAt},
Metric{Name: "ping_packet_loss", Value: t.PacketLoss, Unit: "%", Labels: labels, Timestamp: collectedAt},
Metric{Name: "ping_packets_sent", Value: float64(t.Sent), Unit: "count", Labels: labels, Timestamp: collectedAt},
Metric{Name: "ping_packets_received", Value: float64(t.Received), Unit: "count", Labels: labels, Timestamp: collectedAt},
)
}
return metrics
}
// Metric represents a single time-series metric.
type Metric struct {
Name string `json:"name"`
Value float64 `json:"value"`
Unit string `json:"unit,omitempty"`
Labels map[string]string `json:"labels,omitempty"`
Timestamp time.Time `json:"timestamp"`
}
// EvaluateResult holds the evaluation outcome.
type EvaluateResult struct {
Status int `json:"status"`
Message string `json:"message"`
Code string `json:"code"`
}
const (
StatusOK = 1
StatusWarn = 3
StatusCrit = 4
)
// Evaluate checks the ping data against the given thresholds.
func Evaluate(data *PingData, warningRTT, criticalRTT, warningPacketLoss, criticalPacketLoss float64) EvaluateResult {
overallStatus := StatusOK
var summaryParts []string
for _, target := range data.Targets {
if target.PacketLoss >= criticalPacketLoss || target.RTTAvg >= criticalRTT {
overallStatus = StatusCrit
} else if (target.PacketLoss >= warningPacketLoss || target.RTTAvg >= warningRTT) && overallStatus < StatusWarn {
overallStatus = StatusWarn
}
summaryParts = append(summaryParts, fmt.Sprintf("%s: %.1fms avg, %.0f%% loss", target.Address, target.RTTAvg, target.PacketLoss))
}
return EvaluateResult{
Status: overallStatus,
Message: strings.Join(summaryParts, " | "),
Code: "ping_result",
}
}

74
checker/provider.go Normal file
View file

@ -0,0 +1,74 @@
// This file is part of the happyDomain (R) project.
// Copyright (c) 2020-2026 happyDomain
// Authors: Pierre-Olivier Mercier, et al.
//
// This program is offered under a commercial and under the AGPL license.
// For commercial licensing, contact us at <contact@happydomain.org>.
//
// For AGPL licensing:
// This program is free software: you can redistribute it and/or modify
// it under the terms of the GNU Affero General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU Affero General Public License for more details.
//
// You should have received a copy of the GNU Affero General Public License
// along with this program. If not, see <https://www.gnu.org/licenses/>.
package checker
import (
"encoding/json"
"time"
happydns "git.happydns.org/checker-sdk-go/checker"
)
// Provider returns a new ping observation provider for local execution.
func Provider() happydns.ObservationProvider {
return &pingProvider{}
}
// ProviderWithPrivileged returns a provider with privileged ICMP mode enabled.
func ProviderWithPrivileged(privileged bool) happydns.ObservationProvider {
return &pingProvider{Privileged: privileged}
}
type pingProvider struct {
// Privileged controls whether raw ICMP sockets are used (requires CAP_NET_RAW or root).
Privileged bool
}
func (p *pingProvider) Key() happydns.ObservationKey {
return ObservationKeyPing
}
// Definition implements happydns.CheckerDefinitionProvider.
func (p *pingProvider) Definition() *happydns.CheckerDefinition {
return Definition()
}
// ExtractMetrics implements happydns.CheckerMetricsReporter.
func (p *pingProvider) ExtractMetrics(raw json.RawMessage, collectedAt time.Time) ([]happydns.CheckMetric, error) {
var data PingData
if err := json.Unmarshal(raw, &data); err != nil {
return nil, err
}
metrics := Metrics(&data, collectedAt)
result := make([]happydns.CheckMetric, len(metrics))
for i, m := range metrics {
result[i] = happydns.CheckMetric{
Name: m.Name,
Value: m.Value,
Unit: m.Unit,
Labels: m.Labels,
Timestamp: m.Timestamp,
}
}
return result, nil
}

146
checker/rule.go Normal file
View file

@ -0,0 +1,146 @@
// This file is part of the happyDomain (R) project.
// Copyright (c) 2020-2026 happyDomain
// Authors: Pierre-Olivier Mercier, et al.
//
// This program is offered under a commercial and under the AGPL license.
// For commercial licensing, contact us at <contact@happydomain.org>.
//
// For AGPL licensing:
// This program is free software: you can redistribute it and/or modify
// it under the terms of the GNU Affero General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU Affero General Public License for more details.
//
// You should have received a copy of the GNU Affero General Public License
// along with this program. If not, see <https://www.gnu.org/licenses/>.
package checker
import (
"context"
"fmt"
sdk "git.happydns.org/checker-sdk-go/checker"
)
// Rule returns a new ping check rule for local evaluation.
func Rule() sdk.CheckRule {
return &pingRule{}
}
type pingRule struct{}
func (r *pingRule) Name() string { return "ping_check" }
func (r *pingRule) Description() string {
return "Checks ICMP ping reachability, round-trip time, and packet loss"
}
func (r *pingRule) ValidateOptions(opts sdk.CheckerOptions) error {
warningRTT := float64(100)
criticalRTT := float64(500)
warningPacketLoss := float64(10)
criticalPacketLoss := float64(50)
if v, ok := opts["warningRTT"]; ok {
d, ok := v.(float64)
if !ok {
return fmt.Errorf("warningRTT must be a number")
}
if d <= 0 {
return fmt.Errorf("warningRTT must be positive")
}
warningRTT = d
}
if v, ok := opts["criticalRTT"]; ok {
d, ok := v.(float64)
if !ok {
return fmt.Errorf("criticalRTT must be a number")
}
if d <= 0 {
return fmt.Errorf("criticalRTT must be positive")
}
criticalRTT = d
}
if v, ok := opts["warningPacketLoss"]; ok {
d, ok := v.(float64)
if !ok {
return fmt.Errorf("warningPacketLoss must be a number")
}
if d < 0 || d > 100 {
return fmt.Errorf("warningPacketLoss must be between 0 and 100")
}
warningPacketLoss = d
}
if v, ok := opts["criticalPacketLoss"]; ok {
d, ok := v.(float64)
if !ok {
return fmt.Errorf("criticalPacketLoss must be a number")
}
if d < 0 || d > 100 {
return fmt.Errorf("criticalPacketLoss must be between 0 and 100")
}
criticalPacketLoss = d
}
if v, ok := opts["count"]; ok {
d, ok := v.(float64)
if !ok {
return fmt.Errorf("count must be a number")
}
if d < 1 || d > 20 {
return fmt.Errorf("count must be between 1 and 20")
}
}
if criticalRTT <= warningRTT {
return fmt.Errorf("criticalRTT (%v) must be greater than warningRTT (%v)", criticalRTT, warningRTT)
}
if criticalPacketLoss <= warningPacketLoss {
return fmt.Errorf("criticalPacketLoss (%v) must be greater than warningPacketLoss (%v)", criticalPacketLoss, warningPacketLoss)
}
return nil
}
func (r *pingRule) Evaluate(ctx context.Context, obs sdk.ObservationGetter, opts sdk.CheckerOptions) sdk.CheckState {
var data PingData
if err := obs.Get(ctx, ObservationKeyPing, &data); err != nil {
return sdk.CheckState{
Status: sdk.StatusError,
Message: fmt.Sprintf("Failed to get ping data: %v", err),
Code: "ping_error",
}
}
warningRTT := sdk.GetFloatOption(opts, "warningRTT", 100)
criticalRTT := sdk.GetFloatOption(opts, "criticalRTT", 500)
warningPacketLoss := sdk.GetFloatOption(opts, "warningPacketLoss", 10)
criticalPacketLoss := sdk.GetFloatOption(opts, "criticalPacketLoss", 50)
result := Evaluate(&data, warningRTT, criticalRTT, warningPacketLoss, criticalPacketLoss)
var status sdk.Status
switch result.Status {
case StatusOK:
status = sdk.StatusOK
case StatusWarn:
status = sdk.StatusWarn
case StatusCrit:
status = sdk.StatusCrit
default:
status = sdk.StatusUnknown
}
return sdk.CheckState{
Status: status,
Message: result.Message,
Code: result.Code,
Meta: map[string]any{
"targets": data.Targets,
},
}
}

41
checker/types.go Normal file
View file

@ -0,0 +1,41 @@
// This file is part of the happyDomain (R) project.
// Copyright (c) 2020-2026 happyDomain
// Authors: Pierre-Olivier Mercier, et al.
//
// This program is offered under a commercial and under the AGPL license.
// For commercial licensing, contact us at <contact@happydomain.org>.
//
// For AGPL licensing:
// This program is free software: you can redistribute it and/or modify
// it under the terms of the GNU Affero General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU Affero General Public License for more details.
//
// You should have received a copy of the GNU Affero General Public License
// along with this program. If not, see <https://www.gnu.org/licenses/>.
package checker
// ObservationKeyPing is the observation key for ICMP ping data.
const ObservationKeyPing = "ping"
// PingData holds the collected ping results for all targets.
type PingData struct {
Targets []PingTargetResult `json:"targets"`
}
// PingTargetResult contains the ping statistics for a single IP address.
type PingTargetResult struct {
Address string `json:"address"`
RTTMin float64 `json:"rtt_min"`
RTTAvg float64 `json:"rtt_avg"`
RTTMax float64 `json:"rtt_max"`
PacketLoss float64 `json:"packet_loss"`
Sent int `json:"sent"`
Received int `json:"received"`
}