FAB-10602 NodeSDK - tutorial on logging

How to use the NodeSDK logging. Includes a
small change in the error checking where the
fabric side has changed the message text when
the chaincode is already instantiated.

Change-Id: I7301219980c7726f8c21533091394e5f6a9e6dc2
Signed-off-by: Bret Harrison <beharrison@nc.rr.com>

docs/tutorials/logging.md

@@ -0,0 +1,79 @@
+This tutorial illustrates how to use the Hyperledger Fabric Node.js client logging feature.
+
+### Overview
+
+Hyperledger Fabric Node.js client logging uses the Node.js 'winston' package.
+The logging is initialized when the Node.js applicatiion first loads the Hyperledger
+Fabric package. All Hyperledger Fabric client objects will use the same settings (Peer, Orderer, ChannelEventHub).
+```
+const Client = require('fabric-client');
+// the logging is now set
+```
+There are four levels of logging
+- info
+- warn
+- error
+- debug
+
+By default `info`, `warn`, and `error` log entries will be sent to the 'console'.
+`debug` will not be recorded.
+
+### How to change logging
+
+The Hyperledger Fabric client's logging is controlled by the configuration setting
+`hfc-logging` and by the environment setting `HFC_LOGGING`.
+
+- setting the logging settings in the `default.json` config file with an entry:
+```
+"hfc-logging": "{'debug':'console', 'info':'console'}"
+```
+
+- using an environment setting will override the configuration setting:
+```
+export HFC_LOGGING='{"debug":"console","info":"console"}'
+```
+
+The logging may use a file to write entries by specifying a file location as the
+level value.
+```
+export HFC_LOGGING='{"debug":"/temp/debug.log","info":"console"}'
+```
+
+### Using the logging from application
+
+When there is a need to log entries from the application code along with the
+Hyperledger Fabric client entries, use the following to get access to the same
+logger.
+
+as of 1.2
+```
+const logger = Client.getLogger('APPLICATION');
+```
+
+prior to 1.2
+```
+const sdkUtils = = require('fabric-client/lib/utils.js');
+const logger = sdkUtils.getLogger('APPLICATION');
+```
+
+To log
+```
+const log_info = 'Sometext';
+
+logger.info('%s infotext', log_info);
+// will log
+// info: [APPLICATION]: Sometext infotext
+
+logger.warn('%s warntext', log_info);
+// will log
+// warn: [APPLICATION]: Sometext warntext
+
+logger.error('%s errortext', log_info);
+// will log
+// error: [APPLICATION]: Sometext errortext
+
+logger.debug('%s debugtext', log_info);
+// will log
+// debug: [APPLICATION]: Sometext debugtext
+
+```

docs/tutorials/tutorials.json

@@ -16,5 +16,8 @@
 	},
 	"metadata-chaincode" : {
 		"title": "How to add CouchDB indexes during chaincode installation"
+	},
+	"logging" : {
+		"title": "How to use logging"
 	}
 }

fabric-client/lib/BaseClient.js

@@ -181,6 +181,21 @@ var BaseClient = class {
 		BaseClient.setConfigSetting(name, value);
 	}
 
+
+	/**
+	 * Use this method to get a logger that will add entries to the same location
+	 * being used by the Hyperledger Fabric client.
+	 *
+	 * @param {string} name - The name of the label to be added to the log entries.
+	 *        To help identify the source of the log entry.
+	 * @returns {Logger} The logger that may be used to log entires with
+	 *         'info()', 'warn()', 'error()' and 'debug()' methods to mark the
+	 *         the type of the log entries.
+	 */
+	static getLogger(name) {
+		return sdkUtils.getLogger(name);
+	}
+
 	/**
 	 * Sets the client instance to use the CryptoSuite object for signing and hashing
 	 *

test/integration/instantiate.js

@@ -82,7 +82,7 @@ test('\n\n **** E R R O R  T E S T I N G : instantiate call fails by instantiati
 		txId: ''
 	};
 
-	var error_snip = 'chaincode exists ' + e2e.chaincodeId;
+	var error_snip = 'already exists';
 	instantiateChaincodeForError(request, error_snip, t);
 });
 

test/unit/util.js

@@ -263,13 +263,15 @@ module.exports.checkResults = function(results, error_snip, t) {
 	var proposalResponses = results[0];
 	for(var i in proposalResponses) {
 		let proposal_response = proposalResponses[i];
-		if(proposal_response.response
-			&& proposal_response.response.message
-			&& proposal_response.response.message.indexOf(error_snip) > -1) {
-			t.pass('Successfully got the error' + error_snip);
+		if(proposal_response.response && proposal_response.response.message) {
+			if(proposal_response.response.message.indexOf(error_snip) > -1) {
+				t.pass('Successfully got the error' + error_snip);
+			} else {
+				t.fail( 'Failed to get error with ' + error_snip + ' :: response message ' + proposal_response.response.message);
+			}
 		}
 		else {
-			t.fail(' Failed  :: should have had an error with '+ error_snip);
+			t.fail(' Failed  :: no response message found and should have had an error with '+ error_snip);
 		}
 	}
 };