[[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)`
[horizontal]
`config`::
The object that was passed to the client constructor, use to determine the log level.

==== `error(error)`
[horizontal]
`error`::
`Error` -- The error that occurred

==== `warning(message)`
[horizontal]
`message`::
`String` -- The message to be logged

==== `info(message)`
[horizontal]
`message`::
`String` -- The message to be logged

==== `debug(message)`
[horizontal]
`message`::
`String` -- The message to be logged

==== `trace(httpMethod, requestUrl, requestBody, responseBody, responseStatus)`
Called after every HTTP request.

[horizontal]
`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

[horizontal]
`"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`:::
`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. Default is true.

`"file"`::
Append the log messages to a file.
+
Options:

`path`:::
`String` -- Location of the file to write log messages to. It is created if it does not exists. Default is `"elasticsearch.log"`

`"stream"`::
Send log messages to a <a href="http://nodejs.org/api/stream.html#stream_class_stream_writable">WriteableStream</a>
+
Options:

`stream`:::
`WriteableStream` -- object to write to.

`"console"`::
Default logger for the browser build, logs to the console when one exists.