This directory contains the trace logger framework.

* TraceLogger

    The TraceLogger encapsulates the logging method for traces. A particular thread-local logger
    is created per each packet thread and one for the main thread. The logging configuration
    happens in the module. The logger factory is used to init/cleanup loggers.

    Include "trace_logger.h" to get TraceLogger base class.
    Built-in loggers are defined in "trace_loggers.h/trace_loggers.cc".

* TraceLoggerFactory

    The base TraceLoggerFactory is used to create a particular TraceLogger instance per each
    thread. One factory instance exists which used to init/cleanup loggers and placed
    into TraceConfig. The factory object instantiates in the module due to configuration.

    Include "trace_logger.h" to get TraceLoggerFactory base class and template function
    to create particular objects. Built-in factories are defined in "trace_loggers.h/trace_loggers.cc".

* TraceConfig

    This is a class that contains pointer on TraceLoggerFactory object and Trace list.
    By default all Traces are off. TraceModule fills Traces from configuration.

    TraceConfig placed into "trace_config.h".

* TraceModule

    This module provides configuration for trace logs:
        output - create a concrete logger factory based on the output value (stdout/syslog).
        constraints - set packet constraints to use for trace filtering.
        modules - set modules trace level verbosity.
        ntuple - on/off packet n-tuple info logging.
        timestamp - on/off message time stamps.

    This is a built-in module (from coreinit.lua)

    The module placed into "trace_module.h/trace_module.cc".

    TraceModule ctor should be called after all existed modules due to TraceModule
        dynamic params restriction.

* TraceSwap

    This class extends snort::AnalyzerCommand and represents control channel CLI commands
    for setting/clearing trace configuration from the shell. Commands parameters are encapsulated in
    the TraceSwapParams class.
    Available commands:
        1) trace.set({ modules = {}, constraints = {}, ntuple = true/false, timestamp = true/false })
           -- set new modules traces, constraints, ntuple and timestamp options;
        2) trace.clear() -- clear modules traces and constraints.

* TraceSwapParams

    This is a helper class for TraceSwap which encapsulates dynamic initialization and storing of
    snort::Parameter and snort::Command lists based on TraceModule's parameters.

* TraceParser

    This class encapsulates module trace options and packet constraints parsing and setting logic.

* TraceApi

    TraceApi is a facade API class used to init/reinit/term thread-local trace logger and module's
    trace pointers and to match packets and flows against trace filtering constraints.

    TraceApi placed into "trace_api.h/trace_api.cc"

* Trace

    This class encapsulates trace verbosity functionality.

* Configuration override

    By default, the factory will be initialized based on Snort run mode (stdout or syslog).
    But this can be explicitly overwritten in TraceModule's configuration to specify
    which kind of logger to use.

    Changes will be applied in case of reloading too.

* External dependencies

    Include TraceApi header somewhere in the code where it needs to make trace logs.
    Make sure that TraceApi::thread_init()/thread_term() are provided for thread where
    TraceApi::log() is going used.

    TraceConfig should be configured in SnortConfig before TraceApi init.

    To create specific TraceLogger/TraceLoggerFactory pair just inherit base classes placed
    into "trace_logger.h" and init TraceConfig with a new factory during configuration.

* Extending the trace logger framework with TraceLogger plugins

    It's possible to create a trace logger as an inspector plugin to handle a custom logic of trace
    messages printing. The workflow here is to implement the custom logger and logger factory by
    inheriting from the Snort TraceLogger and TraceLoggerFactory classes, put them into a separate
    plugin, and call TraceApi::override_logger_factory() during the plugin configuration to
    initialize the framework with the custom logger factory.

* Disabling packet constraints matching

    Constraints matching can be disabled by setting "trace.constraints.match = false" during
    configuration. This is effectively saying all packets don't pass the trace filter. It may be
    useful in case of using external packet filtering, such as filtering by the DAQ, or to block
    printing for all trace messages in the context of a packet.

