Release/0.9.0 - all changes

CHANGELOG.md

@@ -1,5 +1,29 @@
-# Splunk Logging Library for JavaScript (beta)
+# Splunk logging for JavaScript
+
+## v0.9.0
+
+### New features & APIs
+
+* Added the ability to configure automated batching with 3 settings: `batchInterval`, `maxBatchCount`, & `maxBatchSize`.
+* Added the ability to retry sending to Splunk Enterprise or Splunk Cloud in the case of network errors with the `maxRetries` configuration setting.
+* Added the ability to configure a custom Splunk Enterprise or Splunk Cloud event format by overriding `eventFormatter(message, severity)`.
+
+### Breaking Changes
+
+* Removed the `autoFlush` configuration setting. To achieve the same effect, set `config.maxBatchCount` to `0`.
+* Removed support for middleware functions.
+* The `context` object has been simplified, `config` and `requestOptions` can no longer be specified there; please use those settings directly on the logger.
+
+### Examples
+
+* Removed the `middleware.js` example.
+* Renamed the `batching.js` example to `manual_batching`.
+* Added the `all_batching.js`, `custom_format.js`, `retry.js` examples.
+
+### Minor changes
+
+* Significant refactor of internal functions.
 
 ## v0.8.0 - beta
 
-* Beta release.
+* Beta release.

README.md

@@ -1,26 +1,34 @@
-# Splunk Logging Library for JavaScript (beta)
+# Splunk logging for JavaScript
 
-#### Version 0.8.0
+#### Version 0.9.0
 
-This project provides a simple interface for logging to Splunk's Event Collector.
+This project provides a simple JavaScript interface for logging to HTTP Event Collector in Splunk Enterprise and Splunk Cloud.
 
 ## Requirements
 
-* Splunk 6.3+.
-* An HTTP Event Collector token from your Splunk server.
-* Node.js v0.10+.
+* Node.js v0.10 or later.
+* Splunk Enterprise 6.3.0 or later, or Splunk Cloud.
+* An HTTP Event Collector token from your Splunk Enterprise server.
 
 ## Installation
 
-If you already have Node.js and npm installed, simply run: `npm install --save splunk-logging`.
+First, update npm to the latest version by running:
+
+    sudo npm install npm -g
+
+Then run: 
+
+    npm install --save splunk-logging
 
 ## Usage
 
-See the `examples` folder for more examples:
+See the `examples` folder for usage examples:
 
-* `basic.js`: shows how to configure a logger and send a log message to Splunk.
-* `batching.js`: shows how to queue log messages, and send them in batches.
-* `middleware.js`: shows how to add an express-like middleware function to be called before sending log messages to Splunk.
+* `all_batching.js`: Shows how to configure a logger with the 3 batching settings: `batchInterval`, `maxBatchCount`, & `maxBatchSize`.
+* `basic.js`: Shows how to configure a logger and send a log message to Splunk.
+* `custom_format.js`: Shows how to configure a logger to log messages to Splunk using a custom format.
+* `manual_batching.js`: Shows how to queue log messages, and send them in batches by manually calling `flush()`.
+* `retry.js`: Shows how to configure retries on errors.
 
 ### Basic example
 
@@ -35,7 +43,7 @@ var config = {
 var Logger = new SplunkLogger(config);
 
 var payload = {
-    // Message can be anything, doesn't have to be an object
+    // Message can be anything; doesn't have to be an object
     message: {
         temperature: "70F",
         chickenCount: 500
@@ -51,7 +59,7 @@ Logger.send(payload, function(err, resp, body) {
 
 ## Community
 
-Stay connected with other developers building on Splunk.
+Stay connected with other developers building on Splunk software.
 
 <table>
 
@@ -62,7 +70,7 @@ Stay connected with other developers building on Splunk.
 
 <tr>
 <td><b>Issues</b>
-<td><span>https://github.com/splunk/splunk-logging-javascript/issues/</span></td>
+<td><span>https://github.com/splunk/splunk-javascript-logging/issues/</span></td>
 </tr>
 
 <tr>
@@ -84,7 +92,7 @@ Stay connected with other developers building on Splunk.
 
 ### Contact us
 
-You can reach the Developer Platform team at _devinfo@splunk.com_.
+You can reach the developer platform team at _devinfo@splunk.com_.
 
 ## License
 

examples/all_batching.js

@@ -0,0 +1,95 @@
+/*
+ * Copyright 2015 Splunk, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"): you may
+ * not use this file except in compliance with the License. You may obtain
+ * a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations
+ * under the License.
+ */
+
+/**
+ * This example shows how to batch events with the
+ * SplunkLogger with all available settings:
+ * batchInterval, maxBatchCount, & maxBatchSize.
+ */
+
+// Change to require("splunk-logging").Logger;
+var SplunkLogger = require("../index").Logger;
+
+/**
+ * Only the token property is required.
+ * 
+ * Here, batchInterval is set to flush every 1 second, when
+ * 10 events are queued, or when the size of queued events totals
+ * more than 1kb.
+ */
+var config = {
+    token: "your-token-here",
+    url: "https://localhost:8088",
+    batchInterval: 1000,
+    maxBatchCount: 10,
+    maxBatchSize: 1024 // 1kb
+};
+
+// Create a new logger
+var Logger = new SplunkLogger(config);
+
+Logger.error = function(err, context) {
+    // Handle errors here
+    console.log("error", err, "context", context);
+};
+
+// Define the payload to send to Splunk's Event Collector
+var payload = {
+    // Message can be anything, doesn't have to be an object
+    message: {
+        temperature: "70F",
+        chickenCount: 500
+    },
+    // Metadata is optional
+    metadata: {
+        source: "chicken coop",
+        sourcetype: "httpevent",
+        index: "main",
+        host: "farm.local",
+    },
+    // Severity is also optional
+    severity: "info"
+};
+
+console.log("Queuing payload", payload);
+// Don't need a callback here
+Logger.send(payload);
+
+var payload2 = {
+    message: {
+        temperature: "75F",
+        chickenCount: 600,
+        note: "New chickens have arrived"
+    },
+    metadata: payload.metadata
+};
+
+console.log("Queuing second payload", payload2);
+// Don't need a callback here
+Logger.send(payload2);
+
+/**
+ * Since we've configured batching, we don't need
+ * to do anything at this point. Events will
+ * will be sent to Splunk automatically based
+ * on the batching settings above.
+ */
+
+// Kill the process
+setTimeout(function() {
+    console.log("Events should be in Splunk! Exiting...");
+    process.exit();
+}, 2000);

examples/basic.js

@@ -23,20 +23,10 @@ var SplunkLogger = require("../index").Logger;
 
 /**
  * Only the token property is required.
- * Defaults are listed explicitly.
- *
- * Alternatively, specify config.url like so:
- *
- * "https://localhost:8088/services/collector/event/1.0"
  */
 var config = {
     token: "your-token-here",
-    host: "localhost",
-    path: "/services/collector/event/1.0",
-    protocol: "https",
-    port: 8088,
-    level: "info",
-    autoFlush: true
+    url: "https://localhost:8088"
 };
 
 // Create a new logger
@@ -47,9 +37,9 @@ Logger.error = function(err, context) {
     console.log("error", err, "context", context);
 };
 
-// Define the payload to send to Splunk's Event Collector
+// Define the payload to send to HTTP Event Collector
 var payload = {
-    // Message can be anything, doesn't have to be an object
+    // Message can be anything, it doesn't have to be an object
     message: {
         temperature: "70F",
         chickenCount: 500
@@ -59,14 +49,40 @@ var payload = {
         source: "chicken coop",
         sourcetype: "httpevent",
         index: "main",
-        host: "farm.local",
+        host: "farm.local"
     },
     // Severity is also optional
     severity: "info"
 };
 
 console.log("Sending payload", payload);
+
+/**
+ * Since maxBatchCount is set to 1 by default,
+ * calling send will immediately send the payload.
+ * 
+ * The underlying HTTP POST request is made to
+ *
+ *     https://localhost:8088/services/collector/event/1.0
+ *
+ * with the following body
+ *
+ *     {
+ *         "source": "chicken coop",
+ *         "sourcetype": "httpevent",
+ *         "index": "main",
+ *         "host": "farm.local",
+ *         "event": {
+ *             "message": {
+ *                 "temperature": "70F",
+ *                 "chickenCount": 500
+ *             },
+ *             "severity": "info"
+ *         }
+ *     }
+ *
+ */
 Logger.send(payload, function(err, resp, body) {
     // If successful, body will be { text: 'Success', code: 0 }
     console.log("Response from Splunk", body);
-});
+});