pmie: add -o|--format option to control output format with archives

Since most rule actions are "fake" when processing performance data
from archives, the -o option provides some rudimentary control over
the format of the output messages when rule actions are executed.

The meta-fields supported in the -o option are (from pmie(1)) ...

   %a  The name of the action, e.g.  print, syslog, etc.
   %d  The  date  and  time  in ctime(3) format when the action would have
       been executed.
   %f  The name of the configuration file containing the action being exe‐
       cuted, else <stdin> if the rules were read from standard input.
   %l  The (approximate) line number in the configuration file for the ac‐
       tion being executed.
   %m  The message component of the action.
   %u  The date and time when the action would have been executed  in  ex‐
       tended ctime(3) format with microsecond precision for the time.
   %%  A literal percent character.

   The default output format is equivalent to a format of %a %d: %m.

Resolves #1799.

man/man1/pmie.1

@@ -29,6 +29,7 @@
 [\f3\-m\f1 \f2note\f1]
 [\f3\-j\f1 \f2stompfile\f1]
 [\f3\-n\f1 \f2pmnsfile\f1]
+[\f3\-o\f1 \f2format\f1]
 [\f3\-O\f1 \f2offset\f1]
 [\f3\-S\f1 \f2starttime\f1]
 [\f3\-t\f1 \f2interval\f1]
@@ -242,6 +243,18 @@ section below.
 An alternative Performance Metrics Name Space (PMNS) is loaded from the file
 .IR pmnsfile .
 .TP
+\fB\-o\fR \fIformat\fR, \fB\-\-format\fR=\fIformat\fR
+When precessing performance data from an archive, the
+.B \-o
+option may be used to specify an alternate output
+.I format
+when a rule action is executed.
+See the
+.B "DIFFERENCES IN HOST AND ARCHIVE MODES"
+section for a description of how the output
+.I format
+may be constructed.
+.TP
 \fB\-O\fR \fIorigin\fR, \fB\-\-origin\fR=\fIorigin\fR
 Specify the \fIorigin\fP of the time window.
 See
@@ -1326,6 +1339,49 @@ or a shell command that might not even work on the host where
 is being run, are all examples of ``badness'' to be avoided.
 Rather the output is text in a regular format suitable for post-processing
 with a range of filters and performance analysis tools.
+.PP
+The output format can be changed using the
+.B \-o
+option which consists of literal characters with the following
+embedded ``meta-field'' tokens:
+.TP 4n
+\f(CB%a\fR
+The name of the action, e.g.
+.BR print ,
+.BR syslog ,
+etc.
+.TP 4n
+\f(CB%d\fR
+The date and time in
+.BR ctime (3)
+format when the action would have been executed.
+.TP 4n
+\f(CB%f\fR
+The name of the configuration file containing the action being
+executed, else
+.B <stdin>
+if the rules were read from standard input.
+.TP 4n
+\f(CB%l\fR
+The (approximate) line number in the configuration file for the action being
+executed.
+.TP 4n
+\f(CB%m\fR
+The message component of the action.
+.TP 4n
+\f(CB%u\fR
+The date and time when the action would have been executed in
+extended
+.BR ctime (3)
+format with microsecond precision for the time.
+.TP 4n
+\f(CB%%\fR
+A literal percent character.
+.PP
+The default output format is equivalent to a
+.I format
+of
+.BR "%a %d: %m" .
 .SH SIGNALS
 If
 .B pmie
@@ -1466,13 +1522,14 @@ a cross-platform dialog box.
 .BR pmcd (1),
 .BR pmconfirm (1),
 .BR pmdumplog (1),
-.BR pmieconf (1),
 .BR pmie_check (1),
+.BR pmieconf (1),
 .BR pmie_daily (1),
 .BR pminfo (1),
 .BR pmlogger (1),
 .BR pmval (1),
 .BR systemd (1),
+.BR ctime (3),
 .BR PMAPI (3),
 .BR pcp.conf (5),
 .BR pcp.env (5)

qa/1912

@@ -0,0 +1,96 @@
+#!/bin/sh
+# PCP QA Test No. 1912
+# pmie -o testing
+#
+# non-valgrind variant, see qa/1913 for the valgrind variant
+#
+# Copyright (c) 2023 Ken McDonell.  All Rights Reserved.
+#
+
+if [ $# -eq 0 ]
+then
+    seq=`basename $0`
+    echo "QA output created by $seq"
+else
+    # use $seq from caller, unless not set
+    [ -n "$seq" ] || seq=`basename $0`
+    echo "QA output created by `basename $0` $*"
+fi
+
+# get standard environment, filters and checks
+. ./common.product
+. ./common.filter
+. ./common.check
+
+$sudo rm -rf $tmp $tmp.* $seq.full
+
+do_valgrind=false
+if [ "$1" = "--valgrind" ]
+then
+    _check_valgrind
+    do_valgrind=true
+elif which valgrind >/dev/null 2>&1
+then
+    [ $PCPQA_VALGRIND = both ] || \
+	_notrun "valgrind variant qa/1913 will be run"
+fi
+
+_cleanup()
+{
+    cd $here
+    $sudo rm -rf $tmp $tmp.*
+}
+
+status=0	# success is the default!
+trap "_cleanup; exit \$status" 0 1 2 3 15
+
+_filter()
+{
+    sed \
+	-e "s@$tmp@TMP@g" \
+	-e '/evaluator exiting/d' \
+# end
+}
+
+# real QA test starts here
+
+cat <<End-of-File >$tmp.config
+// suff at the beginning
+sample.wrap.long > 0
+// stuff in the middle
+    -> print "yippee %v";
+// stuff at the end
+End-of-File
+
+# base tests ...
+#
+for fmt in "%a %d: %m" "%% %m %" "%%a=%a= %%d=%d= %%f=%f= %%l=%l= %%m=%m= %%u=%u=" \
+	   "%m" "prologue %M epilogue" "%"
+do
+    echo
+    echo "-- $fmt --"
+
+    if $do_valgrind
+    then
+	_run_valgrind pmie -t 2 -z -c $tmp.config -a archives/wrap -o "$fmt"
+    else
+	pmie -t 2 -z -c $tmp.config -a archives/wrap -o "$fmt" 2>&1
+    fi \
+    | _filter
+done
+
+# config on stdin, ...
+#
+echo
+echo "-- misc tests --"
+( cat $tmp.config $tmp.config ) \
+| if $do_valgrind
+then
+    _run_valgrind pmie -t 2 -z -a archives/wrap -o "[%f:%l] %m"
+else
+    pmie -t 2 -z -a archives/wrap -o "[%f:%l] %m" 2>&1
+fi \
+| _filter
+
+# success, all done
+exit

qa/1912.out

@@ -0,0 +1,31 @@
+QA output created by 1912
+
+-- %a %d: %m --
+pmie: timezone set to local timezone from archives/wrap
+print Mon Dec  1 16:08:22 1997: yippee 1144454022
+
+-- %% %m % --
+pmie: timezone set to local timezone from archives/wrap
+% yippee 1144454022 %
+
+-- %%a=%a= %%d=%d= %%f=%f= %%l=%l= %%m=%m= %%u=%u= --
+pmie: timezone set to local timezone from archives/wrap
+%a=print= %d=Mon Dec  1 16:08:22 1997= %f=TMP.config= %l=4= %m=yippee 1144454022= %u=Mon Dec  1 16:08:22.423728 1997=
+
+-- %m --
+pmie: timezone set to local timezone from archives/wrap
+yippee 1144454022
+
+-- prologue %M epilogue --
+pmie: timezone set to local timezone from archives/wrap
+Warning: unrecognized field specifier '%M' in format
+prologue %M epilogue
+
+-- % --
+pmie: timezone set to local timezone from archives/wrap
+%
+
+-- misc tests --
+pmie: timezone set to local timezone from archives/wrap
+[<stdin>:4] yippee 1144454022
+[<stdin>:9] yippee 1144454022

qa/1913

@@ -0,0 +1,37 @@
+#!/bin/sh
+# PCP QA Test No. 1913
+# pmie -o testing
+#
+# valgrind variant, see qa/1912 for the non-valgrind variant
+#
+# check-group-include: pmie
+#
+# Copyright (c) 2023 Ken McDonell.  All Rights Reserved.
+#
+
+seq=`basename $0`
+echo "QA output created by $seq"
+
+# get standard environment, filters and checks
+. ./common.product
+. ./common.filter
+. ./common.check
+
+_check_valgrind
+
+_cleanup()
+{
+    cd $here
+    $sudo rm -rf $tmp $tmp.*
+}
+
+status=0	# success is the default!
+$sudo rm -rf $tmp $tmp.* $seq.full
+trap "_cleanup; exit \$status" 0 1 2 3 15
+
+# real QA test starts here
+export seq
+./1912 --valgrind
+
+# success, all done
+exit

qa/1913.out

@@ -0,0 +1,95 @@
+QA output created by 1913
+QA output created by 1912 --valgrind
+
+-- %a %d: %m --
+=== std out ===
+pmie: timezone set to local timezone from archives/wrap
+print Mon Dec  1 16:08:22 1997: yippee 1144454022
+=== std err ===
+=== filtered valgrind report ===
+Memcheck, a memory error detector
+Command: pmie -t 2 -z -c TMP.config -a archives/wrap -o %a\ %d:\ %m
+LEAK SUMMARY:
+definitely lost: 0 bytes in 0 blocks
+indirectly lost: 0 bytes in 0 blocks
+ERROR SUMMARY: 0 errors from 0 contexts ...
+
+-- %% %m % --
+=== std out ===
+pmie: timezone set to local timezone from archives/wrap
+% yippee 1144454022 %
+=== std err ===
+=== filtered valgrind report ===
+Memcheck, a memory error detector
+Command: pmie -t 2 -z -c TMP.config -a archives/wrap -o %%\ %m\ %
+LEAK SUMMARY:
+definitely lost: 0 bytes in 0 blocks
+indirectly lost: 0 bytes in 0 blocks
+ERROR SUMMARY: 0 errors from 0 contexts ...
+
+-- %%a=%a= %%d=%d= %%f=%f= %%l=%l= %%m=%m= %%u=%u= --
+=== std out ===
+pmie: timezone set to local timezone from archives/wrap
+%a=print= %d=Mon Dec  1 16:08:22 1997= %f=TMP.config= %l=4= %m=yippee 1144454022= %u=Mon Dec  1 16:08:22.423728 1997=
+=== std err ===
+=== filtered valgrind report ===
+Memcheck, a memory error detector
+Command: pmie -t 2 -z -c TMP.config -a archives/wrap -o %%a=%a=\ %%d=%d=\ %%f=%f=\ %%l=%l=\ %%m=%m=\ %%u=%u=
+LEAK SUMMARY:
+definitely lost: 0 bytes in 0 blocks
+indirectly lost: 0 bytes in 0 blocks
+ERROR SUMMARY: 0 errors from 0 contexts ...
+
+-- %m --
+=== std out ===
+pmie: timezone set to local timezone from archives/wrap
+yippee 1144454022
+=== std err ===
+=== filtered valgrind report ===
+Memcheck, a memory error detector
+Command: pmie -t 2 -z -c TMP.config -a archives/wrap -o %m
+LEAK SUMMARY:
+definitely lost: 0 bytes in 0 blocks
+indirectly lost: 0 bytes in 0 blocks
+ERROR SUMMARY: 0 errors from 0 contexts ...
+
+-- prologue %M epilogue --
+=== std out ===
+pmie: timezone set to local timezone from archives/wrap
+prologue %M epilogue
+=== std err ===
+Warning: unrecognized field specifier '%M' in format
+=== filtered valgrind report ===
+Memcheck, a memory error detector
+Command: pmie -t 2 -z -c TMP.config -a archives/wrap -o prologue\ %M\ epilogue
+LEAK SUMMARY:
+definitely lost: 0 bytes in 0 blocks
+indirectly lost: 0 bytes in 0 blocks
+ERROR SUMMARY: 0 errors from 0 contexts ...
+
+-- % --
+=== std out ===
+pmie: timezone set to local timezone from archives/wrap
+%
+=== std err ===
+=== filtered valgrind report ===
+Memcheck, a memory error detector
+Command: pmie -t 2 -z -c TMP.config -a archives/wrap -o %
+LEAK SUMMARY:
+definitely lost: 0 bytes in 0 blocks
+indirectly lost: 0 bytes in 0 blocks
+ERROR SUMMARY: 0 errors from 0 contexts ...
+
+-- misc tests --
+=== std out ===
+pmie: timezone set to local timezone from archives/wrap
+[<stdin>:4] yippee 1144454022
+[<stdin>:9] yippee 1144454022
+=== std err ===
+=== filtered valgrind report ===
+Memcheck, a memory error detector
+Command: pmie -t 2 -z -a archives/wrap -o [%f:%l]\ %m
+LEAK SUMMARY:
+definitely lost: 0 bytes in 0 blocks
+indirectly lost: 0 bytes in 0 blocks
+ERROR SUMMARY: 0 errors from 0 contexts ...

qa/group

@@ -2079,6 +2079,8 @@ x11
 1901 pmlogger local
 1902 help local
 1906 pmseries libpcp_web local
+1912 pmie local
+1913 pmie local valgrind
 1914 atop local
 1927 pmda.sockets local
 1931 pmda.bpf local

src/pmie/src/GNUmakefile

@@ -22,7 +22,7 @@ CFILES	= pmie.c symbol.c dstruct.c lexicon.c syntax.c pragmatics.c eval.c \
 	  show.c match_inst.c systemlog.c stomp.c andor.c
 
 HFILES  = fun.h dstruct.h eval.h lexicon.h pragmatics.h stats.h \
-	  show.h symbol.h syntax.h systemlog.h stomp.h andor.h
+	  show.h symbol.h syntax.h systemlog.h stomp.h andor.h act.h
 
 SKELETAL = hdr.sk fetch.sk misc.sk aggregate.sk unary.sk binary.sk \
 	merge.sk act.sk binary_str.sk
@@ -52,6 +52,8 @@ install:	default
 
 lexicon.o syntax.o:	grammar.h
 
+syntax.o:	act.h
+
 fun.o:	fun.h
 
 fun.c:	$(SKELETAL) meta