This is a collection of support libraries for node.js applications running on Cloud Foundry that serve two main purposes: It provides (a) means to emit structured application log messages and (b) instrument parts of your application stack to collect request metrics.
For details on the concepts and log formats, please look at the sibling project for java logging support.
Version 2.0 introduced logging without Winston and changed custom fields to be parsed and reported as strings regardless of original type.
Version 3.0 introduced dynamic log level thresholds, sensitive data reduction and a redesigned field configuration system
- Network logging (http requests) for CloudFoundry
- Custom message logging
- Logging levels
- Dynamic logging level threshold (per request)
- Extendable field configuration
- Sensitive data reduction
- Can be bound to Winston as transport
npm install cf-nodejs-logging-support
var express = require('express');
var log = require('cf-nodejs-logging-support');
var app = express();
// Set the minimum logging level (Levels: error, warn, info, verbose, debug, silly)
log.setLoggingLevel("info");
// Bind to express app
app.use(log.logNetwork);
app.get('/', function (req, res) {
// Context bound custom message
req.logger.info("Hello World will be sent");
res.send('Hello World');
});
app.listen(3000);
// Formatted log message free of request context
log.info("Server is listening on port %d", 3000);
The logging library defaults to express middleware behaviour, but it can be forced to work with other server libraries as well:
var restify = require('restify');
var log = require('cf-nodejs-logging-support');
var app = restify.createServer();
//forces logger to run the restify version. (default is express, forcing express is also legal)
log.forceLogger("restify");
//insert the logger in the server network queue, so each time a https request is recieved, it is will get logged.
app.use(log.logNetwork);
//same usage as express logger, see minimal example above
var log = require("cf-nodejs-logging-support");
const http = require('http');
//forces logger to run the http version.
log.forceLogger("plainhttp");
const server = http.createServer((req, res) => {
//binds logging to the given request for request tracking
log.logNetwork(req, res);
// Context bound custom message
req.logger.info("request bound information:", {
"some": "info"
});
res.end('ok');
});
server.listen(3000);
// Formatted log message free of request context
log.info("Server is listening on port %d", 3000);
The library can be attached as middleware to log all incoming requests as follows:
app.use(log.logNetwork);
When using a plain Node.js http server it is necessary to call the middleware method directly:
http.createServer((req, res) => {
log.logNetwork(req, res);
...
});
In addition to request logging this library also supports logging custom messages. Following common node.js logging levels are supported:
- error
- warn
- info
- verbose
- debug
- silly
There are so called convenient methods for all supported logging levels, which can be called to log a message using the corresponding level. It is also possible to use standard format placeholders equivalent to the util.format method.
Simple message
info("Hello World");
// ... "msg":"Hello World" ...
With additional numeric value
info("Listening on port %d", 5000);
// ... "msg":"Listening on port 5000" ...
With additional string values
info("This %s a %s", "is", "test");
// ... "msg":"This is a test" ...
With custom fields added to custom_fields field. Keep in mind that the last argument is handled as custom_fields object, if it is an object.
info("Test data %j", {"field" :"value"});
// ... "msg":"Test data %j"
// ... "custom_fields": {"field": "value"} ...
With json object forced to be embedded in to the message (nothing will be added to custom_fields).
info("Test data %j", {"field" :"value"}, {});
// ... "msg":"Test data {\"field\": \"value\"}" ...
In some cases you might want to set the actual logging level from a variable. Instead of using conditional expressions you can simply use following method, which also supports format features described above.
var level = "debug";
logMessage(level, "Hello World");
// ... "msg":"Hello World" ...
In general there are two types of logging contexts: global and request contexts.
Each application has a global context, which has no correlation to specific requests. Use the globally defined log
object to log messages in global context:
var log = require("cf-nodejs-logging-support");
...
log.info("Server is listening on port %d", 3000);
The library adds context bound functions to request objects, if the library has been attached as middleware (see ). Use the locally defined req.logger
object to log messages in request context:
app.get('/', function (req, res) {
req.logger.info("This message is request correlated");
...
});
In addition to a message logged using the global context these messages will automatically include following request correlated fields:
- correlation_id
- request_id
- tenant_id
Version 3.0.0 and above implements a sensitive data redaction system, which deactivates the logging of sensitive fields. The field will contain 'redacted' instead of the original content.
Following fields will be redacted by default: remote_ip, remote_host, remote_port, x_forwarded_for, remote_user, referer.
In order to activate normal logging for all or some of these fields, you have to setup environment variables with the following names:
Environment Variable | Optional fields |
---|---|
LOG_SENSITIVE_CONNECTION_DATA: true |
activates the fields remote_ip, remote_host, remote_port, x_forwarded_for |
LOG_REMOTE_USER: true |
activates the field remote_user |
LOG_REFERER: true |
activates the field referer |
This behavior matches with the corresponding mechanism in the CF Java Logging Support library.
Sometimes it is useful to change the logging level threshold for a specific request. This can be achieved using a special header field or setting directly within the corresponding request handler. Changing the logging level threshold only affects the presence of logs but not their individual logging levels.
You can change the logging level threshold for a specific request by providing a JSON Web Token (JWT) via the request header. This way it is not necessary to redeploy your app for every logging level threshold change.
JWTs are signed claims, which consist of a header, a payload and a signature. You can create JWTs by using the TokenCreator from the tools folder.
Basically, JWTs are signed using RSA or HMAC signing algorithms. But we decided to support RSA algorithms (RS256, RS384 and RS512) only. In contrast to HMAC algorithms (HS256, HS384 and HS512), RSA algorithms are asymmetric and therefore require key pairs (public and private key).
The tool mentioned above takes a log level, creates a key pair and signs the resulting JWT with the private key. The payload of a JWT looks like this:
{
"issuer": "<valid e-mail address>",
"level": "debug",
"iat": 1506016127,
"exp": 1506188927
}
This library supports six logging levels: error, warn, info, verbose, debug and silly. Make sure that your JWT specifies one of them in order to work correctly. It is also important to make sure that the JWT has not been expired, when using it.
The logging library will try to verify JWTs attached to incoming requests. In order to do so, the public key (from above) needs to be provided via an environment variable called DYN_LOG_LEVEL_KEY:
DYN_LOG_LEVEL_KEY: <your public key>
Redeploy your app after setting up the environment variable.
Provide the created JWTs via a header field named 'SAP-LOG-LEVEL'. The logging level threshold will be set to the provided level for the request (and also corresponding custom log messages).
Note: If the provided JWT cannot be verified, is expired or contains an invalid logging level, the library ignores it and uses the global logging level threshold.
If you want to use another header name for the JWT, you can specify it using an enviroment variable:
DYN_LOG_HEADER: MY-HEADER-FIELD
You can also change the log level for all requests of a specific request handler by calling:
req.setDynamicLoggingLevel("verbose");
In order to get the correlation_id of a request, you can use the following method:
app.get('/', function (req, res) {
// Call to context bound function
var id = req.getCorrelationId();
res.send('Hello World');
});
It is also possible to change the correlation_id:
app.get('/', function (req, res) {
// Call to context bound function
req.setCorrelationId(YOUR_CUSTOM_CORRELATION_ID);
res.send('Hello World');
});
As stated above the req.logger
acts as context preserving object and provides context bound functions like info(...)
. In some cases you might want to create new context objects in order to create logs in context of other incoming data events (e.g. RabbitMQ). To do so you can use
var ctx = log.createCorrelationObject();
ctx.logMessage(...);
any time to create new context objects. Custom context objects are provided with a newly generated correlation_id.
If you want to provide your own correlation_id, you can use the ctx.setCorrelationId(<id>)
method.
Setup an output pattern to get a human-readable output instead of json. Use '{{' and '}}' to print log parameters.
log.setLogPattern("{{written_at}} - {{msg}}");
Possibility to tailor logs to your needs, you can for example change the msg field for Network-logs to find them in the Human readable format:
log.overrideNetworkField("msg", YOUR_CUSTOM_MSG);
This will replace the value of the previously not existing msg field for network logs with YOUR_CUSTOM_MSG. If the overridden field is already existing, it will be overridden by YOUR_CUSTOM_MSG for ALL subsequent network logs, until you remove the override with:
log.overrideNetworkField("msg", null);
If you use this override feature in conjunction with a log parser, make sure you will not violate any parsing rules.
This logging library can be used in conjunction with Winston. Logging via Winston transport is limited to custom logs. Network activity can not be tracked automatically. Example:
var express = require('express');
var log = require('cf-nodejs-logging-support');
var winston = require('winston');
var app = express();
var logger = winston.createLogger({
// Bind transport to winston
transports: [log.createWinstonTransport()]
});
app.get('/', function (req, res) {
res.send('Hello World');
});
app.listen(3000);
// Messages will now be logged exactly as demonstrated by the Custom Messages paragraph
logger.log("info", "Server is listening on port %d", 3000);