[[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.