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);