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
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
|
# Logging and tracing in Cyclone DDS
A lot of effort has gone into providing as much useful information as possible
when a log message is written and a fair number of mechanisms were put in
place to be able to do so.
The difficulty with logging in Cyclone DDS is the fact that it is both used by
user applications and internal services alike. Both use-cases have different
needs with regard to logging. e.g. a service may just want to write all
information to a log file, whereas a user application may want to display the
message in a graphical user interface or reformat it and write it to stdout.
> This document does not concern itself with error handling, return codes,
> etc. Only logging and tracing are covered.
## Design
The logging and tracing api offered by Cyclone DDS is a merger of the reporting
functionality that existed in the various modules that Cyclone is made out of.
Why the API needed to change is documented in the section
[Issues with previous implementation].
The new and improved logging mechanism in Cyclone DDS allows the user to simply
register a callback function, as is customary for libraries, that matches the
signature `dds_log_write_fn_t`. The callback can be registered by passing it
to `dds_set_log_sink` or `dds_set_trace_sink`. The functions also allow for
registering a `void *` that will be passed along on every invocation of the
the callback. To unregister a log or trace sink, call the respective function
and pass NULL for the callback. This will cause Cyclone DDS to reinstate the
default handler. aka stdout, stderr, or the file specified in the configuration
file.
```C
typedef void(*dds_log_write_fn_t)(dds_log_data_t *, void *);
struct dds_log_data {
uint32_t priority;
const char *file;
uint32_t line;
const char *function;
const char *message;
};
typedef struct dds_log_data dds_log_data_t;
dds_return_t dds_set_log_sink(dds_log_write_fn_t *, const void *);
dds_return_t dds_set_trace_sink(dds_log_write_fn_t *, const void *);
```
> Cyclone DDS offers both a logging and a tracing callback to allow the user to
> easily send traces to a different device than the log messages. The trace
> function receives both the log messages and trace messages, while the log
> function will only receive the log messages.
> The user is responsible for managing resources himself. Cyclone DDS will not
> attempt to free *userdata* under any circumstance. The user should revert to
> the default handler, or register a different sink before invalidating the
> userdata pointer.
> The *dds_set_log_sink* and *dds_set_trace_sink* functions are synchronous.
> It is guaranteed that on return no thread in the Cyclone DDS stack will
> reference the sink or the *userdata*.
To minimize the amount of information that is outputted when tracing is
enabled, the user can enable/disable tracing per category. Actually the
priority member that is passed to the handler consists of the priority,
e.g. error, info, etc and (if it's a trace message) the category.
To be specific. The last four bits of the 32-bit integer contain the priority.
The other bits implicitly indicate it's a trace message and are reserved to
specify the category to which a message belongs.
```C
#define DDS_LC_FATAL 1u
#define DDS_LC_ERROR 2u
#define DDS_LC_WARNING 4u
#define DDS_LC_INFO 8u
#define DDS_LC_CONFIG 16u
...
```
> DDSI is the Cyclone DDS module that the log and trace mechanism originated
> from. For that reason not all categories make sense to use in API code and
> some categories that you would expect may be missing. For now the categories
> are a work-in-progress and may be changed without prior notice.
To control which messages are passed to the registered sinks, the user
must call `dds_set_log_mask` or `dds_set_trace_mask`. Whether or not to call
the internal log and trace functions depends on it. The user is strongly
discouraged to enable all categories and filter messages in the registered
handler, because of the performance impact!
> Tests have shown performance to decrease by roughly 5% if the decision on
> whether or not to write the message is done outside the function. The reason
> obviously not being the *if*-statement, but the creation of the stack frame.
For developer convenience, a couple of macro's are be introduced so the
developer does not have to write boilerplate code each time. The
implementation will roughly follow what is specified below.
```C
#define DDS_FATAL(fmt, ...)
#define DDS_ERROR(fmt, ...)
#define DDS_INFO(fmt, ...)
#define DDS_WARNING(fmt, ...)
#define DDS_TRACE(cat, fmt, ...)
```
> Log and trace messages are finalized by a newline. If a newline is not
> present, the buffer is not flushed. This is can be used to extend messages,
> e.g. to easily append summaries and decisions, and already used throughout
> the ddsi module. The newline is replaced by a null character when the
> message is passed to a sink.
### Default handlers and behavior
If the user does not register a sink, messages are printed to the default
location. Usually this means a cyclonedds.log file created in the working
directory, but the location can be changed in the configuration file. By
default only error and warning messages will be printed.
> As long as no file is open (or e.g. a syslog connection is established),
> messages are printed to stderr.
For convenience a number of log handlers will ship with Cyclone. Initially
the set will consist of a handler that prints to stdout/stderr and one that
prints to a file. However, at some point it would be nice to ship handlers
that can print to the native log api offered by a target. e.g.
* Windows Event Log on Microsoft Windows
* Syslog on Linux
* Unified Logging on macOS
* logMsg or the ED&R (Error Detection and Reporting) subsystem on VxWorks
> For now it is unclear what configuration options are available for all the
> default handlers or how the API to update them will look exactly.
## Log message guidelines
* Write concise reports.
* Do not leave out information, but also don't turn it into an essay.
e.g. a message for a failed write operation could include topic and
partition names to indicate the affected system scope.
* Write consistent reports.
* Use the name of the parameter as it appears in the documentation for that
language binding to reference a parameter where applicable.
* Use the same formatting style as other messages in the same module.
* e.g. use "could not ..." or "failed to ..." consistently.
* Avoid duplicate reports as much as possible.
e.g. if a problem is reported in a lower layer, do not report it again when
the error is propagated.
* Discuss with one of the team members if you must deviate from the
formatting rules/guidelines and update this page if applicable.
* Report only meaningful events.
## Issues with previous implementation
* Multiple files are opened. DDSI, by default, writes to cyclonedds-trace.log,
but also contains info, warning and error log messages written by DDSI
itself. All other modules write to cyclone-info.log and cyclone-error.log.
Options are available, but they're all over the place. Some are adjusted by
setting certain environment variables, others are configured by modifying the
configuration file. Not exactly what you'd call user friendly. Also, simply
writing a bunch of files from a library is not considered good practice.
* Cyclone only offers writing to a *FILE* handle. The filenames mentioned
above by default, but a combination of stdout/stderr can also be used. There
is no easy way to display them in a GUI or redirect them to a logging API.
e.g. syslog on Linux or the Windows Event Log on Microsoft Windows.
* The report stack is a cumbersome mechanism to use and (to a certain extend)
error prone. Every function (at least every function in the "public" APIs)
must start with a report stack instruction and end with a report flush
instruction.
* Cyclone assumes files can always be written. For a number of supported
targets, e.g. FreeRTOS and VxWorks, this is often not the case. Also,
filling the memory with log files is probably undesirable.
* Cyclone (except for DDSI) does not support log categories to selectively
enable/disable messages that the user is interested in. Causing trace logs
to contain (possibly) too much information.
* The report mechanism expects an error code, but it's unclear what "type" of
code it is. It can be a valid errno value, os_result, utility result, DDS
return code, etc. While the problem can be fixed by adding a module field to
the log message struct. The message is often generated in the layer above
the layer that the error originated from. Apart from that, the report
callback is not the place to handle errors gracefully. Return codes and
exceptions are the mechanism to do that.
* The logging API is different across modules. DDSI uses the nn_log macro
family, the abstraction layer uses the OS_REPORT family and DDS uses the
dds_report family. Apart from the macros used, the information that would
end up in the report callback is also different.
|
