1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
|
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);
|
