* Add caching to reporting features

* Fixed a problem with LOG_HEALTHY="Yes" and check_params()
* Other smaller fixes
* Whitespace fixes

etc/opt/hc/core/check_health.conf.dist

@@ -21,6 +21,16 @@ HC_LOG_HEALTHY="No"
 # [values: Yes|No]
 HC_WILL_FIX="Yes"
 
+# cache "last" reporting entries. Set to 'Yes' to speed up reporting of the last
+# registered HC events
+# [values: Yes|No]
+HC_REPORT_CACHE_LAST="No"
+
+# cache "today" reporting entries.  Set to 'Yes' to speed up reporting of today's
+# registered HC events
+# [values: Yes|No]
+HC_REPORT_CACHE_TODAY="No"
+
 
 #******************************************************************************
 # End of FILE

opt/hc/bin/check_health.sh

@@ -38,7 +38,7 @@
 
 # ------------------------- CONFIGURATION starts here -------------------------
 # define the version (YYYY-MM-DD)
-typeset -r SCRIPT_VERSION="2020-03-12"
+typeset -r SCRIPT_VERSION="2020-04-07"
 # location of parent directory containing KSH functions/HC plugins
 typeset -r FPATH_PARENT="/opt/hc/lib"
 # location of custom HC configuration files
@@ -104,6 +104,10 @@ typeset HC_STDOUT_LOG=""
 typeset HC_STDERR_LOG=""
 typeset HC_WILL_FIX=""
 # shellcheck disable=SC2034
+typeset HC_REPORT_CACHE_LAST=""
+# shellcheck disable=SC2034
+typeset HC_REPORT_CACHE_TODAY=""
+# shellcheck disable=SC2034
 typeset LINUX_DISTRO=""
 # shellcheck disable=SC2034
 typeset LINUX_RELEASE=""
@@ -255,8 +259,8 @@ case "${KSH_VERSION}" in
         . ${FPATH_PARENT}/core/include_core.sh
         if [[ -r ${FPATH_PARENT}/core/include_data.sh && -h ${FPATH_PARENT}/core/include_data ]]
         then
-                # shellcheck source=/dev/null
                 (( ARG_DEBUG > 0 )) && print -u2 "DEBUG: including ${FPATH_PARENT}/core/include_data.sh"
+                # shellcheck source=/dev/null
                 . ${FPATH_PARENT}/core/include_data.sh
         else
                 print -u2 "ERROR: library file ${FPATH_PARENT}/core/include_data.sh is not present (tip: run --fix-symlinks)"
@@ -264,8 +268,8 @@ case "${KSH_VERSION}" in
         fi
         if [[ -r ${FPATH_PARENT}/core/include_os.sh && -h ${FPATH_PARENT}/core/include_os ]]
         then
-                # shellcheck source=/dev/null
                 (( ARG_DEBUG > 0 )) && print -u2 "DEBUG: including ${FPATH_PARENT}/core/include_os.sh"
+                # shellcheck source=/dev/null
                 . ${FPATH_PARENT}/core/include_os.sh
         else
                 print -u2 "ERROR: library file ${FPATH_PARENT}/core/include_os.sh is not present (tip: run --fix-symlinks)"
@@ -274,7 +278,7 @@ case "${KSH_VERSION}" in
         ;;
     *)
         # include include_*
-        find ${FPATH_PARENT}/core -name "include_*.sh" -type f -print 2>/dev/null | while read INCLUDE_FILE
+        find ${FPATH_PARENT}/core -name "include_*.sh" -type f -print 2>/dev/null | while read -r INCLUDE_FILE
         do
             if [[ -h ${INCLUDE_FILE%%.sh} ]]
             then
@@ -330,7 +334,7 @@ function check_lock_dir
 (( ARG_DEBUG > 0 && ARG_DEBUG_LEVEL > 0 )) && set "${DEBUG_OPTS}"
 if (( ARG_LOCK > 0 ))
 then
-    mkdir ${LOCK_DIR} >/dev/null || {
+    mkdir ${LOCK_DIR} >/dev/null 2>/dev/null || {
         print -u2 "ERROR: unable to acquire lock ${LOCK_DIR}"
         ARG_VERBOSE=0 warn "unable to acquire lock ${LOCK_DIR}"
         if [[ -f ${LOCK_DIR}/.pid ]]
@@ -465,12 +469,6 @@ then
         exit 1
     fi
 fi
-# --log-healthy
-if (( ARG_LOG_HEALTHY > 0 && ARG_ACTION != 4 ))
-then
-    print -u2 "ERROR: you can only use '--log-healthy' in combination with '--run'"
-    exit 1
-fi
 # check log location
 if (( ARG_LOG > 0 ))
 then
@@ -959,6 +957,7 @@ do
             fi
             ;;
         -list-details|--list-details)
+            # shellcheck disable=SC2034
             ARG_LIST_DETAILS=1
             ARG_ACTION=9
             ;;

opt/hc/lib/core/include_core.sh

@@ -30,7 +30,7 @@
 # RETURNS: 0
 function version_include_core
 {
-typeset _VERSION="2020-03-12"           # YYYY-MM-DD
+typeset _VERSION="2020-04-07"           # YYYY-MM-DD
 
 print "INFO: $0: ${_VERSION#version_*}"
 
@@ -145,6 +145,7 @@ function count_log_errors
 typeset LOG_STASH="${1}"
 typeset ERROR_COUNT=0
 
+# shellcheck disable=SC2002
 ERROR_COUNT=$(cat ${LOG_STASH} 2>/dev/null | awk -F"${LOG_SEP}" '
     BEGIN { num = 0 }
     {
@@ -757,7 +758,7 @@ do
     if (( ERROR_COUNT > 0 ))
     then
     : >${TMP_FILE} 2>/dev/null
-        cat ${FIX_FILE} 2>/dev/null | awk -F"${LOG_SEP}" -v OFS="${LOG_SEP}" '
+    awk -F"${LOG_SEP}" -v OFS="${LOG_SEP}" '
 
     BEGIN { max_log_fields = '"${NUM_LOG_FIELDS}"'
     max_fields = (max_log_fields - 1) * 2
@@ -833,7 +834,7 @@ do
     # correct log line, no rewrite needed
     print $0
     }
-            }' >${TMP_FILE} 2>/dev/null
+    }' ${FIX_FILE} >${TMP_FILE} 2>/dev/null
 
     # count after rewrite (include empty lines again in the count)
     TMP_COUNT=$(wc -l ${TMP_FILE} 2>/dev/null | cut -f1 -d' ' 2>/dev/null)
@@ -882,7 +883,8 @@ return ${FIX_RC}
 # DOES: handle HC results
 # EXPECTS: 1=HC name [string], $HC_MSG_FILE temporary file
 # RETURNS: 0 or $HC_STC_RC
-# REQUIRES: die(), display_*(), notify_*(), warn()
+# REQUIRES: data_contains_string(), data_is_numeric(), die(), display_*(),
+#           notify_*(), warn()
 function handle_hc
 {
 (( ARG_DEBUG > 0 && ARG_DEBUG_LEVEL > 0 )) && set "${DEBUG_OPTS}"
@@ -896,6 +898,15 @@ typeset ONE_MSG_TEXT=""
 typeset ONE_MSG_CUR_VAL=""
 typeset ONE_MSG_EXP_VAL=""
 typeset ALL_MSG_STC=0
+typeset HC_CACHE_LAST_DATE=""
+typeset HC_CACHE_TODAY_DATE=""
+typeset HC_CACHE_LAST_NOW="$(date '+%Y-%m-%d %H:%M:%S' 2>/dev/null)"    # see also $HC_NOW
+typeset HC_CACHE_TODAY_NOW="$(date '+%Y-%m-%d' 2>/dev/null)"            # see also $HC_NOW
+typeset HC_REPORT_CACHE_LAST_STUB="${STATE_PERM_DIR}/cache.report-last"
+typeset HC_REPORT_CACHE_LAST_FILE=""
+typeset HC_REPORT_CACHE_TODAY_FILE="${STATE_PERM_DIR}/cache.report-today"
+typeset LOG_STRING_GOOD=""
+typeset LOG_STRING_FAIL=""
 
 if [[ -s ${HC_MSG_FILE} ]]
 then
@@ -1136,16 +1147,56 @@ then
     ONE_MSG_EXP_VAL=$(data_magic_unquote "${ONE_MSG_EXP_VAL}")
     fi
     fi
+
     if (( ONE_MSG_STC > 0 ))
     then
+    # build log string
+    LOG_STRING_FAIL=$(printf "%s${LOG_SEP}%s${LOG_SEP}%s${LOG_SEP}%s${LOG_SEP}%s${LOG_SEP}" "${ONE_MSG_TIME}" "${HC_NAME}" ${ONE_MSG_STC} "${ONE_MSG_TEXT}" "${HC_FAIL_ID}")
+
     # do atomic log update
     # shellcheck disable=SC1117
-            printf "%s${LOG_SEP}%s${LOG_SEP}%s${LOG_SEP}%s${LOG_SEP}%s${LOG_SEP}\n" \
+    print "${LOG_STRING_FAIL}" >>${HC_LOG}
-                    "${ONE_MSG_TIME}" \
+
-                    "${HC_NAME}" \
+    # cache report (--report --last)
-                    ${ONE_MSG_STC} \
+    HC_REPORT_CACHE_LAST_FILE="${HC_REPORT_CACHE_LAST_STUB}-${HC_NAME}"
-                    "${ONE_MSG_TEXT}" \
+    case "${HC_REPORT_CACHE_LAST}" in
-                    "${HC_FAIL_ID}" >>${HC_LOG}
+    Yes|yes|YES)
+    # fetch date of last cache entry (did we rollover from last HC event?)
+    HC_CACHE_LAST_DATE=$(tail -n 1 ${HC_REPORT_CACHE_LAST_FILE} 2>/dev/null | cut -f1 -d${LOG_SEP} 2>/dev/null)
+    if [[ -z "${HC_CACHE_LAST_DATE}" ]] || [[ "${HC_CACHE_LAST_DATE}" != "${HC_CACHE_LAST_NOW}" ]]
+    then
+    # set and update cache file
+    print "${LOG_STRING_FAIL}" >${HC_REPORT_CACHE_LAST_FILE}
+    else
+    # append cache file
+    print "${LOG_STRING_FAIL}" >>${HC_REPORT_CACHE_LAST_FILE}
+    fi
+    ;;
+    *)
+    # remove cache file if it exists
+    [[ -f ${HC_REPORT_CACHE_LAST_FILE} ]] && rm -f ${HC_REPORT_CACHE_LAST_FILE} >/dev/null 2>/dev/null
+    ;;
+    esac
+    # cache report (--report --today)
+    case "${HC_REPORT_CACHE_TODAY}" in
+    Yes|yes|YES)
+    # fetch date of last cache entry (did we rollover midnight?)
+    HC_CACHE_TODAY_DATE=$(tail -n 1 ${HC_REPORT_CACHE_TODAY_FILE} 2>/dev/null | cut -f1 -d${LOG_SEP} 2>/dev/null | awk '{ print $1 }' 2>/dev/null)
+    if [[ -z "${HC_CACHE_TODAY_DATE}" ]] || [[ "${HC_CACHE_TODAY_DATE}" != "${HC_CACHE_TODAY_NOW}" ]]
+    then
+    # rotate and update cache file
+    (( ARG_DEBUG > 0 )) && debug "rotating today's cache file at ${HC_REPORT_CACHE_TODAY_FILE}"
+    print "${LOG_STRING_FAIL}" >${HC_REPORT_CACHE_TODAY_FILE}
+    else
+    # append cache file
+    print "${LOG_STRING_FAIL}" >>${HC_REPORT_CACHE_TODAY_FILE}
+    fi
+    ;;
+    *)
+    # remove cache file if it exists
+    [[ -f ${HC_REPORT_CACHE_TODAY_FILE} ]] && rm -f ${HC_REPORT_CACHE_TODAY_FILE} >/dev/null 2>/dev/null
+    ;;
+    esac
     # RC handling (max/sum/count)
     if (( ARG_FLIP_RC > 0 ))
     then
@@ -1165,13 +1216,53 @@ then
     HC_STC_RC=$(( HC_STC_RC + 1 ))
     fi
     else
+    # build log string
+    LOG_STRING_GOOD=$(printf "%s${LOG_SEP}%s${LOG_SEP}%s${LOG_SEP}%s${LOG_SEP}" "${ONE_MSG_TIME}" "${HC_NAME}" ${ONE_MSG_STC} "${ONE_MSG_TEXT}")
+
     # do atomic log update
     # shellcheck disable=SC1117
-            printf "%s${LOG_SEP}%s${LOG_SEP}%s${LOG_SEP}%s${LOG_SEP}\n" \
+    print "${LOG_STRING_GOOD}" >>${HC_LOG}
-                    "${ONE_MSG_TIME}" \
+
-                    "${HC_NAME}" \
+    # cache report (--report --last)
-                    ${ONE_MSG_STC} \
+    HC_REPORT_CACHE_LAST_FILE="${HC_REPORT_CACHE_LAST_STUB}-${HC_NAME}"
-                    "${ONE_MSG_TEXT}" >>${HC_LOG}
+    case "${HC_REPORT_CACHE_LAST}" in
+    Yes|yes|YES)
+    # fetch date of last cache entry (did we rollover from last HC event?)
+    HC_CACHE_LAST_DATE=$(tail -n 1 ${HC_REPORT_CACHE_LAST_FILE} 2>/dev/null | cut -f1 -d${LOG_SEP} 2>/dev/null)
+    if [[ -z "${HC_CACHE_LAST_DATE}" ]] || [[ "${HC_CACHE_LAST_DATE}" != "${HC_CACHE_LAST_NOW}" ]]
+    then
+    # set and update cache file
+    print "${LOG_STRING_GOOD}" >${HC_REPORT_CACHE_LAST_FILE}
+    else
+    # append cache file
+    print "${LOG_STRING_GOOD}" >>${HC_REPORT_CACHE_LAST_FILE}
+    fi
+    ;;
+    *)
+    # remove cache file if it exists
+    [[ -f ${HC_REPORT_CACHE_LAST_FILE} ]] && rm -f ${HC_REPORT_CACHE_LAST_FILE} >/dev/null 2>/dev/null
+    ;;
+    esac
+    # cache report (--report --today)
+    case "${HC_REPORT_CACHE_TODAY}" in
+    Yes|yes|YES)
+    # fetch date of last cache last_entry (did we rollover midnight?)
+    HC_CACHE_TODAY_DATE=$(tail -n 1 ${HC_REPORT_CACHE_TODAY_FILE} 2>/dev/null | cut -f1 -d${LOG_SEP} 2>/dev/null | awk '{ print $1 }' 2>/dev/null)
+    if [[ -z "${HC_CACHE_TODAY_DATE}" ]] || [[ "${HC_CACHE_TODAY_DATE}" != "${HC_CACHE_TODAY_NOW}" ]]
+    then
+    # rotate and update cache file
+    (( ARG_DEBUG > 0 )) && debug "rotating today's cache file at ${HC_REPORT_CACHE_TODAY_FILE}"
+    print "${LOG_STRING_GOOD}" >${HC_REPORT_CACHE_TODAY_FILE}
+    else
+    # append cache file
+    print "${LOG_STRING_GOOD}" >>${HC_REPORT_CACHE_TODAY_FILE}
+    fi
+    ;;
+    *)
+    # remove cache file if it exists
+    [[ -f ${HC_REPORT_CACHE_TODAY_FILE} ]] && rm -f ${HC_REPORT_CACHE_TODAY_FILE} >/dev/null 2>/dev/null
+    ;;
+    esac
     fi
     done
 
@@ -1182,7 +1273,7 @@ then
     if [[ -s ${HC_STDOUT_LOG} ]] || [[ -s ${HC_STDERR_LOG} ]]
     then
     # organize logs in sub-directories: YYYY/MM
-            mkdir -p "${EVENTS_DIR}/${DIR_PREFIX}/${HC_FAIL_ID}" >/dev/null 2>&1 || \
+    mkdir -p "${EVENTS_DIR}/${DIR_PREFIX}/${HC_FAIL_ID}" >/reportdev/null 2>&1 || \
     die "failed to create event directory at ${1}"
     if [[ -f ${HC_STDOUT_LOG} ]]
     then
@@ -1388,7 +1479,7 @@ esac
 # mangle $ARG_HC to build the full list of HCs to be executed
 ARG_HC=""
 grep -i '^hc:' ${HOST_CONFIG_FILE} 2>/dev/null |\
-    while IFS=':' read _ HC_EXEC _ _
+    while IFS=':' read -r _ HC_EXEC _ _
 do
     ARG_HC="${ARG_HC},${HC_EXEC}"
 done
@@ -1438,8 +1529,8 @@ function is_scheduled
 (( ARG_DEBUG > 0 && ARG_DEBUG_LEVEL > 0 )) && set "${DEBUG_OPTS}"
 typeset CRON_HC="${1}"
 typeset CRON_COUNT=0
-typeset CRON_SYS_LOCATIONS='/etc/crontab /etc/cron.d/*'
+typeset CRON_SYS_LOCATIONS="/etc/crontab /etc/cron.d/*"
-typeset CRON_ANACRON_LOCATIONS='/etc/anacrontab /etc/cron.*'
+typeset CRON_ANACRON_LOCATIONS="/etc/anacrontab /etc/cron.*"
 
 # check for a scheduled job
 case "${OS_NAME}" in
@@ -1449,11 +1540,13 @@ case "${OS_NAME}" in
     # check system crontabs
     if (( CRON_COUNT == 0 ))
     then
+    # shellcheck disable=SC2002
     CRON_COUNT=$(cat ${CRON_SYS_LOCATIONS} 2>/dev/null | grep -c -E -e "^[^#].*${CRON_HC}" 2>/dev/null)
     fi
     # check anacron
     if (( CRON_COUNT == 0 ))
     then
+    # shellcheck disable=SC2002
     CRON_COUNT=$(cat ${CRON_ANACRON_LOCATIONS} 2>/dev/null | grep -c -E -e "^[^#].*${CRON_HC}" 2>/dev/null)
     fi
     ;;
@@ -1610,7 +1703,7 @@ fi
 print "${FPATH}" | tr ':' '\n' 2>/dev/null | grep -v "core$" 2>/dev/null | sort 2>/dev/null |\
     while read -r FDIR
 do
-    ls -1 ${FDIR}/${FNEEDLE} 2>/dev/null | sort 2>/dev/null | while read -r FFILE
+    find ${FDIR} -name "${FNEEDLE}" 2>/dev/null | sort 2>/dev/null | while read -r FFILE
     do
     # cache script contents in memory
     FSCRIPT=$(<${FFILE})

opt/hc/lib/core/report_std.sh

@@ -30,7 +30,7 @@
 function report_std
 {
 # ------------------------- CONFIGURATION starts here -------------------------
-typeset _VERSION="2019-05-19"                               # YYYY-MM-DD
+typeset _VERSION="2020-04-07"                               # YYYY-MM-DD
 typeset _SUPPORTED_PLATFORMS="AIX,HP-UX,Linux"              # uname -s match
 # ------------------------- CONFIGURATION ends here ---------------------------
 
@@ -59,8 +59,13 @@ typeset _OLDER_MONTH=""
 typeset _OLDER_YEAR=""
 typeset _NEWER_MONTH=""
 typeset _NEWER_YEAR=""
+typeset _HC_REPORT_CACHE_LAST_STUB="${STATE_PERM_DIR}/cache.report-last"
+typeset _HC_REPORT_CACHE_LAST_FILE=""
+typeset _HC_REPORT_CACHE_TODAY_FILE="${STATE_PERM_DIR}/cache.report-today"
+typeset _USE_CACHE=0
+typeset _CACHE_NOTE_BIT=""
 
-# set archive log stash
+# set archive log stash (never use cache files)
 if (( ARG_HISTORY > 0 )) || [[ -n "${ARG_OLDER}" ]] || [[ -n "${ARG_NEWER}" ]]
 then
     set +f  # file globbing must be on
@@ -148,10 +153,45 @@ then
         _HC_LAST_TIME=""
         _HC_LAST_STC=0
         _HC_LAST_FAIL_ID="-"
+        _USE_CACHE=0
+
+        # check for cache usage
+        if (( ARG_HISTORY == 0 ))
+        then
+            case "${HC_REPORT_CACHE_LAST}" in
+                Yes|yes|YES)
+                    _HC_REPORT_CACHE_LAST_FILE="${_HC_REPORT_CACHE_LAST_STUB}-${_HC_LAST}"
+                    # check if cache file exists
+                    if [[ -s "${_HC_REPORT_CACHE_LAST_FILE}" ]]
+                    then
+                        _LOG_STASH="${_HC_REPORT_CACHE_LAST_FILE}"
+                        _USE_CACHE=1
+                        (( ARG_DEBUG > 0 )) && debug "setting log stash to cache file at ${_HC_REPORT_CACHE_LAST_FILE}"
+                    else
+                        (( ARG_DEBUG > 0 )) && debug "HC_REPORT_CACHE_LAST is enabled but unable to find cache file at ${_HC_REPORT_CACHE_LAST_FILE}"
+                        # reset log stash to current log
+                        _LOG_STASH="${HC_LOG} ${_LOG_STASH}"
+                    fi
+                    ;;
+                *)
+                    # no caching: reset log stash to current log
+                    (( ARG_DEBUG > 0 )) && debug "HC_REPORT_CACHE_LAST is disabled"
+                    _LOG_STASH="${HC_LOG} ${_LOG_STASH}"
+                    ;;
+            esac
+        fi
+
+        # determine LAST_TIME from cache or log(s)
+        if (( ARG_HISTORY == 0 )) && (( _USE_CACHE > 1 ))
+        then
+            _HC_LAST_TIME="$(tail -n 1 ${_LOG_STASH} 2>/dev/null | cut -f1 -d${LOG_SEP} 2>/dev/null)"
+        else
             # find last event or block of events (same timestamp)
             # (but unfortunately this is only accurate to events within the SAME second!)
             # shellcheck disable=SC2086
             _HC_LAST_TIME="$(grep -h ${_HC_LAST} ${_LOG_STASH} 2>/dev/null | sort -n 2>/dev/null | cut -f1 -d${LOG_SEP} 2>/dev/null | uniq 2>/dev/null | tail -1 2>/dev/null)"
+        fi
+
         if [[ -z "${_HC_LAST_TIME}" ]]
         then
             _HC_LAST_TIME="-"
@@ -181,12 +221,26 @@ then
         fi
         # report on findings
         # shellcheck disable=SC1117
+        if (( _USE_CACHE > 0 ))
+        then
+            printf "| %-40s | %-20s | %-14s | %-4s (C)\n" \
+                "${_HC_LAST}" "${_HC_LAST_TIME}" "${_HC_LAST_FAIL_ID}" "${_HC_LAST_STC}"
+        else
             printf "| %-40s | %-20s | %-14s | %-4s\n" \
                 "${_HC_LAST}" "${_HC_LAST_TIME}" "${_HC_LAST_FAIL_ID}" "${_HC_LAST_STC}"
+        fi
     done
-    # disclaimer
+    # spacer
-    print "NOTE: this report only shows the overall combined status of all events of each HC within exactly"
+    print
-    print "      the *same* time stamp (seconds precise). It may therefore fail to report certain FAIL IDs."
+    # disclaimer & note(s)
+    if (( _USE_CACHE > 0 ))
+    then
+        print "NOTE: entries suffixed by (C) indicate results were retrieved from a cache file. If you wish to use "
+        print "      the real log files then disable HC_REPORT_CACHE_LAST in ${CONFIG_FILE}"
+    fi
+    (( ARG_HISTORY == 0 )) && _CACHE_NOTE_BIT="for non-cached entries: "
+    print "NOTE: ${_CACHE_NOTE_BIT}this report only shows the overall combined status of all events of each HC"
+    print "      within exactly the *same* time stamp (seconds precise). It may therefore fail to report certain FAIL IDs."
     print "      Use '--report' to get the exact list of failure events."
 # other reports
 else
@@ -198,7 +252,31 @@ else
         (( _IS_VALID_ID > 0 )) || die "invalid ID specified"
          _ID_NEEDLE="${ARG_FAIL_ID}"
     fi
-    (( ARG_TODAY > 0 )) && _ID_NEEDLE="$(date '+%Y%m%d')"    # refers to timestamp of HC FAIL_ID
+    # set today's needle and check cache usage
+    if (( ARG_TODAY > 0 ))
+    then
+        _ID_NEEDLE="$(date '+%Y%m%d')"    # refers to timestamp of HC FAIL_ID
+        # do not use a cache file when --with-history
+        if (( ARG_HISTORY == 0 ))
+        then
+            case "${HC_REPORT_CACHE_TODAY}" in
+                Yes|yes|YES)
+                    # check if cache file exists
+                    if [[ -s "${_HC_REPORT_CACHE_TODAY_FILE}" ]]
+                    then
+                        _LOG_STASH="${_HC_REPORT_CACHE_TODAY_FILE}"
+                        _USE_CACHE=1
+                        (( ARG_DEBUG > 0 )) && debug "setting log stash to today's cache file at ${_HC_REPORT_CACHE_TODAY_FILE}"
+                    else
+                        (( ARG_DEBUG > 0 )) && debug "HC_REPORT_CACHE_TODAY is enabled but unable to find cache file at ${_HC_REPORT_CACHE_TODAY_FILE}"
+                    fi
+                    ;;
+                *)
+                    (( ARG_DEBUG > 0 )) && debug "HC_REPORT_CACHE_TODAY is disabled"
+                    ;;
+            esac
+        fi
+    fi
 
     # reverse?
     if (( ARG_REVERSE == 0 ))
@@ -262,9 +340,9 @@ else
                         split (events[i], event, "|");
                         printf ("\n| %-20s | %-14s | %-40s | %-s", event[1], event[5], event[2], event[4]);
                     }
-                    printf ("\n\nSUMMARY: %s failed HC event(s) found.\n", event_count);
+                    printf ("\n\nSUMMARY: %s failed HC event(s) found.\n\n", event_count);
                 } else {
-                    printf ("\nSUMMARY: 0 failed HC events found.\n");
+                    printf ("\nSUMMARY: 0 failed HC events found.\n\n");
                 }
             }
             ' 2>/dev/null
@@ -316,14 +394,23 @@ else
         # shellcheck disable=SC2183,SC1117
         printf "%80s\n" | tr ' ' -
     fi
+
+    # add notes
+    # cache or not?
+    if (( _USE_CACHE > 0 ))
+    then
+        print "NOTE: results were retrieved from a cache file. If you wish to use the real log files then"
+        print "      remove ${_HC_REPORT_CACHE_TODAY_FILE} and/or disable HC_REPORT_CACHE_TODAY in ${CONFIG_FILE}"
+    fi
 fi
 
-# general note: history or not?
+# add general notes
+# history or not?
 if (( ARG_HISTORY > 0 ))
 then
     print "NOTE: showing results with all history (archive) included (--with-history)"
 else
-    print "NOTE: showing results only of current log entries (use --with-history to view all entries)"
+    print "NOTE: showing only results of current entries (use --with-history to view all entries)"
 fi
 
 # check consistency of log(s)