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
The Java SDK logs events and also provides an event bus that transmits information about the behavior of your database system, including system and metric events.
11
-
It has no hard dependency on a specific logger implementation, but you should add one you are comfortable with.
10
+
The Couchbase Java SDK logs events and also provides an event bus that transmits information about the behavior of your database system, including system and metric events.
12
11
13
12
== Logging
14
13
15
-
The Couchbase Java SDK has no hard dependency on a specific logger implementation.
16
-
It tries to find a logger on the class path and uses that logger if it is supported by the SDK.
17
-
If no logger implementation is found, the standard JDK logger is used.
14
+
The Couchbase Java SDK uses https://www.slf4j.org[SLF4J], a logging façade that lets you use any logging framework that has an SLF4J binding.
15
+
This includes popular Java logging frameworks like Log4j, Logback, and `java.util.logging` (JUL).
18
16
19
-
The following loggers are supported (and tried in this order):
17
+
To see log messages from the Couchbase SDK, add an SLF4J binding as a dependency of your project.
20
18
21
-
. SLF4J
22
-
. JDK Logger (java.util.logging)
23
-
24
-
*Configuring SLF4J*
25
-
26
-
To enable SLF4J, put it on the class path, as well as one of the support logger implementations (like logback).
27
-
If you want to use logback and include logback-classic, it will be pulled in automatically:
19
+
[slf4j-api-versions]
20
+
.SLF4J API versions
21
+
[NOTE]
22
+
====
23
+
At the time of writing, there are two different versions of the SLF4J API:
28
24
29
-
[source,xml]
30
-
----
31
-
<dependency>
32
-
<groupId>ch.qos.logback</groupId>
33
-
<artifactId>logback-classic</artifactId>
34
-
<version>1.2.3</version>
35
-
</dependency>
36
-
----
25
+
*Version 2* is the modern version of SLF4J.
26
+
It is actively maintained, and recommended for most users.
37
27
38
-
By default, the log level for logback is set to DEBUG, but with the addition of a logback configuration this can be configured (for example, as a `logback.xml` in the resources folder):
28
+
*Version 1.7* is no longer maintained, but you can still use it if your preferred SLF4J binding does not support version 2.
The Couchbase SDK is compatible with both versions of the SLF4J API.
31
+
The SDK's Maven POM has a dependency on version 1.7, but you can override this by using version 2 in your project.
32
+
====
48
33
49
-
<root level="info">
50
-
<appender-ref ref="STDOUT" />
51
-
</root>
52
-
</configuration>
53
-
----
34
+
[log4j2]
35
+
=== Using Log4j 2
54
36
55
-
Consult the https://www.slf4j.org/docs.html[SLF4J documentation^] for advanced configuration.
37
+
Log4j 2 is a popular and flexible logging framework.
38
+
This section shows how to configure your project to use Log4j 2 with the Couchbase SDK.
56
39
57
-
*Configuring Log4j*
40
+
First, add an https://logging.apache.org/log4j/2.x/log4j-slf4j-impl.html[SLF4J binding for Log4j 2] as a dependency of your project.
41
+
The following example uses the binding for SLF4J API version 2.
58
42
59
-
Log4j can also be used behind the SLF4J logging facade.
43
+
[{tabs}]
44
+
====
45
+
Maven::
46
+
+
47
+
--
48
+
Add these as children of the `dependencies` element.
60
49
50
+
.`*pom.xml*`
61
51
[source,xml]
62
52
----
63
53
<dependency>
64
-
<groupId>org.slf4j</groupId>
65
-
<artifactId>slf4j-log4j12</artifactId>
66
-
<version>1.7.30</version>
54
+
<groupId>org.apache.logging.log4j</groupId>
55
+
<artifactId>log4j-slf4j2-impl</artifactId>
56
+
<version>2.22.0</version>
67
57
</dependency>
68
-
----
69
58
70
-
If no configuration is applied, the following message appears:
59
+
<!-- If your SLF4J binding requires API version 2
60
+
(like log4j-slf4j2-impl in this example!),
61
+
add this dependency to your project to ensure
62
+
Maven uses the correct SLF4J API version. -->
63
+
<dependency>
64
+
<groupId>org.slf4j</groupId>
65
+
<artifactId>slf4j-api</artifactId>
66
+
<version>2.0.9</version>
67
+
</dependency>
68
+
----
71
69
72
-
[source]
70
+
TIP: An alternate way to ensure Maven uses the correct version of the SLF4J API is to declare the dependency on `log4j-slf4j2-impl` *before* the dependency on the Couchbase SDK.
71
+
See the Maven documentation on https://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html#Transitive_Dependencies[Transitive Dependencies] to learn more about how Maven resolves transitive dependency version conflicts.
72
+
--
73
+
Gradle::
74
+
+
75
+
--
76
+
.`*build.gradle*`
77
+
[source,groovy]
73
78
----
74
-
log4j:WARN No appenders could be found for logger (reactor.util.Loggers$LoggerFactory).
75
-
log4j:WARN Please initialize the log4j system properly.
76
-
log4j:WARN See http://logging.apache.org/log4j/1.2/faq.html#noconfig for more info.
NOTE: Gradle automatically uses the correct SLF4J API 2.x dependency required by `log4j-slf4j2-impl`, even though the Couchbase SDK declares a dependency on SLF4J API 1.7.
83
+
--
84
+
====
85
+
86
+
[configuring-log4j]
87
+
==== Configuring Log4j 2 output
88
+
89
+
Log4j 2 needs a configuration file to tell it which messages to log, where to write them, and how each message should be formatted.
78
90
79
-
Note that the `Reactor` library which the Java SDK depends upon also uses the same strategy with SLF4J, so logging for both can be configured with the same strategies out of the box.
91
+
Here's an example `log4j2.xml` configuration file you can use to get started.
92
+
It tells Log4j 2 to log messages to the console, and sets some reasonable logging levels.
80
93
81
-
This `log4j.xml` sets it to INFO level:
94
+
TIP: If your project uses the https://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html[Maven Standard Directory Layout], this file should live in the `src/main/resources` directory.
95
+
This makes it available at runtime as a class path resource.
<!-- Most messages from the Couchbase SDK are logged under
116
+
this prefix. Change the level to "debug" to see more
117
+
details about SDK activity, or "warn" to see less.
118
+
In production environments, we recommend "info". -->
119
+
<Logger name="com.couchbase" level="info"/>
100
120
101
-
</log4j:configuration>
121
+
<!-- The default level for everything else. -->
122
+
<Root level="info">
123
+
<AppenderRef ref="Console"/>
124
+
</Root>
125
+
</Loggers>
126
+
</Configuration>
102
127
----
103
128
104
-
Consult the https://logging.apache.org/log4j/2.x/javadoc.html[Log4J documentation^] for more information and advanced configuration options.
129
+
Consult the https://logging.apache.org/log4j/2.x/manual/configuration.html[Log4J 2 configuration documentation^] for more information and advanced configuration options.
105
130
106
-
== Configuring the JDK Logger
131
+
[jul]
132
+
=== Using `java.util.logging` (JUL)
107
133
108
-
If no logging library is found on the class path, the JDK logger (also known as JUL from `java.util.logging`) is used as a fallback.
134
+
If `java.util.logging` (JUL) is your preferred logging framework, add the `slf4j-jdk14` SLF4J binding as dependency of your project.
109
135
110
-
By default it logs INFO level and above.
111
-
If you want to set it to DEBUG (or the JUL equivalent: Fine) you can do it like this programmatically before initializing the `Cluster` object (or creating a custom `ClusterEnvironment`):
136
+
[{tabs}]
137
+
====
138
+
Maven::
139
+
+
140
+
--
141
+
Add these as children of the `dependencies` element.
You should not use JUL in production because SLF4J and Log4J provide better configuration options and performance.
163
+
TIP: An alternate way to ensure Maven uses the correct version of the SLF4J API is to declare the dependency on `slf4j-jdk14` *before* the dependency on the Couchbase SDK.
164
+
See the Maven documentation on https://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html#Transitive_Dependencies[Transitive Dependencies] to learn more about how Maven resolves transitive dependency version conflicts.
165
+
--
166
+
Gradle::
167
+
+
168
+
--
169
+
.`*build.gradle*`
170
+
[source,groovy]
171
+
----
172
+
// Add this to your `dependencies` section:
173
+
implementation("org.slf4j:slf4j-jdk14:2.0.9")
174
+
----
175
+
NOTE: Gradle automatically uses the correct SLF4J API 2.x dependency required by `slf4j-jdk14`, even though the Couchbase SDK declares a dependency on SLF4J API 1.7.
176
+
--
177
+
====
119
178
120
-
== Customizing the Logger
179
+
[configuring-the-jdk-logger]
180
+
==== Configuring a JUL Logger
121
181
122
-
The logger is configured in a way that it should work out of the box for most users, but there might still be occasion where you want to tweak it. The behavior of the logger can be tuned by customizing the `LoggerConfig` on the `ClusterEnvironment`. For example, if you always want to log to `stderr` and ignore SLF4J (even if present on the classpath) and disable JUL you can configure it this way:
182
+
By default, JUL logs INFO level and above.
183
+
If you want to set it to DEBUG (or the JUL equivalent: Fine) you can do it like this programmatically before initializing the `Cluster` object (or creating a custom `ClusterEnvironment`):
You can also use it to enable the http://logback.qos.ch/manual/mdc.html[Mapped Diagnostic Context^].
190
+
TIP: We do not recommend using JUL in production.
191
+
Dedicated logging frameworks like Log4j 2 and Logback are more configurable, and tend to perform better than JUL.
130
192
131
193
== The Event Bus
132
194
133
195
[NOTE]
134
196
.Event Bus Stability
135
197
====
136
-
While the event bus functionality itself is considered stable, the events itself may not be. Please only consume the events you are interested in, and add error handling code in case of unexpected behaviour.
198
+
While the event bus functionality itself is considered stable, the events themselves may not be.
199
+
Please only consume the events you are interested in, and add error handling code in case of unexpected behavior.
137
200
====
138
201
139
202
Log files are neither fun to wade through, nor do they have any kind of real-time aspect.
@@ -142,7 +205,8 @@ Since most setups interleave all different kinds of log messages, it makes it ve
142
205
143
206
To make the situation better and ultimately improve supportability, the Java SDK provides you with the ability to tap into all events before they get logged and consume them in "real-time".
144
207
145
-
You can subscribe to the event bus, and receive and react to events as they are happening; not when someone parses the logs, sends them into another system where an alarm is triggered, and eventually a sysadmin checks what iss going on.
208
+
You can subscribe to the event bus, and receive and react to events as they are happening;
209
+
not when someone parses the logs, sends them into another system where an alarm is triggered, and eventually a sysadmin checks what is going on.
146
210
The time delta between an event happening and reacting to it can thus be substantially decreased.
147
211
148
212
The following code subscribes to the event bus and prints out all events that are published on it with INFO or WARN level:
We recommend filtering on the specific events you are interested in, since most of the time only a subset of the published ones will be of use to you. Also, there are new events added between releases so make sure these new events do not break your functionality.
229
+
We recommend filtering on the specific events you are interested in, since most of the time only a subset of the published ones will be of use to you.
230
+
Also, there are new events added between releases so make sure these new events do not break your functionality.
166
231
167
232
[WARNING]
168
233
.Blocking Warning
169
234
====
170
-
If you consume the `EventBus` you MUST NOT block inside the consumer callback. It will stall all other consumers. If you must write into a blocking sink like a blocking HTTP API you MUST write it onto a different thread with a non-blocking queue first.
235
+
If you consume the `EventBus` you MUST NOT block inside the consumer callback. It will stall all other consumers.
236
+
If you must write into a blocking sink like a blocking HTTP API you MUST write it onto a different thread with a non-blocking queue first.
Different redaction levels are supported -- please see the `RedactionLevel` enum description for more information.
185
251
186
252
Note that you need to run this command before any of the SDK code is initialized so all of the logs are captured properly.
187
-
Once the SDK writes the logs with the tags to a file, you can then use the xref:7.1@server:cli:cbcli/cblogredaction.adoc[`cblogredaction` tool] to obfuscate the log.
253
+
Once the SDK writes the logs with the tags to a file, you can then use the xref:7.2@server:cli:cbcli/cblogredaction.adoc[`cblogredaction` tool] to obfuscate the log.
188
254
189
-
* You may wish to read more on Log Redaction xref:7.1@server:manage:manage-logging/manage-logging.adoc#understanding_redaction[in the Server docs].
255
+
* You may wish to read more on Log Redaction xref:7.2@server:manage:manage-logging/manage-logging.adoc#understanding_redaction[in the Server docs].
0 commit comments