« Mezmo Web SiteAPI ReferenceRelease NotesGuidesStart Free Trial
Sign into Mezmo Web App

Node.JS

Suggest Edits

The Node.js library lets you send logs from your Node.js and JavaScript applications to Mezmo. It also supports client-side logging. Mezmo automatically parses Node.js logs with minimal setup and configuration.

There are two ways to send logs from Node.js to Mezmo: by using the Mezmo Node.js library and adding on the Mezmo Winston transport or Mezmo’s Bunyan transport.

The Node.js library is open source. Check out our GitHub repository
.

Requirements

Installing the library requires NPM.

Installation

To install the library, use NPM to install the mezmo package. You can either run the following command in your project's working directory:

$ npm install @mezmo/logger

Or add the library to your package.json file:

"mezmo": "latest"

Bunyan Installation

Mezmo provides a stream for Bunyan called mezmo-bunyan. Use NPM to install the mezmo-bunyan package. For example:

$ npm install --save mezmo-bunyan

Winston Installation

Mezmo provides a transport for Winston called mezmo-winston. Use NPM to install the mezmo-winston package. For example:

$ npm install --save mezmo-winston

Configuration

To add the library to your application, load the Mezmo module and use the createLogger() method to initialize a new logger object. createLogger() takes two arguments: your Mezmo ingestion key, and an optional JSON array of configuration settings:

var Logger = require('mezmo');
var options = {
    hostname: myHostname,
    ip: ipAddress,
    mac: macAddress,
    app: appName,
    env: envName,
    tags = ['logging', 'nodejs', 'mezmo'], // Tags can also be provided in comma-separated string format: 'logging,nodejs,mezmo'    
};

var logger = Logger.createLogger(apikey, options);

apiKey

  • Required
  • Type: String

The Mezmo Ingestion Key associated with your account.

options

  • Optional
  • Type: JSON
  • Default: null

An array of optional arguments used to configure the logger.

app

  • Type: String
  • Default: ''
  • Example: YourCustomApp
  • Max Length: 32

The name of the application.

hostname

  • Type: String
  • Default: ''
  • Example: YourCustomHostname
  • Max Length: 32

The name of the host.

env

  • Type: String
  • Default: ''
  • Examples: Development, Staging, Production
  • Max Length: 32

The environment that the application is running in.

failedBufRetentionLimit

  • Type: Integer
  • Default: 10000000

The size (in bytes) of the buffer used to store logs when the logger can't connect to the server. If this buffer is full, any new logs will be lost.

index_meta

  • Type: Boolean
  • Default: false

Mezmo lets you send custom objects with each log message. This data appears in Mezmo in the meta field. If this option is set to true, then meta objects will be parsed, indexed, and made searchable up to three levels deep. Any fields deeper than three levels will be stored as a single string, won't be indexed, and won't be searchable.

If this options is set to false, then the entire object will be stringified and made unsearchable.

WARNING: When this option is enabled, your metadata must have a consistent typing across all of your logs. Otherwise, it may not be parsed properly!

ip

  • Type: String
  • Default: ''
  • Example: 10.0.0.1

The IP address of the host.

level

  • Type: String
  • Default: Info
  • Examples: Debug, Trace, Info, Warn, Error, Fatal, YourCustomLevel
  • Max Length: 32

The default level of each log message.

mezmo_url

  • Type: String
  • Default: ''
  • Example: https://logs.mezmo.com/logs/ingest

The URL to send logs to. Defaults to Mezmo’s cloud ingestion servers.

mac

  • Type: String
  • Default ''
  • Example: C0:FF:EE:C0:FF:EE

The network MAC address of the host.

max_length

  • Type: Boolean
  • Default: true

If true, each log message will have a maximum length of 32,000 characters. Setting this to false disables this limit.

meta

  • Type: JSON
  • Default: null

A JSON object that provides additional context about the log event. You can control how Mezmo parses metadata using index_meta.

retryTimeout

  • Type: Number
  • Default: 3000

The amount of time (in milliseconds) to wait before attempting to reconnect to Mezmo.

timeout

  • Type: Integer
  • Default: 180000
  • Max Value: 300000

The amount of time (in milliseconds) to wait for a response from the server when sending logs.

with_credentials

  • Type: Boolean
  • Default: false

Whether to send credentials with each request to Mezmo. In order to make CORS requests, this must remain set to false.

Bunyan Configuration

To configure the library for Bunyan, include the mezmo-bunyan module, create a new MezmoStream, and add it to your bunyan instance. Replace apiKey with your Mezmo ingestion key.

let MezmoStream = require('mezmo-bunyan').BunyanStream;

let logDNA = new MezmoStream({
  key: apikey
});

var logger = bunyan.createLogger({
  name: "My Application",
  streams: [
    { stream: process.stdout },
    { stream: logDNA,
      type: 'raw'
    }
  ]
});

createLogger() accepts the following arguments:

name

  • Optional
  • Type: String
  • Example: My Application

The name of your application.

Winston Configuration

To configure the library for Winston, include the mezmo-winston module and add it to your Winston Logger:

const mezmoWinston = require('mezmo-winston');
const winston = require('winston');
const logger = winston.createLogger({});
const options = {
    key: apikey,
    hostname: myHostname,
    ip: ipAddress,
    mac: macAddress,
    app: appName,
    env: envName,
    level: debug, // Uses Winston log levels: https://github.com/winstonjs/winston#logging-levels
    handleExceptions: true
};

logger.add(new mezmoWinston(options));

The options object supports all of the arguments listed above. mezmo-winston also supports the following arguments:

options.handleExceptions

  • Optional
  • Type: Boolean
  • Default: false

Allows the logger to catch and log exceptions.

Usage

log(line, [options])

This method generates a new log message and sends it to Mezmo.

line

  • Required
  • Type: String
  • Default: ''
  • Max Length: 3200

The text that will appear in the log message.

options

  • Optional
  • Type: JSON
  • Default: null

An array of optional arguments used to configure the log message. This uses the same arguments as the options object in the Configuration section.

Please note that if you assign variables to any of these arguments, their values may change in the time between generating the log and sending the log to Mezmo. We highly recommend copying the variable's value instead of referencing the variable directly.

addMetaProperty(key, value)

Adds a new field to the meta object. Fields are stored as key/value pairs and can contain strings, numbers, arrays, or objects. The name of the field is provided by the key argument, and its value is provided by the value argument. You can use removeMetaProperty(key) to remove an existing key/value pair.

key

  • Required
  • Type: String
  • Default: ''

The name of the key/value pair stored in the logger's metadata. If key already exists, this replaces the existing value.

value

  • Required
  • Type String or Object

The value to store under key.

cleanUpAll()

Flushes all existing loggers that have been instantiated using createLogger(), then removes all references to them. Only call this function when you are finished logging.

flushAll()

Flushes all existing loggers that have been instantiated using createLogger().

removeMetaProperty(key)

Removes the key/value pair stored in key from the logger's metadata. See addMetaProperty() for more information.

FAQ

Enabling Client-side Logging

Starting with version 3.0.1, you can bundle the Node.js library into your web applications using Browserify. The library also supports Webpack. Refer to our docs on client side logging for more info.

Adding Custom Metadata

This library lets you add custom metadata that will automatically append to each new log message (also known as fish tagging). The metadata is stored in easily manageable key/value pairs. New messages will include this metadata until you either remove the key, or remove the logger.

To add metadata, use the addMetaProperty(key, value) method, where key is a unique string of your choice and value is the object that you want to store in that string. If the key already exists, this method will overwrite its value. To remove a metadata object, use the removeMetaProperty(key) method.

For example, here we log the name of the current user under the key 'user':

logger.addMetaProperty('user', 'myUserName');

// This log adds a 'meta.user' field with the value 'myUserName':
logger.info('User logged in.');

logger.removeMetaProperty('user');

// This log event does not include the 'meta.user' field:
logger.info('User logged out.');

Logging from AWS Lambda

You can send logs from your AWS Lambda Functions to Mezmo by using one of the above methods, or by overriding the console.log() and console.error() functions. According to the Lambda documentation, Lambda overrides the above functions as well as console.warn() and console.info() within the scope of the handler (main) function. You can leverage this to forward logs to Mezmo as shown here:

'use strict';

const https = require('https');
const Logger = require('mezmo');

const options = {
    env: 'env'
    , app: 'lambda-app'
    , hostname: 'lambda-test'
    , index_meta: true
};

var _log = console.log;
var _error = console.error;

var logger = Logger.setupDefaultLogger('YOUR API KEY', options);

var log = function() {
    logger.log([...arguments].join(' '));
    _log.apply(console, arguments);
};

var error = function() {
    logger.error([...arguments].join(' '));
    _error.apply(console, arguments);
};

/**
 * Pass the data to send as `event.data`, and the request options as
 * `event.options`. For more information see the HTTPS module documentation
 * at https://nodejs.org/api/https.html.
 *
 * Will succeed with the response body.
 */
exports.handler = (event, context, callback) => {
    console.log = log;
    console.error = error;

    // Your code here
    console.log('How bout normal log');
    console.error('Try an error');

    callback();
};

Configuring the Log Buffer

If the logger does not receive a successful response from Mezmo, it retains the logs in a buffer and will retry with the next request. You can configure the size of this buffer, as well as the amount of time to wait between retries, using the failedBufRetentionLimit and retryTimeout options.

var options = {
    failedBufRetentionLimit: 10000000 // Sets the buffer to 10 MB
    retryTimeout: 3000 // Retry every 3 seconds
};

Troubleshooting

This library takes advantage of util.debuglog() to output details about message handling such as:

  • When the logger receives a message (useful for indirect usages such as Bunyan, Winston, or custom wrappers)
  • An indication of when messages are actually sent to the API (they may be buffered for a time)
  • An indication of whether the API responds with a success or failure

For cases where you do not see your log messages appear in Mezmo, these debug messages can make it easier to tell if the problem is on the sending or receiving end. They can also provide valuable information which can speed up diagnosis if you need to work with the Mezmo support staff.

You can enable debug messages with the NODE_DEBUG=mezmo environment variable. See the util.debuglog() documentation for more information.

Updated 9 months ago