[[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"`

`"tracer"`::
Logs in a format that can be executed with bash, where everything is commented except the trace commands which are formatted as curl calls. By default all of the urls are rewritten to protect production systems and to making the scripts easier to reuse/send to other people. In order to control the urls written specify the curlHost and curlPort configs.
+
Options:

`curlHost`:::
`Sting` --  Default is `"localhost"`.
`curlPort`:::
`Sting` --  Default is `9200`.

`"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.