diff options
Diffstat (limited to 'doc/dlt_loglevel_explained.txt')
| -rw-r--r-- | doc/dlt_loglevel_explained.txt | 135 |
1 files changed, 0 insertions, 135 deletions
diff --git a/doc/dlt_loglevel_explained.txt b/doc/dlt_loglevel_explained.txt deleted file mode 100644 index 84ac11a..0000000 --- a/doc/dlt_loglevel_explained.txt +++ /dev/null @@ -1,135 +0,0 @@ -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); |