File: logapp.1

package info (click to toggle)
logapp 0.16-1
  • links: PTS, VCS
  • area: main
  • in suites: bullseye
  • size: 300 kB
  • sloc: ansic: 2,778; xml: 559; makefile: 192
file content (315 lines) | stat: -rw-r--r-- 21,434 bytes parent folder | download | duplicates (2)
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
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
.\" t -*- coding: us-ascii -*-
.if \n(.g .ds T< \\FC
.if \n(.g .ds T> \\F[\n[.fam]]
.de URL
\\$2 \(la\\$1\(ra\\$3
..
.if \n(.g .mso www.tmac
.TH logapp 1 "January 2011" "logapp 0.16svn" ""
.SH NAME
logapp \- An application output supervisor.
.SH SYNOPSIS
'nh
.fi
.ad l
\fBlogapp\fR \kx
.if (\nx>(\n(.l/2)) .nr x (\n(.l/5)
'in \n(.iu+\nxu
[\fIoption\fR]\&... \fIapplication\fR [\fB\-\-logapp_\fIoption\fB\fR]\&... [\fIapp.-argument\fR]\&...
'in \n(.iu-\nxu
.ad b
'hy
.PP
'nh
.fi
.ad l
\fBapplicationsymlink\fR \kx
.if (\nx>(\n(.l/2)) .nr x (\n(.l/5)
'in \n(.iu+\nxu
[\fB\-\-logapp_\fIoption\fB\fR]\&... [\fIapplication-argument\fR]\&...
'in \n(.iu-\nxu
.ad b
'hy
.PP
Instead of calling logapp directly you can also create a symlink with
the name of the application pointing to logapp. Logapp will automatically
start the application the name points to. It will also work if the
symlink name is prefixed with \fIlog\fR.
.SH DESCRIPTION
Logapp is a wrapper utility that helps supervise the execution of applications that produce heavy console output (e.g. make, CVS and Subversion). It does this by logging, trimming, and coloring each line of the output before displaying it. It can be called instead of the executable that should be monitored; it then starts the application and logs all of its console output to a file. The output shown in the terminal is preprocessed, e.g. to limit the length of printed lines and to show the stderr output in a different color. It is also possible to automatically highlight lines that match a certain regular expression. The output is therefore reduced to the necessary amount, and all important lines are easy to identify.
.SH OPTIONS
The options provided before the \fIapplication\fR argument are processed directly by logapp. Options provided after the \fIapplication\fR argument are only parsed if they are prefixed with \*(T<\fB\-\-logapp_\fR\*(T> (long option names only) otherwise they are passed to the application. If logapp is called via a symlink all unprefixed options are passed to the application.
.PP
Every application usually uses two independent output streams: \fIstdout\fR for normal output and \fIstderr\fR for errors and important messages. Both of them are handled independently by logapp, therefore many options are available for both streams.
.PP
Bool options are accepting \fI1/0\fR and \fItrue/false\fR as value. For long boolean options the value can be omitted, in that case it will be assumed to be 'true'.
.SS "GENERAL OPTIONS"
.TP 
\*(T<\fB\-?\fR\*(T>, \*(T<\fB\-\-help\fR\*(T>
Show a short overview over all available options.
.TP 
\*(T<\fB\-\-version\fR\*(T>
Show version information.
.TP 
\*(T<\fB\-\-configfile=\fR\*(T>\fIFILE\fR
Use a specific configuration file instead of searching the configuration search paths.
.TP 
\*(T<\fB\-\-showconfig\fR\*(T>
Print the current configuration of logapp and exit before the application is executed. This can be used this to check if all configuration options are setup correctly if something doesn't work as expected.
.TP 
\*(T<\fB\-\-configsection=\fR\*(T>\fINAME\fR
Enable a specific section in the configuration file. If this option is not provided the application name is used as default.
.TP 
\*(T<\fB\-\-disable\fR\*(T>
This disables logapp data handling completely. The application is still started, but logapp won't touch the data streams coming from the application. Neither logging nor output formating is performed, only the execution time and the exit state tracked. This is useful if logapp won't be able to deal with expected data correctly, for example when starting curses based applications. Have a look at \*(T<\fB\-\-disable_keywords\fR\*(T> to see how this option can be enabled automatically.
.TP 
\*(T<\fB\-\-disable_keywords=\fR\*(T>\fIkeywordlist\fR
With this option a list of comma separated keywords can be provided which will cause the \*(T<\fB\-\-disable\fR\*(T> to be enabled automatically if found in the applications option list. This is useful if an application usually provides line-based output, but creates binary data or uses a curses based frontend if called with a specific parameter. You can also use the \*(T<\fB\-\-detectescape\fR\*(T> option for another way to do this without disabling the logging functionality.
.TP 
\*(T<\fB\-\-detectescape=\fR\*(T>\fIbool\fR
This option can be used to switch escape-sequence detection on or off. With escape-sequence detection logapp will automatically enable char-based stream handling as soon as an escape-sequence is part of the specific stream. This behavior can be useful if you are working with an application that is usually line-based, but starts other applications which may be using escape sequences to format the screen. This option will prevent the terminal from being messed up in that case.
.TP 
\*(T<\fB\-\-dumbterm=\fR\*(T>\fIbool\fR
With this option set to true there will be no terminal output coloring for \fIstdout\fR and \fIstderr\fR. Normally this option is disabled and logapp tries to detect "dumb" terminals itself.
.TP 
\*(T<\fB\-\-usepty=\fR\*(T>\fIbool\fR
This option is only available if logapp has been compiled with PTY support. If PTY support is enabled with this option set to true, logapp will open a \fIpseudo terminal\fR for \fIstdout\fR. This helps wenn running logapp with applications that usually need a real terminal for output. You can disable this option for most line based applications like make, CVS or Subversion. Other applications like telnet or picocom may produce strange results when used without PTY support.
.TP 
\*(T<\fB\-\-ptyremovecr=\fR\*(T>\fIbool\fR
This option is only available if logapp has been compiled with PTY support. When using a pseudo terminal for getting the application output you will always get CR-LF line endings, which is usually not desired when working in UNIX environments. With this option enabled, logapp will automatically translate all CR-LF line endings in LF line endings. This option is enabled as default.
.TP 
\*(T<\fB\-\-stdout_blen=\fR\*(T>\fIbytes\fR
.TP 
\*(T<\fB\-\-stderr_blen=\fR\*(T>\fIbytes\fR
The line buffer size can be adjusted for \fIstdout\fR and \fIstderr\fR independently with this option. If the value is too small, lines will be split up if the buffer is full. The default is \fI2048 byte\fR which should be big enough for most applications.
.TP 
\*(T<\fB\-\-stdout_charbased=\fR\*(T>\fIbool\fR
.TP 
\*(T<\fB\-\-stderr_charbased=\fR\*(T>\fIbool\fR
If you want to use logapp with applications that do not produce line based output you can enable this options for \fIstdout\fR and \fIstderr\fR independently. With this option enabled logapp won't expect complete lines and will handle data as it comes in. By default all single data packets are written to a new line if this option is enabled, this can be changed with the \*(T<\fB\-\-alignlog\fR\*(T> option. If the result will be usable depends on what kind of data is generated by the application.
.TP 
\*(T<\fB\-\-extended\-regexp=\fR\*(T>\fIbool\fR
If this option is enabled logapp will interpret provided regular expression patterns as extended regular expressions. The default is to use basic regular expressions.
.SS "LOGGING OPTIONS"
This section contains options that affect the logfile.
.TP 
\*(T<\fB\-l\fR\*(T>, \*(T<\fB\-\-logfile=\fR\*(T>\fIfile\fR
This option can be used to change the file that is used for storing the logged application data. If an empty string is provided, logging is disabled and no logfile will be created. The default is that logapp creates a logfile called \fIlogapp.log\fR in the current directory.
.TP 
\*(T<\fB\-a\fR\*(T>, \*(T<\fB\-\-appendlog=\fR\*(T>\fIbool\fR
This option specifies if the logfile will be truncated or if the data will be appended to an existing file on logapp startup.
.TP 
\*(T<\fB\-\-maxlogsize=\fR\*(T>\fIkibyte\fR
To limit the maximum size of the logfile you can set this option to a value between \fI10 and 4000000 kiBytes\fR. The default is \fI0\fR which disables the logfile size limit. There are different ways implemented how the logfile is limited. Have a look at the options \*(T<\fB\-\-logrename\fR\*(T> and \*(T<\fB\-\-circularlog\fR\*(T> to learn more. The default way is that the extension \*(T<.old\*(T> is added to the logfile and a new logfile is started.
.TP 
\*(T<\fB\-\-logrename=\fR\*(T>\fIbool\fR
This option specifies the behavior when a logfile is to be truncated. If \*(T<\fB\-\-logrename\fR\*(T> is enabled the logfile is renamed. The new filename will be the same as before with the extension defined with \*(T<\fB\-\-oldlogext\fR\*(T> added. The default extension is \*(T<.old\*(T>. This option is used together with the value of \*(T<\fB\-\-appendlog\fR\*(T> and \*(T<\fB\-\-maxlogsize\fR\*(T>
.TP 
\*(T<\fB\-\-circularlog=\fR\*(T>\fIbool\fR
If this option is enabled together with a logfile size limit set with \*(T<\fB\-\-maxlogsize\fR\*(T>, the logfile will be used in a circular way. This means if the maximum size is reached, the file pointer is set to the beginning of the file and the old content is overwritten from the beginning. There are tags added to the logfile to help navigating in the file.
.TP 
\*(T<\fB\-\-oldlogext=\fR\*(T>\fIextension\fR
This defines the extion that is used when logapp is renaming a logfile. The \*(T<\fB\-\-logrename\fR\*(T> option defines if logapp will rename the file and the default extension is \*(T<.old\*(T>.
.TP 
\*(T<\fB\-\-locklogfile=\fR\*(T>\fIbool\fR
With this option active the logfile is locked in order to prevent it to be overwritten by another task. This is useful if otherwise an unreadable mix up of different contents would be the result. Depending on the value of the \*(T<\fB\-\-maxaltlogfiles\fR\*(T> option another logfile is chosen with the same name and a number added. Logfile locking is activated by default.
.TP 
\*(T<\fB\-\-warnlogfilelock=\fR\*(T>\fIbool\fR
This options defines if there should be a warning printed to the console if the chosen logfile is already locked or in other means not accessible. In this case there will be a message before the application is started and directly after its execution where the name of the alternative logfile is mentioned. This option is enabled by default. Also have a look at the \*(T<\fB\-\-printlogname\fR\*(T> where you can define to always get the current logfile reported.
.TP 
\*(T<\fB\-\-printlogname=\fR\*(T>\fIbool\fR
This option defines if the name of the used logfile should be printed after the application has finished its execution. This option is disabled by default. Also have a look at the \*(T<\fB\-\-warnlogfilelock\fR\*(T> where you can enable/disable a warning if the logfile name is changed because of a locked logfile.
.TP 
\*(T<\fB\-\-maxaltlogfiles=\fR\*(T>\fInumber\fR
This options defines the maximum number that can be added to the logfile name, if the original file is not accessible. On logapp startup it will be checked if the currently defined logfile is writeable, if this is not the case automatically a number is added to the filename. If the alternative file is also not accessible this number is increased until a file is writable or the value of \fImaxaltlogfiles\fR is reached. In the latter case the application will exit with an error. If a value of 0 is used only the original logfile name is tried. Also have a look at the \*(T<\fB\-\-warnlogfilelock\fR\*(T> and \*(T<\fB\-\-printlogname\fR\*(T> options to define if there should be messages about the currently used logfile.
.TP 
\*(T<\fB\-\-alignlog=\fR\*(T>\fIbool\fR
This option is used together with \*(T<\fB\-\-stdout_charbased\fR\*(T> and \*(T<\fB\-\-stderr_charbased\fR\*(T> and defines if data packets are written to the logfile as they come or if they are each written to a new line. The default is that each data packet is written to a new line, set this option to false to disable it.
.TP 
\*(T<\fB\-\-alignlinebreaks=\fR\*(T>\fIbool\fR
This option is used together with \*(T<\fB\-\-stdout_charbased\fR\*(T> and \*(T<\fB\-\-stderr_charbased\fR\*(T> and aligns the lines to the left in the logfile with regard to prefix and timestamp. This option is enabled by default.
.TP 
\*(T<\fB\-\-jointimeout=\fR\*(T>\fItime\fR
This option is used together with \*(T<\fB\-\-stdout_charbased\fR\*(T> and \*(T<\fB\-\-stderr_charbased\fR\*(T> and defines a ms timeout for joining single packets to one. This means if for example two chars get written within the timeout, they are treated as one packet. This is best used together with \*(T<\fB\-\-alignlog\fR\*(T> and \*(T<\fB\-\-logtime\fR\*(T>. Use this option if the data packets have lost their coherency for some reason (e.g. if the data comes through a serial line). This feature is disabled by default and can be enabled by setting \fItime\fR to a value bigger than 0 ms.
.TP 
\*(T<\fB\-t\fR\*(T>, \*(T<\fB\-\-logtime=\fR\*(T>\fIbool\fR
This option can be enabled to add a ms timestamp to each line of the logfile. Normally the time since the application start is used, but this can be changed with the \*(T<\fB\-\-logreltime\fR\*(T> option.
.TP 
\*(T<\fB\-\-logreltime=\fR\*(T>\fIbool\fR
If this option is set this to true, the \*(T<\fB\-\-logreltime\fR\*(T> option will use the relative time since the last line for the logged timestamps.
.TP 
\*(T<\fB\-\-logenv=\fR\*(T>\fIbool\fR
With this option set to true logapp will add a list of all active environment variables to the logfile. This option is disabled by default.
.TP 
\*(T<\fB\-p\fR\*(T>, \*(T<\fB\-\-stdout_lineprefix=\fR\*(T>\fIprefix\fR
.TP 
\*(T<\fB\-P\fR\*(T>, \*(T<\fB\-\-stderr_lineprefix=\fR\*(T>\fIprefix\fR
To be able to distinguish \fIstdout\fR and \fIstderr\fR output in the logfile logapp can prefix each line with a string that indicates if the line belongs to a specific data stream. Those strings can be changed with this option. The default is that \fIstdout\fR does not have a prefix and \fIstderr\fR is prefixed with \fISTDERR:\fR.
.SS "CONSOLE OUTPUT OPTIONS"
This section contains options that affect the visual output on the console.
.TP 
\*(T<\fB\-\-dumbterm=\fR\*(T>\fIbool\fR
This option disables output coloring. This is usually done automatically if a \fIdumb\fR terminal is detected.
.TP 
\*(T<\fB\-s\fR\*(T>, \*(T<\fB\-\-print_summary=\fR\*(T>\fIbool\fR
If this option is set to true, then a short summary will be printed after the application has terminated. This option is disabled by default.
.TP 
\*(T<\fB\-f\fR\*(T>, \*(T<\fB\-\-stdout_fgcol=\fR\*(T>\fIcolor\fR
.TP 
\*(T<\fB\-F\fR\*(T>, \*(T<\fB\-\-stderr_fgcol=\fR\*(T>\fIcolor\fR
This options define the foreground color for the specific data stream. The value can be one of the entries in the \fIconsole color table\fR at the end of this section.
.TP 
\*(T<\fB\-b\fR\*(T>, \*(T<\fB\-\-stdout_bold=\fR\*(T>\fIbool\fR
.TP 
\*(T<\fB\-B\fR\*(T>, \*(T<\fB\-\-stderr_bold=\fR\*(T>\fIbool\fR
This options define if the font for the specific data stream should be printed bold.
.TP 
\*(T<\fB\-r\fR\*(T>, \*(T<\fB\-\-stdout_regexp=\fR\*(T>\fIregular expression\fR
.TP 
\*(T<\fB\-R\fR\*(T>, \*(T<\fB\-\-stderr_regexp=\fR\*(T>\fIregular expression\fR
The regular expression that can be defined with this option is applied to every line of the specific data stream. On a match the background color changes to the value provided with the \*(T<\fB\-\-stdout_regexp_bgcol\fR\*(T> respectively \*(T<\fB\-\-stderr_regexp_bgcol\fR\*(T> option.
.TP 
\*(T<\fB\-\-stdout_regexp_bgcol=\fR\*(T>\fIcolor\fR
.TP 
\*(T<\fB\-\-stderr_regexp_bgcol=\fR\*(T>\fIcolor\fR
This options define the background color for the specific data stream for the case that the appropriate regular expression provided with \*(T<\fB\-\-stdout_regexp\fR\*(T> or \*(T<\fB\-\-stderr_regexp\fR\*(T> matches. The value can be one of the entries in the \fIconsole color table\fR at the end of this section.
.TP 
\*(T<\fB\-c\fR\*(T>, \*(T<\fB\-\-stdout_clip=\fR\*(T>\fIwidth\fR
.TP 
\*(T<\fB\-C\fR\*(T>, \*(T<\fB\-\-stderr_clip=\fR\*(T>\fIwidth\fR
This options define at which column the output should be clipped for the specific stream to reduce the amount of data written to the console. If a value of \fI\-1\fR is provided clipping is disabled for the stream. A value of \fI\-2\fR sets the clipping to the current console width. It is also possible to use \fIdisable\fR and \fIauto\fR instead of the numeric values. The default is that \fIstdout\fR is limited to the console width and that clipping is deactivated for \fIstderr\fR.

\fBConsole color table\fR
.TS
allbox ;
l | l.
T{
#
T}	T{
color
T}
.T&
l | l.
T{
\-1
T}	T{
(console) default
T}
T{
0
T}	T{
black
T}
T{
1
T}	T{
red
T}
T{
2
T}	T{
green
T}
T{
3
T}	T{
brown
T}
T{
4
T}	T{
blue
T}
T{
5
T}	T{
magenta
T}
T{
6
T}	T{
cyan
T}
T{
7
T}	T{
white
T}
.TE

.SS "COMMAND EXECUTION OPTIONS"
This section contains options that configure the execution of commands on regular expression matches.
.TP 
\*(T<\fB\-\-exitonexecfail=\fR\*(T>\fIBOOL\fR
This option defines if logapp should exit and end the wrapped application if the return value of an executed command indicates a failure. As default this option is disabled and logapp ignores the return state of executed commands.
.TP 
\*(T<\fB\-\-preexec=\fR\*(T>\fIcommand\fR
The command that can be provided with this option is executed directly before the application is started. At this time the header is already written to the logfile and can be parsed by the command.
.TP 
\*(T<\fB\-\-postexec=\fR\*(T>\fIcommand\fR
The command that can be provided with this option is executed directly after the application has exited. At this time the logfile is already closed for writing so all application output and the footer are already included and can be processed by the command.
.TP 
\*(T<\fB\-e\fR\*(T>, \*(T<\fB\-\-stdout_execregexp=\fR\*(T>\fIregular expression\fR
.TP 
\*(T<\fB\-E\fR\*(T>, \*(T<\fB\-\-stderr_execregexp=\fR\*(T>\fIregular expression\fR
The regular expression that can be defined with this option is applied to every line of the specific data stream. On a match the command provided with the \*(T<\fB\-\-stdout_execcommand\fR\*(T> respectively \*(T<\fB\-\-stderr_execcomand\fR\*(T> option is executed. An empty value for this option disables the regular expression matching.
.TP 
\*(T<\fB\-x\fR\*(T>, \*(T<\fB\-\-stdout_execcommand=\fR\*(T>\fIcommand\fR
.TP 
\*(T<\fB\-X\fR\*(T>, \*(T<\fB\-\-stderr_execcommand=\fR\*(T>\fIcommand\fR
This option defines the command that is executed on a regular expression match. The regular expression can be defined separately for the \fIstdout\fR and \fIstderr\fR stream with the \*(T<\fB\-\-stdout_execregexp\fR\*(T> respectively \*(T<\fB\-\-stderr_execregexp\fR\*(T> option.
.SH "REGULAR EXPRESSIONS"
Regular expressions are patterns that describe strings. Logapp uses this patterns to execute actions based on strings found in the data stream. The implementation is identical to the one that is used by \fIgrep\fR.
.PP
Logapp understands the "basic" and "extended" syntax of regular expressions as defined by POSIX. The default is to use the basic set, but you can switch to extended patterns with the \*(T<\fB\-\-extended\-regexp\fR\*(T> parameter. Please have a look at the \fBgrep\fR(1) and \fBregex\fR(7) manpage for detailed information.
.SS EXAMPLES
.TP 
\*(T<\fBString\fR\*(T>
Matches "String"
.TP 
\*(T<\fB^String\fR\*(T>
Matches "String" at the beginning of a line
.TP 
\*(T<\fBString$\fR\*(T>
Matches "String" at the end of a line
.TP 
\*(T<\fB^String$\fR\*(T>
Line contains only "String"
.TP 
\*(T<\fB[Ss]tring\fR\*(T>
Matches "String" or "string"
.TP 
\*(T<\fBStr.ng\fR\*(T>
The dot matches all characters, so this matches for example "String" or "Strong"
.TP 
\*(T<\fBStr.*ng\fR\*(T>
The dot together with star matches any number of characters, so this matches for example "String" or "Streaming"
.TP 
\*(T<\fB^[A\-Z] *\fR\*(T>
Matches any one of the characters from A to Z at the beginning of a line followed by zero or any number of spaces
.TP 
\*(T<\fBString\e|Word\fR\*(T>
Matches "String" or "Word" when working with \fIbasic regular expressions\fR
.TP 
\*(T<\fBString|Word\fR\*(T>
Matches "String" or "Word" when working with \fIextended regular expressions\fR
.SH ENVIRONMENT
.TP 
\fBTERM\fR
This variable is checked to see which type of console logapp is running in. Currently only the value \fIdumb\fR is handled in a special way \(em by disabling console colors. If the \fBTERM\fR variable is missing also a dumb terminal is assumed. The setting can be overridden by enabling/disabling the dumb terminal mode using the \*(T<\fB\-\-dumbterm\fR\*(T> option.
.SH FILES
.TP 
\*(T<\fI~/.logapprc\fR\*(T>, \*(T<\fI/etc/logapp.conf\fR\*(T>, \*(T<\fI/etc/logapp/logapp.conf\fR\*(T>
Configuration file locations that are tried if no \*(T<\fB\-\-configfile\fR\*(T> option is provided.
.SH BUGS
See the \*(T<\fITODO\fR\*(T> file included in the source package.
.SH "SEE ALSO"
\fBgrep\fR(1), \fBregex\fR(7)
.SH AUTHOR
Michael Brunner
.SH COPYING
Copyright (C) 2007\(en2011 Michael Brunner
.PP
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
.PP
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 General Public License for more details.