0
# Dropwizard Logging
1

2
A comprehensive logging framework module for Dropwizard applications providing configurable appenders, formatters, and Logback integration. Built on top of Logback and SLF4J, it offers a wide range of configurable appenders including console, file, syslog, and network socket appenders (TCP/UDP), along with advanced features like async logging, custom layouts, filters, and structured JSON logging.
3

4
## Package Information
5

6
- **Package Name**: dropwizard-logging
7
- **Group ID**: io.dropwizard
8
- **Language**: Java
9
- **Installation**: Add to Maven dependencies:
10

11
```xml
12
<dependency>
13
    <groupId>io.dropwizard</groupId>
14
    <artifactId>dropwizard-logging</artifactId>
15
    <version>4.0.14</version>
16
</dependency>
17
```
18

19
## Core Imports
20

21
```java
22
import io.dropwizard.logging.common.*;
23
import io.dropwizard.logging.common.filter.*;
24
import io.dropwizard.logging.common.layout.*;
25
import io.dropwizard.logging.common.async.*;
26
```
27

28
## Basic Usage
29

30
```java
31
import io.dropwizard.logging.common.DefaultLoggingFactory;
32
import io.dropwizard.logging.common.ConsoleAppenderFactory;
33
import io.dropwizard.logging.common.FileAppenderFactory;
34
import io.dropwizard.logging.common.BootstrapLogging;
35
import ch.qos.logback.classic.Level;
36

37
// Bootstrap logging during application startup
38
BootstrapLogging.bootstrap();
39

40
// Configure logging programmatically
41
DefaultLoggingFactory loggingFactory = new DefaultLoggingFactory();
42
loggingFactory.setLevel("INFO");
43

44
// Add console appender
45
ConsoleAppenderFactory<ILoggingEvent> consoleAppender = new ConsoleAppenderFactory<>();
46
consoleAppender.setTarget(ConsoleAppenderFactory.ConsoleStream.STDOUT);
47
consoleAppender.setLogFormat("%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n");
48

49
// Add file appender
50
FileAppenderFactory<ILoggingEvent> fileAppender = new FileAppenderFactory<>();
51
fileAppender.setCurrentLogFilename("./logs/application.log");
52
fileAppender.setArchivedLogFilenamePattern("./logs/application-%d{yyyy-MM-dd}-%i.log.gz");
53
fileAppender.setMaxFileSize(DataSize.megabytes(10));
54

55
// Add appenders to logging factory
56
loggingFactory.setAppenders(Arrays.asList(consoleAppender, fileAppender));
57

58
// Configure the logging system
59
MetricRegistry metrics = new MetricRegistry();
60
loggingFactory.configure(metrics, "MyApplication");
61
```
62

63
## Architecture
64

65
Dropwizard Logging follows a factory-based design pattern with several key components:
66

67
- **LoggingFactory**: Main SPI interface for configuring logging systems with pluggable implementations
68
- **AppenderFactory**: SPI for creating Logback Appender instances with Jackson-based polymorphic configuration
69
- **FilterFactory**: SPI for creating custom Logback filters with type-safe configuration
70
- **LayoutFactory**: System for creating custom log layouts with timezone support
71
- **AsyncAppenderFactory**: Interface for wrapping synchronous appenders in async wrappers
72
- **Extension Points**: Service provider interfaces allowing custom implementations via META-INF/services
73

74
This design provides seamless integration with Dropwizard's YAML configuration system, allowing complex logging setups to be defined declaratively while maintaining full programmatic control when needed.
75

76
## Capabilities
77

78
### Logging Factories
79

80
Core logging system configuration and lifecycle management providing the main entry points for setting up logging in Dropwizard applications.
81

82
```java { .api }
83
public interface LoggingFactory extends Discoverable {
84
    void configure(MetricRegistry metricRegistry, String name);
85
    void stop();
86
    void reset();
87
}
88

89
public class DefaultLoggingFactory implements LoggingFactory {
90
    public void setLevel(String level);
91
    public void setLoggers(Map<String, JsonNode> loggers);
92
    public void setAppenders(List<AppenderFactory<ILoggingEvent>> appenders);
93
    public static Level toLevel(String text);
94
}
95

96
public class ExternalLoggingFactory implements LoggingFactory {
97
    // No-op implementation for external logging configuration
98
}
99
```
100

101
[Logging Factories](./logging-factories.md)
102

103
### Appender Factories
104

105
Comprehensive set of appender implementations for different output destinations including console, files, syslog, and network sockets with extensive configuration options.
106

107
```java { .api }
108
public interface AppenderFactory<E> extends Discoverable {
109
    Appender<E> build(LoggerContext context, String applicationName, 
110
                     LayoutFactory<E> layoutFactory, 
111
                     LevelFilterFactory<E> levelFilterFactory, 
112
                     AsyncAppenderFactory<E> asyncAppenderFactory);
113
}
114

115
public abstract class AbstractAppenderFactory<E> implements AppenderFactory<E> {
116
    public void setThreshold(Level threshold);
117
    public void setLogFormat(String logFormat);
118
    public void setLayout(DiscoverableLayoutFactory<E> layout);
119
    public void setTimeZone(TimeZone timeZone);
120
    public void setQueueSize(int queueSize);
121
    public void setMessageRate(Duration messageRate);
122
    // ... additional configuration methods
123
}
124
```
125

126
[Appender Factories](./appender-factories.md)
127

128
### Layout System
129

130
Flexible layout system for customizing log message formatting with timezone support and custom pattern converters.
131

132
```java { .api }
133
public interface LayoutFactory<E extends DeferredProcessingAware> {
134
    PatternLayoutBase<E> build(LoggerContext context, TimeZone timeZone);
135
}
136

137
@JsonTypeInfo(use = JsonTypeInfo.Id.NAME, property = "type")
138
public interface DiscoverableLayoutFactory<E extends DeferredProcessingAware> extends Discoverable {
139
    LayoutBase<E> build(LoggerContext context, TimeZone timeZone);
140
}
141

142
public class DropwizardLayout extends PatternLayout {
143
    // Default Dropwizard layout with custom converters
144
}
145

146
public class DropwizardLayoutFactory implements LayoutFactory<ILoggingEvent> {
147
    public PatternLayoutBase<ILoggingEvent> build(LoggerContext context, TimeZone timeZone);
148
}
149
```
150

151
[Layout System](./layout-system.md)
152

153
### Filter System
154

155
Configurable filter system for controlling which log events are processed by appenders with threshold and custom filtering capabilities.
156

157
```java { .api }
158
public interface FilterFactory<E> extends Discoverable {
159
    Filter<E> build();
160
}
161

162
public interface LevelFilterFactory<E> {
163
    Filter<E> build(Level threshold);
164
}
165

166
public class ThresholdLevelFilterFactory implements LevelFilterFactory<ILoggingEvent> {
167
    public Filter<ILoggingEvent> build(Level threshold);
168
}
169

170
public class NullLevelFilterFactory<E> implements LevelFilterFactory<E> {
171
    public Filter<E> build(Level threshold);
172
}
173
```
174

175
[Filter System](./filter-system.md)
176

177
### Async Logging
178

179
Asynchronous logging capabilities for high-throughput applications with configurable queue sizes and discard policies.
180

181
```java { .api }
182
public interface AsyncAppenderFactory<E> {
183
    AsyncAppenderBase<E> build();
184
}
185

186
public class AsyncLoggingEventAppenderFactory implements AsyncAppenderFactory<ILoggingEvent> {
187
    public AsyncAppenderBase<ILoggingEvent> build();
188
}
189
```
190

191
[Async Logging](./async-logging.md)
192

193
### Utility Classes
194

195
Essential utility classes for logging system management including bootstrap configuration and JDK logging integration.
196

197
```java { .api }
198
public class BootstrapLogging {
199
    public static void bootstrap();
200
    public static void bootstrap(Level level);
201
    public static void bootstrap(Level level, DiscoverableLayoutFactory<ILoggingEvent> layoutFactory);
202
}
203

204
public class LoggingUtil {
205
    public static LoggerContext getLoggerContext();
206
    public static void hijackJDKLogging();
207
}
208
```
209

210
[Utility Classes](./utility-classes.md)
211

212
## Types
213

214
### Core Configuration Types
215

216
```java { .api }
217
public class LoggerConfiguration {
218
    private String level = "INFO";
219
    private List<AppenderFactory<ILoggingEvent>> appenders;
220
    private boolean additive = true;
221
    
222
    public String getLevel();
223
    public void setLevel(String level);
224
    
225
    public List<AppenderFactory<ILoggingEvent>> getAppenders();
226
    public void setAppenders(List<AppenderFactory<ILoggingEvent>> appenders);
227
    
228
    public boolean isAdditive();
229
    public void setAdditive(boolean additive);
230
}
231
```
232

233
### Appender Configuration Enums
234

235
```java { .api }
236
public enum ConsoleStream {
237
    STDOUT, STDERR
238
}
239

240
public enum Facility {
241
    KERN, USER, MAIL, DAEMON, AUTH, SYSLOG, LPR, NEWS, UUCP, CRON,
242
    AUTHPRIV, FTP, LOCAL0, LOCAL1, LOCAL2, LOCAL3, LOCAL4, LOCAL5, LOCAL6, LOCAL7
243
}
244
```