Guide to Using Log Levels

Use the following log levels to aid in debugging development and production.

• info as first log in a prototype method. Intended to aid in tracing method call stacks for a given use request or action.
• trace Used for logging flow throughout a function body. Useful when logging in a narrow focus.
• error application level error that shouldn't normally ever happen. MongoDB response error for example.
• warn unexpected but non-application level error. Instance document not found in a query for ex.

Example of proper logging of a method.

/**
 * Atomic set to starting
 */
InstanceSchema.methods.setStateToStarting = function (cb) {
  //Share a common base object of log data, extend when necessary.
  var logData = {
    tx: true, // Include tx: true to make this log message 
              // a part of a request-trace batch of logs
    instanceId: this._id,
    instanceName: this.name,
    dockerContainer: this.container.dockerContainer
  };
  
  // Use info for an initial log message at the beginning of a method
  // ### EXAMPLE
  log.info(logData, 'InstanceSchema.methods.setStateToStarting');

  var self = this;
  var owner = this.owner;
  var createdBy = this.createdBy;

  Instance.findOneAndUpdate({
    '_id': this._id,
    'container.dockerContainer': this.container.dockerContainer,
    'container.inspect.State.Starting': {
      '$exists': false
    },
    'container.inspect.State.Stopping': {
      '$exists': false
    }
  }, {
    '$set': {
      'container.inspect.State.Starting': true
    }
  }, function (err, result) {
    if (err) {
      var logErrData = put({err: err}, logData);
      // Use error for application errors
      // ### EXAMPLE
      log.error(logErrData, 'setStateToStarting fineOneAndUpdate error');
      return cb(err);
    }
    else if (!result) {
      // Use warn for non-application errors
      // ### EXAMPLE
      log.warn(logData, 'setStateToStarting fineOneAndUpdate !result');
      // Fetch instance to determine if it exists, or is starting or stopping
      Instance.findOne({
        _id: self._id,
        'container.dockerContainer': self.container.dockerContainer
      }, function (err, result2) {
        if (err) {
          var logErrData = put({err: err}, logData);
          // ### EXAMPLE
          log.error(logErrData, ' fineOneAndUpdate !result findOne error');
          return cb(err);
        }
        else if (!result2) {
          return cb(Boom.badRequest('instance container has changed'));
        }
        // Use trace to assert logic flow reaches key points
        // ### EXAMPLE
        log.trace(logData, 'setStateToStarting fineOneAndUpdate !result findOne success');
        cb(null, result2);
      });
    }
    else {
      log.trace(logData, 'setStateToStarting fineOneAndUpdate success');
      // must preserve owner/createdBy if set via
      // populateOwnerAndCreatedBy
      result.owner = owner;
      result.createdBy = createdBy;
      return cb(null, result);
    }
  });
};