From 0300e26c892ad37e440c3fc91ada1c8583ddb1d5 Mon Sep 17 00:00:00 2001 From: Andrea Longdon Date: Mon, 17 Dec 2018 11:52:20 -0800 Subject: [PATCH 1/3] Updated the readme --- README.md | 372 +++--------------------------------------------------- 1 file changed, 21 insertions(+), 351 deletions(-) diff --git a/README.md b/README.md index f6dd01ca..a78529c4 100644 --- a/README.md +++ b/README.md @@ -2,369 +2,39 @@ #### Version 1.6.2 -This project provides utilities to easily log data using Splunk's recommended -best practices to any supported logger, using any of the three major Java -logging frameworks (Logback, Log4J 2, and java.util.logging), to the [HTTP Event Collector](http://dev.splunk.com/view/event-collector/SP-CAAAE6M) and to Splunk TCP -inputs. +Splunk logging for Java enables you to log events to HTTP Event Collector or to a TCP input on a Splunk Enterprise instance within your Java applications. You can use three major Java logging frameworks: [Logback](http://logback.qos.ch), [Log4j 2](http://logging.apache.org/log4j/2.x/), and [java.util.logging](https://docs.oracle.com/javase/7/docs/api/java/util/logging/package-summary.html). Splunk logging for Java is also enabled for [Simple Logging Facade for Java (SLF4J)](http://www.slf4j.org). -In particular, it provides: +Splunk logging for Java provides: -* Appenders for HTTP Event Collector for pushing from Logback, Log4J 2 and java.util.logging. -* The `SplunkCimLogEvent` class, which encapsulates the CIM (Common - Information Model) in Splunk Enterprise and best practices for semantic - logging. -* A TCP appender for Logback, which is the only one of the three frameworks - listed above that doesn't provide native support for writing to TCP ports. -* Example configuration files for all three frameworks, showing how to - configure them to write to Splunk TCP ports. +* Appender classes that package events into the proper format for the input type you're using (HTTP Event Collector or TCP). -## Advice +* Handler classes that export the logging events. -### Splunk Universal Forwarder vs Splunk TCP Inputs +* An optional error handler to catch failures for HTTP Event Collector events. -If you can, it is better to log to files and monitor them with a Splunk -Universal Forwarder. This provides you with the features of the Universal -Forwarder, and added robustness from having persistent files. However, there -are situations where using a Universal Forwarder is not a possibility. In -these cases, writing directly to a TCP input is a reasonable approach. +* Example configuration files for all three frameworks that show how to configure the frameworks to write to HTTP Event Collector or TCP ports. -In either scenario, we recommend using the `SplunkCimLogEvent` class -provided by this library to construct your log events according to Splunk's -recommended best practices. +* Support for batching events (sent to HTTP Event Collector only). -### Resilience +## Documentation and resources -All of the TCP appenders we show config files for (SocketHandler for -java.util.logging, SocketAppender for Log4J 2, and the TCPAppender provided -with this library for Logback) will attempt to reconnect in case of dropped -connections. +* For more information about installing and using Splunk logging for Java, see: + [Overview of Splunk logging for Java](http://dev.splunk.com/goto/sdk-slj). -### Data Cloning +* For API reference documentation: + [Splunk logging for Java Reference](https://docs.splunk.com/DocumentationStatic/JavaLogging/1.6.2/index.html). -You can use [data cloning](http://docs.splunk.com/Splexicon:Datacloning) by -providing multiple instances of your TCP handler in your logging -configuration, each instance pointing to different indexers. +* For all things developer with Splunk: + [Splunk Developer Portal](http://dev.splunk.com). -### Load Balancing +* For more about about Splunk in general, see: + [Splunk>Docs](http://docs.splunk.com/Documentation/Splunk). -Rather than trying to reinvent -[load balancing](http://docs.splunk.com/Splexicon:Loadbalancing) across your -indexers in your log configuration, set up a Splunk Universal Forwarder with a -TCP input. Have all your logging sources write to that TCP input, and use the -Universal Forwarder's load balancing features to distribute the data from -there to a set of indexers. - -### Thread Safety - -Log4j and Logback are thread-safe. - -### Sending events to HTTP Event Collector - -HTTP Event Collector requires Splunk 6.3+. Splunk Java library supports sending -events through `java.util.logging`, `log4j` and `logback` standard loggers. -In order to use HTTP Event Collector it has to be enabled on the server and an -application token should be created. - -Splunk Logging for Java includes several examples of configuration files in -`src/test/resources` folder. For instance `java.util.logging` configuration looks like: - -``` -handlers=com.splunk.logging.HttpEventCollectorLoggingHandler -com.splunk.logging.HttpEventCollectorLoggingHandler.url=https://splunk-server:8088 -com.splunk.logging.HttpEventCollectorLoggingHandler.token= -``` - -Sending events is simple: - -```java -Logger LOGGER = java.util.logging.Logger.getLogger("splunk.java.util"); -LOGGER.info("hello world"); -``` - -#### Message Format -An event message format could be configured for HTTP event appender in logging framework configuration. It could have one of the two possible values - text, json. It is an optional property with default value as 'text'. Message format 'json' is used where the event message could be in json format. - -It is also possible to use a custom event body serializer for the HTTP event adapter, to format the logging event however you please. Simply create a class implementing `com.splunk.logging.EventBodySerializer`, and add the full class name as a property (`eventBodySerializer`) to the adapter. Default will be a JSON event body containing message, severity, and other properties. - -For more information, see http://dev.splunk.com/view/SP-CAAAE2K. - -# License +## License Splunk logging for Java is licensed under the Apache License 2.0. -Details can be found in the LICENSE file. - -## Using Splunk Logging for Java - -To use the Splunk Logging for Java library, you will need to add it and the -logging library you have chosen to use to your project, open a TCP input on a -Splunk instance to write your log events to, configure your logging system, -and then use the `SplunkCimLogEvent` class to generate well formed log -entries. - -1. Add the Splunk Logging for Java library to your project. If you are using - Maven, add the following to your dependencies section: - - ```xml - - com.splunk.logging - splunk-library-javalogging - 1.5.2 - - ``` - - You might also want to add the following repository to your repositories section: - - ``` - - splunk - splunk-releases - http://splunk.jfrog.io/splunk/ext-releases-local - - ``` - - If you are using Ant, download the corresponding JAR file from - [http://dev.splunk.com/goto/sdk-slj](http://dev.splunk.com/goto/sdk-slj). - -2. Add the logging framework you plan to use. The three big ones in use today - are *Logback*, *Log4J 2.x*, and *java.util.logging* (which comes with your - JDK). If you are using Maven, add the corresponding dependencies below to - your `pom.xml`: - - * Logback: - - ```xml - - org.slf4j - slf4j-api - 1.7.5 - - - ch.qos.logback - logback-classic - 1.0.13 - - - ch.qos.logback - logback-core - 1.0.13 - - ``` - * Log4J 2.x: - - ```xml - - org.apache.logging.log4j - log4j-core - 2.0-beta9 - - ``` - - * java.util.logging ships with the JDK. - -3. Create a TCP input in Splunk that you will write to. To learn how, see - [Get data from TCP and UDP ports](http://docs.splunk.com/Documentation/Splunk/latest/Data/Monitornetworkports). - -4. Configure your logging system. Here are simple example configurations for - each of the three systems. The `log4j2.xml` and `logback.xml` files - should be put somewhere in the classpath of your program. - jdklogging.properties should be specified to your program by passing the - following to the Java executable: - - ``` - -Djava.util.logging.config.file=/path/to/jdklogging.properties - ``` - - * Logback (to be put in `logback.xml` on the classpath) - - ```xml - - - - - 127.0.0.1 - 15000 - - %date{ISO8601} [%thread] %level: %msg%n - - - - - - - - - - - - ``` - - * Log4j 2.x (to be put in `log4j2.xml` on the classpath) - - ```xml - - - - - - - - - - - - - - - - - - ``` - - * java.util.logging - - ``` - # We will write to a Splunk TCP input using java.util.logging's - # SocketHandler. This line sets it 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. - # Note that TCP inputs are *not* the same as Splunk's management - # port. You can find the documentation about how to open TCP - # inputs in Splunk at http://docs.splunk.com/Documentation/Splunk/latest/Data/Monitornetworkports. - # - # You can find the documentation on using a SocketHandler at http://docs.oracle.com/javase/7/docs/api/java/util/logging/SocketHandler.html. - - java.util.logging.SocketHandler.level = INFO - java.util.logging.SocketHandler.host = localhost - java.util.logging.SocketHandler.port = 15000 - - # With Java 7, you can set the format of SimpleFormatter. On Java 6, - # you cannot and you will probably want to write a custom formatter - # for your system. The syntax of the format string is given at - # http://docs.oracle.com/javase/7/docs/api/java/util/Formatter.html#syntax - # and http://docs.oracle.com/javase/7/docs/api/java/util/logging/SimpleFormatter.html - # for logging specific behavior. - java.util.logging.SocketHandler.formatter = SimpleFormatter - java.util.logging.SimpleFormatter.format = "%1$F %1$r %4$s: %6$s%n" - ``` - -5. Import `com.splunk.logging.SplunkCimLogEvent` and use it to create - events. This example code uses Logback as the logger, but the part - relevant to `SplunkCimLogEvent` will be unchanged for other frameworks: - - ```java - logger.info(new SplunkCimLogEvent("Event name", "event-id") {{ - // You can add an arbitrary key=value pair with addField. - addField("name", "value"); - - // If you are logging exceptions, use addThrowable, which - // does nice formatting. If ex is an exception you have caught - // you would log it with - addThrowableWithStacktrace(ex); - - // SplunkCimLogEvent provides lots of convenience methods for - // fields defined by Splunk's Common Information Model. See - // the SplunkCimLogEvent JavaDoc for a complete list. - setAuthAction("deny"); - }}); - ``` - -### Using logback-access with HEC appender -[logback-access](https://logback.qos.ch/access.html) logs different type of events (`ch.qos.logback.access.spi.IAccessEvent`) as logback classic, which logs `ch.qos.logback.classic.spi.ILoggingEvent`. - -To use this library with logback-access, you can try the following configuration: - -* logback access (to be put in `logback-access.xml` on the classpath) - ``` - - - - combined - - - - - https://localhost:8088 - 00000000-0000-0000-0000-000000000000 - devhost - main - logback-client - logback - true - - - %h %l %u %t %r %s %b - - - - - - - ``` - If you run into any issue, try add a `debug=true` attribute to the `configuration` for debugging. - - -## Splunk Enterprise - -If you haven't already installed Splunk Enterprise, download it here: -[http://www.splunk.com/download](http://www.splunk.com/download). -For more about installing and running Splunk Enterprise and system requirements, -see [Splunk Enterprise Installation Manual](http://docs.splunk.com/Documentation/Splunk/latest/Installation/). - -## Resources - -Documentation for this library - -* [http://dev.splunk.com/goto/sdk-slj](http://dev.splunk.com/goto/sdk-slj) - -Splunk Common Information Model - -* [http://docs.splunk.com/Documentation/Splunk/latest/Knowledge/UnderstandandusetheCommonInformationModel](http://docs.splunk.com/Documentation/Splunk/latest/Knowledge/UnderstandandusetheCommonInformationModel) - -Splunk Best Practice Logging Semantics - -* [http://dev.splunk.com/view/logging-best-practices/SP-CAAADP6](http://dev.splunk.com/view/logging-best-practices/SP-CAAADP6) - -Introduction to the Splunk product and some of its capabilities - -* [http://docs.splunk.com/Documentation/Splunk/latest/User/SplunkOverview](http://docs.splunk.com/Documentation/Splunk/latest/User/SplunkOverview) +See the LICENSE file for details. ## Contributions @@ -374,13 +44,13 @@ command: git clone https://github.com/splunk/splunk-library-javalogging.git -If you want to make a code contribution, go to the [Open Source](http://dev.splunk.com/view/opensource/SP-CAAAEDM) page for more information. +To make a code contribution, see the [Open Source](http://dev.splunk.com/view/opensource/SP-CAAAEDM) page for more information. ## Support -The Splunk logging library for Java is community-supported. +The Splunk logging for Java is community-supported. -1. You can find help through our community on [Splunk Answers](http://answers.splunk.com/) (use the `logging-library-java` tag to identify your questions). +1. You can find help through our community on [Splunk Answers](http://answers.splunk.com/) (use the "logging-library-java" tag to identify your questions). 2. File issues on [GitHub](https://github.com/splunk/splunk-library-javalogging/issues). ## Contact us From bc31ebeccf82528143488bdf78a8af3c6966e607 Mon Sep 17 00:00:00 2001 From: Andrea Longdon Date: Mon, 17 Dec 2018 11:56:32 -0800 Subject: [PATCH 2/3] Minor tweaks --- README.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index a78529c4..47db0111 100644 --- a/README.md +++ b/README.md @@ -18,23 +18,23 @@ Splunk logging for Java provides: ## Documentation and resources -* For more information about installing and using Splunk logging for Java, see: +* For more information about installing and using Splunk logging for Java, see [Overview of Splunk logging for Java](http://dev.splunk.com/goto/sdk-slj). -* For API reference documentation: - [Splunk logging for Java Reference](https://docs.splunk.com/DocumentationStatic/JavaLogging/1.6.2/index.html). +* For reference documentation, see the + [Splunk logging for Java API reference](https://docs.splunk.com/DocumentationStatic/JavaLogging/1.6.2/index.html). -* For all things developer with Splunk: +* For all things developer with Splunk, see the [Splunk Developer Portal](http://dev.splunk.com). -* For more about about Splunk in general, see: +* For more about about Splunk in general, see [Splunk>Docs](http://docs.splunk.com/Documentation/Splunk). ## License Splunk logging for Java is licensed under the Apache License 2.0. -See the LICENSE file for details. +See the [LICENSE file](/license.md) for details. ## Contributions From dfb5e053d6549161129683920fadad800655dc00 Mon Sep 17 00:00:00 2001 From: apruneda Date: Mon, 17 Dec 2018 12:38:19 -0800 Subject: [PATCH 3/3] Update README.md The Open Source page is old. --- README.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/README.md b/README.md index 47db0111..82b2c63e 100644 --- a/README.md +++ b/README.md @@ -44,8 +44,6 @@ command: git clone https://github.com/splunk/splunk-library-javalogging.git -To make a code contribution, see the [Open Source](http://dev.splunk.com/view/opensource/SP-CAAAEDM) page for more information. - ## Support The Splunk logging for Java is community-supported.