added docs to the repo

docs/logging.asciidoc

@@ -0,0 +1,141 @@
+[[logging]]
+== setup logging
+Every application needs to have some solution for logging, and there isn't a standard in JavaScript, so instead of forcing you to rely on a specific logging module we created a bare bones logging solution and <<logging-customization>> will show you how to configure it. That said, our implementation of logging is very minimal and ***it is highly recommended that you use something like https://github.com/trentm/node-bunyan[Bunyan] once you move to production***.
+
+=== Using A Library
+When the client receives a function for the `log:` config value, it expects that the function is a constructor for a custom log class. This is the simplest way to integrate other logging libraries into the elasticsearch client at this time. The contract for this Log class is pretty straight-forward. See https://github.com/elasticsearch/elasticsearch-js/blob/master/src/lib/log.js[our implementation] for additional details.
+
+==== `new Constructor(config)`
+  * `config` -- The object that was passed to the client constructor, use to determine the log level.
+
+==== `error(error)`
+  * error -- `Error` The error that occurred
+
+==== `warning(message)`
+  * message -- `String` The message to be logged
+
+==== `info(message)`
+  * message -- `String` The message to be logged
+
+==== `debug(message)`
+  * message -- `String` The message to be logged
+
+==== `trace(httpMethod, requestUrl, requestBody, responseBody, responseStatus)`
+
+Called after every HTTP request.
+
+  * httpMethod -- `String` The request's HTTP method
+  * requestUrl -- `Object, String` Depending on the connector in use, this will either be a url string or the        object passed to node's http.request.
+  * requestBody -- `String, false-y` The body of the http request, if the body is false-y no body was sent
+  * responseStatus -- `Integrer, false-y` The HTTP response status
+
+=== Bunyan Example
+In the future we may add loggers for some of the more common libraries, but for now this is an exercise for the user. Here is a hint to get you started implementing a https://github.com/trentm/node-bunyan[Bunyan] log class. Be sure to check out the Bunyan repo for more info about setting things up.
+
+.in log_to_bunyan.js
+[source,js]
+----------------
+module.exports = LogToBunyan;
+
+var bunyan = require('bunyan');
+
+function LogToBunyan(config) {
+  // config is the object passed to the client constructor.
+  var bun = bunyan.createLogger({name: 'mylogger'});
+  this.error = bun.error.bind(bun);
+  this.warning = bun.warn.bind(bun);
+  this.info = bun.info.bind(bun);
+  this.debug = bun.debug.bind(bun);
+  this.trace = function (method, requestUrl, body, responseBody, responseStatus) {
+    bun.trace({
+      method: method,
+      requestUrl: requestUrl,
+      body: body,
+      responseBody: responseBody,
+      responseStatus: responseStatus
+    });
+  };
+  this.close = function () { /* bunyan's loggers do not need to be closed */ };
+}
+----------------
+
+.in model.js
+[source,js]
+----------------
+var elasticsearch = require('elasticsearch');
+var LogClass = require('./log_to_bunyan');
+// now just pass the log class to the client constructor using the "log" config option.
+var client = new elasticsearch.Client({ log: LogClass });
+----------------
+
+[[logging-customization]]
+== Using the default loggers
+
+By default, the client creates a `"warning"` level, Console or Stdio logger. To change this, specify the client's `log:` config value to either an array of logger config's, a single logger config, a log level, an array of log levels, or a constructor for your own logger. That's a lot of options, so here is an example of each.
+
+.Change the logging level to trace, so we get every log message
+[source,js]
+----------------
+var client = new elasticsearch.Client({ log: 'trace' });
+----------------
+
+.Change the logging level, only listen for error and trace messages
+[source,js]
+----------------
+var client = new elasticsearch.Client({ log: ['error', 'trace'] });
+----------------
+
+.Log every message to a file
+[source,js]
+----------------
+var client = new elasticsearch.Client({
+  log: {
+    type: 'file',
+    level: 'trace',
+    path: '/var/log/elasticsearch.log'
+  }
+});
+----------------
+
+.Log everything to a file and errors to a socket
+[source,js]
+----------------
+var client = new elasticsearch.Client({
+  log: [
+    {
+      type: 'stream',
+      level: 'error',
+      // config option specific to stream type loggers
+      stream: mySocket
+    },
+    {
+      type: 'file',
+      level: 'trace',
+      // config options specific to file type loggers
+      path: '/var/log/elasticsearch.log'
+    }
+  ]
+});
+----------------
+
+=== Logger Types
+==== "stdio"
+The default logger for in Node, writes log messages for "info", "debug", and "trace" to stdout and "error" and "warning" to stderr.
+
+===== Options
+  * `[color=false]` -- `Boolean` Write with a bit of flair. The default value is intelligently chosen by https://github.com/sindresorhus/chalk[chalk] based on the details of your environment.
+
+==== "file"
+Append the log messages to a file.
+
+===== Options
+  * `[path="elasticsearch.log"]` -- `String` Location of the file. It is created if it does not exists
+
+==== "stream"
+Send log messages to a <a href="http://nodejs.org/api/stream.html#stream_class_stream_writable">WriteableStream</a>
+
+===== Options
+  * `stream` -- `WriteableStream` The object to write to.
+
+==== "console"
+Default logger for the browser build, logs to the console when one exists.