You are browsing documentation for an outdated plugin version.
Looking for the plugin's configuration parameters? You can find them in the TCP Log configuration reference doc.
Log request and response data to a TCP server.
Log format
Every request is logged separately in a JSON object, separated by a new line \n
, with the following format:
{
"response": {
"size": 9982,
"headers": {
"access-control-allow-origin": "*",
"content-length": "9593",
"date": "Thu, 19 Sep 2024 22:10:39 GMT",
"content-type": "text/html; charset=utf-8",
"via": "1.1 kong/3.8.0.0-enterprise-edition",
"connection": "close",
"server": "gunicorn/19.9.0",
"access-control-allow-credentials": "true",
"x-kong-upstream-latency": "171",
"x-kong-proxy-latency": "1",
},
"status": 200
},
"route": {
"updated_at": 1726782477,
"tags": [],
"response_buffering": true,
"path_handling": "v0",
"protocols": [
"http",
"https"
],
"service": {
"id": "fb4eecf8-dec2-40ef-b779-16de7e2384c7"
},
"https_redirect_status_code": 426,
"regex_priority": 0,
"name": "example_route",
"id": "0f1a4101-3327-4274-b1e4-484a4ab0c030",
"strip_path": true,
"preserve_host": false,
"created_at": 1726782477,
"request_buffering": true,
"ws_id": "f381e34e-5c25-4e65-b91b-3c0a86cfc393",
"paths": [
"/example-route"
]
},
"workspace": "f381e34e-5c25-4e65-b91b-3c0a86cfc393",
"tries": [
{
"balancer_start": 1726783839539,
"balancer_start_ns": 1.7267838395395e+18,
"ip": "34.237.204.224",
"balancer_latency": 0,
"port": 80,
"balancer_latency_ns": 27904
}
],
"client_ip": "192.168.65.1",
"request": {
"headers": {
"accept": "*/*",
"user-agent": "HTTPie/3.2.3",
"host": "localhost:8000",
"connection": "keep-alive",
"accept-encoding": "gzip, deflate"
},
"uri": "/example-route",
"size": 139,
"method": "GET",
"querystring": {},
"url": "http://localhost:8000/example-route"
},
"started_at": 1726783839538,
"upstream_status": "200",
"latencies": {
"kong": 1,
"proxy": 171,
"request": 173,
},
"service": {
"write_timeout": 60000,
"read_timeout": 60000,
"updated_at": 1726782459,
"host": "httpbin.konghq.com",
"name": "example_service",
"id": "fb4eecf8-dec2-40ef-b779-16de7e2384c7",
"port": 80,
"enabled": true,
"created_at": 1726782459,
"protocol": "http",
"ws_id": "f381e34e-5c25-4e65-b91b-3c0a86cfc393",
"connect_timeout": 60000,
"retries": 5
}
}
Log format definitions
-
service
: Properties about the service associated with the requested route. -
route
: Properties about the specific route requested. -
request
: Properties about the request sent by the client. -
response
: Properties about the response sent to the client. -
latencies
: Latency data.-
kong
: The internal Kong Gateway latency, in milliseconds, that it takes to process the request. It varies based on the actual processing flow. Generally, it consists of three parts:- The time it took to find the right upstream.
- The time it took to receive the whole response from upstream.
- The time it took to run all plugins executed before the log phase.
-
request
: The time in milliseconds that has elapsed between when the first bytes were read from the client and the last byte was sent to the client. This is useful for detecting slow clients. -
proxy
: The time in milliseconds that it took for the upstream to process the request. In other words, it’s the time elapsed between transferring the request to the final service and when Kong Gateway starts receiving the response.
-
-
tries
: a list of iterations made by the load balancer for this request.-
balancer_start
: A Unix timestamp for when the balancer started. -
ip
: The IP address of the contacted balancer. -
port
: The port number of the contacted balancer. -
balancer_latency
: The latency of the balancer expressed in milliseconds.
-
-
client_ip
: The original client IP address. -
workspace
: The UUID of the workspace associated with this request. -
upstream_uri
: The URI, including query parameters, for the configured upstream. -
authenticated_entity
: Properties about the authenticated credential (if an authentication plugin has been enabled). -
consumer
: The authenticated consumer (if an authentication plugin has been enabled). -
started_at
: The unix timestamp of when the request has started to be processed.
Log plugins enabled on services and routes contain information about the service or route.
Kong process errors
This logging plugin logs HTTP request and response data, and also supports stream data (TCP, TLS, and UDP).
The Kong process error file is the Nginx error file. You can find it at the following path:
{prefix}/logs/error.log
Configure the prefix in
kong.conf
.
Custom fields by Lua
The custom_fields_by_lua
configuration allows for the dynamic modification of
log fields using Lua code. Below is a snippet of an example configuration that
removes the route
field from the logs:
curl -i -X POST http://localhost:8001/plugins \
...
--data config.custom_fields_by_lua.route="return nil"
Similarly, new fields can be added:
curl -i -X POST http://localhost:8001/plugins \
...
--data config.custom_fields_by_lua.header="return kong.request.get_header('h1')"
Plugin precedence and managing fields
All logging plugins use the same table for logging.
If you set custom_fields_by_lua
in one plugin, all logging plugins that execute after that plugin will also use the same configuration.
For example, if you configure fields via custom_fields_by_lua
in File Log, those same fields will appear in Kafka Log, since File Log executes first.
If you want all logging plugins to use the same configuration, we recommend using the Pre-function plugin to call kong.log.set_serialize_value so that the function is applied predictably and is easier to manage.
If you don’t want all logging plugins to use the same configuration, you need to manually disable the relevant fields in each plugin.
For example, if you configure a field in File Log that you don’t want appearing in Kafka Log, set that field to return nil
in the Kafka Log plugin:
curl -i -X POST http://localhost:8001/plugins/ \
...
--data config.name=kafka-log \
--data config.custom_fields_by_lua.my_file_log_field="return nil"
See the plugin execution order reference for more details on plugin ordering.
Limitations
Lua code runs in a restricted sandbox environment, whose behavior is governed
by the untrusted_lua
configuration properties configuration
properties.
Sandboxing consists of several limitations in the way the Lua code can be executed, for heightened security.
The following functions are not available because they can be used to abuse the system:
-
string.rep
: Can be used to allocate millions of bytes in one operation. -
{set|get}metatable
: Can be used to modify the metatables of global objects (strings, numbers). -
collectgarbage
: Can be abused to kill the performance of other workers. -
_G
: Is the root node which has access to all functions. It is masked by a temporary table. -
load{file|string}
: Is deemed unsafe because it can grant access to the global environment. -
raw{get|set|equal}
: Potentially unsafe because sandboxing relies on some metatable manipulation. -
string.dump
: Can display confidential server information (such as implementation of functions). -
math.randomseed
: Can affect the host system. Kong Gateway already seeds the random number generator properly. - All
os.*
(exceptos.clock
,os.difftime
, andos.time
).os.execute
can significantly alter the host system. -
io.*
: Provides access to the hard drive. -
dofile|require
: Provides access to the hard drive.
The exclusion of require
means that plugins must only use PDK functions kong.*
. The ngx.*
abstraction is
also available, but it is not guaranteed to be present in future versions of the plugin.
In addition to the above restrictions:
- All the provided modules (like
string
ortable
) are read-only and can’t be modified. -
Bytecode execution is disabled.
- The
kong.cache
points to a cache instance that is dedicated to the Serverless Functions plugins. It does not provide access to the global Kong Gateway cache. It only exposes theget
method. Explicit write operations likeset
orinvalidate
are not available.
Further, as code runs in the context of the log phase, only PDK methods that can run in said phase can be used.