pro-bing

When using HTTPCaller, you can control the load applied to the target using two primary options:

• callFrequency: Sets how often calls are made.
• maxConcurrentCalls: Sets the maximum number of concurrent requests.

If you set a callFrequency that cannot be met, you may need to increase maxConcurrentCalls. Note that the logic within your callbacks can also impact execution performance.

On Linux, pro-bing attempts to use unprivileged UDP pings. To allow this, you must enable the ping_group_range sysctl:

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

Alternatively, you can use privileged raw sockets by:

1. Calling pinger.SetPrivileged(true) in your Go code.
2. Granting the capability to your binary using setcap or running as root:

setcap cap_net_raw=+ep /path/to/your/compiled/binary

Additional Linux Features:

• Socket Marking: Use pinger.SetMark(int) to set the SO_MARK option (requires CAP_NET_ADMIN).
• Don't Fragment: Use pinger.SetDoNotFragment(true) to set the 'Don't Fragment' bit.

To use the library in your Go projects, use go get to add it to your dependencies:

go get -u github.com/prometheus-community/pro-bing

To install the native Go ping executable binary, run:

go get -u github.com/prometheus-community/pro-bing/...
$GOPATH/bin/ping

The TraceSuite struct is passed to all lifecycle callbacks. It provides thread-safe access to timestamps for various stages of the HTTP request. You can use these to calculate latencies for specific parts of the network stack.

Timing Methods:

• GetGeneralStart() / GetGeneralEnd()
• GetDNSStart() / GetDNSEnd()
• GetConnStart() / GetConnEnd()
• GetTLSStart() / GetTLSEnd()
• GetWroteHeaders()
• GetFirstByteReceived()

Additionally, TraceSuite contains an Extra any field that allows you to pass custom data between callbacks.

// Example: measuring DNS latency in a callback
caller := probing.NewHTTPCaller("https://example.com",
    probing.WithHTTPCallerOnDNSDone(func(suite *probing.TraceSuite, info httptrace.DNSDoneInfo) {
    	dnsLatency := suite.GetDNSEnd().Sub(suite.GetDNSStart())
    fmt.Printf("DNS lookup took: %v\n", dnsLatency)
    }),
)

On Windows, you must call pinger.SetPrivileged(true). Failure to do so will result in the following error:

socket: The requested protocol has not been configured into the system, or no implementation for it exists.

Note: Accessing packet TTL values is not supported on Windows due to limitations in the Go x/net/ipv4 and x/net/ipv6 packages.

Use probing.NewPinger to initialize a pinger for a specific host. You can set the Count of packets to send and then call Run(), which blocks until the process is complete. After Run() returns, you can retrieve statistics using Statistics().

pinger, err := probing.NewPinger("www.google.com")
if err != nil {
	panic(err)
}
pinger.Count = 3
err = pinger.Run() // Blocks until finished.
if err != nil {
	panic(err)
}
stats := pinger.Statistics() // get send/receive/duplicate/rtt stats

The library supports HTTP probing via probing.NewHTTPCaller. This allows you to monitor HTTP endpoint availability and latency. You can configure the caller using functional options like WithHTTPCallerCallFrequency and WithHTTPCallerOnResp.

httpCaller := probing.NewHTTPCaller("https://www.google.com",
    probing.WithHTTPCallerCallFrequency(time.Second),
    probing.WithHTTPCallerOnResp(func(suite *probing.TraceSuite, info *probing.HTTPCallInfo) {
        fmt.Printf("got resp, status code: %d, latency: %s\n",
            info.StatusCode,
            suite.GetGeneralEnd().Sub(suite.GetGeneralStart()),
        )
    }),
)

// To stop the caller, call:
// httpCaller.Stop()

httpCaller.Run()

To perform a basic ping, set the Count field to the number of packets you wish to send, and call Run(). Note that Run() is a blocking function.

pinger, err := probing.NewPinger("www.google.com")
if err != nil {
	panic(err)
}
pinger.Count = 3
err = pinger.Run() // blocks until finished
if err != nil {
	panic(err)
}
stats := pinger.Statistics() // get send/receive/rtt stats