diff --git a/app/_hub/kong-inc/http-log/0.1-x.md b/app/_hub/kong-inc/http-log/0.1-x.md deleted file mode 100644 index 46d2e9ce13f4..000000000000 --- a/app/_hub/kong-inc/http-log/0.1-x.md +++ /dev/null @@ -1,207 +0,0 @@ ---- -name: HTTP Log -publisher: Kong Inc. -version: 0.1-x - -desc: Send request and response logs to an HTTP server -description: | - Send request and response logs to an HTTP server. - -
- Note: The functionality of this plugin as bundled - with versions of Kong prior to 0.10.2 differs from - what is documented herein. Refer to the - CHANGELOG - for details. -
- -type: plugin -categories: - - logging - -kong_version_compatibility: - community_edition: - compatible: - - 0.14.x - - 0.13.x - - 0.12.x - - 0.11.x - - 0.10.x - - 0.9.x - - 0.8.x - - 0.7.x - - 0.6.x - - 0.5.x - - 0.4.x - - 0.3.x - enterprise_edition: - compatible: - - 0.34-x - - 0.33-x - - 0.32-x - - 0.31-x - -params: - name: http-log - api_id: true - service_id: true - route_id: true - consumer_id: true - config: - - name: http_endpoint - required: true - default: - value_in_examples: http://mockbin.org/bin/:id - description: The HTTP endpoint (including the protocol to use) to which the data will be sent. - - name: method - required: false - default: "`POST`" - value_in_examples: POST - description: | - An optional method used to send data to the http server, other supported values are `PUT`, `PATCH` - - name: timeout - required: false - default: "`10000`" - value_in_examples: 1000 - description: An optional timeout in milliseconds when sending data to the upstream server - - name: keepalive - required: false - default: "`60000`" - value_in_examples: 1000 - description: An optional value in milliseconds that defines for how long an idle connection will live before being closed - extra: | - **NOTE:** If the `config.http_endpoint` contains a username and password (ex. - `http://bob:password@example.com/logs`), then Kong will automatically include - a basic-auth `Authorization` header in the log requests. - ---- - -## Log Format - -Every request will be logged separately in a JSON object, with the following format: - -```json -{ - "request": { - "method": "GET", - "uri": "/get", - "url": "http://httpbin.org:8000/get", - "size": "75", - "querystring": {}, - "headers": { - "accept": "*/*", - "host": "httpbin.org", - "user-agent": "curl/7.37.1" - }, - "tls": { - "version": "TLSv1.2", - "cipher": "ECDHE-RSA-AES256-GCM-SHA384", - "supported_client_ciphers": "ECDHE-RSA-AES256-GCM-SHA384", - "client_verify": "NONE" - } - }, - "upstream_uri": "/", - "response": { - "status": 200, - "size": "434", - "headers": { - "Content-Length": "197", - "via": "kong/0.3.0", - "Connection": "close", - "access-control-allow-credentials": "true", - "Content-Type": "application/json", - "server": "nginx", - "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" - }, - "route": { - "created_at": 1521555129, - "hosts": null, - "id": "75818c5f-202d-4b82-a553-6a46e7c9a19e", - "methods": null, - "paths": [ - "/example-path" - ], - "preserve_host": false, - "protocols": [ - "http", - "https" - ], - "regex_priority": 0, - "service": { - "id": "0590139e-7481-466c-bcdf-929adcaaf804" - }, - "strip_path": true, - "updated_at": 1521555129 - }, - "service": { - "connect_timeout": 60000, - "created_at": 1521554518, - "host": "example.com", - "id": "0590139e-7481-466c-bcdf-929adcaaf804", - "name": "myservice", - "path": "/", - "port": 80, - "protocol": "http", - "read_timeout": 60000, - "retries": 5, - "updated_at": 1521554518, - "write_timeout": 60000 - }, - "consumer": { - "username": "demo", - "created_at": 1491847011000, - "id": "35b03bfc-7a5b-4a23-a594-aa350c585fa8" - }, - "latencies": { - "proxy": 1430, - "kong": 9, - "request": 1921 - }, - "client_ip": "127.0.0.1", - "started_at": 1433209822425 -} -``` - -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 -* `route` contains Kong properties about the specific Route requested -* `service` contains Kong properties about the Service associated with the requested Route -* `authenticated_entity` contains Kong properties about the authenticated credential (if an authentication plugin has been enabled) -* `consumer` contains the authenticated Consumer (if an authentication plugin has been enabled) -* `latencies` contains some data about the latencies involved: - * `proxy` is the time it took for the final service to process the request - * `kong` is the internal Kong latency that it took to run all the plugins - * `request` is the time elapsed between the first bytes were read from the client and after the last bytes were sent to the client. Useful for detecting slow clients. -* `client_ip` contains the original client IP address -* `started_at` contains the UTC timestamp of when the request has started to be processed. - ----- - -## 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: -`$KONG_PREFIX/logs/error.log`, -where `$KONG_PREFIX` means -[prefix in the configuration](/gateway/latest/reference/configuration/#prefix). diff --git a/app/_hub/kong-inc/http-log/1.0.x.md b/app/_hub/kong-inc/http-log/1.0.x.md deleted file mode 100644 index ef719ba1552a..000000000000 --- a/app/_hub/kong-inc/http-log/1.0.x.md +++ /dev/null @@ -1,227 +0,0 @@ ---- -name: HTTP Log -publisher: Kong Inc. -version: 1.0.x - -desc: Send request and response logs to an HTTP server -description: | - Send request and response logs to an HTTP server. - -
- Note: The functionality of this plugin as bundled - with versions of Kong prior to 0.10.2 differs from - what is documented herein. Refer to the - CHANGELOG - for details. -
- -type: plugin -categories: - - logging - -kong_version_compatibility: - community_edition: - compatible: - - 1.5.x - - 1.4.x - - 1.3.x - - 1.2.x - - 1.1.x - - 1.0.x - - 0.14.x - - 0.13.x - - 0.12.x - - 0.11.x - - 0.10.x - - 0.9.x - - 0.8.x - - 0.7.x - - 0.6.x - - 0.5.x - - 0.4.x - - 0.3.x - enterprise_edition: - compatible: - - 1.5.x - - 1.3-x - - 0.36-x - - 0.35-x - - 0.34-x - - 0.33-x - - 0.32-x - - 0.31-x - -params: - name: http-log - service_id: true - route_id: true - consumer_id: true - protocols: ["http", "https", "grpc", "grpcs"] - dbless_compatible: yes - config: - - name: http_endpoint - required: true - default: - value_in_examples: http://mockbin.org/bin/:id - description: The HTTP endpoint (including the protocol to use) to which the data is sent. - - name: method - required: false - default: "`POST`" - value_in_examples: POST - description: | - An optional method used to send data to the HTTP server. Supported values are `POST` (default), `PUT`, and `PATCH`. - - name: timeout - required: false - default: "`10000`" - value_in_examples: 1000 - description: An optional timeout in milliseconds when sending data to the upstream server. - - name: keepalive - required: false - default: "`60000`" - value_in_examples: 1000 - description: An optional value in milliseconds that defines how long an idle connection will live before being closed. - extra: | - **NOTE:** If the `config.http_endpoint` contains a username and password (for example, - `http://bob:password@example.com/logs`), then Kong automatically includes - a basic-auth `Authorization` header in the log requests. - ---- - -## Log Format - -Every request is logged separately in a JSON object in the following format: - -```json -{ - "request": { - "method": "GET", - "uri": "/get", - "url": "http://httpbin.org:8000/get", - "size": "75", - "querystring": {}, - "headers": { - "accept": "*/*", - "host": "httpbin.org", - "user-agent": "curl/7.37.1" - }, - "tls": { - "version": "TLSv1.2", - "cipher": "ECDHE-RSA-AES256-GCM-SHA384", - "supported_client_ciphers": "ECDHE-RSA-AES256-GCM-SHA384", - "client_verify": "NONE" - } - }, - "upstream_uri": "/", - "response": { - "status": 200, - "size": "434", - "headers": { - "Content-Length": "197", - "via": "kong/0.3.0", - "Connection": "close", - "access-control-allow-credentials": "true", - "Content-Type": "application/json", - "server": "nginx", - "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" - }, - "route": { - "created_at": 1521555129, - "hosts": null, - "id": "75818c5f-202d-4b82-a553-6a46e7c9a19e", - "methods": null, - "paths": [ - "/example-path" - ], - "preserve_host": false, - "protocols": [ - "http", - "https" - ], - "regex_priority": 0, - "service": { - "id": "0590139e-7481-466c-bcdf-929adcaaf804" - }, - "strip_path": true, - "updated_at": 1521555129 - }, - "service": { - "connect_timeout": 60000, - "created_at": 1521554518, - "host": "example.com", - "id": "0590139e-7481-466c-bcdf-929adcaaf804", - "name": "myservice", - "path": "/", - "port": 80, - "protocol": "http", - "read_timeout": 60000, - "retries": 5, - "updated_at": 1521554518, - "write_timeout": 60000 - }, - "workspaces": [ - { - "id":"b7cac81a-05dc-41f5-b6dc-b87e29b6c3a3", - "name": "default" - } - ], - "consumer": { - "username": "demo", - "created_at": 1491847011000, - "id": "35b03bfc-7a5b-4a23-a594-aa350c585fa8" - }, - "latencies": { - "proxy": 1430, - "kong": 9, - "request": 1921 - }, - "client_ip": "127.0.0.1", - "started_at": 1433209822425 -} -``` - -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 tries and retries (successes and failures) made by the load balancer for the request. -* `route` contains Kong properties about the specific Route requested. -* `service` contains Kong properties about the Service associated with the requested Route. -* `authenticated_entity` contains Kong properties about the authenticated credential if an authentication plugin has been enabled. -* `workspaces` contains Kong properties of the Workspaces associated with the requested Route. **Only in Kong Gateway version >= 0.34**. -* `consumer` contains the authenticated Consumer if an authentication plugin has been enabled. -* `latencies` contains some data about the latencies involved: - * `proxy` is the time it took for the final service to process the request. - * `kong` is the internal Kong latency that it took to run all the plugins. - * `request` is the time elapsed between the first bytes were read from the client and after the last bytes were sent to the client. Useful for detecting slow clients. -* `client_ip` contains the original client IP address. -* `started_at` contains the UTC timestamp of when the request started to be processed. - ----- - -## Kong Process Errors - -This logging plugin only logs 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: - -`$KONG_PREFIX/logs/error.log` - -where `$KONG_PREFIX` means -[prefix in the configuration](/gateway/latest/reference/configuration/#prefix). diff --git a/app/_hub/kong-inc/http-log/2.0.x.md b/app/_hub/kong-inc/http-log/2.0.x.md deleted file mode 100644 index a128704d4aa4..000000000000 --- a/app/_hub/kong-inc/http-log/2.0.x.md +++ /dev/null @@ -1,137 +0,0 @@ ---- -name: HTTP Log -publisher: Kong Inc. -version: 2.0.x -# internal handler version 2.0.1 - -desc: Send request and response logs to an HTTP server -description: | - Send request and response logs to an HTTP server. - -type: plugin -categories: - - logging - -kong_version_compatibility: - community_edition: - compatible: - - 2.3.x - - 2.2.x - - 2.1.x - - 2.0.x - - 1.5.x - - 1.4.x - - 1.3.x - - 1.2.x - - 1.1.x - - 1.0.x - - 0.14.x - - 0.13.x - - 0.12.x - - 0.11.x - - 0.10.x - - 0.9.x - - 0.8.x - - 0.7.x - - 0.6.x - - 0.5.x - - 0.4.x - - 0.3.x - enterprise_edition: - compatible: - - 2.3.x - - 2.2.x - - 2.1.x - - 1.5.x - - 1.3-x - - 0.36-x - -params: - name: http-log - service_id: true - route_id: true - consumer_id: true - protocols: ["http", "https", "grpc", "grpcs", "tcp", "tls", "udp"] - dbless_compatible: yes - config: - - name: http_endpoint - required: true - default: - value_in_examples: http://mockbin.org/bin/:id - datatype: string - description: The HTTP URL endpoint (including the protocol to use) to which the data is sent. - - name: method - required: false - default: "`POST`" - value_in_examples: POST - datatype: string - description: | - An optional method used to send data to the HTTP server. Supported values are - `POST` (default), `PUT`, and `PATCH`. - - name: content_type - required: false - default: "`application/json`" - value_in_examples: - datatype: string - description: | - Indicates the type of data sent. The only available option is `application/json`. - - name: timeout - required: false - default: "`10000`" - value_in_examples: 1000 - datatype: number - description: An optional timeout in milliseconds when sending data to the upstream server. - - name: keepalive - required: false - default: "`60000`" - value_in_examples: 1000 - datatype: number - description: An optional value in milliseconds that defines how long an idle connection will live before being closed. - - name: flush_timeout - required: false - default: "`2`" - value_in_examples: 2 - datatype: number - description: | - Optional time in seconds. If `queue_size` > 1, this is the max idle time before sending a log with less than `queue_size` records. - - name: retry_count - required: false - default: 10 - value_in_examples: 15 - datatype: integer - description: Number of times to retry when sending data to the upstream server. - - name: queue_size - required: false - default: 1 - datatype: integer - description: Maximum number of log entries to be sent on each message to the upstream server. - - name: headers - required: false - default: empty table - datatype: array of string elements - description: | - An optional table of headers added to the HTTP message to the upstream server. The following - headers are not allowed: `Host`, `Content-Length`, `Content-Type`. - - **Note:** This parameter is only available for versions - 2.3.x and later. - extra: | - **NOTE:** If the `config.http_endpoint` contains a username and password (for example, - `http://bob:password@example.com/logs`), then Kong Gateway automatically includes - a basic-auth `Authorization` header in the log requests. - ---- - -## Log format - -**Note:** If the `queue_size` argument > 1, a request is logged as an array of JSON objects. - -{% include /md/plugins-hub/log-format.md %} - -### JSON object considerations - -{% include /md/plugins-hub/json-object-log.md %} - -## Kong process errors - -{% include /md/plugins-hub/kong-process-errors.md %} diff --git a/app/_hub/kong-inc/http-log/_index.md b/app/_hub/kong-inc/http-log/_index.md index 239bef86941d..ff792272a49e 100644 --- a/app/_hub/kong-inc/http-log/_index.md +++ b/app/_hub/kong-inc/http-log/_index.md @@ -1,7 +1,6 @@ --- name: HTTP Log publisher: Kong Inc. -version: 2.1.x desc: Send request and response logs to an HTTP server description: | Send request and response logs to an HTTP server. @@ -45,7 +44,12 @@ params: value_in_examples: 'http://mockbin.org/bin/:id' datatype: string encrypted: true - description: The HTTP URL endpoint (including the protocol to use) to which the data is sent. + description: | + The HTTP URL endpoint (including the protocol to use) to which the data is sent. + + If the `http_endpoint` contains a username and password (for example, + `http://bob:password@example.com/logs`), then Kong Gateway automatically includes + a basic-auth `Authorization` header in the log requests. - name: method required: false default: '`POST`' @@ -91,20 +95,37 @@ params: default: 1 datatype: integer description: Maximum number of log entries to be sent on each message to the upstream server. + + # ----- Old version of the 'headers' parameter ----- - name: headers required: false default: empty table - datatype: array of string elements + datatype: table description: | - An optional table of headers added to the HTTP message to the upstream server. The following - headers are not allowed: `Host`, `Content-Length`, `Content-Type`. - - **Note:** This parameter is only available for versions - 2.3.x and later. - extra: | - **NOTE:** If the `config.http_endpoint` contains a username and password (for example, - `http://bob:password@example.com/logs`), then Kong Gateway automatically includes - a basic-auth `Authorization` header in the log requests. + + An optional table of headers added to the HTTP message to the upstream server. + The table contains arrays of values, indexed by the header name (multiple values per header). + + The following headers are not allowed: `Host`, `Content-Length`, `Content-Type`. + + minimum_version: "2.3.x" + maximum_version: "2.8.x" + # --------------------------------------------------- + + - name: headers + required: false + default: empty table + datatype: table + description: | + An optional table of headers included in the HTTP message to the + upstream server. Values are indexed by header name, and each header name + accepts a single string. + + The following headers are not allowed: `Host`, `Content-Length`, `Content-Type`. + + > **Note:** Before version 3.0.0, the values were arrays of strings (multiple values per header name). + + minimum_version: "3.0.x" - name: custom_fields_by_lua required: false default: @@ -113,11 +134,13 @@ params: A list of key-value pairs, where the key is the name of a log field and the value is a chunk of Lua code, whose return value sets or replaces the log field value. + minimum_version: "2.4.x" --- ## Log format -**Note:** If the `queue_size` argument > 1, a request is logged as an array of JSON objects. +{:.note} +> **Note:** If the `queue_size` argument > 1, a request is logged as an array of JSON objects. {% include /md/plugins-hub/log-format.md %} @@ -126,6 +149,8 @@ params: {% include /md/plugins-hub/json-object-log.md %} +{% if_plugin_version gte:2.3.x %} + ## Custom Headers The log server that receives these messages might require extra headers, such as for authorization purposes. @@ -139,19 +164,52 @@ The log server that receives these messages might require extra headers, such as ... ``` +{% endif_plugin_version %} + ## Kong process errors {% include /md/plugins-hub/kong-process-errors.md %} + +{% if_plugin_version gte:2.4.x %} + ## Custom Fields by Lua {% include /md/plugins-hub/log_custom_fields_by_lua.md %} +{% endif_plugin_version %} + --- +{% if_plugin_version gte:2.3.x %} ## Changelog -### 2.2.1 +{% if_plugin_version gte:3.0.x %} + +### Kong Gateway 3.0.x + +* The `headers` parameter now takes a single string per header name, where it +previously took an array of values. + +{% endif_plugin_version %} +{% if_plugin_version gte:2.7.x %} + +### Kong Gateway 2.7.x + +* If keyring encryption is enabled, the `config.http_endpoint` parameter value +will be encrypted. + +{% endif_plugin_version %} +{% if_plugin_version gte:2.3.x %} + +### Kong Gateway 2.4.x + +* Added the `custom_fields_by_lua` parameter. + +{% endif_plugin_version %} + +### Kong Gateway 2.3.x + +* Custom headers can now be specified for the log request using the `headers` parameter. -* Starting with {{site.base_gateway}} 2.7.0.0, if keyring encryption is enabled, - the `config.http_endpoint` parameter value will be encrypted. +{% endif_plugin_version %} diff --git a/app/_hub/kong-inc/http-log/versions.yml b/app/_hub/kong-inc/http-log/versions.yml index 28b8d91826b3..0be35db98e9a 100644 --- a/app/_hub/kong-inc/http-log/versions.yml +++ b/app/_hub/kong-inc/http-log/versions.yml @@ -1,4 +1,12 @@ -- release: 2.1.x -- release: 2.0.x -- release: 1.0.x -- release: 0.1-x +strategy: gateway +delegate_releases: true + +overrides: + 2.8.x: 2.1.x + 2.7.x: 2.1.x + 2.6.x: 2.1.x + 2.5.x: 2.1.x + 2.4.x: 2.1.x + 2.3.x: 2.0.x + 2.2.x: 2.0.x + 2.1.x: 2.0.x