.\" $Id: pingstats.man,v 1.5 2012/02/29 18:45:36 ksb Exp $
.\" by Kevin Braunsdorf
.\" $Compile: Display%h
.\" $Display: ${nroff-groff} -Tascii -man %f | ${PAGER:-less}
.\" $Install: %b -mDeinstall %o %f && cp %f $DESTDIR/usr/local/man/man8/pingstats.8
.\" $Deinstall: ${rm-rm} -f $DESTDIR/usr/local/man/[cm]a[nt]8/pingstats.8*
.TH PINGSTATS 8 LOCAL
.SH NAME
pingstats - report lost frames, ttl, and round trip time to PEG for a network peer
.SH SYNOPSIS
.ds PN "pingstats
\fI\*(PN\fP [\fB\-dx\fP] [\fB\-N\fP\~\fInode\fP] [\fB\-O\fP\~\fIadmin\fP] [\fB\-p\fP\~\fIdelay\fP] [\fB\-R\fP\~\fItarget\fP] [\fB\-S\fP\~\fIsuffix\fP] [\fB\-T\fP\~\fItoplevel\fP] [\fB\-X\fP\~\fIas\fP] [\fIpeg\fP][:\fIport\fP]
.br
\fI\*(PN\fP \fB\-h\fP
.br
\fI\*(PN\fP \fB\-V\fP

.SH DESCRIPTION
The performance and engineering site accepts 3 simple ping peer
server statistics under the \fBping.cvu\fP RRD type.  This program
sends those data sources to PEG.
.P
If you need to report under a difference hostname (or VIP name)
use the \fB\-N\fP option to change the effective hostname, or
the other options to modify the hostname.
.P
If you have more than one link partner use \fB\-X\fP to label
each metric RRD file.  The default file is "ping.rrd".
By provisioning \fB\-X\fP \fBlv426\fP we change the name to
"pinglv426.rrd", so PEG presents a more meaningful name.


.SH OPTIONS
No options are forced when the program is called "pingstats".
.TP
\fB\-d\fP
Display RRD path only.
.TP
\fB\-h\fP
Print a brief help message.
.TP
\fB\-N\fP \fInode\fP
Use this node name, rather than our hostname whittled.
.TP
\fB\-O\fP \fIadmin\fP
Set the local administrators department suffix.  This suffix is removed
from the hostname sent to PEG.
.TP
\fB\-p\fP \fIdelay\fP
Update persistantly, about every \fIdelay\fP seconds.  The default is
60 seconds.
.TP
\fB\-S\fP \fIsuffix\fP
Remove this suffix after \fItoplevel\fP, if present.
.TP
\fB\-T\fP \fItoplevel\fP
Remove this from the end of our hostname before it is sent to PEG.
.TP
\fB\-V\fP
Output only the standard version information.
.TP
\fB\-x\fP
Trace updates on \fIstderr\fP.
.TP
\fB\-X\fP \fIas\fP
Report \fIas\fP on the end of the basename of the RRD file on PEG.
.TP
\fIpeg\fP
Sample collection host, running \fBrrdd\fP(8l).
.TP
\fIport\fP
Rrdd update port (otherwise 31415).

.SH EXAMPLES
.TP
daemon \-cf /usr/local/libexec/pingstats \-p 105 \-R mypeer.example.com
Update the PEG instance at the default site (\fBpeg.sac.fedex.com\fP)
with metrics for \fBmypeer.example.com\fP every 105 seconds, from background.
.TP
/usr/local/libexec/pingstats \-p 74 \-R myserv.example.com \-X NFS
Update the default PEG instance with stats from \fBmyserv.example.com\fP
every 74 seconds, reporting it under "pingNFS.rrd" rather than the
default "ping.rrd".  Run in foreground.

.SH BUGS
The code is pretty specific to the version of \fBping\fP, which
must support \fB\-i\fP.
.P
If you name the file something other than "ping.rrd" you \fBmust\fP
build a link to the ping.cvu file by the name provided.  For the file
named latency.rrd run:
.RS
.nf
ln \-s /var/peg/lib/cvu/ping.cvu latency.cvu
.fi
.RE

.SH AUTHORS
Kevin Braunsdorf, NPC Guild
.br
peg within-no_spamming-hat ksb.npcguild.org

.SH "SEE ALSO"
sh(1), rrdup(1l), ping(8), rrdd(8l)