WWW-www.enlightenment.org pushed a commit to branch master. http://git.enlightenment.org/website/www-content.git/commit/?id=81ecab3a0af17f156994e6a92556a55d509a5d49
commit 81ecab3a0af17f156994e6a92556a55d509a5d49 Author: Gareth Halfacree <[email protected]> Date: Mon Dec 11 08:19:38 2017 -0800 Wiki page logging.md changed with summary [] by Gareth Halfacree --- pages/develop/guides/c/eina/logging.md.txt | 165 ++++++++++++++++++----------- 1 file changed, 106 insertions(+), 59 deletions(-) diff --git a/pages/develop/guides/c/eina/logging.md.txt b/pages/develop/guides/c/eina/logging.md.txt index 620983055..e58fbfb08 100644 --- a/pages/develop/guides/c/eina/logging.md.txt +++ b/pages/develop/guides/c/eina/logging.md.txt @@ -1,8 +1,8 @@ --- -~~Title: Error Logging~~ +~~Title: Eina Logging~~ --- -# Error Logging # +# Eina Logging # 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. @@ -18,70 +18,117 @@ The ``Eina_Log`` module provides logging facilities for libraries and applicatio |Info | 3 | ``EINA_LOG_INFO()`` | |Debug | 4 | ``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 2 being logged on a domain with level set to 3 would be displayed while a message with level 4 wouldn't. ## Setting the Log Level ## -Logging of domain and global messages can be controlled at runtime using the following environment variables. - -### Domain Logging ### - -Domain level logging is set during runtime, in contrast with the name and color, through the environment variable ``EINA_LOG_LEVELS``. - -```bash -EINA_LOG_LEVELS=module1:4,module2:2,module3:0 ./{application} -``` - -In this example the command would set the log level of ``module1`` to 4, ``module2`` to 2, and ``module3`` to 0. - -### 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. - -> **NOTE:** -> The global ``EINA_LOG_LEVEL`` can also be set within your code using the ``eina_log_level_set()`` function. - -#### Disabling Internal Eina Logging #### - -While developing your libraries or applications, you may notice that the ``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 the logging of intenal ``Eina`` code: - -```bash -EINA_LOG_LEVEL={N} EINA_LOG_LEVELS_GLOB=eina_*:0 ./{application} -``` - -Where ``{N}`` is the log level number and ``{application}`` the binary you are currently debugging. Removing these internal logs from the output makes it easier for you to see your own domain messages. - -### Aborting on Selected Log Level ## - -As well as controlling the logs themselves, the respective log levels can be used to close a program - calling ``abort()`` - once a message of a given level is logged, allowing you to automatically terminate execution. This is toggled through the environment variable ``EINA_LOG_ABORT``, while the level to be considered critical - and thus terminate execution - through the environment variable ``EINA_LOG_ABORT_LEVEL``. - -> **NOTE:** -> Aborting at a particular log level can also be controlled from within the application itself using the ``eina_log_abort_on_critical_set()`` and ``eina_log_abort_on_critical_level_set()`` functions. +``Eina`` provides ``eina_log_print()``, a standard function to manage all logging messages. This function may be called directly or using helper macros including ``EINA_LOG_DBG()``, ``EINA_LOG_ERR()`` or those that take a specific domain as an argument as with ``EINA_LOG_DOM_DBG()`` and ``EINA_LOG_DOM_ERR()``. Internally, ``eina_log_print()`` will call the function defined with ``eina_log_print_cb_set()``, which defaults to ``eina_log_print_cb_stderr()`` but may be changed to do whatever [...] -```bash -EINA_LOG_ABORT=1 EINA_LOG_ABORT_LEVEL={N} ./{application} +The logging system is thread-safe once initialized with ``eina_log_threads_enable()``. The thread that calls this function first is considered "main thread" and other threads will have their thread ID (``pthread_self()``) printed in the log message so it is easy to detect from where the messages are coming. + +The different logging levels serve to customize the amount of debugging information and may be used to automatically call ``abort()`` once a message of a given level is printed. This is controlled by the environment variable ``EINA_LOG_ABORT`` and the level to be considered critical with ``EINA_LOG_ABORT_LEVEL``. These can be changed with ``eina_log_abort_on_critical_set()`` and ``eina_log_abort_on_critical_level_set()``. + +The default maximum level to print is defined by the environment variable ``EINA_LOG_LEVEL`` but may be set per-domain with ``EINA_LOG_LEVELS``. It will default to ``EINA_LOG_ERR``. This can be changed with ``eina_log_level_set()``. + +To use the log system ``Eina`` must be initialized with ``eina_init()`` and later shut down with ``eina_shutdown()``. + +### Controlling Print Callbacks ### + +The log module allows the user to change the way ``eina_log_print()`` displays messages. It suffices to pass to ``eina_log_print_cb_set()`` the function used to display the message. That function must be of type ``#Eina_Log_Print_Cb``. As custom data can be passed to that callback, customized messages can be displayed. + +It is suggested to not use ``__FILE__``, ``__FUNCTION__`` or ``__LINE__`` when writing that callback, but when defining macros like ``EINA_LOG_ERR()`` and others. + +## Logging Example ## + +The following example, available for download from the [Enlightenment Project git repository](https://git.enlightenment.org/tools/examples.git/tree/reference/c/eina/src/eina_log.c), demonstrates the control of logging from within an application. + +```c +#define EFL_EO_API_SUPPORT 1 +#define EFL_BETA_API_SUPPORT 1 + +#include <stdio.h> + +#include <Eina.h> +#include <Efl_Core.h> + +/* + * Efl Core Log examples. + * + * This demo shows how to log at various levels and to change what log is shown. + * You can also use a custom log printer in your app as shown in _log_custom. + */ + +static double +_divide(int num, int denom) +{ + if (denom == 0) + EINA_LOG_CRIT("Attempt to divide by 0\n"); + else + { + if (denom < 0) + EINA_LOG_WARN("Possible undesirable effect, divide by negative number"); + + double ret = ((double) num / denom); + EINA_LOG_INFO("%d / %d = %f\n", num, denom, ret); + return ret; + } + + return -1; +} + +static void +_divides() +{ + _divide(5, 1); + _divide(5, -1); + _divide(5, 0); +} + +static void +_log_levels() +{ + printf("Executing with default logging\n"); + _divides(); + + eina_log_level_set(EINA_LOG_LEVEL_WARN); + printf("Executing with WARN level\n"); // same as EINA_LOG_LEVEL = 2 + _divides(); + + eina_log_level_set(EINA_LOG_LEVEL_INFO); + printf("Executing with INFO on\n"); // same as EINA_LOG_LEVEL = 3 + _divides(); +} + +void _print_cb(const Eina_Log_Domain *domain EINA_UNUSED, Eina_Log_Level level, + const char *file, const char *fnc, int line, + const char *fmt, void *data EINA_UNUSED, va_list args) +{ + fprintf(stdout, "LOG %d <%s (%s:%d)> ", level, fnc, file, line); + vfprintf(stdout, fmt, args); + putc('\n', stdout); +} + +static void +_log_custom() +{ + printf("Executing with custom log printer\n"); + eina_log_print_cb_set(_print_cb, NULL); + _divides(); +} + +EAPI_MAIN void +efl_main(void *data EINA_UNUSED, const Efl_Event *ev EINA_UNUSED) +{ + _log_levels(); + _log_custom(); + + efl_exit(0); +} +EFL_MAIN() ``` -Where ``{N}`` is the log level number and ``{application}`` the binary you are currently debugging. ## Further Reading ## -[Eina Programming Guide: Logging](/develop/c/eina/logging.md) -: A reference, including example, for the Eina_Log module. \ No newline at end of file +[Error Logging](/develop/debug/log-levels.md) +: A reference for controlling log levels at runtime. \ No newline at end of file --
