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

NAME

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

SYNOPSIS

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

DESCRIPTION

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
29
30           /* Activate tracing for all _warning and _error event recorders */
31           recorder_trace_set(".*_(warning|error)");
32
33           /* User trace configuration, possible overriding the above */
34           recorder_trace_set(getenv("MY_PROGRAM_TRACES"));
35
36
37       The  trace  description  is  a  space-delimited  list of trace actions.
38       Alternatively, a colon (:) can also be used as a separator.
39
40
41       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
46
47   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
52
53       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
58
59       If no equal sign is given, the numerical value 1 is used.
60
61
62   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
69
70   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
74
75       help   displays  the  list  of  all available recorders, along with the
76              associated self-documentation string.
77
78
79       share  sets the name of the shared-memory file used to communicate with
80              external programs, see recorder_share(3).
81
82
83       dump   causes a recorder dump. See recorder_dump(3).
84
85
86       traces lists the current values for all trace configurations.
87
88
89       all    activates all traces.
90
91
92

RETURN VALUE

94       The function can return one of:
95
96
97       RECORDER_TRACE_OK
98              Thec trace description was successfully applied
99
100
101       RECORDER_TRACE_INVALID_NAME
102              One of the trace selection regular expressions is invalid.
103
104
105       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
109
110

EXAMPLES

112       The program below records its input arguments, and  crashes  if  passed
113       crash as the first command-line argument.
114
115           #include <recorder/recorder.h>
116           #include <string.h>
117
118           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
126               if (argc >= 2 && strcmp(argv[1], "crash") == 0)
127               {
128                   char *ptr = NULL;
129                   strcpy(ptr, argv[1]);
130               }
131           }
132
133       When  a crash occurs, previously recorded events are printed out on the
134       console.
135
136
137       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
142           #include <recorder/recorder.h>
143           #include <string.h>
144           #include <stdio.h>
145           #include <stdlib.h>
146
147           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
152           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
165           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
181       This program will produce an output similar to the following:
182
183           % 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
204
205       The  same  program can also be run with additional tracing or warnings,
206       for example:
207
208           % 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
228

BUGS

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
234
235       Bugs should be reported using https://github.com/c3d/recorder/issues.
236
237
238

SEE ALSO

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
245
246       Additional   documentation   and   tutorials   can    be    found    at
247       https://github.com/c3d/recorder.
248
249
250

AUTHOR

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