Release/0.9.0 - all changes

CHANGELOG.md

@@ -1,5 +1,29 @@
 # Splunk Logging Library for JavaScript (beta)
 
+## v0.9.0 - beta
+
+### New Features & APIs
+
+* Added the ability to configure automated batching with 3 settings: `batchInterval`, `maxBatchCount`, & `maxBatchSize`.
+* Added the ability to retry sending to Splunk in the case of network errors with the `maxRetries` configuration setting.
+* Added the ability to configure a custom Splunk 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.

README.md

@@ -1,6 +1,6 @@
 # Splunk Logging Library for JavaScript (beta)
 
-#### Version 0.8.0
+#### Version 0.9.0
 
 This project provides a simple interface for logging to Splunk's Event Collector.
 
@@ -18,9 +18,11 @@ If you already have Node.js and npm installed, simply run: `npm install --save s
 
 See the `examples` folder for more examples:
 
+* `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.
-* `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.
+* `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
 

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
@@ -49,7 +39,7 @@ Logger.error = function(err, 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 can be anything, it doesn't have to be an object
     message: {
         temperature: "70F",
         chickenCount: 500
@@ -59,13 +49,39 @@ 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);

examples/custom_format.js

@@ -0,0 +1,113 @@
+/*
+ * 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 use a custom event format for SplunkLogger.
+ */
+
+// Change to require("splunk-logging").Logger;
+var SplunkLogger = require("../index").Logger;
+
+/**
+ * Only the token property is required.
+ */
+var config = {
+    token: "your-token-here",
+    url: "https://localhost:8088"
+};
+
+// Create a new logger
+var Logger = new SplunkLogger(config);
+
+Logger.error = function(err, context) {
+    // Handle errors here
+    console.log("error", err, "context", context);
+};
+
+/**
+ * Override the default eventFormatter() function,
+ * which takes a message and severity, returning
+ * any type - string or object are recommended.
+ *
+ * The message parameter can be any type. It will
+ * be whatever was passed to Logger.send().
+ * Severity will always be a string.
+ *
+ * In this example, we're building up a string
+ * of key=value pairs if message is an object,
+ * otherwise the message value is as value for
+ * the message key.
+ * This string is prefixed with the event
+ * severity in square brackets.
+ */
+Logger.eventFormatter = function(message, severity) {
+    var event = "[" + severity + "]";
+
+    if (typeof message === "object") {
+        for (var key in message) {
+            event += key + "=" + message[key] + " ";
+        }
+    }
+    else {
+        event += "message=" + message;
+    }
+
+    return event;
+};
+
+// Define the payload to send to Splunk's Event Collector
+var payload = {
+    // Message can be anything, it 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("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": "[info]temperature=70F chickenCount=500 "
+ *     }
+ *
+ */
+Logger.send(payload, function(err, resp, body) {
+    // If successful, body will be { text: 'Success', code: 0 }
+    console.log("Response from Splunk", body);
+});

examples/batching.js → examples/manual_batching.js

@@ -18,11 +18,7 @@
  * This example shows how to batch events with the
  * SplunkLogger by manually calling flush.
  *
- * By default autoFlush is enabled, this means
- * an HTTP request is made each time send() 
- * is called.
- *
- * By disabling autoFlush, events will be queued
+ * By setting maxbatchCount=0, events will be queued
  * until flush() is called.
  */
 
@@ -32,16 +28,12 @@ var SplunkLogger = require("../index").Logger;
 /**
  * Only the token property is required.
  * 
- * Here, autoFlush is set to false
+ * Here, maxBatchCount is set to 0.
  */
 var config = {
     token: "your-token-here",
-    host: "localhost",
-    path: "/services/collector/event/1.0",
-    protocol: "https",
-    port: 8088,
-    level: "info",
-    autoFlush: false
+    url: "https://localhost:8088",
+    maxBatchCount: 0 // Manually flush events
 };
 
 // Create a new logger
@@ -64,7 +56,7 @@ var payload = {
         source: "chicken coop",
         sourcetype: "httpevent",
         index: "main",
-        host: "farm.local",
+        host: "farm.local"
     },
     // Severity is also optional
     severity: "info"
@@ -88,7 +80,7 @@ console.log("Queuing second payload", payload2);
 Logger.send(payload2);
 
 /**
- * Since autoFlush is disabled, call flush manually.
+ * Call flush manually.
  * This will send both payloads in a single
  * HTTP request.
  *