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
efl.LOG_LEVEL_*
constants.Return value
Checks whether the given log level will be logged or ignored.
Syntax
var willAbortOnCritical = efl.getLogAbortOnCritical();
Return value
Returns true
if events with level equal or smaller to efl.getLogAbortOnCriticalLevel()
should abort the program.
Syntax
var abortLevel = efl.getLogAbortOnCriticalLevel();
Return type
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
Determines whether colors are disabled in the log messages.
Syntax
var level = efl.getLogDomainLevel(domainname);
Parameters
Return type
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
Return type
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
Returns whether the originating file name is disabled from log messages.
Syntax
var isFunctionDisabled = efl.getLogFunctionDisabled();
Return type
Returns whether the originating function name is disabled from log messages.
Syntax
var default_level = efl.getLogLevel();
Return type
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
Helper wrapper around efl.logPrint
that prints a message with efl.LOG_LEVEL_CRITICAL
to the global domain.
Syntax
efl.logDebug(message);
Parameters
Helper wrapper around efl.logPrint
that prints a message with efl.LOG_LEVEL_DBG
to the global domain.
Syntax
efl.logError(message);
Parameters
Helper wrapper around efl.logPrint
that prints a message with efl.LOG_LEVEL_ERR
to the global domain.
Syntax
efl.logInfo(message);
Parameters
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
efl.LOG_LEVEL_*
constants.
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
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
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
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
Sets whether the program should terminate upon a logging event with a level at least of the same severity of efl.getLogAbortOnCriticalLevel
.
EINA_LOG_ABORT
.
Syntax
efl.setLogAbortOnCritical(level);
Parameters
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.
EINA_LOG_ABORT_LEVEL
.
Syntax
efl.setLogColorDisable(boolvar);
Parameters
Sets whether the colored logging should be disabled or not.
Syntax
efl.setLogDomainLevel(name, level);
Parameters
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
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
Sets whether the filename logging should be disabled or not.
Syntax
efl.setLogFunctionDisable(boolvar);
Parameters
Sets whether the function name logging should be disabled or not.
Syntax
efl.setLogLevel(level);
Parameters
efl.LOG_LEVEL_*
constants.
Sets the default level for log events. Messages less severe (higher numerical value) than level
will be ignored.
EINA_LOG_LEVEL
.
Syntax
function callback(name, color, level, file, func, line, message){...} efl.setLogPrintCb(callback);
Parameters
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.
CRI<30206>: /home/user/dev/myapp/main.js:254 () MessageFrom logPrint
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
Forgets about a logging domain registered from efl.registerLogDomain
.