logapp(1)

📦
version 0.16 · 2 versions
, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble

logapp 💖 the manual page, bestie edition

okay so welcome to logapp(1) — yes that's the manual section, section 1, we love her 💅 — and she's an application output supervisor. Let's get into it.

✨ NAME ✨

logapp — an application output supervisor. 🫶

✨ SYNOPSIS ✨

logapp [option]... application [--logapp_option]... [app.-argument]...

applicationsymlink [--logapp_option]... [application-argument]...

so, plot twist: you don't have to call logapp directly 👀 you can also make a symlink named after the application, pointing at logapp. logapp will then automatically start the application that the name points to. and yes, it still works if the symlink name is prefixed with log. iconic behavior honestly 🎀

✨ DESCRIPTION ✨

so here's the vibe: logapp is a wrapper utility that helps you supervise the execution of applications that produce heavy console output — think 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 you want monitored — then it starts the application and logs all of its console output to a file. the output shown in the terminal gets pre-processed, like, to limit the length of printed lines and to show the stderr output in a different color. you can also set it up to automatically highlight lines matching a certain regular expression. 💖

so the output gets reduced to the necessary amount, and all the important lines are easy to identify. no cap, that's the whole point. periodt. 👑

✨ OPTIONS ✨

okay so first, the rules of engagement 🎀

options placed before the application argument get processed directly by logapp. options placed after the application argument are only parsed if they're prefixed with --logapp_ (long option names only) — otherwise they get passed straight to the application. and if logapp is called via a symlink, all unprefixed options go to the application. 🦋

every application usually uses two independent output streams: stdout for normal output and stderr for errors and important messages. both of them are handled independently by logapp, which is why there are so many options available for both streams. (it's giving twin flames, honestly. 😭)

Bool options accept 1/0 and true/false as value. for long boolean options the value can be omitted — in that case it will be assumed to be 'true'. 💅

🌸 GENERAL OPTIONS 🌸

  • -?, --help — show a short overview over all available options. your lil cheat sheet 🫶
  • --version — show version information. ⭐
  • --configfile=FILE — use a specific configuration file instead of searching the configuration search paths. 📁
  • --showconfig — print the current configuration of logapp and exit before the application is executed. this is the move when you wanna check if all configuration options are set up correctly and something doesn't work as expected. 🔍
  • --configsection=NAME — enable a specific section in the configuration file. if this option isn't provided, the application name is used as default. 🎀
  • --disable — 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 formatting is performed — only the execution time and the exit state are 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 --disable_keywords to see how this option can be enabled automatically. 🙈
  • --disable_keywords=keywordlist — with this option you can provide a list of comma separated keywords which will cause --disable to be enabled automatically if found in the application's option list. useful if an application usually provides line-based output but creates binary data or uses a curses based frontend when called with a specific parameter. you can also use the --detectescape option for another way to do this without disabling the logging functionality. 💡
  • --detectescape=bool — 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 is useful when you're working with an application that's 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. 💀➡️😌
  • --dumbterm=bool — with this set to true there will be no terminal output coloring for stdout and stderr. normally this option is disabled and logapp tries to detect "dumb" terminals itself. 🖍️
  • --usepty=bool — 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 pseudo terminal for stdout. this helps when 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. 👻
  • --ptyremovecr=bool — also 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 into LF line endings. this option is enabled as default. 🧚
  • --stdout_blen=bytes and --stderr_blen=bytes — the line buffer size can be adjusted for stdout and stderr independently with this option. if the value is too small, lines will be split up if the buffer is full. the default is 2048 byte which should be big enough for most applications. 📏
  • --stdout_charbased=bool and --stderr_charbased=bool — if you want to use logapp with applications that do not produce line based output, you can enable these options for stdout and stderr 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 --alignlog option. whether the result will be usable depends on what kind of data is generated by the application. 🤷♀️
  • --extended-regexp=bool — if enabled, logapp will interpret provided regular expression patterns as extended regular expressions. the default is to use basic regular expressions. 🔤

🎀 LOGGING OPTIONS 🎀

this section contains options that affect the logfile. 📓

  • -l, --logfile=file — change the file that's 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 logapp.log in the current directory. 🗂️
  • -a, --appendlog=bool — specifies if the logfile will be truncated or if the data will be appended to an existing file on logapp startup. ➕
  • --maxlogsize=kibyte — to limit the maximum size of the logfile, set this option to a value between 10 and 4000000 kiBytes. the default is 0 which disables the logfile size limit. there are different ways implemented for how the logfile is limited — have a look at the options --logrename and --circularlog to learn more. the default way is that the extension .old is added to the logfile and a new logfile is started. 🔥
  • --logrename=bool — specifies the behavior when a logfile is to be truncated. if --logrename is enabled, the logfile is renamed. the new filename will be the same as before with the extension defined with --oldlogext added. the default extension is .old. this option is used together with the value of --appendlog and --maxlogsize. 🔄
  • --circularlog=bool — if enabled together with a logfile size limit set with --maxlogsize, 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. 🌀
  • --oldlogext=extension — defines the extension that's used when logapp is renaming a logfile. the --logrename option defines if logapp will rename the file, and the default extension is .old. 🏷️
  • --locklogfile=bool — with this option active, the logfile is locked to prevent it from being overwritten by another task. useful, because otherwise an unreadable mix up of different contents would be the result. 😵 depending on the value of the --maxaltlogfiles option, another logfile is chosen with the same name and a number added. logfile locking is activated by default. 🔒
  • --warnlogfilelock=bool — defines if there should be a warning printed to the console if the chosen logfile is already locked or is otherwise 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 --printlogname, where you can define to always get the current logfile reported. ⚠️
  • --printlogname=bool — 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 --warnlogfilelock where you can enable/disable a warning if the logfile name is changed because of a locked logfile. 📢

bestie, this page is long, so more parts are coming — stay tuned 💖🦋

  • --maxaltlogfiles=number — bestie, this one sets the max number that can be added to the logfile name if the original file isn’t accessible. On logapp startup it checks if the currently defined logfile is writeable. If it’s not, a number is automatically added to the filename. If the alternative file is also not accessible, that number keeps increasing until a file is writable or you hit the value of maxaltlogfiles. In that latter case, the application will exit with an error 😭. If you use a value of 0, only the original logfile name is tried. Also, go peek at the --warnlogfilelock and --printlogname options to define if there should be messages about the currently used logfile. 👑
  • --alignlog=bool — this one works together with --stdout_charbased and --stderr_charbased. It defines if data packets are written to the logfile as they come, or if each one is written to a new line. The default is that each data packet gets its own new line, so set this to false to disable that. ✨
  • --alignlinebreaks=bool — also used with --stdout_charbased and --stderr_charbased. It aligns the lines to the left in the logfile with regard to prefix and timestamp. This option is enabled by default. 🦋
  • --jointimeout=time — used with --stdout_charbased and --stderr_charbased. It defines a ms timeout for joining single packets into one. So if two chars get written within the timeout, they’re treated as one packet. Best used with --alignlog and --logtime. Use this if the data packets have lost their coherency for some reason (like if data comes through a serial line). This feature is disabled by default and can be enabled by setting time to a value bigger than 0 ms. 💅
  • -t, --logtime=bool — enable this to add a ms timestamp to each line of the logfile. Normally the time since the application start is used, but you can change that with the --logreltime option. ⏰
  • --logreltime=bool — if you set this to true, the --logreltime option will use the relative time since the last line for the logged timestamps. 🕰️
  • --logenv=bool — set this to true and logapp will add a list of all active environment variables to the logfile. This option is disabled by default. 🌈
  • -p, --stdout_lineprefix=prefix — to distinguish stdout and stderr output in the logfile, logapp can prefix each line with a string that indicates if the line belongs to a specific data stream. You can change that string for stdout with this option. The default is that stdout does not have a prefix and stderr is prefixed with STDERR:. 🎀
  • -P, --stderr_lineprefix=prefix — same idea, but this one changes the prefix string for stderr. The default is that stdout does not have a prefix and stderr is prefixed with STDERR:. 💖

🎀 CONSOLE OUTPUT OPTIONS 🎀

This section contains options that affect the visual output on the console. 👀

  • --dumbterm=bool — this disables output coloring. Usually done automatically if a dumb terminal is detected. 🖥️
  • -s, --print_summary=bool — if set to true, a short summary will be printed after the application has terminated. This option is disabled by default. 📝
  • -f, --stdout_fgcol=color — defines the foreground color for the stdout data stream. The value can be one of the entries in the console color table at the end of this section. 🎨
  • -F, --stderr_fgcol=color — defines the foreground color for the stderr data stream. The value can be one of the entries in the console color table at the end of this section. 🎨
  • -b, --stdout_bold=bool — defines if the font for the stdout data stream should be printed bold. BOLD energy! 💪
  • -B, --stderr_bold=bool — defines if the font for the stderr data stream should be printed bold. 💪
  • -r, --stdout_regexp=regular expression — the regular expression you define here is applied to every line of the stdout data stream. On a match, the background color changes to the value provided with the --stdout_regexp_bgcol option. 🔍
  • -R, --stderr_regexp=regular expression — same but for stderr. On a match, the background color changes to the value provided with the --stderr_regexp_bgcol option. 🔍
  • --stdout_regexp_bgcol=color — defines the background color for stdout for the case that the appropriate regular expression provided with --stdout_regexp matches. The value can be one of the entries in the console color table at the end of this section. 🎨
  • --stderr_regexp_bgcol=color — defines the background color for stderr for the case that the appropriate regular expression provided with --stderr_regexp matches. The value can be one of the entries in the console color table at the end of this section. 🎨
  • -c, --stdout_clip=width — defines at which column the output should be clipped for stdout to reduce the amount of data written to the console. If you provide -1, clipping is disabled for the stream. A value of -2 sets the clipping to the current console width. You can also use disable and auto instead of the numeric values. The default is that stdout is limited to the console width and that clipping is deactivated for stderr. ✂️
  • -C, --stderr_clip=width — defines at which column the output should be clipped for stderr. If you provide -1, clipping is disabled. A value of -2 sets clipping to the current console width. You can also use disable and auto. The default is that stdout is limited to the console width and that clipping is deactivated for stderr. ✂️

Console color table 🎨

  • -1 — (console) default
  • 0 — black
  • 1 — red
  • 2 — green
  • 3 — brown
  • 4 — blue
  • 5 — magenta
  • 6 — cyan
  • 7 — white

COMMAND EXECUTION OPTIONS

This section contains options that configure the execution of commands on regular expression matches. 🎯

  • --exitonexecfail=BOOL — 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. 🚪
  • --preexec=command — the command you provide here 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. 📜
  • --postexec=command — the command you provide here 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. 📜
  • -e, --stdout_execregexp=regular expression — the regular expression defined here is applied to every line of the stdout data stream. On a match, the command provided with the --stdout_execcommand option is executed. An empty value for this option disables the regular expression matching. 🎯
  • -E, --stderr_execregexp=regular expression — same for stderr. On a match, the command provided with the --stderr_execcomand option is executed. An empty value disables matching. 🎯
  • -x, --stdout_execcommand=command — defines the command that is executed on a regular expression match. The regular expression can be defined separately for stdout with the --stdout_execregexp option. 💻
  • -X, --stderr_execcommand=command — defines the command executed on a match for stderr. The regular expression can be defined with the --stderr_execregexp option. 💻

🔥 REGULAR EXPRESSIONS 🔥

Regular expressions are patterns that describe strings. Logapp uses these patterns to execute actions based on strings found in the data stream. The implementation is identical to the one used by grep. 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 --extended-regexp parameter. Please have a look at the grep(1) and regex(7) manpage for detailed information. 🔍

🌸 EXAMPLES 🌸

Here are some string matches for "String":

  • ^String — Matches "String" at the beginning of a line
  • String$ — Matches "String" at the end of a line
  • ^String$ — Line contains only "String"
  • [Ss]tring — Matches "String" or "string"
  • Str.ng — The dot matches all characters, so this matches for example "String" or "Strong"
  • Str.*ng — The dot together with star matches any number of characters, so this matches for example "String" or "Streaming"
  • ^[A-Z] * — Matches any one of the characters from A to Z at the beginning of a line followed by zero or any number of spaces
  • String\|Word — Matches "String" or "Word" when working with basic regular expressions
  • String|Word — Matches "String" or "Word" when working with extended regular expressions

🌈 ENVIRONMENT 🌈

  • TERM — This variable is checked to see which type of console logapp is running in. Currently only the value dumb is handled in a special way — by disabling console colors. If the TERM variable is missing, a dumb terminal is also assumed. The setting can be overridden by enabling/disabling the dumb terminal mode using the --dumbterm option. 🌍

💾 FILES 💾

  • ~/.logapprc, /etc/logapp.conf, /etc/logapp/logapp.conf — Configuration file locations that are tried if no --configfile option is provided. 📁

🐛 BUGS 🐛

See the TODO file included in the source package. 🐜

👀 SEE ALSO 👀

grep(1), regex(7)

👑 AUTHOR 👑

Michael Brunner

📜 COPYING 💖

okay bestie, the legal bit, but make it cute bc we're doing it together 🫶

  • Copyright (C) 2007–2011 Michael Brunner — yeah, the whole span, 2007 through 2011, all his. give the man his flowers 💐

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. so like, v2, or whatever comes after, your call, no cap ✨

This program is distributed in the hope that it will be useful 🎀 but — and this is the important part, don't skip it — WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 😭

fr fr, no promises, no guarantees, no "it'll definitely work on your machine" energy. if it eats your logs that's between you and the universe. 💀

See the General Public License for more details — that's where the actual fine print lives, go read it, it's giving responsible bestie 💅

okay that's literally the whole page!! 🌈 we did it, we read an entire manpage together, that's main character behavior, I'm obsessed 👑

this one's logapp 0.16svn from January 2011, and yeah it's logapp(1) — the section 1, user commands, right where it belongs 🦋

go log something, bestie, you've earned it 💖✨

📦 where this page comes from