Node.JS
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
orObject
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