From 6699a1d58a390a22e5cb675bcd3795af948dcafb Mon Sep 17 00:00:00 2001 From: Lutz Helwing Date: Mon, 7 Aug 2017 13:13:20 +0200 Subject: Add short explanation for DLT log level (#20) Signed-off-by: Lutz Helwing --- doc/dlt_book.txt | 2 + doc/dlt_loglevel_explained.txt | 135 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 137 insertions(+) create mode 100644 doc/dlt_loglevel_explained.txt diff --git a/doc/dlt_book.txt b/doc/dlt_book.txt index 695c36f..1026bb4 100644 --- a/doc/dlt_book.txt +++ b/doc/dlt_book.txt @@ -45,6 +45,8 @@ include::dlt_user_manual.txt[] include::dlt_cheatsheet.txt[] +include::dlt_loglevel_explained.txt[] + include::dlt_design_specification.txt[] include::dlt_filetransfer.txt[] diff --git a/doc/dlt_loglevel_explained.txt b/doc/dlt_loglevel_explained.txt new file mode 100644 index 0000000..84ac11a --- /dev/null +++ b/doc/dlt_loglevel_explained.txt @@ -0,0 +1,135 @@ +DLT Log Level Explained +======================= +Lutz Helwing +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); -- cgit v1.2.1