forked from circonus-labs/nad
-
Notifications
You must be signed in to change notification settings - Fork 0
/
nad.8
137 lines (135 loc) · 4.02 KB
/
nad.8
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
.TH nad 8 "March 20, 2011" "version 1.0"
.SH NAME
nad \- node\-agent daemon
.SH SYNOPSIS
.B nad
[\-h] [\-i] [\-c configdir] [\-p [ip:]port] [\-s [ip:]sslport] [\-v]
.SH DESCRIPTION
The node\-agent daemon provides a simple mechanism to expose
systems and application metrics to external onlookers. It
inventories all executable programs in
.I configdir
and executes them upon external request (via http or https)
and returns the results in JSON format.
.PP
It is recommended that executable checks be stored in subdirectories
of the
.I configdir.
Because those subdirectories are not scanned, those
scripts will not be executed with an additional step. Those scripts
that the administrator wishes activated can be soft linked directly
within
.I configdir.
.PP
No arguments are accepted from the onlooker and thus no special
precautions must be taken handling/validating/sanitizing arguments.
.PP
The daemon provides several locations for information:
.TP
/ and /run
cause execution and consolidation of all scripts and their output.
.TP
/run/scriptname
causes the executation of a single script (minus the extension on
script if it exists)
.TP
/inventory
returns the current active inventory of scripts.
.SH OPTIONS
.TP
\-h
Display the help text.
.TP
\-i
Display an inventory of plugins.
.TP
\-c <configdir>
Sets the configuration directory (home of scripts and SSL credentials).
.TP
\-p <port>
Sets the port (and IP) on which the HTTP server shall listen. (default 2609).
.TP
\-s <sslport>
Sets the port (and IP) on which the HTTPS server shall listen. If this option is
specified,
.I na.key
and
.I na.crt
must be present in the
.I configdir.
.TP
\-v
Causes the daemon to validate the connecting client's certificate against
the provided certificate authorities. A list of CA certificates must exist
in the
.I na.ca
file in the
.I configdir.
.SH SCRIPT OUTPUT
The executable programs that you place in the
.I configdir
must produce metrics to standard output. They may produce JSON output.
Alternatively, the may produce simple tab-separated metric output that
adheres to the folling format.
.TP
.I metric_name metric_type
Indicating the the metric specified has a null value.
.TP
.I metric_name metric_type value
Indicating the the metric specified has
.I value
.SS The metric_type
.PP
.B i
\- indicating a signed 32bit integer value,
.PP
.B I
\- indicating an unsigned 32bit integer value,
.PP
.B l
\- indicating a signed 64bit integer value,
.PP
.B L
\- indicating an unsigned 64bit integer value,
.PP
.B n
\- indicating a value to be represented as a double, or
.PP
.B s
\- indicating the the value is a string.
.SS Control Information
You may provide control information in a line starting with a #
character and followed by a JSON block. Currently,
.I
timeout
is the only parameter accepted and the argument is interpretted as
seconds. For example, to indicate that the script should be aborted if
a set of output metrics cannot be completed in 1.12 seconds:
.pf
# { "timeout": 1.12 }
.nf
.SS Continuous Output
Continuous output is supported by long-running scripts. After a set
of metrics is emitted to standard output, emit a single empty line.
nad will accept the previous metrics into a result set and return them
on the next request for data. The program can then pause for some
ad-hoc amount of time and produce another set of metrics followed by
a blank line. This mode can be useful for collectin information such
as mpstat or vmstat information.
.PP
Note, that in most cases if you can get raw accumulated counters
(instead of averages over some amount of time), that the output can
be more useful to monitoring applications as a derivative can be
applied after the fact without the risk of data loss.
.SS JSON format
If you elect to product JSON formatted output in your programs, you
must provide a JSON object whose keys have values that look so:
.pf
{ "_type": <metric_type>, "_value": "yourvalue" }
.nf
.SH BUGS
No known bugs, report bugs to Theo Schlossnagle <[email protected]>
.SH AUTHOR
Theo Schlossnagle ([email protected]).
.PP
Copyright (c) 2011, OmniTI Computer Consulting, Inc.