You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
// Licensed under the Apache Software License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
5
+
////
6
+
7
+
:_mod-docs-content-type: CONCEPT
8
+
9
+
// file included in the following:
10
+
//
11
+
// assembly-proxy-monitoring.adoc
12
+
13
+
[id='con-proxy-structured-log-fields-{context}']
14
+
= Structured log fields
15
+
16
+
[role="_abstract"]
17
+
18
+
Kroxylicious uses structured logging, attaching context as key-value pairs that are visible in both text and JSON output.
19
+
In text format, they appear at the end of each log line.
20
+
In JSON format, they appear as top-level fields.
21
+
22
+
The following table lists commonly emitted fields.
23
+
24
+
.Structured log fields
25
+
[cols="1,3",options="header"]
26
+
|===
27
+
|Field |Description
28
+
29
+
|`sessionId`
30
+
|Unique identifier for the client-to-proxy connection. Use this field to correlate all log messages for a single client session.
31
+
32
+
|`clientId`
33
+
|The Kafka `client.id` value supplied by the connecting Kafka client.
34
+
35
+
|`apiKey`
36
+
|The Kafka API key that identifies the request type (for example, `Produce`, `Fetch`, `Metadata`).
37
+
38
+
|`apiVersion`
39
+
|The Kafka API version used in the request.
40
+
41
+
|`kekRef`
42
+
|Reference to the Key Encryption Key (KEK) used by the Record Encryption filter. This field is emitted only when the Record Encryption filter is configured with the HashiCorp Vault KMS provider.
43
+
44
+
|`error`
45
+
|Error message associated with a failure condition. This field is emitted across the proxy runtime, filters, and KMS providers when an error is encountered.
Copy file name to clipboardExpand all lines: kroxylicious-docs/docs/_modules/monitoring/proc-proxy-setting-log-levels.adoc
+62-22Lines changed: 62 additions & 22 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -18,44 +18,82 @@
18
18
19
19
The Kroxylicious {github-release}[binary distribution^] includes https://logging.apache.org/log4j/2.x[log4j2] as the default logging backend.
20
20
21
-
When using the `bin/kroxylicious-start.sh` script from the binary distribution, you can set an environment variable to load a custom `log4j2` configuration file or change the root logging level.
22
-
23
-
.Environment variable to load a custom `log4j2` file
21
+
When you use the `bin/kroxylicious-start.sh` script from the binary distribution, you can configure logging behavior using the following environment variables.
|JSON layout template used when `KROXYLICIOUS_LOG_FORMAT=json`. For example, use `classpath:EcsLayout.json` for Elastic Common Schema or `classpath:GelfLayout.json` for GELF format.
47
+
48
+
|`KROXYLICIOUS_LOGGING_OPTIONS`
49
+
|(built-in defaults)
50
+
|Any valid log4j2 JVM system properties.
51
+
|Overrides the entire set of log4j2 JVM system properties. When set, the default `-Dlog4j2.configurationFile` and `-Dlog4j2.contextSelector` options are replaced. You must include all required options explicitly.
52
+
|===
53
+
54
+
The following examples show how to set the application log level and configure a custom Log4j2 configuration.
NOTE: Setting the root log level to `DEBUG` or `TRACE` will produce very verbose logs.
71
+
WARNING: Setting `KROXYLICIOUS_LOGGING_OPTIONS` replaces the built-in defaults.
72
+
Always include `-Dlog4j2.contextSelector=org.apache.logging.log4j.core.async.AsyncLoggerContextSelector` to preserve asynchronous logging.
36
73
37
74
[id='proc-proxy-json-log-format-{context}']
38
75
== Switching to JSON log format
39
76
40
-
By default, Kroxylicious outputs logs in human-readable text format. You can switch to structured JSON output for integration with log aggregation systems.
77
+
By default, Kroxylicious outputs logs in human-readable text format.
78
+
You can switch to structured JSON output to integrate with log aggregation systems such as the Elastic Stack (ELK) or Splunk.
79
+
80
+
The JSON format uses https://logging.apache.org/log4j/2.x/manual/json-template-layout.html[Log4j2's JsonTemplateLayout] with the Logstash JSON Event V1 format.
81
+
Structured context fields emitted by Kroxylicious appear as top-level fields alongside standard log metadata.
41
82
42
83
.Procedure
43
84
44
-
. Set the `KROXYLICIOUS_LOG_FORMAT` environment variable:
85
+
. Set the `KROXYLICIOUS_LOG_FORMAT` environment variable before starting the proxy:
45
86
+
46
87
[source,bash]
47
88
----
48
89
export KROXYLICIOUS_LOG_FORMAT=json
49
-
----
50
-
51
-
. Start Kroxylicious:
52
-
+
53
-
[source,bash]
54
-
----
55
90
bin/kroxylicious-start.sh
56
91
----
57
92
58
-
.Expected output (JSON format)
93
+
94
+
+
95
+
Example JSON log output:
96
+
+
59
97
60
98
[source,json]
61
99
----
@@ -67,17 +105,19 @@ bin/kroxylicious-start.sh
67
105
"thread_name": "kafka-request-handler-1",
68
106
"level": "INFO",
69
107
"level_value": 20000,
70
-
"stack_trace": null,
71
108
"sessionId": "abc-123",
72
-
"clientId": "producer-1"
109
+
"clientId": "producer-1",
110
+
"apiKey": "Produce"
73
111
}
74
112
----
75
113
76
-
NOTE: Structured logging parameters like `sessionId` and `clientId` appear as top-level fields in JSON output.
77
114
78
-
.Switching back to text format
115
+
+
116
+
When an exception is logged, a `stack_trace` field is included in the output.
117
+
118
+
. To switch back to text format, remove the environment variable or set it to `text`:
119
+
+
79
120
80
-
Remove the environment variable or set it to `text`:
0 commit comments