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
138
139
140
141
|
.TH TALLYMAN 1 "August 14, 2019" "TALLYMAN" "Tallyman User Reference"
.SH NAME
tallyman \- health state collector for docker containers
.SH SYNOPSIS
.na
.nh
\fBtallyman\fR\
[\fB\-dq\fR]\
[\fB\-h\fR \fINAME\fR]\
[\fB\-s\fR \fIHOST:PORT\fR]\
[\fB\-v\fR \fIJSON\fR]\
[\fB\-\-connection\-timeout=\fISECONDS\fR]\
[\fB\-\-debug\fR]\
[\fB\-\-execution\-timeout=\fISECONDS\fR]\
[\fB\-\-hostname=\fINAME\fR]\
[\fB\-\-quiet\fR]\
[\fB\-\-server=\fIHOST:PORT\fR]\
[\fB\-\-value=\fIJSON\fR]\
\fISRVID\fR\
\fICOMMAND\fR\
\fIARGS\fR...
.sp
\fBtallyman\fR\
\fB\-?\fR |\
\fB\-\-help\fR |\
\fB\-V\fR |\
\fB\-\-version\fR
.ad
.hy
.SH DESCRIPTION
Runs \fICOMMAND\fR with \fIARGS\fR and sends its return code, standard
output and error to the remote data collector. Exits with the exit
status of \fICOMMAND\fR.
.PP
The program must be configured to run periodically via the
.B HEALTHCHECK CMD
statement in the
.BR Dockerfile .
.PP
It is supposed that each container is responsible for certain
.IR service .
Each service is assigned a name. Multiple containers can run
the same service (for example you can have several database
containers).
.PP
Containers are configured to run
.B tallyman
as their
.B HEALTHCHECK
command. The
.I SRVID
argument supplies the name of the service the container is responsible
for. The \fICOMMAND\fR and optional additional arguments supply the
name of the actual health-checking program and its command line
arguments.
.B Tallyman
will run this command, collect its standard error and standard output,
pack them along with the program exit code in a JSON packet, and send
this packet to the predefined address using HTTP POST request. It will
then exit with the same code as the health-checking program it ran. To
the container, the effect of running
.B tallyman
is the same as if it ran the health-checking program itself: error
code, standard error and standard output are all preserved. On the
other hand, they are copied to the collector listening on the
predefined address outside the container.
.PP
The data collector program
.BR stevedore (8)
must be listening at \fIHOST:PORT\fR. See its manual for
details.
.PP
In the absense of the
.B \-s
option,
.B tallyman
will send statistics to the container's default gateway, port 8990.
.SS Diagnostics
The program attempts to be as transparent as it is reasonable. It
will display diagnostic messages on the standard error if it is
unable to connect to the collector or if the communication with it
does not succeed, or if the
.I COMMAND
terminates on signal. If it terminates with a non-zero exit status
a diagnostic message to this effect will be displayed only if the
program did not print any messages to the standard error on its own.
.SH OPTIONS
.TP
\fB\-d\fR, \fB\-\-debug\fR
Increase debug verbosity.
.TP
\fB\-h\fR, \fB\-\-hostname=\fINAME\fR
Set this server hostname. By default it is determined automatically.
.TP
\fB\-q\fR, \fB\-\-quiet\fR
By default, \fBtallyman\fR would transparently pass \fICOMMAND\fR's
stdout and stderr to the corresponding streams. A single \fB\-q\fR
option suppresses reproducing the stdout. Two \fB\-q\fR options
suppress both stdout and stderr.
.TP
\fB\-s\fR, \fB\-\-server=\fIHOST:PORT\fR
Address and port of the data collector. Default is \fIGW\fR:8990,
where \fIGW\fR is the default gateway of the container.
.TP
\fB\-v\fR, \fB\-\-value=\fIJSON\fR
Add \fIJSON\fR object to each report.
.TP
\fB\-\-connection\-timeout=\fISECONDS\fR
Set timeout for initial connection to the collector. Default is 5 seconds.
.TP
\fB\-\-execution\-timeout=\fISECONDS\fR
Set \fICOMMAND\fR execution timeout. Default is 5 seconds.
.TP
\fB\-?\fR, \fB\-\-help\fR
Display short help text and exit.
.TP
\fB\-V\fR, \fB\-\-version\fR
Display program version and licensing information and exit.
.SH "SEE ALSO"
.BR stevedore (8).
.SH AUTHORS
Sergey Poznyakoff
.SH "BUG REPORTS"
Report bugs to <gray@gnu.org>.
.SH COPYRIGHT
Copyright \(co 2018\-2019 Sergey Poznyakoff
.br
.na
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
.br
.ad
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
.\" Local variables:
.\" eval: (add-hook 'write-file-hooks 'time-stamp)
.\" time-stamp-start: ".TH [A-Z_][A-Z0-9_.\\-]* [0-9] \""
.\" time-stamp-format: "%:B %:d, %:y"
.\" time-stamp-end: "\""
.\" time-stamp-line-limit: 20
.\" end:
|
