check_http update docs

check_http

@@ -34,9 +34,9 @@ Additionally you can verify the response by
 SYNTAX:
   $_self [-h]
   $_self [-m METHOD] -u URL [-c PARAMS]\\
-      [-b REGEX] [-j FILTER] [-n REGEX] \\ 
-      [-r REGEX] \\
+      [-j FILTER] \\ 
       [-s STATUSCODE] \\
+      [-b REGEX] [-n REGEX] [-r REGEX] \\
       [-l LABEL]
 
 OPTIONS:
@@ -51,17 +51,19 @@ PARAMETERS:
   -c PARAMS        additional curl params; curl will be executed 
                    with '[PARAMS] -si -X [METHOD] --connect-timeout 10 [URL]'
 
+  Filtering:
+  -j JQ-FILTER     for JSON Response: filter response body by jq
+
   What to check:
   -s STATUSCODE    exact Statuscode to check; 3 digits; by default critical
                    is a statuscode greater equal 400
   -r REGEX         Regex must match in http response header
-  -j JQ-FILTER     for JSON Response: filter data by a jq
   -b REGEX         Regex must match in response body
   -n REGEX         Regex must NOT match in response body
 
   Output:
   -l LABEL         set a custom label; default: METHOD + URL eg.
-                   "GET https://example.com/status"
+                   "GET https://example.com/status (200)"
 
 EXAMPLES:
 

docs/20_Checks/check_http.md

@@ -7,7 +7,8 @@ Additionally you can verify the response.
 
 ## Requirements
 
-* `curl` binary
+* ``curl`` - a tool for transferring data from or to a server
+* ``jq`` - commandline JSON processor - optional: for param ``-j``
 
 ## Syntax
 
@@ -32,10 +33,10 @@ Additionally you can verify the response by
 
 SYNTAX:
   check_http [-h]
-  check_http [-m METHOD] -u URL \
-      [-b REGEX] [-j FILTER] [-n REGEX] \ 
-      [-r REGEX] \
+  check_http [-m METHOD] -u URL [-c PARAMS]\
+      [-j FILTER] \ 
       [-s STATUSCODE] \
+      [-b REGEX] [-n REGEX] [-r REGEX] \
       [-l LABEL]
 
 OPTIONS:
@@ -50,17 +51,19 @@ PARAMETERS:
   -c PARAMS        additional curl params; curl will be executed 
                    with '[PARAMS] -si -X [METHOD] --connect-timeout 10 [URL]'
 
+  Filtering:
+  -j JQ-FILTER     for JSON Response: filter response body by jq
+
   What to check:
   -s STATUSCODE    exact Statuscode to check; 3 digits; by default critical
                    is a statuscode greater equal 400
   -r REGEX         Regex must match in http response header
-  -j JQ-FILTER     for JSON Response: filter data by a jq
   -b REGEX         Regex must match in response body
   -n REGEX         Regex must NOT match in response body
 
   Output:
   -l LABEL         set a custom label; default: METHOD + URL eg.
-                   "GET https://example.com/status"
+                   "GET https://example.com/status (200)"
 
 EXAMPLES:
 
@@ -137,3 +140,41 @@ Or you can check a flag file that must be absent.
 You can verify if the response matches a given regex. You can search in the response header with ``-r REGEX`` and in the response body with ``-b REGEX``.
 
 ``check_http -u [URL] -b "contact"`` will resppns OK if the status code is not an error (lower 400) and the word "contact" is found in response body.
+
+### JSON filtering
+
+With the parameter ``-j JQ-FILTER`` the jq command will be applied on the response body.
+Whenever you add ``-j`` a search in the body with params ``-b REGEX`` and ``-n REGEX`` won't be applied to the complete response body but on the result after filtering with jq. So you can build API checks that respond a json structure.
+
+Keycloak responds on its health url
+
+```txt
+$ curl -k https://keycloak.example.com:8443/health 
+{
+    "status": "UP",
+    "checks": [
+    ]
+}
+```
+
+First test a filter string on command line
+
+``curl -k https://keycloak.example.com:8443/health | jq ".status"``
+
+Its result is just "UP" - all other json stuff is blown away.
+This filter we put into the ``-j`` param:
+
+`` ./check_http -u "https://keycloak.example.com:8443/health" -j ".status" -b "UP" `` returns
+
+```txt
+OK: GET https://keycloak.example.com:8443/health (200)
+
+Found:
+- jq filter [.status] matches.
+- Http status is a 2xx OK [200];
+- [UP] was found in body;
+
+Hints:
+Content aufter jq filter: "UP"
+
+```