How to use semantic logging support with the Splunk Plug-in for Eclipse

Splunk recommends using the Common Information Model (CIM) for semantic logging. If you added logging support to your Splunk® SDK for Java project, the Splunk Plug-in for Eclipse provides libraries and a set of templates to quickly create CIM-compliant log entries.

To use logging support:

  1. On the File menu, point to New, and then click Project.

  2. In the New Project window, expand the Java category and click Splunk SDK for Java Project. Click Next.

  3. On the Create a Splunk SDK for Java project screen, enter a name for your project.

  4. At the bottom of the window, under Add support for logging libraries, select Add logging support, and then choose one of the types listed. (If you don't see the Add logging support option, scroll down.)

  5. Set any other optional preferences, and then click Finish.

  6. In the project's Package Explorer, click the triangle next to your project's name to expand its contents.

  7. Right-click the src folder, point to New, and then click Class.

  8. In the New Java Class window, enter a name for the class and, under Which method stubs would you like to create?, select the check box next to public static void main(String[] args). Click Finish.

  9. Add some program logic.

  10. Before adding a logging template, do the following:

    1. Add the following import statement to the top of the file:

      import org.slf4j.*;
    2. Add the following line of code within main:

      Logger logger = LoggerFactory.getLogger("splunk.logger");

    The reason you need to do this is that each logging template assumes that there is a variable logger in the scope of class org.slf4j.Logger, and that you'll get the logger from the class org.slf4j.LoggerFactory.

  11. To see all the available logging templates, type spog, and then press Ctrl + Spacebar (or your custom Content Assist key combination):

    • spogdebug - log a structured debug message
    • spogerror - log a structured error message
    • spoginfo - log a structured info message
    • spogtrace - log a structured trace message
    • spogwarn - log a structured warn message
    Screen shot of the template proposals after typing spog
    Note: At this time, the Splunk plug-in for Eclipse incorrectly inserts a SplunkLogEvent object when you insert a logging template. Because the class name in the Splunk logging for Java library was changed to SplunkCIMLogEvent, this will not work. Until this issue has been fixed, you must manually change all instances of SplunkLogEvent to SplunkCIMLogEvent, including any import statements that have been added. The rest of this topic assumes that the correct object has been inserted. We apologize for the inconvenience.

    Each template expands into a single command that creates a new SplunkCIMLogEvent object and logs it using Simple Logging Facade for Java (SLF4J). Expanding the template also adds the necessary import statement. The SplunkCIMLogEvent object is defined in the splunk-plugin-slf4j.jar file that is created when you select the logging support option when creating your project.

  12. Double-click one of the logging templates, and "spog" is replaced by the code necessary to log the specified error message. Be sure to replace the placeholder values with actual ones. For instance, you could replace eventName and eventId with "ssh login failed" and "ssh:login_fail" (including quotation marks), respectively.

  13. You can add any combination of key-value pairs to the SplunkCIMLogEvent object, but the SplunkCIMLogEvent object also provides numerous setters for common fields. To see all of the available setters, inside the template body, type set. Then press Ctrl + Spacebar (or your custom Content Assist key combination). Browse the list and choose the template you want.

    Screen shot of the template proposals after typing set
  14. To make your app log to Splunk Enterprise, you will need to edit the configuration file that was added when you created the project. The configuration file is at the root level of the project, but its name is different depending on the framework you chose:

    • Logback: logback.xml
    • Log4j:
    • java.util.logging: To enable java.util.logging support, add the following VM argument to this project's run configuration:

    For this example, we'll look at logback.xml, but the other configuration files are very similar. Double-click logback.xml in the Package Explorer and expand the appender elements until you find the one with its name attribute set to splunkrawtcp. This element defines a log appender, which writes to a Splunk Enterprise TCP input. By default it writes to TCP port 5150 on the localhost. You will need to add this input to your Splunk Enterprise instance (or change the host and port elements to point to a TCP input). For more about setting up a TCP input in "Add a network input using Splunk Web" in the main Splunk Enterprise documentation.

  15. Also in the configuration file, expand the logger element, and then change splunk.logger in the name attribute to the name of the logger you specified when you created your Logger object in step 3 ("splunk.logger").

You've now enabled your app to log custom events to your Splunk Enterprise log.