Merge branch '6468-docs-and-harmonize' into 'master'

6468 docs and harmonize - check_php-fpm-status

See merge request !142

check_php-fpm-status

@@ -13,12 +13,15 @@
 # 2022-04-01  v0.6  <axel.hahn@iml.unibe.ch>  use wget default params; shell fixes
 # 2022-05-09  v0.7  <axel.hahn@iml.unibe.ch>  use wget default params
 # 2022-07-08  v0.8  <axel.hahn@iml.unibe.ch>  eliminate division by 0
-# 2022-10-21  v1.3  <axel.hahn@unibe.ch>      remove grep: warning: stray \ before white space
+# 2022-10-21  v1.0  <axel.hahn@unibe.ch>      remove grep: warning: stray \ before white space
+# 2023-08-24  v1.1  <axel.hahn@unibe.ch>      update help; do not use tmp file anymore
 # ======================================================================
 
 . $( dirname $0 )/inc_pluginfunctions
 
-tmpfile=/tmp/check_fpm_processes_1
+export self_APPVERSION=1.1
+
+outFpmStatus=
 defaulturl=localhost/status
 
 sDeltaunit="min"
@@ -29,16 +32,16 @@ sDeltaunit="min"
 
 # get service data from json output
 function _getServicedata(){
-    cat $tmpfile | jq | grep '^  "' | grep -v "\[" | cut -f 1 -d ","
+    echo "$outFpmStatus" | jq | grep '^  "' | grep -v "\[" | cut -f 1 -d ","
 }
 
 function _getWorkerStates(){
-    cat $tmpfile | jq | grep '"state": ' | cut -f 2 -d ":" | cut -f 1 -d "," | sort -u
+    echo "$outFpmStatus" | jq | grep '"state": ' | cut -f 2 -d ":" | cut -f 1 -d "," | sort -u
 }
 
 
 function _getWorkerOfState(){
-    cat $tmpfile | jq -c ".processes[] | select(.state == \"$1\" )"
+    echo "$outFpmStatus" | jq -c ".processes[] | select(.state == \"$1\" )"
 }
 
 # get a value from fpm status
@@ -61,7 +64,6 @@ function _getWorkerOfState(){
 #
 # param  string  variable (part before ":")
 function _getvalue(){
-        # grep "^$1:" $tmpfile | cut -d ":" -f 2 | awk '{ print $1 }'
         _getServicedata | grep "^  \"$1\":" | cut -d ":" -f 2 | awk '{ print $1 }'
 }
 
@@ -69,14 +71,7 @@ function _getvalue(){
 function showHelp(){
     local _self=$(basename $0)
 cat <<EOF
-______________________________________________________________________
-
-CHECK_PHP-FPM-Status
-Get counters from PHP-FPM status output for active/ idle processes.
-
-(c) Institute for Medical Education - University of Bern
-Licence: GNU GPL 3
-______________________________________________________________________
+$( ph.showImlHelpHeader )
 
 The check fetches several counters from php-fm-status page.
 
@@ -141,11 +136,14 @@ url=$( ph.getValueWithParam $defaulturl u "$@" )
 
 paramsWget="-T 5 -t 1 --no-check-certificate"
 
-# --- get /server-status page
-wget $paramsWget -O $tmpfile "$url?full&json" 2>/dev/null
-if [ $? -ne 0 ]; then
-   rm -f $tmpfile
-   ph.abort "UNKNOWN: request to url $url failed. $(wget $paramsWget -O - -S $url)"
+# --- get fpm status page
+if ! outFpmStatus=$( wget $paramsWget -O - "$url?full&json" 2>/dev/null ); then
+    
+   ph.abort "UNKNOWN: request to url '$url' failed.
+
+   DEBUG: repeating the request showing header and STDERR
+   $( wget $paramsWget -O - -S $url 2>&1 )"
+   
 fi
 
 # ----------------------------------------------------------------------
@@ -180,32 +178,13 @@ typeset -i iWorkerIdle=$(    _getWorkerOfState "Idle"            | wc -l )
 # ----------------------------------------------------------------------
 # set status
 # ----------------------------------------------------------------------
-# damn, count of slots is in the config only - not in status output
-# iUsage=$iActive*100/$iSlots
-# ph.setStatusByLimit $iUsage $iWarnLimit $iCriticalLimit
-if [ $iQueue -gt 0 ]; then
-    ph.setStatus warning
-fi
 
-# remove switch to warning level if just one slow request was detected
-# if [ $iSlow -gt 0 ]; then
-#     ph.setStatus warning
-# fi
+# something queued and waiting for a free worker?
+test $iQueue -gt 0 &&  ph.setStatus warning
 
-# 5601 - remove warning for this limit (it is a flag and won't remove)
-# if [ $iMaxChilds -gt 0 ]; then
-#     # ph.setStatus critical
-#     ph.setStatus warning
-# fi
+# free worker down to 0?
+test $iWorkerIdle -eq 0 && ph.setStatus warning
 
-if [ $iWorkerIdle -eq 0 ]; then
-    ph.setStatus warning
-fi
-
-# seems not to be useful
-# if [ $iWorkerReading -eq 0 ]; then
-#     ph.setStatus warning
-# fi
 
 # ----------------------------------------------------------------------
 # output
@@ -242,7 +221,7 @@ fi
 #     echo
 # fi
 if [ $iQueue -gt 0 ]; then
-    echo $hint
+    echo "$hint"
     echo "WARNING: $iQueue queued requests were found. Maximum of queued items is $iMaxQueue (since last start of fpm service)."
     echo
 fi
@@ -275,8 +254,6 @@ ph.perfadd "php-fpm-idle"      "${iWorkerIdle}"      "" "" 0 0
 ph.perfadd "php-fpm-running"   "${iWorkerRunning}"   "" "" 0 0
 ph.perfadd "php-fpm-reading"   "${iWorkerReading}"   "" "" 0 0
 
-
-rm -f $tmpfile
 ph.exit
 
 # ----------------------------------------------------------------------

docs/20_Checks/_index.md

@@ -31,8 +31,8 @@ There is one include script used by all checks:
 * [check_onehost](check_onehost.md)
 * [check_onevm](check_onevm.md)
 * [check_opencpu](check_opencpu.md)
-* [check_packages2install](check_packages2install)
-* check_php-fpm-status
+* [check_packages2install](check_packages2install.md)
+* [check_php-fpm-status](check_php-fpm-status.md)
 * check_proc_mem
 * check_proc_ressources
 * check_proc_zombie

docs/20_Checks/check_php-fpm-status.md

+# check_php-fpm-status
+
+## Introduction
+
+The check fetches several counters from php-fm-status page.
+
+### Requirements
+
+* wget
+* running PHP FPM service
+* enabled status page
+
+
+To enable a status page as http://localhost/fpm-status.php
+
+* Set pm.status_path in your pool config eg. /etc/php/8.1/fpm/pool.d/www.conf
+
+```txt
+[www]
+pm.status_path = /fpm-status.php
+```
+
+* In your webservice config limit the access; here a snippet for Apache 2.4:
+
+```txt
+<Location /fpm-status.php>
+  Require local
+</Location>
+```
+
+
+## Syntax
+
+```text
+> check_php-fpm-status -h
+______________________________________________________________________
+
+CHECK_PHP-FPM-STATUS
+v1.1
+
+(c) Institute for Medical Education - University of Bern
+Licence: GNU GPL 3
+
+https://os-docs.iml.unibe.ch/icinga-checks/Checks/check_php-fpm-status.html
+______________________________________________________________________
+
+The check fetches several counters from php-fm-status page.
+
+It shows a short service status in a single line and then the dump of the 
+status page.
+For performance data it echos:
+
+    php-fpm-active     count of active workers (="Rrunning" + "Reading headers")
+    php-fpm-maxactive  max active processes (sum of idle + running + reading)
+    php-fpm-idle       count of workers in state "Idle"
+    php-fpm-running    count of workers in state "Running"
+    php-fpm-reading    count of workers in state "Reading headers"
+    php-fpm-queue      count of items in the queue
+    php-fpm-maxqueue   max listen queue
+    php-fpm-slow       slow requests per min (since last execution of this check)
+    php-fpm-speed      requests per min (since last execution of this check)
+
+SYNTAX:
+check_php-fpm-status [-u URL]
+
+OPTIONS:
+
+    -u  url to fpm status page  (optional; default: localhost/status)
+    -h or --help   show this help.
+
+PARAMETERS:
+
+    None.
+
+EXAMPLE:
+check_php-fpm-status -u http://localhost/my-custom-fpm-statuspage.php
+
+```
+
+## Examples
+
+
+`./check_php-fpm-status -u localhost/fpm-status.php` returns
+
+```txt
+OK: PHP-FPM service: running: 1 .. active: 2 (max: 5) .. idle workers: 3 .. queue: 0 .. speed: 1 req per min ... slow: 0 req per min (0%; total: 0)
+Workers:               Running: 1
+               Reading headers: 1
+                          Idle: 3
+
+  Waiting for a worker (queue): 0 (max: 0)
+
+--- Status of service
+  "pool": "www"
+  "process manager": "dynamic"
+  "start time": 1692402233
+  "start since": 479084
+  "accepted conn": 10960
+  "listen queue": 0
+  "max listen queue": 0
+  "listen queue len": 0
+  "idle processes": 3
+  "active processes": 2
+  "total processes": 5
+  "max active processes": 5
+  "max children reached": 0
+  "slow requests": 0
+
+--- workers in state Running
+{"pid":588192,"state":"Running","start time":1692856027,"start since":25290,"requests":197,"request duration":42053467,"request method":"GET","request uri":"/fpm-status.php?full&json","content length":0,"user":"-","script":"-","last request cpu":0,"last request memory":0}
+
+ |php-fpm-active=2;;;0;0 php-fpm-maxactive=5;;;0;0 php-fpm-queue=0;;;0;0 php-fpm-maxqueue=0;;;0;0 php-fpm-slow=0;;;0;0 php-fpm-speed=1;;;0;0 php-fpm-idle=3;;;0;0 php-fpm-running=1;;;0;0 php-fpm-reading=1;;;0;0 
+ ```