devguide: more on low level logging

Use the extending/output section to introduce the low level logging
API.

Ticket: #7227

diff --git a/doc/userguide/devguide/extending/output/index.rst b/doc/userguide/devguide/extending/output/index.rst
index 559723ee0af44dc928e36100320117db7863547b..cb6315e88ff01a8d0610bd4c458725b51a973dd1 100644 (file)
--- a/doc/userguide/devguide/extending/output/index.rst
+++ b/doc/userguide/devguide/extending/output/index.rst
@@ -1,7 +1,48 @@
 Output
 ======
 
-Introduction
-------------
+Low Level Logging
+-----------------
 
-Extending Suricata's alert and event output.
+Suricata's alert, protocol, and other types of output are built up
+from a set of low level loggers. These loggers include:
+
+- Packet logging (alerts)
+- Flow logging
+- Transaction logging (application layer)
+- File information logging
+- File data logging (file extraction)
+- Statistics
+
+These low level logging facilities are used to build up Suricata's
+logging include EVE, but they can also be hooked into by plugins or
+applications using Suricata as a library.
+
+.. note:: At this time only a C API exists to hook into the low level
+          logging functions.
+
+The Suricata source code contains an example plugin demonstrating how
+to hook into some of these APIs. See
+https://github.com/OISF/suricata/blob/master/examples/plugins/c-custom-loggers/custom-logger.c.
+
+Packet Logging
+~~~~~~~~~~~~~~
+
+Packet loggers can be registered with the
+``SCOutputRegisterPacketLogger`` function:
+
+.. literalinclude:: ../../../../../src/output-packet.h
+   :language: c
+   :start-at: /** \brief Register a packet logger
+   :end-at: );
+
+Flow Logging
+~~~~~~~~~~~~
+
+Flow loggers can be registered with the ``SCOutputRegisterFlowLogger``
+function:
+
+.. literalinclude:: ../../../../../src/output-flow.h
+   :language: c
+   :start-at: /** \brief Register a flow logger
+   :end-at: );

diff --git a/src/output-flow.h b/src/output-flow.h
index d91e044ae9676d7919c01dca9d025edaaa461bb3..c4a69febeb776be34e5b84e1bf2e612d53603e64 100644 (file)
--- a/src/output-flow.h
+++ b/src/output-flow.h
@@ -35,8 +35,7 @@
  */
 typedef int (*FlowLogger)(ThreadVars *, void *thread_data, Flow *f);
 
-/**
- * \brief Register a flow logger.
+/** \brief Register a flow logger.
  *
  * \param name An informational name for this logger. Used only for
  *     debugging.

diff --git a/src/output-packet.h b/src/output-packet.h
index 4d7309d7f28bfa5c50a80270192d4fb2c1d03fd3..30bbe09bb1dcaa22b800a84c07944f65c0849a2a 100644 (file)
--- a/src/output-packet.h
+++ b/src/output-packet.h
@@ -42,8 +42,7 @@ typedef int (*PacketLogger)(ThreadVars *, void *thread_data, const Packet *);
  */
 typedef bool (*PacketLogCondition)(ThreadVars *, void *thread_data, const Packet *);
 
-/**
- * \brief Register a packet logger.
+/** \brief Register a packet logger.
  *
  * \param logger_id An ID used to distinguish this logger from others
  *     while profiling.