path: root/docs
diff options
authorVincent Sanders <>2017-09-09 09:31:34 +0100
committerVincent Sanders <>2017-09-09 09:31:34 +0100
commit4837ffb0ad6099b9a301fc040ad0e99be681bec3 (patch)
treeb35a3004d61bb8b5ab15d830c8806b681f902f1e /docs
parent053fd7b5830b4adfe9703be281f6ecfa68e0410b (diff)
add some basic logging documentation
Diffstat (limited to 'docs')
2 files changed, 95 insertions, 0 deletions
diff --git a/docs/ b/docs/
new file mode 100644
index 000000000..41c7ea1bd
--- /dev/null
+++ b/docs/
@@ -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:
+ - INFO
+Compilation control
+At compilation time the logging behaviour can be controlled by using
+configuration overrides in a Makefile.config The parameters are:
+ 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.
+ 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.
+ When using nslog this sets the default non-verbose filter. The
+ default value ("level:WARNING") shows all messages of level WARNING
+ and above
+ 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
+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());
+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](
diff --git a/docs/ b/docs/
index 41f26d441..fa72d1464 100644
--- a/docs/
+++ b/docs/
@@ -15,6 +15,11 @@ There are some basic user guides for the
The [core user options](docs/ of the browser are
documented which are augmented by each frontend in a specific manner.
+### Logging
+The [logging](docs/ interface controls debug and error
+messages not output through the GUI.
Documented API