1recorder_trace_set(3) Recorder Library recorder_trace_set(3)
3
7 recorder_trace_set - Configure tracing for event recorders
8 RECORDER_TRACE - Retrieve configured value
9
13 #include <recorder/recorder.h>
14 int recorder_trace_set(const char * trace_set);
16 #define RECORDER_TRACE(trace_name) ...
17
19 The recorder_trace_set() function configures tracing for event
20 recorder, based on a trace description given in trace_set. The func‐
21 tion accepts a NULL input. A typical usage is to call it twice at the
22 beginning of the program, the first time to set some default configura‐
23 tion for important recorders such as warnings or errors, the second
24 time to pass some environment variable letting users configure tracing
25 easily.
26 /* Activate tracing for all _warning and _error event recorders */
29 recorder_trace_set(".*_(warning|error)");
30 /* User trace configuration, possible overriding the above */
32 recorder_trace_set(getenv("MY_PROGRAM_TRACES"));
33 The trace description is a space-delimited list of trace actions.
36 Alternatively, a colon (:) can also be used as a separator.
37 Each trace action starts with a regular expression used to select event
40 recorders by name. That regular expression can optionally be followed
41 by an equal sign = itself followed by either a numerical value or a
42 comma-separated list of names.
43 Tracing
46 If a numerical value is given, this value is associated to the selected
47 recorder(s), and can be read in the program by using
48 RECORDER_TRACE(trace_name).
49 The configured value is primarily used to activate tracing for the
52 record(3) and record_fast(3) functions. When the value is non-zero,
53 these functions will immediately show the events (tracing mode). Other‐
54 wise, they will simply record the events.
55 If no equal sign is given, the numerical value 1 is used.
58 Sharing for real-time graphing
61 If a comma-separated list of names is given, the corresponding event
62 recorder is shared for use by external programs such as
63 recorder_scope(1). All events must have the same number and type of
64 arguments. The comma-separated list sets the names of the data channels
65 that can then be graphed in real-time.
66 Special trace selectors
69 A number of trace selectors have a special meaning, and are normally
70 intended for the user of the program.
71 help displays the list of all available recorders, along with the
74 associated self-documentation string.
75 share sets the name of the shared-memory file used to communicate with
78 external programs, see recorder_share(3).
79 dump causes a recorder dump. See recorder_dump(3).
82 traces lists the current values for all trace configurations.
85 all activates all traces.
88
92 The function can return one of:
93 RECORDER_TRACE_OK
96 Thec trace description was successfully applied
97 RECORDER_TRACE_INVALID_NAME
100 One of the trace selection regular expressions is invalid.
101 RECORDER_TRACE_INVALID_VALUE
104 One of the trace configuration values is neither a numerical
105 value nor a comma-separated list of names.
106
110 The program below records its input arguments, and crashes if passed
111 crash as the first command-line argument.
112 #include <recorder/recorder.h>
114 #include <string.h>
115 RECORDER(program_args, 32, "Program command-line arguments");
117 int main(int argc, char **argv)
118 {
119 int a;
120 recorder_dump_on_common_signals(0, 0);
121 for (a = 0; a < argc; a++)
122 record(program_args, "Argument %d is %+s", a, argv[a]);
123 if (argc >= 2 && strcmp(argv[1], "crash") == 0)
125 {
126 char *ptr = NULL;
127 strcpy(ptr, argv[1]);
128 }
129 }
130 When a crash occurs, previously recorded events are printed out on the
132 console.
133 The program below is an instrumented version of the classical recursive
136 Fibonacci computation. It uses several recorders corresponding to dif‐
137 ferent types of events, and activates warnings and errors in a way that
138 can be configured by setting an environment variable.
139 #include <recorder/recorder.h>
141 #include <string.h>
142 #include <stdio.h>
143 #include <stdlib.h>
144 RECORDER(fib_main, 32, "Loops in fib function");
146 RECORDER(fib_loops, 32, "Loops in fib function");
147 RECORDER(fib_warning, 32, "Warnings in fib function");
148 RECORDER(fib_error, 32, "Errors in fib function");
149 int fib(int n)
151 {
152 if (n <= 1) {
153 if (n < 0)
154 record(fib_error, "fib is undefined for negative value %d", n);
155 return n;
156 }
157 record(fib_loops, "Computing fib(%d)", n);
158 int result = fib(n-1) + fib(n-2);
159 record(fib_loops, "Computed fib(%d) = %d", n, result);
160 return result;
161 }
162 int main(int argc, char **argv)
164 {
165 int a;
166 recorder_dump_on_common_signals(0, 0);
167 recorder_trace_set(".*_warning=35 .*_error");
168 recorder_trace_set(getenv("FIB_TRACES"));
169 for (a = 1; a < argc; a++) {
170 int n = atoi(argv[a]);
171 if (n >= RECORDER_TRACE(fib_warning))
172 record(fib_warning, "Computing for %d may take a while", n);
173 printf("fib(%d) = %d0, n, fib(n));
174 if (n >= RECORDER_TRACE(fib_warning))
175 record(fib_warning, "Computation for %d finally completed", n);
176 }
177 }
178 This program will produce an output similar to the following:
180 % fib 1 2 3 4 10 20 30 35 10 40 -1
182 fib(1) = 1
183 fib(2) = 1
184 fib(3) = 2
185 fib(4) = 3
186 fib(10) = 55
187 fib(20) = 6765
188 fib(30) = 832040
189 [2714667 0.177725] fib_warning: Computing for 35 may take a while
190 fib(35) = 9227465
191 [32575370 1.859156] fib_warning: Computation for 35 finally completed
192 fib(10) = 55
193 [32575547 1.859171] fib_warning: Computing for 40 may take a while
194 fib(40) = 102334155
195 [363735828 20.527882] fib_warning: Computation for 40 finally completed
196 [363735829 20.527887] fib_error: fib is undefined for negative value -1
197 fib(-1) = -1
198 The first column in trace outputs is the number of events that were
199 recorded. THe second column is the time in seconds since the program
200 started.
201 The same program can also be run with additional tracing or warnings,
204 for example:
205 % FIB_TRACES="recorder_location fib_loops fib_warning=3" /tmp/fib 3 4
207 /tmp/fib.c:33:[82 0.000496] fib_warning: Computing for 3 may take a while
208 /tmp/fib.c:18:[83 0.000561] fib_loops: Computing fib(3)
209 /tmp/fib.c:18:[84 0.000570] fib_loops: Computing fib(2)
210 /tmp/fib.c:20:[85 0.000575] fib_loops: Computed fib(2) = 1
211 /tmp/fib.c:20:[86 0.000581] fib_loops: Computed fib(3) = 2
212 fib(3) = 2
213 /tmp/fib.c:36:[87 0.000590] fib_warning: Computation for 3 finally completed
214 /tmp/fib.c:33:[88 0.000596] fib_warning: Computing for 4 may take a while
215 /tmp/fib.c:18:[89 0.000601] fib_loops: Computing fib(4)
216 /tmp/fib.c:18:[90 0.000607] fib_loops: Computing fib(3)
217 /tmp/fib.c:18:[91 0.000612] fib_loops: Computing fib(2)
218 /tmp/fib.c:20:[92 0.000619] fib_loops: Computed fib(2) = 1
219 /tmp/fib.c:20:[93 0.000625] fib_loops: Computed fib(3) = 2
220 /tmp/fib.c:18:[94 0.000664] fib_loops: Computing fib(2)
221 /tmp/fib.c:20:[95 0.000707] fib_loops: Computed fib(2) = 1
222 /tmp/fib.c:20:[96 0.000724] fib_loops: Computed fib(4) = 3
223 fib(4) = 3
224 /tmp/fib.c:36:[97 0.000741] fib_warning: Computation for 4 finally completed
225
228 When a recorder is shared, incorrect data can be fetched by the client
229 graphing program if the types and number of arguments is not consistent
230 for all entries in the recorder.
231 Bugs should be reported using https://github.com/c3d/recorder/issues.
234
238 RECORDER_DEFINE(3), RECORDER_DECLARE(3)
239 recorder_dump(3), recorder_dump_for(3),
240 recorder_configure_output(3), recorder_configure_show(3)
241 recorder_configure_format(3), recorder_configure_type(3)
242 Additional documentation and tutorials can be found at
245 https://github.com/c3d/recorder.
246
250 Written by Christophe de Dinechin
2511.0 2019-03-09 recorder_trace_set(3)