docs(log) http-log authentication and retries logging

Deals with Kong issue 2429: logging retries and failure info and 2430 for adding a basic auth header with the http log plugin
Kong · Apr 30, 2017 · d7be0cb · d7be0cb
1 parent 1d8ea33
commit d7be0cb
Show file tree

Hide file tree

Showing 6 changed files with 93 additions and 8 deletions.
diff --git a/app/plugins/file-log.md b/app/plugins/file-log.md
@@ -77,9 +77,21 @@ Every request will be logged separately in a JSON object separated by a new line
             "access-control-allow-origin": "*"
         }
     },
+    "tries": [
+        {
+            "state": "next",
+            "code": 502,
+            "ip": "127.0.0.1",
+            "port": 8000
+        },
+        {
+            "ip": "127.0.0.1",
+            "port": 8000
+        }
+    ],
     "authenticated_entity": {
         "consumer_id": "80f74eef-31b8-45d5-c525-ae532297ea8e",
-        "id": "eaa330c0-4cff-47f5-c79e-b2e4f355207e",
+        "id": "eaa330c0-4cff-47f5-c79e-b2e4f355207e"
     },
     "api": {
         "created_at": 1488830759000,
@@ -112,6 +124,7 @@ A few considerations on the above JSON object:
 
 * `request` contains properties about the request sent by the client
 * `response` contains properties about the response sent to the client
+* `tries` contains the list of (re)tries (successes and failures) made by the load balancer for this request
 * `api` contains Kong properties about the specific API requested
 * `authenticated_entity` contains Kong properties about the authenticated consumer (if an authentication plugin has been enabled)
 * `latencies` contains some data about the latencies involved:

diff --git a/app/plugins/http-log.md b/app/plugins/http-log.md
@@ -40,11 +40,15 @@ form parameter                  | default | description
 ---                             | ---     | ---
 `name`                          |         | The name of the plugin to use, in this case: `http-log`
 `consumer_id`<br>*optional*     |         | The CONSUMER ID that this plugin configuration will target. This value can only be used if [authentication has been enabled][faq-authentication] so that the system can identify the user making the request.
-`config.http_endpoint`          |         | The HTTP endpoint (including the protocol to use) where to send the data to
+`config.http_endpoint`          |         | The HTTP endpoint (including the protocol to use) to which the data will be sent.
 `config.method`<br>*optional*   | `POST`  | An optional method used to send data to the http server, other supported values are PUT, PATCH
 `config.timeout`<br>*optional*  | `10000` | An optional timeout in milliseconds when sending data to the upstream server
 `config.keepalive`<br>*optional*| `60000` | An optional value in milliseconds that defines for how long an idle connection will live before being closed
 
+**NOTE:** If the `config.http_endpoint` contains a username and password (ex.
+`http://bob:[email protected]/logs`), then Kong will automatically include
+a basic-auth `Authorization` header in the log requests.
+
 [api-object]: /docs/latest/admin-api/#api-object
 [configuration]: /docs/latest/configuration
 [consumer-object]: /docs/latest/admin-api/#consumer-object
@@ -83,9 +87,21 @@ Every request will be logged separately in a JSON object, with the following for
             "access-control-allow-origin": "*"
         }
     },
+    "tries": [
+        {
+            "state": "next",
+            "code": 502,
+            "ip": "127.0.0.1",
+            "port": 8000
+        },
+        {
+            "ip": "127.0.0.1",
+            "port": 8000
+        }
+    ],
     "authenticated_entity": {
         "consumer_id": "80f74eef-31b8-45d5-c525-ae532297ea8e",
-        "id": "eaa330c0-4cff-47f5-c79e-b2e4f355207e",
+        "id": "eaa330c0-4cff-47f5-c79e-b2e4f355207e"
     },
     "api": {
         "created_at": 1488830759000,
@@ -118,6 +134,7 @@ A few considerations on the above JSON object:
 
 * `request` contains properties about the request sent by the client
 * `response` contains properties about the response sent to the client
+* `tries` contains the list of (re)tries (successes and failures) made by the load balancer for this request
 * `api` contains Kong properties about the specific API requested
 * `authenticated_entity` contains Kong properties about the authenticated consumer (if an authentication plugin has been enabled)
 * `latencies` contains some data about the latencies involved:
@@ -129,4 +146,7 @@ A few considerations on the above JSON object:
 
 ## Kong Process Errors
 
-This logging plugin will only log HTTP request and response data. If you are looking for the Kong process error file (which is the nginx error file), then you can find it at the following path: {[prefix](/docs/{{site.data.kong_latest.release}}/configuration/#prefix)}/logs/error.log
+This logging plugin will only log HTTP request and response data. If you are
+looking for the Kong process error file (which is the nginx error file), then
+you can find it at the following path: 
+`{[prefix](/docs/{{site.data.kong_latest.release}}/configuration/#prefix)}/logs/error.log`.
diff --git a/app/plugins/loggly.md b/app/plugins/loggly.md
@@ -85,9 +85,21 @@ Every request will be transmitted to Loggly in [SYSLOG](https://en.wikipedia.org
             "access-control-allow-origin": "*"
         }
     },
+    "tries": [
+        {
+            "state": "next",
+            "code": 502,
+            "ip": "127.0.0.1",
+            "port": 8000
+        },
+        {
+            "ip": "127.0.0.1",
+            "port": 8000
+        }
+    ],
     "authenticated_entity": {
         "consumer_id": "80f74eef-31b8-45d5-c525-ae532297ea8e",
-        "id": "eaa330c0-4cff-47f5-c79e-b2e4f355207e",
+        "id": "eaa330c0-4cff-47f5-c79e-b2e4f355207e"
     },
     "api": {
         "created_at": 1488830759000,
@@ -120,6 +132,7 @@ A few considerations on the above JSON object:
 
 * `request` contains properties about the request sent by the client
 * `response` contains properties about the response sent to the client
+* `tries` contains the list of (re)tries (successes and failures) made by the load balancer for this request
 * `api` contains Kong properties about the specific API requested
 * `authenticated_entity` contains Kong properties about the authenticated consumer (if an authentication plugin has been enabled)
 * `latencies` contains some data about the latencies involved:

diff --git a/app/plugins/syslog.md b/app/plugins/syslog.md
@@ -80,9 +80,21 @@ Every request will be logged to System log in [SYSLOG](https://en.wikipedia.org/
             "access-control-allow-origin": "*"
         }
     },
+    "tries": [
+        {
+            "state": "next",
+            "code": 502,
+            "ip": "127.0.0.1",
+            "port": 8000
+        },
+        {
+            "ip": "127.0.0.1",
+            "port": 8000
+        }
+    ],
     "authenticated_entity": {
         "consumer_id": "80f74eef-31b8-45d5-c525-ae532297ea8e",
-        "id": "eaa330c0-4cff-47f5-c79e-b2e4f355207e",
+        "id": "eaa330c0-4cff-47f5-c79e-b2e4f355207e"
     },
     "api": {
         "created_at": 1488830759000,
@@ -115,6 +127,7 @@ A few considerations on the above JSON object:
 
 * `request` contains properties about the request sent by the client
 * `response` contains properties about the response sent to the client
+* `tries` contains the list of (re)tries (successes and failures) made by the load balancer for this request
 * `api` contains Kong properties about the specific API requested
 * `authenticated_entity` contains Kong properties about the authenticated consumer (if an authentication plugin has been enabled)
 * `latencies` contains some data about the latencies involved:

diff --git a/app/plugins/tcp-log.md b/app/plugins/tcp-log.md
@@ -83,9 +83,21 @@ Every request will be logged separately in a JSON object, separated by a new lin
             "access-control-allow-origin": "*"
         }
     },
+    "tries": [
+        {
+            "state": "next",
+            "code": 502,
+            "ip": "127.0.0.1",
+            "port": 8000
+        },
+        {
+            "ip": "127.0.0.1",
+            "port": 8000
+        }
+    ],
     "authenticated_entity": {
         "consumer_id": "80f74eef-31b8-45d5-c525-ae532297ea8e",
-        "id": "eaa330c0-4cff-47f5-c79e-b2e4f355207e",
+        "id": "eaa330c0-4cff-47f5-c79e-b2e4f355207e"
     },
     "api": {
         "created_at": 1488830759000,
@@ -118,6 +130,7 @@ A few considerations on the above JSON object:
 
 * `request` contains properties about the request sent by the client
 * `response` contains properties about the response sent to the client
+* `tries` contains the list of (re)tries (successes and failures) made by the load balancer for this request
 * `api` contains Kong properties about the specific API requested
 * `authenticated_entity` contains Kong properties about the authenticated consumer (if an authentication plugin has been enabled)
 * `latencies` contains some data about the latencies involved:

diff --git a/app/plugins/udp-log.md b/app/plugins/udp-log.md
@@ -81,9 +81,21 @@ Every request will be logged separately in a JSON object with the following form
             "access-control-allow-origin": "*"
         }
     },
+    "tries": [
+        {
+            "state": "next",
+            "code": 502,
+            "ip": "127.0.0.1",
+            "port": 8000
+        },
+        {
+            "ip": "127.0.0.1",
+            "port": 8000
+        }
+    ],
     "authenticated_entity": {
         "consumer_id": "80f74eef-31b8-45d5-c525-ae532297ea8e",
-        "id": "eaa330c0-4cff-47f5-c79e-b2e4f355207e",
+        "id": "eaa330c0-4cff-47f5-c79e-b2e4f355207e"
     },
     "api": {
         "created_at": 1488830759000,
@@ -116,6 +128,7 @@ A few considerations on the above JSON object:
 
 * `request` contains properties about the request sent by the client
 * `response` contains properties about the response sent to the client
+* `tries` contains the list of (re)tries (successes and failures) made by the load balancer for this request
 * `api` contains Kong properties about the specific API requested
 * `authenticated_entity` contains Kong properties about the authenticated consumer (if an authentication plugin has been enabled)
 * `latencies` contains some data about the latencies involved: