0
# Network Logging
1
2
Network-based logging capabilities including TCP sockets, syslog protocol, email notifications, and SSL/TLS security for remote log transmission. Network appenders enable centralized logging and integration with log management systems.
3
4
## Capabilities
5
6
### SocketAppender
7
8
TCP socket-based appender for streaming log events to remote hosts with automatic reconnection and buffering.
9
10
```java { .api }
11
/**
12
* TCP socket appender for remote log transmission.
13
* Supports automatic reconnection, queuing, and connection management.
14
*/
15
public class SocketAppender extends AppenderBase<ILoggingEvent> {
16
private String remoteHost;
17
private int port;
18
private Duration reconnectionDelay = Duration.valueOf("30 seconds");
19
private int queueSize = 128;
20
private boolean includeCallerData = false;
21
22
/**
23
* Set the remote host to connect to.
24
* @param host hostname or IP address
25
*/
26
public void setRemoteHost(String host);
27
28
/**
29
* Get the remote host.
30
* @return remote host
31
*/
32
public String getRemoteHost();
33
34
/**
35
* Set the remote port to connect to.
36
* @param port TCP port number
37
*/
38
public void setPort(int port);
39
40
/**
41
* Get the remote port.
42
* @return port number
43
*/
44
public int getPort();
45
46
/**
47
* Set the delay before attempting reconnection after connection failure.
48
* @param delay reconnection delay
49
*/
50
public void setReconnectionDelay(Duration delay);
51
52
/**
53
* Get the reconnection delay.
54
* @return reconnection delay
55
*/
56
public Duration getReconnectionDelay();
57
58
/**
59
* Set the queue size for buffering events during connection issues.
60
* @param queueSize maximum number of events to buffer
61
*/
62
public void setQueueSize(int queueSize);
63
64
/**
65
* Get the queue size.
66
* @return queue size
67
*/
68
public int getQueueSize();
69
70
/**
71
* Enable inclusion of caller data in transmitted events.
72
* @param includeCallerData true to include caller information
73
*/
74
public void setIncludeCallerData(boolean includeCallerData);
75
76
/**
77
* Check if caller data is included.
78
* @return true if caller data is included
79
*/
80
public boolean isIncludeCallerData();
81
82
@Override
83
protected void append(ILoggingEvent event);
84
85
@Override
86
public void start();
87
88
@Override
89
public void stop();
90
}
91
```
92
93
### SyslogAppender
94
95
Syslog protocol appender supporting RFC3164 and RFC5424 formats with facility and severity mapping.
96
97
```java { .api }
98
/**
99
* Syslog protocol appender for integration with syslog daemons.
100
* Supports standard syslog facilities and severities.
101
*/
102
public class SyslogAppender extends AppenderBase<ILoggingEvent> {
103
private String syslogHost = "localhost";
104
private int port = 514;
105
private String facility = "USER";
106
private String suffixPattern;
107
private boolean throwExceptionOnWrite = true;
108
109
/**
110
* Set the syslog server hostname.
111
* @param syslogHost hostname of syslog server
112
*/
113
public void setSyslogHost(String syslogHost);
114
115
/**
116
* Get the syslog server hostname.
117
* @return syslog server hostname
118
*/
119
public String getSyslogHost();
120
121
/**
122
* Set the syslog server port.
123
* @param port UDP port (default 514)
124
*/
125
public void setPort(int port);
126
127
/**
128
* Get the syslog server port.
129
* @return port number
130
*/
131
public int getPort();
132
133
/**
134
* Set the syslog facility.
135
* @param facilityStr facility name (e.g., "USER", "LOCAL0", "MAIL")
136
*/
137
public void setFacility(String facilityStr);
138
139
/**
140
* Get the syslog facility.
141
* @return facility name
142
*/
143
public String getFacility();
144
145
/**
146
* Set the pattern for formatting the message part of syslog entries.
147
* @param suffixPattern message format pattern
148
*/
149
public void setSuffixPattern(String suffixPattern);
150
151
/**
152
* Get the suffix pattern.
153
* @return message format pattern
154
*/
155
public String getSuffixPattern();
156
157
/**
158
* Control whether to throw exceptions on write failures.
159
* @param throwExceptionOnWrite true to throw exceptions
160
*/
161
public void setThrowExceptionOnWrite(boolean throwExceptionOnWrite);
162
163
/**
164
* Check if exceptions are thrown on write failures.
165
* @return true if exceptions are thrown
166
*/
167
public boolean isThrowExceptionOnWrite();
168
169
@Override
170
protected void append(ILoggingEvent event);
171
172
@Override
173
public void start();
174
175
@Override
176
public void stop();
177
}
178
```
179
180
### SMTPAppender
181
182
Email-based appender for sending log events via SMTP with buffering and authentication support.
183
184
```java { .api }
185
/**
186
* SMTP appender for email-based log notifications.
187
* Supports authentication, SSL/TLS, and event buffering.
188
*/
189
public class SMTPAppender extends AppenderBase<ILoggingEvent> {
190
private String to;
191
private String from;
192
private String subject = "Log4j Log Messages";
193
private String smtpHost;
194
private int smtpPort = 25;
195
private boolean STARTTLS = false;
196
private boolean SSL = false;
197
private String username;
198
private String password;
199
private int bufferSize = 512;
200
201
/**
202
* Set recipient email addresses (comma-separated).
203
* @param to recipient addresses
204
*/
205
public void setTo(String to);
206
207
/**
208
* Get recipient addresses.
209
* @return recipient addresses
210
*/
211
public String getTo();
212
213
/**
214
* Set sender email address.
215
* @param from sender address
216
*/
217
public void setFrom(String from);
218
219
/**
220
* Get sender address.
221
* @return sender address
222
*/
223
public String getFrom();
224
225
/**
226
* Set email subject line.
227
* @param subject email subject
228
*/
229
public void setSubject(String subject);
230
231
/**
232
* Get email subject.
233
* @return email subject
234
*/
235
public String getSubject();
236
237
/**
238
* Set SMTP server hostname.
239
* @param smtpHost SMTP server hostname
240
*/
241
public void setSMTPHost(String smtpHost);
242
243
/**
244
* Get SMTP server hostname.
245
* @return SMTP server hostname
246
*/
247
public String getSMTPHost();
248
249
/**
250
* Set SMTP server port.
251
* @param smtpPort SMTP port (default 25)
252
*/
253
public void setSMTPPort(int smtpPort);
254
255
/**
256
* Get SMTP server port.
257
* @return SMTP port
258
*/
259
public int getSMTPPort();
260
261
/**
262
* Enable STARTTLS for secure connection.
263
* @param startTLS true to enable STARTTLS
264
*/
265
public void setSTARTTLS(boolean startTLS);
266
267
/**
268
* Check if STARTTLS is enabled.
269
* @return true if STARTTLS is enabled
270
*/
271
public boolean isSTARTTLS();
272
273
/**
274
* Enable SSL for secure connection.
275
* @param ssl true to enable SSL
276
*/
277
public void setSSL(boolean ssl);
278
279
/**
280
* Check if SSL is enabled.
281
* @return true if SSL is enabled
282
*/
283
public boolean isSSL();
284
285
/**
286
* Set SMTP authentication username.
287
* @param username authentication username
288
*/
289
public void setUsername(String username);
290
291
/**
292
* Get authentication username.
293
* @return username
294
*/
295
public String getUsername();
296
297
/**
298
* Set SMTP authentication password.
299
* @param password authentication password
300
*/
301
public void setPassword(String password);
302
303
/**
304
* Get authentication password.
305
* @return password
306
*/
307
public String getPassword();
308
309
/**
310
* Set buffer size for batching events before sending email.
311
* @param bufferSize number of events to buffer
312
*/
313
public void setBufferSize(int bufferSize);
314
315
/**
316
* Get buffer size.
317
* @return buffer size
318
*/
319
public int getBufferSize();
320
321
@Override
322
protected void append(ILoggingEvent event);
323
324
@Override
325
public void start();
326
327
@Override
328
public void stop();
329
}
330
```
331
332
## SSL/TLS Support
333
334
### SSLContextFactoryBean
335
336
Factory for creating SSL contexts with keystore and truststore configuration.
337
338
```java { .api }
339
/**
340
* Factory for creating SSL contexts with custom keystore and truststore.
341
*/
342
public class SSLContextFactoryBean extends ContextAwareBase {
343
private KeyStoreFactoryBean keyStore;
344
private KeyStoreFactoryBean trustStore;
345
private String keyManagerPassword;
346
private String secureRandom;
347
private String protocol = "SSL";
348
349
/**
350
* Set the keystore factory for client certificates.
351
* @param keyStore keystore factory
352
*/
353
public void setKeyStore(KeyStoreFactoryBean keyStore);
354
355
/**
356
* Get the keystore factory.
357
* @return keystore factory
358
*/
359
public KeyStoreFactoryBean getKeyStore();
360
361
/**
362
* Set the truststore factory for server certificate validation.
363
* @param trustStore truststore factory
364
*/
365
public void setTrustStore(KeyStoreFactoryBean trustStore);
366
367
/**
368
* Get the truststore factory.
369
* @return truststore factory
370
*/
371
public KeyStoreFactoryBean getTrustStore();
372
373
/**
374
* Set the key manager password.
375
* @param keyManagerPassword password for key manager
376
*/
377
public void setKeyManagerPassword(String keyManagerPassword);
378
379
/**
380
* Get the key manager password.
381
* @return key manager password
382
*/
383
public String getKeyManagerPassword();
384
385
/**
386
* Set the secure random algorithm.
387
* @param secureRandomName secure random algorithm name
388
*/
389
public void setSecureRandom(String secureRandomName);
390
391
/**
392
* Get the secure random algorithm.
393
* @return secure random algorithm name
394
*/
395
public String getSecureRandom();
396
397
/**
398
* Set the SSL protocol.
399
* @param protocol SSL protocol (e.g., "TLS", "SSL")
400
*/
401
public void setProtocol(String protocol);
402
403
/**
404
* Get the SSL protocol.
405
* @return SSL protocol
406
*/
407
public String getProtocol();
408
409
/**
410
* Create the SSL context.
411
* @return configured SSL context
412
* @throws Exception if SSL context creation fails
413
*/
414
public SSLContext createContext() throws Exception;
415
}
416
```
417
418
### KeyStoreFactoryBean
419
420
Factory for creating keystores from various sources.
421
422
```java { .api }
423
/**
424
* Factory for creating keystores from files, resources, or URLs.
425
*/
426
public class KeyStoreFactoryBean extends ContextAwareBase {
427
private String location;
428
private String password;
429
private String provider;
430
private String type = "JKS";
431
432
/**
433
* Set keystore location (file path, classpath resource, or URL).
434
* @param location keystore location
435
*/
436
public void setLocation(String location);
437
438
/**
439
* Get keystore location.
440
* @return keystore location
441
*/
442
public String getLocation();
443
444
/**
445
* Set keystore password.
446
* @param password keystore password
447
*/
448
public void setPassword(String password);
449
450
/**
451
* Get keystore password.
452
* @return keystore password
453
*/
454
public String getPassword();
455
456
/**
457
* Set security provider name.
458
* @param provider security provider name
459
*/
460
public void setProvider(String provider);
461
462
/**
463
* Get security provider name.
464
* @return security provider name
465
*/
466
public String getProvider();
467
468
/**
469
* Set keystore type.
470
* @param type keystore type (e.g., "JKS", "PKCS12")
471
*/
472
public void setType(String type);
473
474
/**
475
* Get keystore type.
476
* @return keystore type
477
*/
478
public String getType();
479
480
/**
481
* Create the keystore.
482
* @return loaded keystore
483
* @throws Exception if keystore creation fails
484
*/
485
public KeyStore createKeyStore() throws Exception;
486
}
487
```
488
489
### SSL Configuration Interface
490
491
```java { .api }
492
/**
493
* Interface for SSL-configurable components.
494
*/
495
public interface SSLConfigurable {
496
/**
497
* Get the SSL context.
498
* @return SSL context
499
*/
500
SSLContext getSslContext();
501
502
/**
503
* Set SSL configuration.
504
* @param ssl SSL configuration
505
*/
506
void setSsl(SSL ssl);
507
508
/**
509
* Get SSL configuration.
510
* @return SSL configuration
511
*/
512
SSL getSsl();
513
}
514
515
/**
516
* SSL configuration aggregator.
517
*/
518
public class SSL implements SSLConfigurable {
519
private KeyStoreFactoryBean keyStore;
520
private KeyStoreFactoryBean trustStore;
521
private SSLContextFactoryBean sslContextFactoryBean;
522
523
/**
524
* Set keystore configuration.
525
* @param keyStore keystore factory
526
*/
527
public void setKeyStore(KeyStoreFactoryBean keyStore);
528
529
/**
530
* Get keystore configuration.
531
* @return keystore factory
532
*/
533
public KeyStoreFactoryBean getKeyStore();
534
535
/**
536
* Set truststore configuration.
537
* @param trustStore truststore factory
538
*/
539
public void setTrustStore(KeyStoreFactoryBean trustStore);
540
541
/**
542
* Get truststore configuration.
543
* @return truststore factory
544
*/
545
public KeyStoreFactoryBean getTrustStore();
546
547
@Override
548
public SSLContext getSslContext();
549
550
@Override
551
public void setSsl(SSL ssl);
552
553
@Override
554
public SSL getSsl();
555
}
556
```
557
558
## Server Components
559
560
### ServerSocketAppender
561
562
Server-side socket appender for receiving log events from remote clients.
563
564
```java { .api }
565
/**
566
* Server socket appender for receiving log events from remote clients.
567
*/
568
public class ServerSocketAppender<E> extends AppenderBase<E> {
569
private int port = 4560;
570
private String address;
571
private int clientQueueSize = 100;
572
private int timeout = 0;
573
574
/**
575
* Set the port to listen on.
576
* @param port listen port
577
*/
578
public void setPort(int port);
579
580
/**
581
* Get the listen port.
582
* @return port number
583
*/
584
public int getPort();
585
586
/**
587
* Set the address to bind to.
588
* @param address bind address (null for all interfaces)
589
*/
590
public void setAddress(String address);
591
592
/**
593
* Get the bind address.
594
* @return bind address
595
*/
596
public String getAddress();
597
598
/**
599
* Set client queue size.
600
* @param clientQueueSize queue size per client
601
*/
602
public void setClientQueueSize(int clientQueueSize);
603
604
/**
605
* Get client queue size.
606
* @return client queue size
607
*/
608
public int getClientQueueSize();
609
610
/**
611
* Set connection timeout.
612
* @param timeout timeout in milliseconds (0 = no timeout)
613
*/
614
public void setTimeout(int timeout);
615
616
/**
617
* Get connection timeout.
618
* @return timeout in milliseconds
619
*/
620
public int getTimeout();
621
622
@Override
623
protected void append(E eventObject);
624
625
@Override
626
public void start();
627
628
@Override
629
public void stop();
630
}
631
```
632
633
## Utility Classes
634
635
### SocketConnector Interface
636
637
Interface for creating socket connections with custom implementations.
638
639
```java { .api }
640
/**
641
* Interface for creating socket connections.
642
* Allows custom socket creation strategies.
643
*/
644
public interface SocketConnector {
645
/**
646
* Create a new socket connection to the specified address and port.
647
* @param address target address
648
* @param port target port
649
* @return connected socket
650
* @throws Exception if connection fails
651
*/
652
Socket newSocket(InetAddress address, int port) throws Exception;
653
654
/**
655
* Create a new socket connection to the specified host and port.
656
* @param host target hostname
657
* @param port target port
658
* @return connected socket
659
* @throws Exception if connection fails
660
*/
661
Socket newSocket(String host, int port) throws Exception;
662
}
663
```
664
665
### DefaultSocketConnector
666
667
Default implementation of SocketConnector.
668
669
```java { .api }
670
/**
671
* Default socket connector implementation using standard TCP sockets.
672
*/
673
public class DefaultSocketConnector implements SocketConnector {
674
private int connectionTimeout = 0;
675
676
/**
677
* Set connection timeout.
678
* @param connectionTimeout timeout in milliseconds
679
*/
680
public void setConnectionTimeout(int connectionTimeout);
681
682
/**
683
* Get connection timeout.
684
* @return timeout in milliseconds
685
*/
686
public int getConnectionTimeout();
687
688
@Override
689
public Socket newSocket(InetAddress address, int port) throws Exception;
690
691
@Override
692
public Socket newSocket(String host, int port) throws Exception;
693
}
694
```
695
696
### SyslogConstants
697
698
Constants for syslog facilities and severities.
699
700
```java { .api }
701
/**
702
* Constants for syslog protocol implementation.
703
*/
704
public class SyslogConstants {
705
// Syslog facilities
706
public static final int KERN_FACILITY = 0;
707
public static final int USER_FACILITY = 1;
708
public static final int MAIL_FACILITY = 2;
709
public static final int DAEMON_FACILITY = 3;
710
public static final int AUTH_FACILITY = 4;
711
public static final int SYSLOG_FACILITY = 5;
712
public static final int LPR_FACILITY = 6;
713
public static final int NEWS_FACILITY = 7;
714
public static final int UUCP_FACILITY = 8;
715
public static final int CRON_FACILITY = 9;
716
public static final int AUTHPRIV_FACILITY = 10;
717
public static final int FTP_FACILITY = 11;
718
public static final int LOCAL0_FACILITY = 16;
719
public static final int LOCAL1_FACILITY = 17;
720
public static final int LOCAL2_FACILITY = 18;
721
public static final int LOCAL3_FACILITY = 19;
722
public static final int LOCAL4_FACILITY = 20;
723
public static final int LOCAL5_FACILITY = 21;
724
public static final int LOCAL6_FACILITY = 22;
725
public static final int LOCAL7_FACILITY = 23;
726
727
// Syslog severities
728
public static final int EMERGENCY_SEVERITY = 0;
729
public static final int ALERT_SEVERITY = 1;
730
public static final int CRITICAL_SEVERITY = 2;
731
public static final int ERROR_SEVERITY = 3;
732
public static final int WARNING_SEVERITY = 4;
733
public static final int NOTICE_SEVERITY = 5;
734
public static final int INFO_SEVERITY = 6;
735
public static final int DEBUG_SEVERITY = 7;
736
}
737
```
738
739
## Usage Examples
740
741
### Basic Socket Appender
742
743
```java
744
import ch.qos.logback.core.net.SocketAppender;
745
import ch.qos.logback.core.util.Duration;
746
747
// Create socket appender for remote logging
748
SocketAppender socketAppender = new SocketAppender();
749
socketAppender.setContext(context);
750
socketAppender.setRemoteHost("log-server.example.com");
751
socketAppender.setPort(4560);
752
socketAppender.setReconnectionDelay(Duration.valueOf("10 seconds"));
753
socketAppender.setQueueSize(256);
754
socketAppender.setIncludeCallerData(true);
755
socketAppender.start();
756
757
// Use with other appenders
758
logger.addAppender(socketAppender);
759
```
760
761
### Syslog Appender Configuration
762
763
```java
764
import ch.qos.logback.core.net.SyslogAppender;
765
766
// Configure syslog appender
767
SyslogAppender syslogAppender = new SyslogAppender();
768
syslogAppender.setContext(context);
769
syslogAppender.setSyslogHost("syslog.example.com");
770
syslogAppender.setPort(514);
771
syslogAppender.setFacility("LOCAL0");
772
syslogAppender.setSuffixPattern("%logger{20} - %msg");
773
syslogAppender.start();
774
```
775
776
### SMTP Appender with Authentication
777
778
```java
779
import ch.qos.logback.core.net.SMTPAppender;
780
781
// Configure SMTP appender for error notifications
782
SMTPAppender smtpAppender = new SMTPAppender();
783
smtpAppender.setContext(context);
784
smtpAppender.setTo("admin@example.com,ops@example.com");
785
smtpAppender.setFrom("app@example.com");
786
smtpAppender.setSubject("Application Error Alert");
787
smtpAppender.setSMTPHost("smtp.example.com");
788
smtpAppender.setSMTPPort(587);
789
smtpAppender.setSTARTTLS(true);
790
smtpAppender.setUsername("app@example.com");
791
smtpAppender.setPassword("smtp-password");
792
smtpAppender.setBufferSize(1); // Send immediately on each event
793
smtpAppender.start();
794
795
// Use with error filter
796
ErrorFilter errorFilter = new ErrorFilter();
797
errorFilter.start();
798
smtpAppender.addFilter(errorFilter);
799
```
800
801
### SSL-Enabled Socket Appender
802
803
```java
804
import ch.qos.logback.core.net.ssl.*;
805
806
// Create SSL configuration
807
KeyStoreFactoryBean keyStore = new KeyStoreFactoryBean();
808
keyStore.setContext(context);
809
keyStore.setLocation("client-keystore.jks");
810
keyStore.setPassword("keystore-password");
811
812
KeyStoreFactoryBean trustStore = new KeyStoreFactoryBean();
813
trustStore.setContext(context);
814
trustStore.setLocation("client-truststore.jks");
815
trustStore.setPassword("truststore-password");
816
817
SSLContextFactoryBean sslContext = new SSLContextFactoryBean();
818
sslContext.setContext(context);
819
sslContext.setKeyStore(keyStore);
820
sslContext.setTrustStore(trustStore);
821
822
SSL ssl = new SSL();
823
ssl.setKeyStore(keyStore);
824
ssl.setTrustStore(trustStore);
825
826
// Create SSL socket appender (custom implementation)
827
SSLSocketAppender sslAppender = new SSLSocketAppender();
828
sslAppender.setContext(context);
829
sslAppender.setRemoteHost("secure-log-server.example.com");
830
sslAppender.setPort(6514);
831
sslAppender.setSsl(ssl);
832
sslAppender.start();
833
```
834
835
### Server Socket for Log Collection
836
837
```java
838
import ch.qos.logback.core.net.server.ServerSocketAppender;
839
840
// Create server socket appender to receive logs
841
ServerSocketAppender<ILoggingEvent> serverAppender = new ServerSocketAppender<>();
842
serverAppender.setContext(context);
843
serverAppender.setPort(4560);
844
serverAppender.setAddress("0.0.0.0"); // Listen on all interfaces
845
serverAppender.setClientQueueSize(1000);
846
serverAppender.setTimeout(30000); // 30 second timeout
847
serverAppender.start();
848
849
// Server will accept connections and forward events to attached appenders
850
FileAppender<ILoggingEvent> fileAppender = new FileAppender<>();
851
fileAppender.setContext(context);
852
fileAppender.setFile("collected-logs.log");
853
fileAppender.setEncoder(encoder);
854
fileAppender.start();
855
856
serverAppender.addAppender(fileAppender);
857
```
858
859
### Custom Network Appender
860
861
```java
862
import ch.qos.logback.core.AppenderBase;
863
import java.net.DatagramSocket;
864
import java.net.DatagramPacket;
865
import java.net.InetAddress;
866
867
public class UDPAppender<E> extends AppenderBase<E> {
868
private String host = "localhost";
869
private int port = 9999;
870
private DatagramSocket socket;
871
872
@Override
873
protected void append(E eventObject) {
874
try {
875
String message = eventObject.toString();
876
byte[] buffer = message.getBytes("UTF-8");
877
878
DatagramPacket packet = new DatagramPacket(
879
buffer, buffer.length,
880
InetAddress.getByName(host), port
881
);
882
883
socket.send(packet);
884
} catch (Exception e) {
885
addError("Failed to send UDP packet", e);
886
}
887
}
888
889
@Override
890
public void start() {
891
try {
892
socket = new DatagramSocket();
893
super.start();
894
} catch (Exception e) {
895
addError("Failed to create UDP socket", e);
896
}
897
}
898
899
@Override
900
public void stop() {
901
if (socket != null && !socket.isClosed()) {
902
socket.close();
903
}
904
super.stop();
905
}
906
907
public void setHost(String host) {
908
this.host = host;
909
}
910
911
public void setPort(int port) {
912
this.port = port;
913
}
914
}
915
```
916
917
## Security Considerations
918
919
1. **SSL/TLS**: Use SSL for sensitive log data transmission
920
2. **Authentication**: Configure SMTP authentication for email appenders
921
3. **Firewall**: Ensure appropriate firewall rules for network appenders
922
4. **Credentials**: Store passwords securely, avoid hardcoding
923
5. **Certificate Validation**: Properly configure truststores for SSL
924
6. **Network Timeouts**: Set appropriate timeouts to prevent hanging connections
925
926
## Performance and Reliability
927
928
1. **Buffering**: Use queues and buffers to handle network latency
929
2. **Reconnection**: Configure appropriate reconnection delays
930
3. **Fallback**: Consider local fallback appenders for network failures
931
4. **Monitoring**: Monitor network appender connection status
932
5. **Resource Management**: Properly close network connections on shutdown