1
2
3recorder_trace_set(3)          Recorder Library          recorder_trace_set(3)
4
5
6

NAME

8       recorder_trace_set - Configure tracing for event recorders
9       RECORDER_TRACE - Retrieve configured value
10
11
12

SYNOPSIS

14       #include <recorder/recorder.h>
15
16       int recorder_trace_set(const char * trace_set);
17       #define RECORDER_TRACE(trace_name) ...
18

DESCRIPTION

20       The   recorder_trace_set()   function   configures  tracing  for  event
21       recorder, based on a trace description given in trace_set.   The  func‐
22       tion  accepts  a NULL input. A typical usage is to call it twice at the
23       beginning of the program, the first time to set some default configura‐
24       tion  for  important  recorders  such as warnings or errors, the second
25       time to pass some environment variable letting users configure  tracing
26       easily.
27
28
29           /* Activate tracing for all _warning and _error event recorders */
30           recorder_trace_set(".*_(warning|error)");
31
32           /* User trace configuration, possible overriding the above */
33           recorder_trace_set(getenv("MY_PROGRAM_TRACES"));
34
35
36       The  trace  description  is  a  space-delimited  list of trace actions.
37       Alternatively, a colon (:) can also be used as a separator.
38
39
40       Each trace action starts with a regular expression used to select event
41       recorders  by  name. That regular expression can optionally be followed
42       by an equal sign = itself followed by either a  numerical  value  or  a
43       comma-separated list of names.
44
45
46   Tracing
47       If a numerical value is given, this value is associated to the selected
48       recorder(s),   and   can   be   read   in   the   program   by    using
49       RECORDER_TRACE(trace_name).
50
51
52       The  configured  value  is  primarily  used to activate tracing for the
53       record(3) and record_fast(3) functions. When  the  value  is  non-zero,
54       these functions will immediately show the events (tracing mode). Other‐
55       wise, they will simply record the events.
56
57
58       If no equal sign is given, the numerical value 1 is used.
59
60
61   Sharing for real-time graphing
62       If a comma-separated list of names is given,  the  corresponding  event
63       recorder   is   shared   for   use   by   external   programs  such  as
64       recorder_scope(1).  All events must have the same number  and  type  of
65       arguments. The comma-separated list sets the names of the data channels
66       that can then be graphed in real-time.
67
68
69   Special trace selectors
70       A number of trace selectors have a special meaning,  and  are  normally
71       intended for the user of the program.
72
73
74       help   displays  the  list  of  all available recorders, along with the
75              associated self-documentation string.
76
77
78       share  sets the name of the shared-memory file used to communicate with
79              external programs, see recorder_share(3).
80
81
82       dump   causes a recorder dump. See recorder_dump(3).
83
84
85       traces lists the current values for all trace configurations.
86
87
88       all    activates all traces.
89
90
91

RETURN VALUE

93       The function can return one of:
94
95
96       RECORDER_TRACE_OK
97              Thec trace description was successfully applied
98
99
100       RECORDER_TRACE_INVALID_NAME
101              One of the trace selection regular expressions is invalid.
102
103
104       RECORDER_TRACE_INVALID_VALUE
105              One  of  the  trace  configuration values is neither a numerical
106              value nor a comma-separated list of names.
107
108
109

EXAMPLES

111       The program below records its input arguments, and  crashes  if  passed
112       crash as the first command-line argument.
113
114           #include <recorder/recorder.h>
115           #include <string.h>
116
117           RECORDER(program_args, 32, "Program command-line arguments");
118           int main(int argc, char **argv)
119           {
120               int a;
121               recorder_dump_on_common_signals(0, 0);
122               for (a = 0; a < argc; a++)
123                   record(program_args, "Argument %d is %+s", a, argv[a]);
124
125               if (argc >= 2 && strcmp(argv[1], "crash") == 0)
126               {
127                   char *ptr = NULL;
128                   strcpy(ptr, argv[1]);
129               }
130           }
131
132       When  a crash occurs, previously recorded events are printed out on the
133       console.
134
135
136       The program below is an instrumented version of the classical recursive
137       Fibonacci  computation. It uses several recorders corresponding to dif‐
138       ferent types of events, and activates warnings and errors in a way that
139       can be configured by setting an environment variable.
140
141           #include <recorder/recorder.h>
142           #include <string.h>
143           #include <stdio.h>
144           #include <stdlib.h>
145
146           RECORDER(fib_main,    32, "Loops in fib function");
147           RECORDER(fib_loops,   32, "Loops in fib function");
148           RECORDER(fib_warning, 32, "Warnings in fib function");
149           RECORDER(fib_error,   32, "Errors in fib function");
150
151           int fib(int n)
152           {
153               if (n <= 1) {
154                   if (n < 0)
155                       record(fib_error, "fib is undefined for negative value %d", n);
156                   return n;
157               }
158               record(fib_loops, "Computing fib(%d)", n);
159               int result = fib(n-1) + fib(n-2);
160               record(fib_loops, "Computed fib(%d) = %d", n, result);
161               return result;
162           }
163
164           int main(int argc, char **argv)
165           {
166               int a;
167               recorder_dump_on_common_signals(0, 0);
168               recorder_trace_set(".*_warning=35 .*_error");
169               recorder_trace_set(getenv("FIB_TRACES"));
170               for (a = 1; a < argc; a++) {
171                   int n = atoi(argv[a]);
172                   if (n >= RECORDER_TRACE(fib_warning))
173                       record(fib_warning, "Computing for %d may take a while", n);
174                   printf("fib(%d) = %d0, n, fib(n));
175                   if (n >= RECORDER_TRACE(fib_warning))
176                       record(fib_warning, "Computation for %d finally completed", n);
177               }
178           }
179
180       This program will produce an output similar to the following:
181
182           % fib 1 2 3 4 10 20 30 35 10 40 -1
183           fib(1) = 1
184           fib(2) = 1
185           fib(3) = 2
186           fib(4) = 3
187           fib(10) = 55
188           fib(20) = 6765
189           fib(30) = 832040
190           [2714667 0.177725] fib_warning: Computing for 35 may take a while
191           fib(35) = 9227465
192           [32575370 1.859156] fib_warning: Computation for 35 finally completed
193           fib(10) = 55
194           [32575547 1.859171] fib_warning: Computing for 40 may take a while
195           fib(40) = 102334155
196           [363735828 20.527882] fib_warning: Computation for 40 finally completed
197           [363735829 20.527887] fib_error: fib is undefined for negative value -1
198           fib(-1) = -1
199       The  first  column  in  trace outputs is the number of events that were
200       recorded. THe second column is the time in seconds  since  the  program
201       started.
202
203
204       The  same  program can also be run with additional tracing or warnings,
205       for example:
206
207           % FIB_TRACES="recorder_location fib_loops fib_warning=3" /tmp/fib 3 4
208           /tmp/fib.c:33:[82 0.000496] fib_warning: Computing for 3 may take a while
209           /tmp/fib.c:18:[83 0.000561] fib_loops: Computing fib(3)
210           /tmp/fib.c:18:[84 0.000570] fib_loops: Computing fib(2)
211           /tmp/fib.c:20:[85 0.000575] fib_loops: Computed fib(2) = 1
212           /tmp/fib.c:20:[86 0.000581] fib_loops: Computed fib(3) = 2
213           fib(3) = 2
214           /tmp/fib.c:36:[87 0.000590] fib_warning: Computation for 3 finally completed
215           /tmp/fib.c:33:[88 0.000596] fib_warning: Computing for 4 may take a while
216           /tmp/fib.c:18:[89 0.000601] fib_loops: Computing fib(4)
217           /tmp/fib.c:18:[90 0.000607] fib_loops: Computing fib(3)
218           /tmp/fib.c:18:[91 0.000612] fib_loops: Computing fib(2)
219           /tmp/fib.c:20:[92 0.000619] fib_loops: Computed fib(2) = 1
220           /tmp/fib.c:20:[93 0.000625] fib_loops: Computed fib(3) = 2
221           /tmp/fib.c:18:[94 0.000664] fib_loops: Computing fib(2)
222           /tmp/fib.c:20:[95 0.000707] fib_loops: Computed fib(2) = 1
223           /tmp/fib.c:20:[96 0.000724] fib_loops: Computed fib(4) = 3
224           fib(4) = 3
225           /tmp/fib.c:36:[97 0.000741] fib_warning: Computation for 4 finally completed
226
227

BUGS

229       When a recorder is shared, incorrect data can be fetched by the  client
230       graphing program if the types and number of arguments is not consistent
231       for all entries in the recorder.
232
233
234       Bugs should be reported using https://github.com/c3d/recorder/issues.
235
236
237

SEE ALSO

239       RECORDER_DEFINE(3), RECORDER_DECLARE(3)
240       recorder_dump(3), recorder_dump_for(3),
241       recorder_configure_output(3), recorder_configure_show(3)
242       recorder_configure_format(3), recorder_configure_type(3)
243
244
245       Additional   documentation   and   tutorials   can    be    found    at
246       https://github.com/c3d/recorder.
247
248
249

AUTHOR

251       Written by Christophe de Dinechin
252
253
254
2551.0                               2019-03-09             recorder_trace_set(3)
Impressum