Skip to content

Commit b43819e

Browse files
darrachequesnedarrachequesne
committed
docs: how to display the debug logs
Related: #498
1 parent de7f932 commit b43819e

File tree

2 files changed

+214
-0
lines changed

2 files changed

+214
-0
lines changed

‎src/site/markdown/logging.md‎

Lines changed: 213 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,213 @@
1+
# Logging
2+
3+
This library uses JUL (`java.util.logging`) for its debug logs.
4+
5+
Here's how you can display those logs, depending on your logging library:
6+
7+
<!-- MACRO{toc} -->
8+
9+
## Usage with JUL
10+
11+
`src/main/resources/logging.properties`
12+
13+
```properties
14+
handlers = java.util.logging.ConsoleHandler
15+
16+
java.util.logging.ConsoleHandler.level = ALL
17+
18+
.level = INFO
19+
io.socket.level = FINE
20+
```
21+
22+
`src/main/java/MyApp.java`
23+
24+
```java
25+
public class MyApp {
26+
private static final Logger logger = Logger.getLogger("MyApp");
27+
28+
public static void main(String[] argz) throws Exception {
29+
InputStream stream = MyApp.class.getResourceAsStream("logging.properties");
30+
LogManager.getLogManager().readConfiguration(stream);
31+
32+
Socket socket = IO.socket(URI.create("https://example.com"));
33+
34+
socket.on(Socket.EVENT_CONNECT, args -> logger.info("connected!"));
35+
36+
socket.connect();
37+
}
38+
}
39+
```
40+
41+
Reference: https://docs.oracle.com/en/java/javase/17/core/java-logging-overview.html
42+
43+
## Usage with Log4j2
44+
45+
`pom.xml`
46+
47+
```xml
48+
<?xml version="1.0" encoding="UTF-8"?>
49+
<project>
50+
<dependencies>
51+
<dependency>
52+
<groupId>org.apache.logging.log4j</groupId>
53+
<artifactId>log4j-api</artifactId>
54+
<version>2.18.0</version>
55+
</dependency>
56+
<dependency>
57+
<groupId>org.apache.logging.log4j</groupId>
58+
<artifactId>log4j-core</artifactId>
59+
<version>2.18.0</version>
60+
</dependency>
61+
<dependency>
62+
<groupId>org.apache.logging.log4j</groupId>
63+
<artifactId>log4j-jul</artifactId>
64+
<version>2.18.0</version>
65+
</dependency>
66+
...
67+
</dependencies>
68+
...
69+
</project>
70+
```
71+
72+
Maven repository:
73+
74+
- https://mvnrepository.com/artifact/org.apache.logging.log4j/log4j-api
75+
- https://mvnrepository.com/artifact/org.apache.logging.log4j/log4j-core
76+
- https://mvnrepository.com/artifact/org.apache.logging.log4j/log4j-jul
77+
78+
`src/main/resources/log4j2.xml`
79+
80+
```xml
81+
<?xml version="1.0" encoding="UTF-8"?>
82+
<Configuration status="WARN">
83+
<Appenders>
84+
<Console name="console" target="SYSTEM_OUT" follow="true">
85+
<PatternLayout pattern="%d{HH:mm:ss.SSS} [%t] %-5level %logger{36} - %msg%n" />
86+
</Console>
87+
</Appenders>
88+
89+
<Loggers>
90+
<Root level="INFO">
91+
<AppenderRef ref="console" />
92+
</Root>
93+
94+
<Logger name="io.socket" level="TRACE" />
95+
</Loggers>
96+
</Configuration>
97+
```
98+
99+
`src/main/java/MyApp.java`
100+
101+
Either by setting the `java.util.logging.manager` environment variable:
102+
103+
```java
104+
public class MyApp {
105+
private static final Logger logger;
106+
107+
static {
108+
System.setProperty("java.util.logging.manager", "org.apache.logging.log4j.jul.LogManager");
109+
logger = LogManager.getLogger(MyApp.class);
110+
}
111+
112+
public static void main(String[] argz) throws Exception {
113+
Socket socket = IO.socket(URI.create("https://example.com"));
114+
115+
socket.on(Socket.EVENT_CONNECT, args -> logger.info("connected!"));
116+
117+
socket.connect();
118+
}
119+
}
120+
```
121+
122+
Or with the `Log4jBridgeHandler` class:
123+
124+
```java
125+
public class MyApp {
126+
private static final Logger logger = LogManager.getLogger(MyApp.class);
127+
128+
public static void main(String[] argz) throws Exception {
129+
Log4jBridgeHandler.install(true, "", true);
130+
131+
Socket socket = IO.socket(URI.create("https://example.com"));
132+
133+
socket.on(Socket.EVENT_CONNECT, args -> logger.info("connected!"));
134+
135+
socket.connect();
136+
}
137+
}
138+
```
139+
140+
Reference: https://logging.apache.org/log4j/2.x/log4j-jul/index.html
141+
142+
## Usage with Slf4j + logback
143+
144+
`pom.xml`
145+
146+
```xml
147+
<?xml version="1.0" encoding="UTF-8"?>
148+
<project>
149+
<dependencies>
150+
<dependency>
151+
<groupId>ch.qos.logback</groupId>
152+
<artifactId>logback-classic</artifactId>
153+
<version>1.2.11</version>
154+
</dependency>
155+
<dependency>
156+
<groupId>org.slf4j</groupId>
157+
<artifactId>jul-to-slf4j</artifactId>
158+
<version>1.7.36</version>
159+
</dependency>
160+
...
161+
</dependencies>
162+
...
163+
</project>
164+
```
165+
166+
Maven repository:
167+
168+
- https://mvnrepository.com/artifact/ch.qos.logback/logback-classic
169+
- https://mvnrepository.com/artifact/org.slf4j/jul-to-slf4j
170+
171+
`src/main/resources/logback.xml`
172+
173+
```xml
174+
<configuration>
175+
<contextListener class="ch.qos.logback.classic.jul.LevelChangePropagator">
176+
<resetJUL>true</resetJUL>
177+
</contextListener>
178+
179+
<appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
180+
<encoder>
181+
<pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
182+
</encoder>
183+
</appender>
184+
185+
<logger name="io.socket" level="DEBUG" />
186+
187+
<root level="INFO">
188+
<appender-ref ref="STDOUT" />
189+
</root>
190+
</configuration>
191+
```
192+
193+
`src/main/java/MyApp.java`
194+
195+
```java
196+
public class MyApp {
197+
private static final Logger logger = LoggerFactory.getLogger(MyApp.class);
198+
199+
static {
200+
SLF4JBridgeHandler.install();
201+
}
202+
203+
public static void main(String[] argz) throws Exception {
204+
Socket socket = IO.socket(URI.create("https://example.com"));
205+
206+
socket.on(Socket.EVENT_CONNECT, args -> logger.info("connected!"));
207+
208+
socket.connect();
209+
}
210+
}
211+
```
212+
213+
Reference: https://www.slf4j.org/manual.html

‎src/site/site.xml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@
3030
<item name="Listening to events" href="./listening_to_events.html"/>
3131
<item name="The Socket instance" href="./socket_instance.html"/>
3232
<item name="Migrating from 1.x" href="./migrating_from_1_x.html"/>
33+
<item name="Logging" href="./logging.html"/>
3334
<item name="FAQ" href="./faq.html"/>
3435
<item name="Android" href="./android.html"/>
3536
</menu>

0 commit comments

Comments
 (0)