structured-log - npm Package Compare versions

Comparing version 0.0.15 to 0.0.16

package.json

 {
   "name": "structured-log",
-  "version": "0.0.15",
+  "version": "0.0.16",
   "description": "(Development version). NodeJS structured logging framework based on Serilog.",
@@ -5,0 +5,0 @@ "main": "structured-log.js",

README.MD

@@ -26,6 +26,6 @@ #structured-log [![Build Status](https://travis-ci.org/structured-log/structured-log.svg)](https://travis-ci.org/structured-log/structured-log)
 	var structuredLog = require('structured-log');
-	var coloredConsoleSink = require('structured-log/colored-console-sink');
+	var consoleSink = require('structured-log/console-sink');
 
 	var log = structuredLog.configure()
-    	.writeTo(coloredConsoleSink())
+    	.writeTo(consoleSink())
 	    .create();
@@ -53,3 +53,3 @@
 		.writeTo(consoleSink)
-		.writeTo(httpSink({ url: '<some-url>' }))
+		.writeTo(httpSink({ url: 'http://somewhere.com' }))
 		.create();
@@ -73,23 +73,24 @@
 
-Debugging:
+Verbose (not output by default):
 
-	log.trace('My debug message!');
-	log.debug('My debug message!');
 	log.verbose('My debug message!');
  
-Information:
+Info:
 
 	log.info('Something happened in the application...');
 
-Information alternative:
+Info alternative:
 
 	log('Something happened in the application...');
 
-Warnings:
+Warning:
   
 	log.warn('Some not-fatal error happened...');
 
-Errors:
+Error:
 
 	log.error('Something bad happened...');
+
+Error can also accept an exception or error object:
+
 	log.error(exceptionOrErrorObject, 'Something bad happend...');
@@ -99,4 +100,6 @@
 
-All the logging functions accept a message template and a set of key/value properties that are used to render the template when constring the log message for display. The properties are maintained separately to the template and rendered message which is what makes this a structured logging system.
+All the logging functions accept a message template and a set of key/value properties. When the template is rendered for display the values of the properties can be included in the message. 
 
+The properties are maintained separately to the template and rendered message which is what makes this a structured logging system.
+
 Here are some examples that have been adapted for Javascript from the [Serilog C# examples](http://serilog.net/):
@@ -112,3 +115,3 @@
 
-Properties can also be specified by positional parameters, the same as how it works in Serilog C#: 
+Properties can also be specified by positional parameters, the same as in Serilog C#: 
 
@@ -129,10 +132,10 @@ log.info("Processed {@Position} in {Elapsed:000} ms.", position, elapsedMs);
 
-| Name | Description | Batched/Unbatched |
-| ---- | ----------- | ----------------- |
-| console-sink | Writes formatted log events to the *console* | Unbatched |
-| colored-console-sink | Same as above, but with colors | Unbatched |
-| json-console-sink | Writes structured json to the console for each log event | Unbatched |
-| stream-sink | Writes formatted log events to a Nodejs stream | Unbatched |
-| json-stream-sink | Writes structured json tot he console for each log event | Unbatched |
-| http-sink | Outputs structured json log events via HTTP post |  Batched |
+| Name | Description |
+| ---- | ----------- |
+| console-sink | Writes formatted log events to the *console* |
+| colored-console-sink | Same as above, but with colors |
+| json-console-sink | Writes structured json to the console for each log event |
+| stream-sink | Writes formatted log events to a Nodejs stream |
+| json-stream-sink | Writes structured json tot he console for each log event |
+| http-sink | Outputs structured json log events via HTTP post |
 
@@ -143,13 +146,13 @@ ### Client-side
 | ---- | ------------- |
-| console-sink | Writes formatted log events to the *console* | Unbatched |
-| json-console-sink | Writes structured json to the console for each log event | Unbatched |
-| http-sink | Outputs structured json log events via HTTP post | Batched |
+| console-sink | Writes formatted log events to the *console* |
+| json-console-sink | Writes structured json to the console for each log event |
+| http-sink | Outputs structured json log events via HTTP post |
 
 ## Batching
 
-Some of the sinks are batched. Batched sinks process multiple log events at once usually for increased performance or to reduce timing issues (eg HTTP logs being received out of order). 
+All sinks can be batched, although it only really makes sense for sinks that require batching for increased performance or to reduce timing issues (eg HTTP logs being received out of order). 
 
-### Configuring Batched Sinks
+### Configuring Batching
 
-All batched sinks (even custom batched sinks) have the same standard configuration options.
+All sinks can have batching enabled by calling the *batch* function with an appropriate configuration:
 
@@ -172,3 +175,3 @@ var httpSink = require('structured-log-http-sink');
 
-Either of these options can be omitted and be set to default values.
+Either of these options can be omitted and will be set to default values.
 
@@ -229,15 +232,13 @@ ### Flushing Queued Logs
 
-It is very easy to make your own sink. You first have to decide if the sink should process log events individually or as a batch.
+It is very easy to make your own sink. There are plenty of built-in examples of sinks. So can you can always copy and modify an existing sink.
 
-There are plenty of built-in examples of sinks. So can you can always copy and modify an existing sink.
+### Custom sink
 
-### Non-batched custom sink
+All sinks are designed to run in either *batched* or *unbatched* modes. The *emit* function always accepts an array of *log events*. When running unbatched this array will contain only a single item. When running batched the array may contain more than 1 *log event* depending on how many have been queued. 
 
-Non-batched sinks process each log event individually:
-
 	var myCustomSink = function (options) {
 		return {
-			emit: function (logEvent) {
+			emit: function (logEvents) {
 				//
-				// ... your custom log event processing goes here ...
+				// ... process array of log events ...
 				//
@@ -256,11 +257,9 @@ }
 
-### As a Nodejs module
+**As a Nodejs module:**
 
-MyCustomSink.js:
-
 	module.exports = function (options) {
 		return {
-			emit: function (logEvent) {
+			emit: function (logEvents) {
 				//
-				// ... your custom log event processing goes here ...
+				// ... process array of log events ...
 				//
@@ -271,3 +270,3 @@ }
 
-SomewhereElse.js:
+**Somewhere else:**
 
@@ -285,16 +284,2 @@ var myCustomSink = require('./MyCustomSink');
 
-### Batched custom sink
-
-Batched sinks process a batch of log events at a time. *structured-log* buffers log events until the log queue is flushed. By simply replacing the *emit* function with *emitBatch* you can convert your sink to work in batched mode, accepting an *array* of log events instead of just a single  log event.
-
-	var myCustomSink = function (options) {
-		return {
-			emitBatch: function (logEvents) {
-				//
-				// ... process the array of log events ...
-				//
-			}
-		};
-	};
-
 ## Advanced Setup
@@ -313,3 +298,3 @@
 
-*minimumLevel* applies to subsequent sinks in the configuration, so you can use it to set a different level for each sink: 
+*minLevel* applies to subsequent sinks in the configuration, so you can use it to set a different level for each sink: 
 
@@ -316,0 +301,0 @@ var log = structuredLog.configuration()

No alert changes

Worsened metrics

Total package byte prevSize

55389

decreased by-0.97%

Number of lines in readme file

381

decreased by-3.79%

No dependency changes