Enable logging to TCP inputs in your Java project

This topic describes how to integrate the Splunk logging for Java library into your Java project to enable logging to Splunk Enterprise TCP inputs. To learn how to add logging to HTTP Event Collector, see Enable logging to HTTP Event Collector in your Java project.

To use the Splunk logging for Java library with your Java project, do the following:

  1. Add the Splunk logging for Java library to your project
  2. Add the logging library you have chosen to use (Logback, Log4j 2, or java.util.logging) to your project.
  3. Open a TCP input on a Splunk Enterprise instance to write your log events to.
  4. Configure your logging system.
  5. Use the SplunkCimLogEvent class to generate well-formed log entries.

Add the Splunk logging for Java library to your project

If you are using Maven, add the following to the dependencies section of your pom.xml file. Update the version number to correspond to the version of Splunk logging for Java that you are using.

    <dependency>
        <groupId>com.splunk.logging</groupId>
        <artifactId>splunk-library-javalogging</artifactId>
        <version>1.5.0</version>
    </dependency>

If you are using Ant, download the JAR file from http://dev.splunk.com/goto/loggingjavajar, and then add it to your project as a dependency.

Add the logging framework you plan to use

The three major frameworks are Logback, Log4j 2, and java.util.logging (which is included with the JDK). Follow the instructions provided here to add your preferred logging framework to your project.

Logback

If you are using Maven, add the following to the dependencies section of your pom.xml file to include the necessary libraries:

<dependency>
	<groupId>org.slf4j</groupId>
	<artifactId>slf4j-api</artifactId>
	<version>1.7.7</version>
</dependency>
<dependency>
	<groupId>ch.qos.logback</groupId>
	<artifactId>logback-classic</artifactId>
	<version>1.1.3</version>
</dependency>
<dependency>
	<groupId>ch.qos.logback</groupId>
	<artifactId>logback-core</artifactId>
	<version>1.1.3</version>
</dependency>

Otherwise, download and add the following .JAR files to your classpath, as described on the Logback setup page:

  • logback-core-1.1.3.jar
  • logback-classic-1.1.3.jar
  • slf4j-api-1.7.7.jar

Log4j 2

If you are using Maven, add the following to the dependencies section of your pom.xml file to include the necessary library:

<dependency>
	<groupId>org.apache.logging.log4j</groupId>
	<artifactId>log4j-core</artifactId>
	<version>2.3</version>
</dependency>

Otherwise, download and add the following .JAR file to your classpath, as described on the Log4j download and setup page:

  • log4j-core-2.3.jar

java.util.logging

The java.util.logging library ships with the JDK, so just add the following import statement:

import java.util.logging.*;

SLF4J

To use SLF4J, download and add the following .JAR files to your classpath, as described in the SLF4J user manual:

  • slf4j-api-1.7.12.jar
  • slf4j-simple-1.7.12.jar

Then include the import statement and (at least) the Java code shown here:

import org.slf4j.*;

...

    Logger logger = LoggerFactory.getLogger("splunk.logger");
    logger.info("This is a test");

Create a TCP input in Splunk Enterprise that you will write to

To learn how to create a Splunk Enterprise TCP input, see Get data from TCP and UDP ports.

Configure your logging system

In this section are simple example configurations for each of the three logging systems.

Note: The example configuration files shown here are available in the Splunk logging for Java download in splunk-library-javalogging/src/test/resources.

The log4j2.xml and logback.xml files should be placed somewhere in the classpath of your program. Specify jdklogging.properties to your program by passing the following to the Java executable:

-Djava.util.logging.config.file=/path/to/jdklogging.properties

Logback

Following is an example Logback configuration. This example assumes that you have Splunk Enterprise running locally (with an IP address of 127.0.0.1), with a TCP input configured on port 15000. TCP inputs do not have the same port number as the Splunk Enterprise management port.

First, define an appender that writes to a TCP socket. Because Logback does not ship with a usable appender for TCP sockets, use the TcpAppender class included with the Splunk logging for Java library.

You can control the logging format by changing the pattern. For details, see PatternLayout in Chapter 6 of the Logback documentation. The pattern in the example produces a simple timestamp, followed by the full message and a newline, like the following:

2012-04-26 14:54:38,461 [%thread] %level text of my event

After you define an appender, define a logger named splunk.logger. The logger writes to the socket appender.

Put the following in logback.xml on the classpath, changing values to correspond to your setup as necessary:

<configuration>
	<appender name="socket" class="com.splunk.logging.TcpAppender">
		<RemoteHost>127.0.0.1</RemoteHost>
		<Port>15000</Port>
		<layout class="ch.qos.logback.classic.PatternLayout">
		<pattern>%date{ISO8601} [%thread] %level: %msg%n</pattern>
		</layout>
	</appender>

	<logger name="splunk.logger" additivity="false" level="INFO">
		<appender-ref ref="socket"/>
	</logger>

	<root level="INFO">
		<appender-ref ref="socket"/>
	</root>
</configuration>

Log4j 2

Following is an example Log4j 2 configuration. This example assumes that you have Splunk Enterprise running locally (with an IP address of 127.0.0.1), with a TCP input configured on port 15000. TCP inputs do not have the same port number as the Splunk Enterprise management port.

First, define an appender that writes to a TCP socket. The example uses the Log4j SocketAppender.

You can control the logging format by changing the pattern. For details, see PatternLayout in the Log4j documentation. The pattern in the example produces a priority, followed by the full message and a newline.

After you define an appender, define a logger named splunk.logger. The logger writes to the socket appender.

Put the following in log4j2.xml on the classpath, changing values to correspond to your setup as necessary:

<Configuration status="info" name="example" packages="">
	<Appenders>
		<Socket name="socket" host="127.0.0.1" port="15000">
		<PatternLayout pattern="%p: %m%n" charset="UTF-8"/>
		</Socket>
	</Appenders>
	<Loggers>
		<Root level="INFO">
		</Root>
		<Logger name="splunk.logger" level="info">
		<AppenderRef ref="socket"/>
		</Logger>
	</Loggers>
</Configuration>

java.util.logging

Following is an example java.util.logging configuration. This example assumes that you have Splunk Enterprise running on the localhost, with a TCP input configured on port 15000. TCP inputs do not have the same port number as the Splunk Enterprise management port.

First, specify the java.util.logging SocketHandler as the default handler. Then, set the default logging level for the root logger. Next, create a logger called splunk.logger, set its level to INFO, and specify SocketHandler as its logger. Finally, configure the SocketHandler to write to TCP port localhost:15000.

You can control the logging format using the SimpleFormatter class, with syntax as defined on the definition page for the Formatter class.

Specify jdklogging.properties to your program by passing the following to the Java executable:

-Djava.util.logging.config.file=/path/to/jdklogging.properties

Put the following in jdklogging.properties, changing values to correspond to your setup as necessary:

# Sets SocketHandler to be the default handler for all loggers.
handlers = java.util.logging.SocketHandler
config =

# Set the default logging level for the root logger
.level = INFO

# Implicitly create a logger called 'splunk.logger', set its 
# level to INFO, and make it log using the SocketHandler.
splunk.logger.level = INFO
splunk.logger.handlers = java.util.logging.SocketHandler

# Configure the SocketHandler to write to TCP port localhost:15000. 
java.util.logging.SocketHandler.level = INFO
java.util.logging.SocketHandler.host = localhost
java.util.logging.SocketHandler.port = 15000

# Set the format of SimpleFormatter. 
java.util.logging.SocketHandler.formatter = SimpleFormatter
java.util.logging.SimpleFormatter.format = "%1$F %1$r %4$s: %6$s%n"

Use the SplunkCimLogEvent class to generate well-formed log entries

Import com.splunk.logging.SplunkCimLogEvent and use it to create events.

You can use the addField method to add a key/value pair. If you are logging exceptions, use the addThrowableWithStacktrace method, which formats exceptions. The setAuthAction method specifies the action performed on the resource. For a list of all of the available convenience methods, see the SplunkCimLogEvent class reference documentation.

The following example code uses Logback as its logger, but the part relevant to SplunkCimLogEvent will be unchanged for other frameworks:

logger.info(new SplunkCimLogEvent("Event name", "event-id") {{
	addField("name", "value");

	addThrowableWithStacktrace(ex);

	setAuthAction("deny");
}});