Commit 4837ffb0 authored by Vincent Sanders's avatar Vincent Sanders
Browse files

add some basic logging documentation

parent 053fd7b5
NetSurf logging
===============
NetSurf has a large number of internal diagnostic messages which can
be viewed by the developer (or user if they wish)
Each message has a category and a level which can be used to control
which messages are displayed.
The message category is used to allow filters to separate messages of
the same level from different sources.
The logging levels, from low to high, are:
- DEEPDEBUG
- DEBUG
- VERBOSE
- INFO
- WARNING
- ERROR
- CRITICAL
Compilation control
-------------------
At compilation time the logging behaviour can be controlled by using
configuration overrides in a Makefile.config The parameters are:
- NETSURF_USE_NSLOG
This controls if the NetSurf logging library (nslog) is used to
allow comprehensive filtering of messages. The value defaults to
AUTO which will use pkg-config to locate the library and enable if
present. If set to NO or the library cannot be located the browsers
logging will revert to simple boolean enabled/disabled logging
controlled by the -v command line switch.
- NETSURF_LOG_LEVEL
This controls what level of message is compiled into the NetSurf
binary. The default value is VERBOSE and when not using nslog this
value is also used to select what level of logging is shown with the
-v command line switch.
- NETSURF_BUILTIN_LOG_FILTER
When using nslog this sets the default non-verbose filter. The
default value ("level:WARNING") shows all messages of level WARNING
and above
- NETSURF_BUILTIN_VERBOSE_FILTER
When using nslog this sets the default verbose filter. The default
value ("level:VERBOSE") shows all messages of level VERBOSE and
above. The verbose level is selected from the commandline with the
-v switch
Command line
------------
The main command line switches that control logging are:
- -v
switches between the normal and verbose levels
- -V <file>
Send the logging to a file instead of standard output
- -log_filter=<filter>
Set the non verbose filter
- -log_verbose_filter=<filter>
Set the verbose filter
Options
-------
The logging filters can be configured by setting the log_filter and
log_verbose_filter options.
Adding messages
---------------
Messages can be easily added by including the utils/log.h header and
he NSLOG() macro. for example
NSLOG(netsurf, INFO, "An example message %d", example_func());
nslog
-----
If the nslog library is used it allows for application of a filter to
control which messages are output. The nslog filter syntax is best
viewed in its [documentation](http://source.netsurf-browser.org/libnslog.git/tree/docs/mainpage.md)
......@@ -15,6 +15,11 @@ There are some basic user guides for the
The [core user options](docs/netsurf-options.md) of the browser are
documented which are augmented by each frontend in a specific manner.
### Logging
The [logging](docs/logging.md) interface controls debug and error
messages not output through the GUI.
Documented API
--------------
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment