Back to the JS Eina page

The Eina framework provides a comprehensive system to manage logging events in your application. For example, it can group message in domains, assign different levels to the messages. There's also the possibility of intercepting the log messages, allowing further processing.

The main workhorse is efl.log_print. It will call the function defined in efl.log_print_cb_set, defaulting to a function that will print to the stderr. You can pass many options to log_print to control the output.

The log levels are ranked according to their usual severity. For example, critical errors can be configured to abort the application while debug messages are usually required only in development or when triaging bugs. In descending order of severity:

• efl.LOG_LEVEL_CRITICAL
• efl.LOG_LEVEL_ERR
• efl.LOG_LEVEL_WARN
• efl.LOG_LEVEL_INFO
• efl.LOG_LEVEL_DBG

The levels are also ordered numerically, with the most severe (CRITICAL) being the smallest value and the least severe (DBG) the largest value.

The states are used in efl.logTiming to indicate transitions in phases for a given domain.

• efl.LOG_STATE_START
• efl.LOG_STATE_STOP

Log domains are used to group messages, like messages from different modules, different features, etc. You can filter domains by means of log levels through efl.log_domain_level_set. They are represented by a name that you pass to efl.registerLogDomain and an id (integer) that it returns.

By default, Eina offers a global domain to be used by the application.

• efl.LOG_DOMAIN_GLOBAL

The logging system uses the terminal colors format to specify a color for a given domain. With the default callback, only the domain name is shown with the given color. Currently, the following string constants are exported as shortcuts:

• efl.COLOR_LIGHTRED
• efl.COLOR_RED
• efl.COLOR_LIGHTBLUE
• efl.COLOR_BLUE
• efl.COLOR_GREEN
• efl.COLOR_YELLOW
• efl.COLOR_ORANGE
• efl.COLOR_WHITE
• efl.COLOR_LIGHTCYAN
• efl.COLOR_CYAN
• efl.COLOR_RESET
• efl.COLOR_HIGH

A number of environment variables affect the behavior of the log module. These are:

• EINA_LOG_ABORT - If true, messages with severity of at least the level returned from efl.getLogAbortOnCriticalLevel or in the environment variable EINA_LOG_ABORT_LEVEL will trigger program termination. Can be overriden through efl.setLogAbortOnCritical.
• EINA_LOG_ABORT_LEVEL - The least severe level that can trigger program termination. Can be overriden through efl.setLogAbortOnCriticalLevel.
• EINA_LOG_COLOR_DISABLE - If true, color printing is disabled. See efl.setLogColorDisable.
• EINA_LOG_FILE_DISABLE - If true, filename in the messages is disabled. See efl.setLogFileDisable.
• EINA_LOG_FUNCTION_DISABLE - If true, function name in the messages is disabled. See efl.setLogFunctionDisable.
• EINA_LOG_LEVEL - The least severe level that will trigger log events to be shown. Can be overriden in efl.setLogLevel.
• EINA_LOG_LEVELS - Works like EINA_LOG_LEVEL, but on a per-domain basis. It take values as <domain>:<level>. Can be overriden for each domain in efl.setLogDomainLevel and efl.setLogDomainRegisteredLevel.

Syntax

var willBeLogged = efl.checkLogLevel(level);

Parameters

• level - An integer representing the target log level. Usually one of the efl.LOG_LEVEL_* constants.

Return value

• boolean - True if the level is triggering log level.

Checks whether the given log level will be logged or ignored.

Syntax

var willAbortOnCritical = efl.getLogAbortOnCritical();

Return value

• boolean - True if will abort upon triggering a critical level.

Returns true if events with level equal or smaller to efl.getLogAbortOnCriticalLevel() should abort the program.

Syntax

var abortLevel = efl.getLogAbortOnCriticalLevel();

Return type

• integer - The least severe level that will trigger termination. Usually one of the efl.LOG_LEVEL_* constants.

Returns the least severe (largest numerically) level that will trigger the program termination upon happening. Events most severe than the value returned also trigger termination.

Syntax

var colorDisabled = efl.getLogColorDisable();

Return type

• boolean - True if color logging is disabled.

Determines whether colors are disabled in the log messages.

Syntax

var level = efl.getLogDomainLevel(domainname);

Parameters

• domainname - A string with the name of the target domain.

Return type

• integer - The level associated to the given domain.

Gets the domain level given its name. If the domain was not yet registered through efl.registerLogDomain but is pending after a previous efl.setLogDomainLevel call or the environment variable EINA_LOG_LEVELS, the respective value is returned. If nothing else was found, the default level from efl.getLogLevel is returned.

Syntax

var level = efl.getLogDomainRegisteredLevel(domain);

Parameters

• domain - A string with the name of the target domain.

Return type

• integer - The level associated to the given domain.

Gets the level for the given domain. Works much faster than efl.getLogDomainLevel but relies on the domain being previously registered with efl.registerLogDomain.

Syntax

var isFileDisabled = efl.getLogFileDisabled();

Return type

• boolean - True if the filename in the log is disabled.

Returns whether the originating file name is disabled from log messages.

Syntax

var isFunctionDisabled = efl.getLogFunctionDisabled();

Return type

• boolean - True if the function name is disabled in logging messages.

Returns whether the originating function name is disabled from log messages.

Syntax

var default_level = efl.getLogLevel();

Return type

• integer - The default level of the logging system. Usually one of the efl.LOG_LEVEL* constants.

Returns the default log level. Messages less severe than this level will be ignored by efl.logPrint.

Syntax

efl.logCritical(message);

Parameters

• message - The string to be logged.

Helper wrapper around efl.logPrint that prints a message with efl.LOG_LEVEL_CRITICAL to the global domain.

Syntax

efl.logDebug(message);

Parameters

• message - The string to be logged.

Helper wrapper around efl.logPrint that prints a message with efl.LOG_LEVEL_DBG to the global domain.

Syntax

efl.logError(message);

Parameters

• message - The string to be logged.

Helper wrapper around efl.logPrint that prints a message with efl.LOG_LEVEL_ERR to the global domain.

Syntax

efl.logInfo(message);

Parameters

• message - The string to be logged.

Helper wrapper around efl.logPrint that prints a message with efl.LOG_LEVEL_INFO to the global domain.

Syntax

efl.logPrint(domain, level, message)

Parameters

• domain - The id (integer) of the target domain.
• level - The severity level (integer) of the event. Usually one of the efl.LOG_LEVEL_* constants.
• message - The string to be logged.

Prints the string message related domain with severity level. If level is of a lower severity (higher numerical value) than the value from efl.getLogLevel, the call is ignored.

For the global domain, you can use the helper functions efl.logCritical, efl.logInfo and related.

Example usage:

efl.logPrint(efl.LOG_DOMAIN_GLOBAL, efl.LOG_LEVEL_WARN, "Warning. Exclamation point. Warning.");
efl.logPrint(mydomain, efl.LOG_LEVEL_INFO, "Information. We want information.");

Syntax

efl.logTiming(domainId, state, phase);

Parameters

• domainId - The id of the target domain
• state - State indicating if we are starting or stopping a phase.
• phase - The name of the phase.

Starts or stop the timing of a phase. If given efl.LOG_STATE_START, it assumes the previously started phase has stopped.

Syntax

efl.logWarning(message);

Parameters

• message - The string to be logged.

Helper wrapper around efl.logPrint what prints a message with efl.LOG_LEVEL_WARN to the global domain.

Syntax

var domainId = efl.registerLogDomain(domainname, color);

Parameters

• domainname - A string with the name of the new domain
• color - A string with a color description according to VT specs. Usually one of the efl.COLOR_* constants.

Registers a new domain with name name and color color. The returned id will be used to reference the domain on the other log functions. If a negative number is returned, a log event occurred.

Example usage

var myid = efl.registerLogDomain("mydomain", efl.COLOR_CYAN);

Syntax

efl.setLogAbortOnCritical(boolvar);

Parameters

• boolvar - Flag indicating if the program should terminate if a message of the configured level occurs.

Sets whether the program should terminate upon a logging event with a level at least of the same severity of efl.getLogAbortOnCriticalLevel.

Syntax

efl.setLogAbortOnCritical(level);

Parameters

• level - An integer with the target level. Usually one of the efl.LOG_LEVEL_* constants.

Sets the minimal message level the program should check if it should abort. Messages less severe than level are ignored for this check.

Syntax

efl.setLogColorDisable(boolvar);

Parameters

• boolvar - Flag indicating if the color should be disabled.

Sets whether the colored logging should be disabled or not.

Syntax

efl.setLogDomainLevel(name, level);

Parameters

• name - The name of the target domain.
• level - An integer with the target level. Usually one of the efl.LOG_LEVEL_* constants.

Sets the trigger level for a given domain with name name. It works like setting the environment variable EINA_LOG_LEVELS=<name>:<level>.

If the domain name was not registered before, it is marked as a pending set and is applied upon registration.

Syntax

efl.setLogDomainRegisteredLevel(name, level);

Parameters

• name - The name of a previously registered domain.
• level - An integer with the target level. Usually one of the efl.LOG_LEVEL_* constants.

Sets the trigger level for a given domain with name name. It's a much faster version of efl.setLogDomainLevel, requiring a previously registered domain.

Syntax

efl.setLogFileDisable(boolvar);

Parameters

• boolvar - Flag indicating if the filename should be disabled.

Sets whether the filename logging should be disabled or not.

Syntax

efl.setLogFunctionDisable(boolvar);

Parameters

• boolvar - Flag indicating if the function name should be disabled.

Sets whether the function name logging should be disabled or not.

Syntax

efl.setLogLevel(level);

Parameters

• level - An integer with the target level. Usually one of the efl.LOG_LEVEL_* constants.

Sets the default level for log events. Messages less severe (higher numerical value) than level will be ignored.

Syntax

function callback(name, color, level, file, func, line, message){...}
efl.setLogPrintCb(callback);

Parameters

• callback - A function receiving the following arguments, in order: The domain name (string), the color (string), the level (integer), the file name (string), the function (string), the line number (integer) and the log message (string).

Sets the callback that will be called whenever a log command would be executed, i.e., above or equal to the current log level, is called. It receives as arguments the domain, output color, level, filename, function and line number of the call, and finally the message. It allows further customization of the output.

Example usage

function mycallback(domain, color, level, file, func, line, message) {
    // Save log to file, print, etc.
}
 
efl.setLogPrintCb(callback);
efl.logWarning("Kaboom"); // Calls mycallback if efl.LOG_LEVEL_WARN is a triggering level.

Syntax

efl.unregisterDomain(domain);

Parameters

• domainid - The id of the domain to be deleted.

Forgets about a logging domain registered from efl.registerLogDomain.