0
# Apache Log4j Docker Support
1

2
Apache Log4j Docker Support provides Docker container information lookup functionality for the Log4j logging framework. It enables applications running within Docker containers to access container metadata such as container ID, image information, and network settings through the DockerLookup plugin.
3

4
## Package Information
5

6
- **Package Name**: log4j-docker
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Group ID**: org.apache.logging.log4j
10
- **Artifact ID**: log4j-docker
11
- **Installation**: Add to Maven dependencies:
12

13
```xml
14
<dependency>
15
    <groupId>org.apache.logging.log4j</groupId>
16
    <artifactId>log4j-docker</artifactId>
17
    <version>2.25.1</version>
18
</dependency>
19
```
20

21
Gradle:
22
```gradle
23
implementation 'org.apache.logging.log4j:log4j-docker:2.25.1'
24
```
25

26
## Core Imports
27

28
```java
29
import org.apache.logging.log4j.docker.DockerLookup;
30
import org.apache.logging.log4j.docker.model.Container;
31
import org.apache.logging.log4j.docker.model.Network;
32
import org.apache.logging.log4j.docker.model.NetworkSettings;
33
import org.apache.logging.log4j.docker.model.Mount;
34
import org.apache.logging.log4j.docker.model.PortDefinition;
35
import org.apache.logging.log4j.docker.model.IPAMConfig;
36
```
37

38
## Basic Usage
39

40
The DockerLookup plugin automatically registers with Log4j and can be used in configuration files:
41

42
```xml
43
<?xml version="1.0" encoding="UTF-8"?>
44
<Configuration status="WARN">
45
    <Appenders>
46
        <Console name="Console" target="SYSTEM_OUT">
47
            <PatternLayout pattern="%d{HH:mm:ss.SSS} [%t] %-5level %logger{36} - [${docker:containerId}] %msg%n"/>
48
        </Console>
49
    </Appenders>
50
    <Loggers>
51
        <Root level="info">
52
            <AppenderRef ref="Console"/>
53
        </Root>
54
    </Loggers>
55
</Configuration>
56
```
57

58
## Configuration
59

60
Set the `DOCKER_URI` environment variable or system property to the Docker daemon endpoint:
61

62
```bash
63
export DOCKER_URI=http://localhost:2375
64
```
65

66
Or in Java:
67
```java
68
System.setProperty("DOCKER_URI", "http://localhost:2375");
69
```
70

71
## Capabilities
72

73
### Docker Lookup Plugin
74

75
The main plugin that provides Docker container information to Log4j patterns.
76

77
```java { .api }
78
@Plugin(name = "docker", category = StrLookup.CATEGORY)
79
public class DockerLookup extends AbstractLookup {
80
    public DockerLookup();
81
    public String lookup(LogEvent ignored, String key);
82
}
83
```
84

85
**Supported Lookup Keys:**
86
- `shortContainerId` - Returns the first 12 characters of the container ID
87
- `containerId` - Returns the full container ID
88
- `containerName` - Returns the container name(s)
89
- `shortImageId` - Returns the first 12 characters of the image ID  
90
- `imageId` - Returns the full image ID
91
- `imageName` - Returns the image name
92

93
Usage in Log4j configuration:
94
```xml
95
<PatternLayout pattern="%d - [${docker:shortContainerId}] [${docker:imageName}] %msg%n"/>
96
```
97

98
### Container Information Model
99

100
The library provides comprehensive data models for Docker container information.
101

102
```java { .api }
103
public class Container {
104
    public String getId();
105
    public void setId(String id);
106
    
107
    public List<String> getNames();
108
    public void setNames(List<String> names);
109
    
110
    public String getImage();
111
    public void setImage(String image);
112
    
113
    public String getImageId();
114
    public void setImageId(String imageId);
115
    
116
    public String getCommand();
117
    public void setCommand(String command);
118
    
119
    public Long getCreated();
120
    public void setCreated(Long created);
121
    
122
    public List<PortDefinition> getPorts();
123
    public void setPorts(List<PortDefinition> ports);
124
    
125
    public Map<String, String> getLabels();
126
    public void setLabels(Map<String, String> labels);
127
    
128
    public String getState();
129
    public void setState(String state);
130
    
131
    public String getStatus();
132
    public void setStatus(String status);
133
    
134
    public HostConfig getHostConfig();
135
    public void setHostConfig(HostConfig hostConfig);
136
    
137
    public NetworkSettings getNetworkSettings();
138
    public void setNetworkSettings(NetworkSettings networkSettings);
139
    
140
    public List<Mount> getMounts();
141
    public void setMounts(List<Mount> mounts);
142
}
143
```
144

145
### Network Configuration
146

147
Access to Docker network settings and configuration.
148

149
```java { .api }
150
public class NetworkSettings {
151
    public Map<String, Network> getNetworks();
152
    public void setNetworks(Map<String, Network> networks);
153
    
154
    public String getBridge();
155
    public void setBridge(String bridge);
156
    
157
    public String getSandboxId();
158
    public void setSandboxId(String sandboxId);
159
    
160
    public boolean isHairpinMode();
161
    public void setHairpinMode(boolean hairpinMode);
162
    
163
    public String getLinkLocalIPv6Address();
164
    public void setLinkLocalIPv6Address(String linkLocalIPv6Address);
165
    
166
    public int getLinkLocalIPv6PrefixLen();
167
    public void setLinkLocalIPv6PrefixLen(int linkLocalIPv6PrefixLen);
168
    
169
    public Map<String, String> getPorts();
170
    public void setPorts(Map<String, String> ports);
171
    
172
    public String getSandboxKey();
173
    public void setSandboxKey(String sandboxKey);
174
    
175
    public String getSecondaryIPaddresses();
176
    public void setSecondaryIPaddresses(String secondaryIPaddresses);
177
    
178
    public String getEndpointId();
179
    public void setEndpointId(String endpointId);
180
    
181
    public String getGateway();
182
    public void setGateway(String gateway);
183
    
184
    public String getGlobalIPv6Address();
185
    public void setGlobalIPv6Address(String globalIPv6Address);
186
    
187
    public int getGlobalIPv6PrefixLen();
188
    public void setGlobalIPv6PrefixLen(int globalIPv6PrefixLen);
189
    
190
    public String getIpAddress();
191
    public void setIpAddress(String ipAddress);
192
    
193
    public int getIpPrefixLen();
194
    public void setIpPrefixLen(int ipPrefixLen);
195
    
196
    public String getIpv6Gateway();
197
    public void setIpv6Gateway(String ipv6Gateway);
198
    
199
    public String getMacAddress();
200
    public void setMacAddress(String macAddress);
201
}
202
```
203

204
```java { .api }
205
public class Network {
206
    public IPAMConfig getIpamConfig();
207
    public void setIpamConfig(IPAMConfig ipamConfig);
208
    
209
    public String getLinks();
210
    public void setLinks(String links);
211
    
212
    public String[] getAliases();
213
    public void setAliases(String[] aliases);
214
    
215
    public String getNetworkId();
216
    public void setNetworkId(String networkId);
217
    
218
    public String getEndpointId();
219
    public void setEndpointId(String endpointId);
220
    
221
    public String getGateway();
222
    public void setGateway(String gateway);
223
    
224
    public String getIpAddress();
225
    public void setIpAddress(String ipAddress);
226
    
227
    public Integer getIpPrefixLen();
228
    public void setIpPrefixLen(Integer ipPrefixLen);
229
    
230
    public String getIpv6Gateway();
231
    public void setIpv6Gateway(String ipv6Gateway);
232
    
233
    public String getGlobalIPv6Address();
234
    public void setGlobalIPv6Address(String globalIPv6Address);
235
    
236
    public Integer getGlobalIPv6PrefixLen();
237
    public void setGlobalIPv6PrefixLen(Integer globalIPv6PrefixLen);
238
    
239
    public String getMacAddress();
240
    public void setMacAddress(String macAddress);
241
    
242
    public String getDriverOpts();
243
    public void setDriverOpts(String driverOpts);
244
}
245
```
246

247
### Volume Mount Information
248

249
Access to Docker volume and bind mount details.
250

251
```java { .api }
252
public class Mount {
253
    public String getType();
254
    public void setType(String type);
255
    
256
    public String getName();
257
    public void setName(String name);
258
    
259
    public String getSource();
260
    public void setSource(String source);
261
    
262
    public String getDestination();
263
    public void setDestination(String destination);
264
    
265
    public String getDriver();
266
    public void setDriver(String driver);
267
    
268
    public String getMode();
269
    public void setMode(String mode);
270
    
271
    public Boolean getReadWrite();
272
    public void setReadWrite(Boolean readWrite);
273
    
274
    public String getPropagation();
275
    public void setPropagation(String propagation);
276
}
277
```
278

279
### Port Mapping Information
280

281
Access to Docker port mapping and networking details.
282

283
```java { .api }
284
public class PortDefinition {
285
    public String getIp();
286
    public void setIp(String ip);
287
    
288
    public Integer getPrivatePort();
289
    public void setPrivatePort(Integer privatePort);
290
    
291
    public Integer getPublicPort();
292
    public void setPublicPort(Integer publicPort);
293
    
294
    public String getType();
295
    public void setType(String type);
296
}
297
```
298

299
### Host Configuration
300

301
Docker host configuration settings are accessible through the Container class, but the HostConfig class itself has no public methods in the current implementation.
302

303
### IP Address Management
304

305
Access to Docker network IP address management configuration.
306

307
```java { .api }
308
public class IPAMConfig {
309
    public String getSubnet();
310
    public void setSubnet(String subnet);
311
    
312
    public String getIpRange();
313
    public void setIpRange(String ipRange);
314
    
315
    public String getGateway();
316
    public void setGateway(String gateway);
317
    
318
    public String getIpv4Address();
319
    public void setIpv4Address(String ipv4Address);
320
}
321
```
322

323
## Error Handling
324

325
The DockerLookup plugin handles connection failures gracefully:
326

327
- Returns `null` when Docker information is unavailable
328
- Logs warnings when Docker URI is not configured
329
- Logs warnings when unable to connect to Docker daemon
330
- Logs warnings when unable to determine current container
331

332
When Docker information is unavailable, lookup operations return `null` values, allowing logging to continue normally without Docker context.
333

334
## Dependencies
335

336
This library requires:
337
- Apache Log4j Core
338
- Apache Log4j API
339
- Jackson JSON processing libraries (core, databind, annotations)
340

341
## Usage Examples
342

343
### Basic Container Identification
344

345
```xml
346
<PatternLayout pattern="%d [${docker:shortContainerId}] %level - %msg%n"/>
347
```
348

349
### Detailed Container Context
350

351
```xml
352
<PatternLayout pattern="%d [${docker:containerName}@${docker:imageName}] %level - %msg%n"/>
353
```
354

355
### Environment-Specific Logging
356

357
```java
358
// Application code
359
Logger logger = LogManager.getLogger(MyApplication.class);
360
logger.info("Application started in container");
361

362
// Output with Docker context:
363
// 2024-01-15 10:30:45 [abc123456789] INFO - Application started in container
364
```