summaryrefslogtreecommitdiff
path: root/docs/logging.md
diff options
context:
space:
mode:
authorVincent Sanders <vince@kyllikki.org>2017-09-09 08:31:34 (GMT)
committer Vincent Sanders <vince@kyllikki.org>2017-09-09 08:31:34 (GMT)
commit4837ffb0ad6099b9a301fc040ad0e99be681bec3 (patch)
treeb35a3004d61bb8b5ab15d830c8806b681f902f1e /docs/logging.md
parent053fd7b5830b4adfe9703be281f6ecfa68e0410b (diff)
downloadnetsurf-4837ffb0ad6099b9a301fc040ad0e99be681bec3.tar.gz
netsurf-4837ffb0ad6099b9a301fc040ad0e99be681bec3.tar.bz2
add some basic logging documentation
Diffstat (limited to 'docs/logging.md')
-rw-r--r--docs/logging.md90
1 files changed, 90 insertions, 0 deletions
diff --git a/docs/logging.md b/docs/logging.md
new file mode 100644
index 0000000..41c7ea1
--- a/dev/null
+++ b/docs/logging.md
@@ -0,0 +1,90 @@
+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)