134 lines
5.4 KiB
Plaintext
134 lines
5.4 KiB
Plaintext
---
|
|
~~Title: Eina 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.
|
|
|
|
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 ##
|
|
|
|
| Level | Number | Macro |
|
|
|---------|--------|---------------------|
|
|
|Critical | 0 | ``EINA_LOG_CRIT()`` |
|
|
|Error | 1 | ``EINA_LOG_ERR()`` |
|
|
|Warning | 2 | ``EINA_LOG_WARN()`` |
|
|
|Info | 3 | ``EINA_LOG_INFO()`` |
|
|
|Debug | 4 | ``EINA_LOG_DBG()`` |
|
|
|
|
|
|
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 ##
|
|
|
|
``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 you need such as networking or syslog logging.
|
|
|
|
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/enlightenment/examples/src/branch/master/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()
|
|
```
|
|
|
|
## Further Reading ##
|
|
|
|
[Error Logging](/develop/debug/log-levels.md)
|
|
: A reference for controlling log levels at runtime. |