forked from enlightenment/www-content
Wiki page logging changed with summary [Move Javascript docs to legacy API] by Andrew Williams
This commit is contained in:
Andrew Williams
apache
parent
74facf36bc
commit
8d8cc462a1
|
|
@ -0,0 +1,511 @@
|
|||
===== Javascript binding API - Eina Logging =====
|
||||
|
||||
[[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 ''<domain>:<level>''. Can be overriden for each domain in ''efl.setLogDomainLevel'' and ''efl.setLogDomainRegisteredLevel''.
|
||||
|
||||
==== Functions ====
|
||||
|
||||
=== checkLogLevel(level) ===
|
||||
|
||||
Syntax
|
||||
|
||||
<code javascript>
|
||||
var willBeLogged = efl.checkLogLevel(level);
|
||||
</code>
|
||||
|
||||
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
|
||||
|
||||
<code javascript>
|
||||
var willAbortOnCritical = efl.getLogAbortOnCritical();
|
||||
</code>
|
||||
|
||||
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
|
||||
|
||||
<code javascript>
|
||||
var abortLevel = efl.getLogAbortOnCriticalLevel();
|
||||
</code>
|
||||
|
||||
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
|
||||
|
||||
<code javascript>
|
||||
var colorDisabled = efl.getLogColorDisable();
|
||||
</code>
|
||||
|
||||
Return type
|
||||
|
||||
* boolean - True if color logging is disabled.
|
||||
|
||||
Determines whether colors are disabled in the log messages.
|
||||
|
||||
=== getLogDomainLevel(domain) ===
|
||||
|
||||
Syntax
|
||||
|
||||
<code javascript>
|
||||
var level = efl.getLogDomainLevel(domainname);
|
||||
</code>
|
||||
|
||||
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
|
||||
|
||||
<code javascript>
|
||||
var level = efl.getLogDomainRegisteredLevel(domain);
|
||||
</code>
|
||||
|
||||
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
|
||||
|
||||
<code javascript>
|
||||
var isFileDisabled = efl.getLogFileDisabled();
|
||||
</code>
|
||||
|
||||
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
|
||||
|
||||
<code javascript>
|
||||
var isFunctionDisabled = efl.getLogFunctionDisabled();
|
||||
</code>
|
||||
|
||||
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
|
||||
|
||||
<code javascript>
|
||||
var default_level = efl.getLogLevel();
|
||||
</code>
|
||||
|
||||
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
|
||||
|
||||
<code javascript>
|
||||
efl.logCritical(message);
|
||||
</code>
|
||||
|
||||
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
|
||||
|
||||
<code javascript>
|
||||
efl.logDebug(message);
|
||||
</code>
|
||||
|
||||
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
|
||||
|
||||
<code javascript>
|
||||
efl.logError(message);
|
||||
</code>
|
||||
|
||||
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
|
||||
|
||||
<code javascript>
|
||||
efl.logInfo(message);
|
||||
</code>
|
||||
|
||||
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
|
||||
|
||||
<code javascript>
|
||||
efl.logPrint(domain, level, message)
|
||||
</code>
|
||||
|
||||
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:
|
||||
|
||||
<code javascript>
|
||||
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.");
|
||||
</code>
|
||||
|
||||
=== logTiming(domain, state, phase) ===
|
||||
|
||||
Syntax
|
||||
|
||||
<code javascript>
|
||||
efl.logTiming(domainId, state, phase);
|
||||
</code>
|
||||
|
||||
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
|
||||
|
||||
<code javascript>
|
||||
efl.logWarning(message);
|
||||
</code>
|
||||
|
||||
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
|
||||
|
||||
<code javascript>
|
||||
var domainId = efl.registerLogDomain(domainname, color);
|
||||
</code>
|
||||
|
||||
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
|
||||
|
||||
<code javascript>
|
||||
var myid = efl.registerLogDomain("mydomain", efl.COLOR_CYAN);
|
||||
</code>
|
||||
|
||||
=== setLogAbortOnCritical(boolvar) ===
|
||||
|
||||
Syntax
|
||||
|
||||
<code javascript>
|
||||
efl.setLogAbortOnCritical(boolvar);
|
||||
</code>
|
||||
|
||||
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''.
|
||||
|
||||
<note important>
|
||||
Upon initializaton, it takes the value from the environment variable ''EINA_LOG_ABORT''.
|
||||
</note>
|
||||
|
||||
=== setLogAbortOnCriticalLevel(level) ===
|
||||
|
||||
Syntax
|
||||
|
||||
<code javascript>
|
||||
efl.setLogAbortOnCritical(level);
|
||||
</code>
|
||||
|
||||
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.
|
||||
|
||||
<note important>
|
||||
Upon initializaton, it takes the value from the environment variable ''EINA_LOG_ABORT_LEVEL''.
|
||||
</note>
|
||||
|
||||
=== setLogColorDisable(bool) ===
|
||||
|
||||
Syntax
|
||||
|
||||
<code javascript>
|
||||
efl.setLogColorDisable(boolvar);
|
||||
</code>
|
||||
|
||||
Parameters
|
||||
|
||||
* boolvar - Flag indicating if the color should be disabled.
|
||||
|
||||
Sets whether the colored logging should be disabled or not.
|
||||
|
||||
=== setLogDomainLevel(domainname, level) ===
|
||||
|
||||
Syntax
|
||||
|
||||
<code javascript>
|
||||
efl.setLogDomainLevel(name, level);
|
||||
</code>
|
||||
|
||||
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.
|
||||
|
||||
=== setLogDomainRegisteredLevel(domainname, level) ===
|
||||
|
||||
Syntax
|
||||
|
||||
<code javascript>
|
||||
efl.setLogDomainRegisteredLevel(name, level);
|
||||
</code>
|
||||
|
||||
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
|
||||
|
||||
<code javascript>
|
||||
efl.setLogFileDisable(boolvar);
|
||||
</code>
|
||||
|
||||
Parameters
|
||||
|
||||
* boolvar - Flag indicating if the filename should be disabled.
|
||||
|
||||
Sets whether the filename logging should be disabled or not.
|
||||
|
||||
=== setLogFunctionDisable(enable) ===
|
||||
|
||||
Syntax
|
||||
|
||||
<code javascript>
|
||||
efl.setLogFunctionDisable(boolvar);
|
||||
</code>
|
||||
|
||||
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
|
||||
|
||||
<code javascript>
|
||||
efl.setLogLevel(level);
|
||||
</code>
|
||||
|
||||
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.
|
||||
|
||||
<note important>
|
||||
Upon initialization, the default level is set to the value from the environment variable ''EINA_LOG_LEVEL''.
|
||||
</note>
|
||||
|
||||
=== setLogPrintCb(callback) ===
|
||||
|
||||
Syntax
|
||||
|
||||
<code javascript>
|
||||
function callback(name, color, level, file, func, line, message){...}
|
||||
efl.setLogPrintCb(callback);
|
||||
</code>
|
||||
|
||||
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.
|
||||
|
||||
<note important>
|
||||
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''
|
||||
</note>
|
||||
|
||||
Example usage
|
||||
|
||||
<code javascript>
|
||||
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.
|
||||
</code>
|
||||
|
||||
=== unregisterLogDomain(domainId) ===
|
||||
|
||||
Syntax
|
||||
|
||||
<code javascript>
|
||||
efl.unregisterDomain(domain);
|
||||
</code>
|
||||
|
||||
Parameters
|
||||
|
||||
* domainid - The id of the domain to be deleted.
|
||||
|
||||
Forgets about a logging domain registered from ''efl.registerLogDomain''.
|
||||
Loading…
Reference in New Issue