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