Skip to content

Commit 1ead67a

Browse files
kortemikkortemik
committed
Update README.adoc
1 parent 7a235d1 commit 1ead67a

1 file changed

Lines changed: 115 additions & 69 deletions

File tree

‎README.adoc‎

Lines changed: 115 additions & 69 deletions
Original file line numberDiff line numberDiff line change
@@ -1,57 +1,118 @@
1-
# Java Util Logging RELP Handler
1+
= Java Util Logging RELP Handler
22
[![Build Status](https://scan.coverity.com/projects/23156/badge.svg)](https://scan.coverity.com/projects/jla_04)
33

4-
Creates Java Util Logging appender that uses RELP to ensure no events are lost.
5-
6-
## Supported system properties
7-
* com.teragrep.jla_04.RelpHandler.LOGGERNAME.hostname
8-
** Stream hostname identifier. Maximum length of 255 characters, limited by RFC5424
9-
* com.teragrep.jla_04.RelpHandler.LOGGERNAME.appname
10-
** Stream application identifier. Maximum length of 48 characters, limited by RFC5424
11-
* com.teragrep.jla_04.RelpHandler.LOGGERNAME.server.address
12-
** Connection destination address
13-
* com.teragrep.jla_04.RelpHandler.LOGGERNAME.server.connectionTimeout
14-
** Time to wait before timing out connection
15-
* com.teragrep.jla_04.RelpHandler.LOGGERNAME.server.port
16-
** Connection destination port
17-
* com.teragrep.jla_04.RelpHandler.LOGGERNAME.server.readTimeout
18-
** Time to wait for destination to acknowledge sent data (low values cause duplicates)
19-
* com.teragrep.jla_04.RelpHandler.LOGGERNAME.server.reconnectInterval
20-
** Time to wait between re-connection attempts
21-
* com.teragrep.jla_04.RelpHandler.LOGGERNAME.server.writeTimeout
22-
** Time to wait for destination to accept data
23-
* com.teragrep.jla_04.RelpHandler.LOGGERNAME.useStructuredData
24-
** Enables structured data containing uuid and source information
25-
26-
## Supported logging.properties file directives
27-
* java.util.logging.RelpHandler.LOGGERNAME.hostname
28-
** Stream hostname identifier. Maximum length of 255 characters, limited by RFC5424
29-
* java.util.logging.RelpHandler.LOGGERNAME.appname
30-
** Stream application identifier. Maximum length of 48 characters, limited by RFC5424
31-
* java.util.logging.RelpHandler.LOGGERNAME.server.address
32-
** Connection destination address
33-
* java.util.logging.RelpHandler.LOGGERNAME.server.connectionTimeout
34-
** Time to wait before timing out connection
35-
* java.util.logging.RelpHandler.LOGGERNAME.server.port
36-
** Connection destination port
37-
* java.util.logging.RelpHandler.LOGGERNAME.server.readTimeout
38-
** Time to wait for destination to acknowledge sent data (low values cause duplicates)
39-
* java.util.logging.RelpHandler.LOGGERNAME.server.reconnectInterval
40-
** Time to wait between re-connection attempts
41-
* java.util.logging.RelpHandler.LOGGERNAME.server.writeTimeout
42-
** Time to wait for destination to accept data
43-
* java.util.logging.RelpHandler.LOGGERNAME.useStructuredData
44-
** Enables structured data containing uuid and source information
45-
46-
## Passing properties file
47-
48-
```
4+
Creates Java Util Logging handler that uses RELP to ensure no events are lost.
5+
6+
== Configuring pre-built Java Util Logging application
7+
8+
Java Util Logging supports passing a log handler without any modifications to
9+
the program code.
10+
11+
NOTE: Java Util Logging restricts one handler type from
12+
the logging.properties configuration so one can not have different JLA_04
13+
handler, for example, for INFO and DEBUG. See xref:README
14+
.adoc#_advanced_configuration[advanced configration] to get around
15+
this limitation.
16+
17+
First download wanted versions of jla_04, rlp_01 and syslog-java-client from the following urls:
18+
19+
https://search.maven.org/artifact/com.teragrep/jla_04[jla_04]
20+
21+
https://search.maven.org/artifact/com.teragrep/rlp_01[rlp_01]
22+
23+
https://search.maven.org/artifact/com.cloudbees/syslog-java-client[syslog-java-client]
24+
25+
26+
Configuration file, see xref:README.adoc#Supported logging.properties file
27+
directives[logging.properties file directives] for explanation of the keys.
28+
[source,properties]
29+
----
30+
handlers=com.teragrep.jla_04.RelpHandler
31+
java.util.logging.RelpHandler.default.server.address=127.0.0.1
32+
java.util.logging.RelpHandler.default.server.port=10601
33+
java.util.logging.RelpHandler.default.appname=jul-logger
34+
java.util.logging.RelpHandler.default.hostname=host1.example.com
35+
java.util.logging.RelpHandler.default.formatter=java.util.logging.SimpleFormatter
36+
java.util.logging.SimpleFormatter.format=[%1$tc] [%4$s] %5$s
37+
.level = ALL
38+
----
39+
40+
Then run java while pointing classpath to the directory where you downloaded
41+
the jars and the standard property "java.util.logging
42+
.config.file" to your logging.properties file.
43+
44+
Example command-line:
45+
46+
[source,bash]
47+
----
48+
java -cp "path/to/downloaded/jars/*:target/example.jar" -Djava.util.logging
49+
.config.file=logging.properties com.teragrep.example.Main
50+
.Main
51+
----
52+
53+
== Advanced configuration
54+
55+
JLA_04 supports programmatic creation of multiple handlers, these are not
56+
available for programs which are not modified to support them because of Java
57+
Util Logging (JUL) limitation. JUL supports only one handler of a handler
58+
type via external configuration file.
59+
60+
61+
=== Supported system properties
62+
* com.teragrep.jla_04.RelpHandler.LOGGERNAME.hostname
63+
** Stream hostname identifier.Maximum length of 255 characters, limited by RFC5424
64+
* com.teragrep.jla_04.RelpHandler.LOGGERNAME.appname
65+
** Stream application identifier.Maximum length of 48 characters, limited by RFC5424
66+
* com.teragrep.jla_04.RelpHandler.LOGGERNAME.server.address
67+
** Connection destination address
68+
* com.teragrep.jla_04.RelpHandler.LOGGERNAME.server.connectionTimeout
69+
** Time to wait before timing out connection
70+
* com.teragrep.jla_04.RelpHandler.LOGGERNAME.server.port
71+
** Connection destination port
72+
* com.teragrep.jla_04.RelpHandler.LOGGERNAME.server.readTimeout
73+
** Time to wait for destination to acknowledge sent data (low values cause duplicates)
74+
* com.teragrep.jla_04.RelpHandler.LOGGERNAME.server.reconnectInterval
75+
** Time to wait between re-connection attempts
76+
* com.teragrep.jla_04.RelpHandler.LOGGERNAME.server.writeTimeout
77+
** Time to wait for destination to accept data
78+
* com.teragrep.jla_04.RelpHandler.LOGGERNAME.useStructuredData
79+
** Enables structured data containing uuid and source information
80+
81+
=== Supported logging.properties file directives
82+
83+
Default logger has LOGGERNAME "default" which is the only one available
84+
without code modifications.
85+
86+
* java.util.logging.RelpHandler.LOGGERNAME.hostname
87+
** Stream hostname identifier.Maximum length of 255 characters, limited by RFC5424
88+
* java.util.logging.RelpHandler.LOGGERNAME.appname
89+
** Stream application identifier.Maximum length of 48 characters, limited by RFC5424
90+
* java.util.logging.RelpHandler.LOGGERNAME.server.address
91+
** Connection destination address
92+
* java.util.logging.RelpHandler.LOGGERNAME.server.connectionTimeout
93+
** Time to wait before timing out connection
94+
* java.util.logging.RelpHandler.LOGGERNAME.server.port
95+
** Connection destination port
96+
* java.util.logging.RelpHandler.LOGGERNAME.server.readTimeout
97+
** Time to wait for destination to acknowledge sent data (low values cause duplicates)
98+
* java.util.logging.RelpHandler.LOGGERNAME.server.reconnectInterval
99+
** Time to wait between re-connection attempts
100+
* java.util.logging.RelpHandler.LOGGERNAME.server.writeTimeout
101+
** Time to wait for destination to accept data
102+
* java.util.logging.RelpHandler.LOGGERNAME.useStructuredData
103+
** Enables structured data containing uuid and source information
104+
105+
=== Passing properties file
106+
107+
[source,bash]
108+
----
49109
-Dcom.teragrep.jla_04.logging.config.file=path/to/logging.properties
50-
```
110+
----
51111

52-
## Usage
112+
=== Code Usage
53113

54-
```
114+
[source,java]
115+
----
55116
// RelpHandler without arguments defaults LOGGERNAME to "default"
56117
System.setProperty("com.teragrep.jla_04.RelpHandler.default.server.address", "127.0.0.1");
57118
System.setProperty("com.teragrep.jla_04.RelpHandler.default.server.port", "1667");
@@ -74,30 +135,15 @@ logger.addHandler(relpHandler_custom);
74135
// Set level and send messages
75136
logger.setLevel(Level.WARNING);
76137
logger.severe("Severe message");
77-
```
138+
----
78139

79-
## Maven dependency definition
140+
=== Maven dependency definition
80141

81-
```
142+
[source,xml]
143+
----
82144
<dependency>
83145
<groupId>com.teragrep</groupId>
84146
<artifactId>jla_04</artifactId>
85147
<version>%VERSION%</version>
86148
</dependency>
87-
```
88-
89-
## Configuring pre-built Java Util Logging application
90-
91-
First download wanted versions of jla_04, rlp_01 and syslog-java-client from the following urls:
92-
93-
https://search.maven.org/artifact/com.teragrep/jla_04[jla_04]
94-
95-
https://search.maven.org/artifact/com.teragrep/rlp_01[rlp_01]
96-
97-
https://search.maven.org/artifact/com.cloudbees/syslog-java-client[syslog-java-client]
98-
99-
Then run java while pointing classpath to the directory where you downloaded the jars to like:
100-
101-
```
102-
java -cp "path/to/downloaded/jars/*:target/example.jar" com.teragrep.example.Main
103-
```
149+
----

0 commit comments

Comments
 (0)