DLT Log Level Explained
=======================
Lutz Helwing <Lutz_Helwing@mentor.com>
0.0.1, 23rd July 2017: Initial version

Overview
--------
From the DLT point of view an application logger is defined by its "context". Part of this context is a log level value. When an application registers its context at the daemon (`DLT_REGISTER_CONTEXT()` or `dlt_register_context()`) the context's log level is set by the daemon to a value specified in dlt.conf (`ContextLogLevel`). All log messages sent by the application also have a log level which could be different from context log level. When this log level is greater than the context log level the message is not sent to dlt-daemon (i.e. filtered at application level). Usually this per-message log level is hard-coded in the application or could be part of a config file read by the application. This is a task the application developer has to take care of.

Example for context log level / message log level relation:

Context log level: `DLT_LOG_INFO`

Message log level: `DLT_LOG_INFO`

=> Message is logged


Context log level: `DLT_LOG_INFO`

Message log level: `DLT_LOG_DEBUG`

=> Message is not logged


Context log level: `DLT_LOG_ERROR`

Message log level: `DLT_LOG_INFO`

=> Message is not logged


Methods to set the log level for an application context
-------------------------------------------------------
- dlt-daemon sets initial application log level
    + There is a configuration parameter (see /etc/dlt.conf) `ContextLogLevel`.
        When a new application registers itself at the daemon, the daemon sets the application's log level to the value defined by the parameter.
    + This happens when the application registers itself with `DLT_REGISTER_CONTEXT()` or `dlt_register_context()`

- Environment variable `DLT_INITIAL_LOG_LEVEL`
    + There is an environment variable which is called `DLT_INITIAL_LOG_LEVEL`. Its value has the following form: `APID:CTID:LEVEL(;APID:CTID:LEVEL...)`. It allows to set a per-application-context log level. Values are separated by ';'.
    + Example: `DLT_INITIAL_LOG_LEVEL="AP1:CTX1:2;MLP:MLPC:3" ./my_logging_program` => my_logging_program context is started with log level `DLT_LOG_WARN` (can be seen in DLT Viewer)

- Application registers itself at daemon with self defined log level
    + In this case no log level is set by the daemon but by the application itself.
    + This happens when the application registers itself with `DLT_REGISTER_CONTEXT_LL_TS()` or `dlt_register_context_ll_ts()`

- Client (e.g. DLT Viewer) changes the log level of a particular application context at runtime.
    + The context's initial log level is set by one of the two methods described above.


DLT Code Snippets
-----------------
Excerpt from DLT API dlt_user_macros.h (Macro interface):

    /**
     * Register context (with default log level and default trace status)
     * @param CONTEXT object containing information about one special logging context
     * @param CONTEXTID context id with maximal four characters
     * @param DESCRIPTION ASCII string containing description
     */
    #define DLT_REGISTER_CONTEXT(CONTEXT,CONTEXTID,DESCRIPTION)

    /**
     * Register context with pre-defined log level and pre-defined trace status.
     * @param CONTEXT object containing information about one special logging context
     * @param CONTEXTID context id with maximal four characters
     * @param DESCRIPTION ASCII string containing description
     * @param LOGLEVEL log level to be pre-set for this context
     (DLT_LOG_DEFAULT is not allowed here)
     * @param TRACESTATUS trace status to be pre-set for this context
     (DLT_TRACE_STATUS_DEFAULT is not allowed here)
     */
    #define DLT_REGISTER_CONTEXT_LL_TS(CONTEXT,CONTEXTID,DESCRIPTION,LOGLEVEL,TRACESTATUS)


    /**
     * Send log message with variable list of messages (intended for verbose mode)
     * @param CONTEXT object containing information about one special logging context
     * @param LOGLEVEL the log level of the log message
     * @param ARGS variable list of arguments
     * @note To avoid the MISRA warning "The comma operator has been used outside a for statement"
     *       use a semicolon instead of a comma to separate the ARGS.
     *       Example: DLT_LOG(hContext, DLT_LOG_INFO, DLT_STRING("Hello world"); DLT_INT(123));
     */
    #define DLT_LOG(CONTEXT,LOGLEVEL,ARGS...)



Excerpt from DLT API dlt_user.h (function interface):

    /**
     * Register a context in the daemon.
     * This function has to be called before first usage of the context.
     * @param handle pointer to an object containing information about one special logging context
     * @param contextid four byte long character array with the context id
     * @param description long name of the context
     * @return Value from DltReturnValue enum
     */
    DltReturnValue dlt_register_context(DltContext *handle, const char *contextid, const char * description);

    /**
     * Register a context in the daemon with pre-defined log level and pre-defined trace status.
     * This function has to be called before first usage of the context.
     * @param handle pointer to an object containing information about one special logging context
     * @param contextid four byte long character array with the context id
     * @param description long name of the context
     * @param loglevel This is the log level to be pre-set for this context
              (DLT_LOG_DEFAULT is not allowed here)
     * @param tracestatus This is the trace status to be pre-set for this context
              (DLT_TRACE_STATUS_DEFAULT is not allowed here)
     * @return Value from DltReturnValue enum
     */
    DltReturnValue dlt_register_context_ll_ts(DltContext *handle, const char *contextid, const char * description, int loglevel, int tracestatus);

    /**
     * Write a null terminated ASCII string into a DLT log message.
     * @param handle pointer to an object containing information about one special logging context
     * @param loglevel this is the current log level of the log message to be sent
     * @param text pointer to the ASCII string written into log message containing null termination.
     * @return Value from DltReturnValue enum
     */
    DltReturnValue dlt_log_string(DltContext *handle,DltLogLevelType loglevel, const char *text);

    /**
     * Initialize the generation of a DLT log message (intended for usage in non-verbose mode)
     * This function has to be called first, when an application wants to send a new log messages.
     * Following functions like dlt_user_log_write_string and dlt_user_log_write_finish must only be called,
     * when return value is bigger than zero.
     * @param handle pointer to an object containing information about one special logging context
     * @param log pointer to an object containing information about logging context data
     * @param loglevel this is the current log level of the log message to be sent
     * @return Value from DltReturnValue enum, DLT_RETURN_TRUE if log level is matching
     */
    DltReturnValue dlt_user_log_write_start(DltContext *handle, DltContextData *log, DltLogLevelType loglevel);
