Skip to main content

Logging

Creating a Logger​

The SAP Cloud SDK provides an easy way to create a logger:

import { createLogger } from '@sap-cloud-sdk/util';

const myLogger = createLogger('my-message-context');

The string argument in the createLogger() function is the identifier for the logger and you should use a separate message context for each logical part of your application. Since it is used to group messages or set the log level per context.

Use a Logger​

The logger provides the usual log methods:

myLogger.debug('Here is some debug.');
myLogger.info('Here is some info.');
myLogger.warn('Here is a warning.');
myLogger.error('Here is a error.');

The log level can be set using the environment variable SAP_CLOUD_SDK_LOG_LEVEL. You can then create a logger as below:

process.env.SAP_CLOUD_SDK_LOG_LEVEL = 'warn';

const myLogger = createLogger({
  messageContext: 'my-message-context'
});

In the example above, the first two lines will not appear in the logs.

You can set the log level either on creation:

const myLogger = createLogger({
  messageContext: 'my-message-context',
  level: 'error'
});

or later in you application via the setLogLevel() method:

setLogLevel('error', 'my-message-context');

In the example above, the first three lines would not appear in the logs.

If none of the above methods are specified, the default value for the log level is info.

Logging Exceptions​

In the example above a string was passed to the logging method:

myLogger.info('Here is some info.');

and in the logs, you would find a related entry:

TimeStamp [INFO] my-message-context The message you provided.

However, you can also pass an error object also known as an exception to the log statement. In this case, the log statement will contain only the message of the exception for all log functions except for error. If myLogger.error(err) is called with an error object it will also log the stack trace:

myLogger.error(new Error('Log this message and stack.')

Exception Logger​

The SAP Cloud SDK enables an exception logger once you create a logger instance somewhere in your project. The exception logger logs unhandled exceptions as if you would log the error manually. In other words, the exception logger does the following for you:

try {
  someMethodThrowing();
} catch (err) {
  logger.error(err);
  throw err;
}

You can disable this functionality with the disableExceptionLogger() method.

What Happens Under the Hood​

The SAP Cloud SDK logger instances are based on winston. A logger instance is created from a central container that knows all existing loggers. Via the container class, the SAP Cloud SDK provides methods per message context:

getLogger('my-message-context'); // get logger if present
setLogLevel('error', 'my-message-context'); // set log level
setLogFormat(logFormat.kibana, 'my-message-context'); // set log format

or global methods for all loggers:

setGlobalLogLevel('warn'); // set the global log level to warn
setGlobalLogFormat(logFormat.kibana); // set the global log format to kibana
setGlobalTransports(new winston.transports.File(options)); // set the global transport to file
muteLoggers(); // mute all loggers completely
unmuteLogger(); // unmute all loggers

The SAP Cloud SDK sets the log level during the creation of a logger based on the following order:

  1. log level set in the environment variable: process.env.SAP_CLOUD_SDK_LOG_LEVEL = 'silly';
  2. log level for a specific message context or logger: setLogLevel('info', messageContextOrLogger)
  3. level field in the createLogger() function: createLogger({..., level: "info"})
  4. global log level: setGlobalLogLevel('info')
  5. default log level: info
note

Please notice that the setGlobalLogLevel() function will not only affect the creation of the next logger, but also the log level of all existing loggers.

The SAP Cloud SDK sets the log format based on the following order of priority:

  1. log format for a specific message context or logger: setLogFormat(logFormat.local, messageContextOrLogger)
  2. format field in the createLogger() function: createLogger({..., format: logFormat.local})
  3. global log format: setGlobalLogFormat(logFormat.local)
  4. default log format: set NODE_ENV=production to get kibana, otherwise local
note

Please notice that the setGlobalLogFormat() method will not only affect the creation of the next logger, but also the log format of all existing loggers.

tip

nodejs_buildpack sets NODE_ENV=production by default. Therefore, Node.js applications deployed on Cloud Foundry using nodejs_buildpack has kibana as the default log format.

In case you see a need for higher flexibility of the logging instance feel free to create an issue in the SAP Cloud SDK repository or make a contribution.