0
# Logging and Monitoring
1

2
Logging interfaces and implementations, plus profiling capabilities for monitoring driver behavior and query execution.
3

4
## Capabilities
5

6
### Log Interface
7

8
Unified logging interface supporting multiple logging frameworks.
9

10
```java { .api }
11
package com.mysql.cj.log;
12

13
public interface Log {
14
    // Check log levels
15
    boolean isDebugEnabled();
16
    boolean isErrorEnabled();
17
    boolean isFatalEnabled();
18
    boolean isInfoEnabled();
19
    boolean isTraceEnabled();
20
    boolean isWarnEnabled();
21

22
    // Debug logging
23
    void logDebug(Object msg);
24
    void logDebug(Object msg, Throwable thrown);
25

26
    // Error logging
27
    void logError(Object msg);
28
    void logError(Object msg, Throwable thrown);
29

30
    // Fatal logging
31
    void logFatal(Object msg);
32
    void logFatal(Object msg, Throwable thrown);
33

34
    // Info logging
35
    void logInfo(Object msg);
36
    void logInfo(Object msg, Throwable thrown);
37

38
    // Trace logging
39
    void logTrace(Object msg);
40
    void logTrace(Object msg, Throwable thrown);
41

42
    // Warn logging
43
    void logWarn(Object msg);
44
    void logWarn(Object msg, Throwable thrown);
45
}
46
```
47

48
### Standard Logger
49

50
Built-in logger that writes to STDERR.
51

52
```java { .api }
53
package com.mysql.cj.log;
54

55
public class StandardLogger implements Log {
56
    // Constructor
57
    public StandardLogger(String name);
58
    public StandardLogger(String name, boolean logLocationInfo);
59

60
    // Implements all Log methods
61
}
62
```
63

64
Usage:
65

66
```java
67
// Enable standard logger
68
String url = "jdbc:mysql://localhost:3306/mydb?logger=StandardLogger&profileSQL=true";
69
Connection conn = DriverManager.getConnection(url, "user", "pass");
70

71
// Logger will output to System.err
72
Statement stmt = conn.createStatement();
73
ResultSet rs = stmt.executeQuery("SELECT * FROM users");
74
// Logs query execution details
75
```
76

77
### SLF4J Logger
78

79
Logger implementation using SLF4J.
80

81
```java { .api }
82
package com.mysql.cj.log;
83

84
public class Slf4JLogger implements Log {
85
    // Constructor
86
    public Slf4JLogger(String name);
87

88
    // Implements all Log methods, delegates to SLF4J
89
}
90
```
91

92
Usage:
93

94
```java
95
// Use SLF4J logger (requires slf4j-api on classpath)
96
String url = "jdbc:mysql://localhost:3306/mydb?logger=Slf4JLogger&profileSQL=true";
97
Connection conn = DriverManager.getConnection(url, "user", "pass");
98

99
// Logging goes through SLF4J to configured backend (logback, log4j, etc.)
100
```
101

102
### JDK 1.4 Logger
103

104
Logger implementation using java.util.logging.
105

106
```java { .api }
107
package com.mysql.cj.log;
108

109
public class Jdk14Logger implements Log {
110
    // Constructor
111
    public Jdk14Logger(String name);
112

113
    // Implements all Log methods, delegates to java.util.logging
114
}
115
```
116

117
Usage:
118

119
```java
120
// Use JDK logger
121
String url = "jdbc:mysql://localhost:3306/mydb?logger=Jdk14Logger&profileSQL=true";
122
Connection conn = DriverManager.getConnection(url, "user", "pass");
123

124
// Configure java.util.logging as usual
125
```
126

127
### Null Logger
128

129
No-op logger that discards all log messages.
130

131
```java { .api }
132
package com.mysql.cj.log;
133

134
public class NullLogger implements Log {
135
    // Constructor
136
    public NullLogger(String instanceName);
137

138
    // Implements all Log methods as no-ops
139
}
140
```
141

142
### Profiler Event Interface
143

144
Interface for profiling events.
145

146
```java { .api }
147
package com.mysql.cj.log;
148

149
public interface ProfilerEvent {
150
    // Event type
151
    byte getEventType();
152

153
    // Event type constants
154
    byte TYPE_EXECUTE = 1;
155
    byte TYPE_FETCH = 2;
156
    byte TYPE_OBJECT_CREATION = 3;
157
    byte TYPE_PREPARE = 4;
158
    byte TYPE_QUERY = 5;
159
    byte TYPE_WARN = 6;
160
    byte TYPE_SLOW_QUERY = 7;
161

162
    // Event details
163
    String getCatalog();
164
    long getConnectionId();
165
    int getResultSetColumnCount();
166
    long getResultSetRowsCount();
167
    String getMessage();
168

169
    // Timing information
170
    long getEventCreationTime();
171
    long getEventDuration();
172
    String getDurationUnits();
173

174
    // Stack trace
175
    String getEventCreationPointAsString();
176
}
177
```
178

179
### Profiler Event Handler
180

181
Interface for handling profiler events.
182

183
```java { .api }
184
package com.mysql.cj.log;
185

186
public interface ProfilerEventHandler {
187
    // Initialize handler
188
    void init(Log log);
189

190
    // Destroy handler
191
    void destroy();
192

193
    // Consume profiler event
194
    void consumeEvent(ProfilerEvent evt);
195
}
196
```
197

198
Usage:
199

200
```java
201
// Implement custom profiler event handler
202
public class MyProfilerEventHandler implements ProfilerEventHandler {
203
    private Log log;
204

205
    public void init(Log log) {
206
        this.log = log;
207
    }
208

209
    public void destroy() {
210
        // Cleanup
211
    }
212

213
    public void consumeEvent(ProfilerEvent evt) {
214
        if (evt.getEventType() == ProfilerEvent.TYPE_SLOW_QUERY) {
215
            log.logWarn("Slow query detected: " + evt.getMessage() +
216
                       ", Duration: " + evt.getEventDuration() + evt.getDurationUnits());
217
        }
218
    }
219
}
220

221
// Enable profiling with custom handler
222
String url = "jdbc:mysql://localhost:3306/mydb" +
223
             "?profileSQL=true" +
224
             "&profilerEventHandler=com.mycompany.MyProfilerEventHandler";
225
Connection conn = DriverManager.getConnection(url, "user", "pass");
226

227
// Or use built-in slow query logging
228
String url2 = "jdbc:mysql://localhost:3306/mydb" +
229
              "?profileSQL=true" +
230
              "&logSlowQueries=true" +
231
              "&slowQueryThresholdMillis=1000";  // Log queries slower than 1 second
232
```
233

234
### Log Utilities
235

236
Utility methods for logging.
237

238
```java { .api }
239
package com.mysql.cj.log;
240

241
public class LogUtils {
242
    // Convenience logging methods
243
    public static void logInfo(Log logger, Object message);
244
    public static void logDebug(Log logger, Object message);
245
    public static void logWarn(Log logger, Object message);
246
    public static void logError(Log logger, Object message);
247
    public static void logFatal(Log logger, Object message);
248
    public static void logTrace(Log logger, Object message);
249

250
    // Expand exception stack trace
251
    public static String stackTraceToString(Throwable t);
252
}
253
```
254

255
### Configuration Properties
256

257
Logging and monitoring related configuration properties:
258

259
```java
260
// Enable SQL profiling
261
profileSQL=true
262

263
// Enable query logging
264
logger=StandardLogger  // or Slf4JLogger, Jdk14Logger
265

266
// Log slow queries
267
logSlowQueries=true
268
slowQueryThresholdMillis=2000
269

270
// Enable usage advisor (warns about inefficient usage patterns)
271
useUsageAdvisor=true
272

273
// Gather performance metrics
274
gatherPerfMetrics=true
275

276
// Report metrics interval (milliseconds)
277
reportMetricsIntervalMillis=30000
278

279
// Enable statement timing
280
maintainTimeStats=true
281

282
// Enable automatic reconnection logging
283
autoReconnectForPools=true
284
```
285

286
Complete usage example:
287

288
```java
289
// Comprehensive logging and monitoring configuration
290
String url = "jdbc:mysql://localhost:3306/mydb" +
291
             "?logger=Slf4JLogger" +
292
             "&profileSQL=true" +
293
             "&logSlowQueries=true" +
294
             "&slowQueryThresholdMillis=1000" +
295
             "&useUsageAdvisor=true" +
296
             "&gatherPerfMetrics=true" +
297
             "&maintainTimeStats=true";
298

299
Connection conn = DriverManager.getConnection(url, "user", "pass");
300

301
// Execute queries - will be logged and profiled
302
Statement stmt = conn.createStatement();
303
ResultSet rs = stmt.executeQuery("SELECT * FROM large_table");
304

305
// Slow queries will be logged
306
PreparedStatement pstmt = conn.prepareStatement("SELECT * FROM users WHERE id = ?");
307
pstmt.setInt(1, 1);
308
pstmt.executeQuery();
309

310
// Usage advisor warnings will be logged for inefficient patterns
311
stmt.executeQuery("SELECT * FROM users");
312
// Iterating without calling rs.next() properly will trigger warning
313

314
conn.close();
315
```
316