README.adoc

Java Util Logging RELP Handler

Creates Java Util Logging handler that uses RELP to ensure no events are lost.

Configuring pre-built Java Util Logging application

Java Util Logging supports passing a log handler without any modifications to the program code.

Note	Java Util Logging restricts one handler type from the logging.properties configuration so one can not have different JLA_04 handler, for example, for INFO and DEBUG. See advanced configration to get around this limitation.

First download wanted versions of jla_04, rlp_01 and syslog-java-client from the following urls:

• jla_04

• rlp_01

• syslog-java-client

Configuration file, see logging.properties file directives for explanation of the keys.

handlers=com.teragrep.jla_04.RelpHandler
java.util.logging.RelpHandler.default.server.address=127.0.0.1
java.util.logging.RelpHandler.default.server.port=10601
java.util.logging.RelpHandler.default.appname=jul-logger
java.util.logging.RelpHandler.default.hostname=host1.example.com
java.util.logging.RelpHandler.default.formatter=java.util.logging.SimpleFormatter
java.util.logging.SimpleFormatter.format=[%1$tc] [%4$s] %5$s
.level = ALL

Then run java while pointing classpath to the directory where you downloaded the jars and the standard property "java.util.logging .config.file" to your logging.properties file.

Example command-line:

java -cp "path/to/downloaded/jars/*:target/example.jar" -Djava.util.logging
.config.file=logging.properties com.teragrep.example.Main
.Main

Advanced configuration

JLA_04 supports programmatic creation of multiple handlers, these are not available for programs which are not modified to support them because of Java Util Logging (JUL) limitation. JUL supports only one handler of a handler type via external configuration file.

Supported system properties

Property	Description
com.teragrep.jla_04.RelpHandler.LOGGERNAME.hostname	Stream hostname identifier.Maximum length of 255 characters, limited by RFC5424
com.teragrep.jla_04.RelpHandler.LOGGERNAME.appname	Stream application identifier.Maximum length of 48 characters, limited by RFC5424
com.teragrep.jla_04.RelpHandler.LOGGERNAME.server.address	Connection destination address
com.teragrep.jla_04.RelpHandler.LOGGERNAME.server.connectionTimeout	Time to wait before timing out connection
com.teragrep.jla_04.RelpHandler.LOGGERNAME.server.port	Connection destination port
com.teragrep.jla_04.RelpHandler.LOGGERNAME.server.readTimeout	Time to wait for destination to acknowledge sent data (low values cause duplicates)
com.teragrep.jla_04.RelpHandler.LOGGERNAME.server.reconnectInterval	Time to wait between re-connection attempts
com.teragrep.jla_04.RelpHandler.LOGGERNAME.server.writeTimeout	Time to wait for destination to accept data
com.teragrep.jla_04.RelpHandler.LOGGERNAME.useStructuredData	Enables structured data containing uuid and source information

Supported logging.properties file directives

Default logger has LOGGERNAME "default" which is the only one available without code modifications.

Property	Description
java.util.logging.RelpHandler.LOGGERNAME.hostname	Stream hostname identifier.Maximum length of 255 characters, limited by RFC5424
java.util.logging.RelpHandler.LOGGERNAME.appname	Stream application identifier.Maximum length of 48 characters, limited by RFC5424
java.util.logging.RelpHandler.LOGGERNAME.server.address	Connection destination address
java.util.logging.RelpHandler.LOGGERNAME.server.connectionTimeout	Time to wait before timing out connection
java.util.logging.RelpHandler.LOGGERNAME.server.port	Connection destination port
java.util.logging.RelpHandler.LOGGERNAME.server.readTimeout	Time to wait for destination to acknowledge sent data (low values cause duplicates)
java.util.logging.RelpHandler.LOGGERNAME.server.reconnectInterval	Time to wait between re-connection attempts
java.util.logging.RelpHandler.LOGGERNAME.server.writeTimeout	Time to wait for destination to accept data
java.util.logging.RelpHandler.LOGGERNAME.useStructuredData	Enables structured data containing uuid and source information

Passing properties file

-Dcom.teragrep.jla_04.logging.config.file=path/to/logging.properties

Code Usage

// RelpHandler without arguments defaults LOGGERNAME to "default"
System.setProperty("com.teragrep.jla_04.RelpHandler.default.server.address", "127.0.0.1");
System.setProperty("com.teragrep.jla_04.RelpHandler.default.server.port", "1667");
System.setProperty("com.teragrep.jla_04.RelpHandler.default.appname", "Default");
System.setProperty("com.teragrep.jla_04.RelpHandler.default.hostname", "localhost.localdomain");
RelpHandler relpHandler_default = new RelpHandler();

// Other logger
System.setProperty("com.teragrep.jla_04.RelpHandler.custom.server.address", "127.0.0.1");
System.setProperty("com.teragrep.jla_04.RelpHandler.custom.server.port", "1668");
System.setProperty("com.teragrep.jla_04.RelpHandler.custom.appname", "CustomLogger");
System.setProperty("com.teragrep.jla_04.RelpHandler.custom.hostname", "customhost.localdomain");
RelpHandler relpHandler_custom = new RelpHandler("custom");

// Reset logger and add handlers to it
LogManager.getLogManager().reset();
logger.addHandler(relpHandler_default);
logger.addHandler(relpHandler_custom);

// Set level and send messages
logger.setLevel(Level.WARNING);
logger.severe("Severe message");

Maven dependency definition

<dependency>
    <groupId>com.teragrep</groupId>
    <artifactId>jla_04</artifactId>
    <version>%VERSION%</version>
</dependency>

Contributing

You can involve yourself with our project by opening an issue or submitting a pull request.

Contribution requirements:

1. All changes must be accompanied by a new or changed test. If you think testing is not required in your pull request, include a sufficient explanation as why you think so.

2. Security checks must pass

3. Pull requests must align with the principles and values of extreme programming.

4. Pull requests must follow the principles of Object Thinking and Elegant Objects (EO).

Read more in our Contributing Guideline.

Contributor License Agreement

Contributors must sign Teragrep Contributor License Agreement before a pull request is accepted to organization’s repositories.

You need to submit the CLA only once. After submitting the CLA you can contribute to all Teragrep’s repositories.