===== Javascript binding API - Eina Logging ===== [[:develop:legacy:api:javascript:eina|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. ==== Constants ==== === Levels === 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. === State === The states are used in ''efl.logTiming'' to indicate transitions in phases for a given domain. * ''efl.LOG_STATE_START'' * ''efl.LOG_STATE_STOP'' === Domain === 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'' === Colors === The logging system uses the [[http://misc.flogisoft.com/bash/tip_colors_and_formatting|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'' ==== Environment Variables ==== 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 '':''. Can be overriden for each domain in ''efl.setLogDomainLevel'' and ''efl.setLogDomainRegisteredLevel''. ==== Functions ==== === checkLogLevel(level) === 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. === getLogAbortOnCritical() === 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. === getLogAbortOnCriticalLevel() === 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. === getLogColorDisable() === Syntax var colorDisabled = efl.getLogColorDisable(); Return type * boolean - True if color logging is disabled. Determines whether colors are disabled in the log messages. === getLogDomainLevel(domain) === 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. === getLogDomainRegisteredLevel(name) === 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''. === getLogFileDisable() === 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. === getLogFunctionDisable() === 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. === getLogLevel() === 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''. === logCritical(message) === 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. === logDebug(message) === 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. === logError(message) === 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. === logInfo(message) === 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. === logPrint(domain, level, message) === 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."); === logTiming(domain, state, phase) === 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. === logWarning(message) === 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. === registerLogDomain(name, color) === 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 [[http://misc.flogisoft.com/bash/tip_colors_and_formatting|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); === setLogAbortOnCritical(boolvar) === 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''. Upon initializaton, it takes the value from the environment variable ''EINA_LOG_ABORT''. === setLogAbortOnCriticalLevel(level) === 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. Upon initializaton, it takes the value from the environment variable ''EINA_LOG_ABORT_LEVEL''. === setLogColorDisable(bool) === Syntax efl.setLogColorDisable(boolvar); Parameters * boolvar - Flag indicating if the color should be disabled. Sets whether the colored logging should be disabled or not. === setLogDomainLevel(domainname, level) === 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=:''. If the domain name was not registered before, it is marked as a pending set and is applied upon registration. === setLogDomainRegisteredLevel(domainname, level) === 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. === setLogFileDisable(bool) === Syntax efl.setLogFileDisable(boolvar); Parameters * boolvar - Flag indicating if the filename should be disabled. Sets whether the filename logging should be disabled or not. === setLogFunctionDisable(enable) === 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. === setLogLevel(level) === 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. Upon initialization, the default level is set to the value from the environment variable ''EINA_LOG_LEVEL''. === setLogPrintCb(callback) === 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. If not set, EFL defaults the output to the standard error output, like this: ''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. === unregisterLogDomain(domainId) === Syntax efl.unregisterDomain(domain); Parameters * domainid - The id of the domain to be deleted. Forgets about a logging domain registered from ''efl.registerLogDomain''.