Overview of Splunk logging for Java

Welcome to Splunk logging for Java!

Splunk logging for Java enables you to log events to either HTTP Event Collector or a TCP input on a Splunk Enterprise instance from within your Java applications. You can use any of the three major Java logging frameworks: Logback, Log4j 2, and java.util.logging. Splunk logging for Java is also enabled for Simple Logging Facade for Java (SLF4J).

Note: If you are new to Java logging, or just need a refresher, the following are good starting points:

In particular, Splunk logging for Java provides:

  • Appender classes that package events into the proper format for the input type you're using--either HTTP Event Collector or TCP inputs.
  • Handler classes that export the logging events.
  • An optional error handler to catch failures for HTTP Event Collector events.
  • Example configuration files for all three frameworks that show how to configure the frameworks to write to HTTP Event Collector or Splunk TCP ports.
  • Support for batching events (sent to HTTP Event Collector only).

Choosing a logging destination

HTTP Event Collector is ideal if you want to log data from your Java application in any of the following scenarios:

  • You want to send events directly to Splunk Enterprise rather than requiring writing to disk and installing a forwarder
  • You want to send data securely to Splunk Enterprise, with the option of an HTTPS connection and a unique token.
  • You expect to send data at a high volume and frequency.

Alternately, you can log to a TCP input either directly or by first logging to a file and then using a Splunk Universal Forwarder to monitor the file and send data any time the file is updated. Doing so gives you the features of the Universal Forwarder, plus added robustness from having persistent files. In either case, you can use the SplunkCimLogEvent class provided by this library to construct your log events according to Splunk recommended best practices.

Getting started

HTTP Event Collector

To get started with logging to Splunk HTTP Event Collector using Splunk logging for Java, you should first understand how HTTP Event Collector works, and what you need to configure before you can use it.

Once you're familiar with HTTP Event Collector, you can proceed to the Get started with Splunk logging for Java topic.

TCP Inputs

To get started with logging to Splunk Enterprise TCP inputs, you should first understand how network inputs work in Splunk Enterprise, and what you need to configure before you can use them.

Once you're familiar with TCP inputs, you can proceed to the Get started with Splunk logging for Java topic.
Architecture
Splunk logging for Java is comprised of two groups of classes within com.splunk.logging--one for logging to HTTP Event Collector and another for logging to TCP inputs.

HTTP Event Collector

There are five classes for logging to HTTP Event Collector:

  • HttpAppender: Creates logging events to send to HTTP Event Collector. This class is for all loggers except Logback.
  • HttpLogbackAppender: Creates logging events to send to HTTP Event Collector using Logback.
  • HttpInputHandler: Exports logging events to HTTP Event Collector.
  • HttpInputLoggingErrorHandler: HTTP Event Collector error handler to which your application can subscribe to catch error responses from the Splunk server.
  • HttpInputLoggingEventInfo: Container for event data.

In addition, the HttpInputEventSender class is an internal helper class that is used by the other classes in the library. Do not use this class.

TCP inputs

There are two classes for logging to TCP inputs: 

  • SplunkCimLogEvent: Encapsulates the best practice logging semantics recommended by Splunk. Events created with this class contain key-value pairs, properly formatted and quoted for logging with any of Java's standard logging libraries (Logback, Log4j 2, and java.util.logging) and indexing by Splunk Enterprise. SplunkCimLogEvent has convenience methods to set the fields defined in the standard Splunk Common Information Model (CIM).
  • TcpAppender: This class writes logging events to a TCP Input. It extends from the ch.qos.logback.core.AppenderBase<E> class, and is included with Splunk logging for Java because Logback does not ship with a usable appender for TCP sockets.

Other considerations

This section contains notes on resilience, load balancing, and thread safety.

Resilience

All of the appenders mentioned in the documentation will attempt to reconnect in case of dropped connections.

Load Balancing

It's easy to set up HTTP Event Collector in a load balanced Splunk environment. See High volume HTTP Event Collector data collection using distributed deployment for more information about your options.
For TCP inputs, you can set up a Splunk Universal Forwarder, and then have all your logging sources write to that TCP input. Use the Universal Forwarder's load balancing features to distribute the data from there to a set of indexers.

Thread Safety

For HTTP Event Collector, Log4J, Logback, and java.util.logging adapters for HTTP Event Collector are thread-safe.
For TCP inputs, Log4J and Logback are thread-safe.