Wiki page log-levels.md changed with summary [] by Gareth Halfacree

pages/develop/debug/log-levels.md.txt

@@ -6,9 +6,7 @@
 
 EFL uses a common method to log error messages, called ``Eina_Log``, which allows you to adjust the verbosity of the logs using environment variables.
 
-``Eina_Log`` introduces the concept of *logging domains*, or *loggers*. For those unfamiliar with this term, it offers a way to separate a set of log messages into a specific context (e.g. a module) and provides a way of controlling this set as a whole.
-
-The log level is used to control which messages should appear. It specifies the lowest level that should be displayed, i.e. a message with level 11 being logged on a domain with level set to 10 would be displayed while a message with level 9 wouldn't.
+The ``Eina_Log`` module provides logging facilities for libraries and applications. It provides colored logging, basic logging levels (error, warning, debug, info, critical) and *logging domains*, or *loggers*. For those unfamiliar with this term, it offers a way to separate a set of log messages into a specific context (e.g. a module) and provides a way of controlling this set as a whole.
 
 ## Available Log Levels ##
 
@@ -20,15 +18,26 @@ The log level is used to control which messages should appear. It specifies the
 |Info     |``EINA_LOG_INFO()``           |
 |Debug    |``EINA_LOG_DBG()``            |
 
+## Logging Domains ##
+
+Logging domains are a way to separate a set of log messages into a context (e.g. a module) and provide a way of controlling this set as a whole.
+
+Suppose you have three different modules in your application and you want to get logging only from one of them (i.e. to create some sort of filter). To achieve that all you need to do is create a logging domain for each module so that all logging inside a module can be considered as a whole.
+
+Logging domains are specified by a name, color applied to the name and the level. The first two (log name and log color) are set through code inside your application, module or library.
+
+The log level is used to control which messages should appear. It specifies the lowest level that should be displayed, i.e. a message with level 11 being logged on a domain with level set to 10 would be displayed while a message with level 9 wouldn't.
+
 ## Setting the Log Level ##
 
-To set the general log level use the ``EINA_LOG_LEVEL`` environment variable:
+Logging of domain and global messages can be controlled at runtime using the following environment variables.
 
-```bash
-EINA_LOG_LEVEL={N} ./{application}
-```
+> **NOTE:**
+> If you compiled Eina without debug mode, execution will yield only one log message: "argument is negative".
 
-Where ``{N}`` is the log level number and ``{application}`` the binary you are currently debugging.
+### Domain Logging ###
+
+Domain level logging is set during runtime, in contrast with the name and color, through the environment variable ``EINA_LOG_LEVELS``.
 
 You can also use finer-grained control via the ``EINA_LOG_LEVELS`` environment variable:
 
@@ -38,7 +47,23 @@ EINA_LOG_LEVELS=module1:5,module2:2,module3:0 ./{application}
 
 In this example the command would set the log level of ``module1`` to 5, ``module2`` to 2, and ``module3`` to 0.
 
-To tidy up the logging output use the following command to disable logging of internal ``eina`` code:
+### General Logging ###
+
+The global logger to which ``EINA_LOG_{ERR, DBG, INFO, CRIT, WARN}`` macros log is created internally by ``Eina_Log`` with an empty name and can be used for general logging, where logging domains do not apply.
+
+Since this global logger doesn't have a name, you can't set its level through the ``EINA_LOG_LEVELS`` variable. Instead, it is controlled via the ``EINA_LOG_LEVEL`` variable.
+
+To set the general log level use the ``EINA_LOG_LEVEL`` environment variable:
+
+```bash
+EINA_LOG_LEVEL={N} ./{application}
+```
+
+Where ``{N}`` is the log level number and ``{application}`` the binary you are currently debugging.
+
+The global ``EINA_LOG_LEVEL`` can also be set within your code using the ``eina_log_level_set()`` function.
+
+While developing your libraries or applications, you may notice that ``EINA_LOG_DOM_{ERR, DBG, INFO, CRIT, WARN}`` macros also print out messages from ``eina`` itself. To tidy up the logging output use the following command to disable logging of intenal ``eina`` code:
 
 ```bash
 EINA_LOG_LEVEL={N} EINA_LOG_LEVELS_GLOB=eina_*:0 ./{application}