Documentation for "expecto"

Download the whole documentation as one plain text file


4. Template Syntax

4.8. Custom Reports

WARNING: This chapter is for experts.

If you need more control of the report in case of a mismatch, you can do so by creating a "default branch" that uses the ECHO statement, optionally accompanied by HEAD and TAIL statements. This chapter explains how to do that.

Within a group, a "default branch" is a branch that always matches. Obviously this should be the last branch in the group, because expecto ignores the remaining branches as soon as it encounters one that matches. But why would you want to create a branch that always matches? Well, this is where the ECHO statement comes into play ...

The ECHO statement can do two things. First, by writing "ECHO ON" or "ECHO OFF", you can instruct expecto to copy matching lines to the output. Second, you can specify a string (enclosed in single or double quotes) that will be printed verbatim.

It's time for an example. Let's assume that you have a cron job that produces several paragraphs, separated by empty lines, just like FreeBSD's "daily run". Here's a simplified example:

Verifying group file syntax: /etc/group is fine Checking status of gmirror(8) devices: Name Status Components mirror/gm0 COMPLETE ada1 (ACTIVE) ada0 (ACTIVE) Mail in local queue: /var/spool/mqueue is empty Total requests: 0 Checking for login failures: None. -- End of daily output --

We're using the following template:

* "" + ( "Verifying group file syntax:" "/etc/group is fine" "" | "Checking status of gmirror(8) devices:" " Name Status Components" {w} "mirror/gm0 COMPLETE ada" {bw} && "(ACTIVE)" {e} " ada" {bw} && "(ACTIVE)" {e} "" | "Mail in local queue:" "/var/spool/mqueue is empty" "Total requests: 0" {e} "" | "Checking for login failures:" "None." "" | "-- End of daily output --" | ECHO "Unexpected section in the daily run output:" ECHO "-------- BEGIN --------" ECHO ON * !"" ECHO OFF ECHO "--------- END ---------" * "" )

Let's look closer at the last branch of that template which is a "default" branch because it always matches: The * !"" statement matches an arbitrary number of non-empty lines, and the * "" statement matches an arbitrary number of empty lines.

Under normal circumstances (i.e. when we get only expected output from the cron job), one of the preceding branches would always match, so expecto never reaches the last branch, and nothing special happens.

However, if none of the preceding branches match, expecto will finally reach the last branch. Since it always matches, expecto will execute the ECHO statements contained inside. For example, when one disk of the mirror failed, and a user tried to use the "su" command with the wrong password, expecto will produce the following output:

Unexpected section in the daily run output: -------- BEGIN -------- Checking status of gmirror(8) devices: Name Status Components mirror/gm0 COMPLETE ada0 DEGRADED --------- END --------- Unexpected section in the daily run output: -------- BEGIN -------- Checking for login failures: Apr 17 10:22:38 host su: BAD SU cathy to root on /dev/pts/5 --------- END ---------

Optionally, you can use the HEAD and TAIL statements to enhance the output. Unlike ECHO, these are global statements, so they should be put at the top of the template. They are used to define strings that are placed before (HEAD) or after (TAIL) any output generated by ECHO. If no ECHO statements were processed, nothing is printed.

Additionally, the parts copied from the input when "ECHO ON" is in effect can be indented, i.e. those lines can be prefixed with an arbitrary string. This string is specified with the "ECHO INDENT" command; see the next example. Note: If there are any Tab characters, the formatting might come out wrong if the length of the prefix is not a multiple of 8. By default the prefix is empty, i.e. lines are not indented.

So now we'll enhance the above template:

HEAD "One or more sections of the daily run output did not" HEAD "match any expected pattern. These sections are copied" HEAD "below. Please check them carefully." HEAD "" TAIL "Everything else matched expected patterns and is not" TAIL "included here. The complete daily run output can be" TAIL "found in /var/log if needed." ECHO INDENT "| " * "" + ( "Verifying group file syntax:" "/etc/group is fine" "" | "Checking status of gmirror(8) devices:" " Name Status Components" {w} "mirror/gm0 COMPLETE ada" {bw} && "(ACTIVE)" {e} " ada" {bw} && "(ACTIVE)" {e} "" | "Mail in local queue:" "/var/spool/mqueue is empty" "Total requests: 0" {e} "" | "Checking for login failures:" "None." "" | "-- End of daily output --" | ECHO "+------- BEGIN --------" ECHO ON * !"" ECHO OFF ECHO "+-------- END ---------" ECHO "" * "" )

The report that was generated above will now look much better:

One or more sections of the daily run output did not match any expected pattern. These sections are copied below. Please check them carefully. +------- BEGIN -------- | Checking status of gmirror(8) devices: | Name Status Components | mirror/gm0 COMPLETE ada0 DEGRADED +-------- END --------- +------- BEGIN -------- | Checking for login failures: | Apr 17 10:22:38 host su: BAD SU cathy to root on /dev/pts/5 +-------- END --------- Everything else matched expected patterns and is not included here. The complete daily run output can be found in /var/log if needed.

Nice, isn't it? :-)



[Valid XHTML 1.0]