recorder_trace_set(3)

📦 version 1.2.3, in fedora 43, fedora 44

✨ recorder_trace_set ✨

okay bestie, welcome to the Recorder Library, section 3 🎀 this is recorder_trace_set(3) and it's genuinely the vibe-control panel for all your event recorders. let's go 💅

🌸 NAME 🌸

  • recorder_trace_set — configure tracing for event recorders
  • RECORDER_TRACE — retrieve configured value

🦋 SYNOPSIS 🦋

#include <recorder/recorder.h>

int recorder_trace_set(const char * trace_set);
#define RECORDER_TRACE(trace_name) ...

💖 DESCRIPTION 💖

The recorder_trace_set() function configures tracing for event recorder, based on a trace description given in trace_set. It literally accepts a NULL input, no drama. The typical slay is calling it twice at the beginning of your program: first time to set some default configuration for the important recorders (warnings, errors, the whole main-character squad), second time to pass some environment variable so users can configure tracing easily. it's giving ✨considerate✨

/* Activate tracing for all _warning and _error event recorders */
recorder_trace_set(".*_(warning|error)");

/* User trace configuration, possible overriding the above */
recorder_trace_set(getenv("MY_PROGRAM_TRACES"));

The trace description is a space-delimited list of trace actions. Alternatively, a colon (:) can also be used as a separator. both? iconic. choose your fighter 🫶

Each trace action starts with a regular expression used to select event recorders by name. That regular expression can optionally be followed by an equal sign = itself followed by either a numerical value or a comma-separated list of names.

🔥 Tracing 🔥

If a numerical value is given, this value is associated to the selected recorder(s), and can be read in the program by using RECORDER_TRACE(trace_name).

The configured value is primarily used to activate tracing for the record(3) and record_fast(3) functions. When the value is non-zero, these functions will immediately show the events (tracing mode). Otherwise, they will simply record the events. no cap.

If no equal sign is given, the numerical value 1 is used. default queen 👑

🌈 Sharing for real-time graphing 🌈

If a comma-separated list of names is given, the corresponding event recorder is shared for use by external programs such as recorder_scope(1). All events must have the same number and type of arguments. The comma-separated list sets the names of the data channels that can then be graphed in real-time. live graphing era 📈

⭐ Special trace selectors ⭐

A number of trace selectors have a special meaning, and are normally intended for the user of the program.

  • help — displays the list of all available recorders, along with the associated self-documentation string.
  • share — sets the name of the shared-memory file used to communicate with external programs, see recorder_share(3).
  • dump — causes a recorder dump. See recorder_dump(3).
  • traces — lists the current values for all trace configurations.
  • all — activates all traces.

🎀 RETURN VALUE 🎀

The function can return one of:

  • RECORDER_TRACE_OK — The trace description was successfully applied
  • RECORDER_TRACE_INVALID_NAME — One of the trace selection regular expressions is invalid.
  • RECORDER_TRACE_INVALID_VALUE — One of the trace configuration values is neither a numerical value nor a comma-separated list of names.

💜 EXAMPLES 💜

The program below records its input arguments, and crashes if passed crash as the first command-line argument.

#include <recorder/recorder.h>
#include <string.h>

RECORDER(program_args, 32, "Program command-line arguments");
int main(int argc, char **argv)
{
    int a;
    recorder_dump_on_common_signals(0, 0);
    for (a = 0; a < argc; a++)
        record(program_args, "Argument %d is %+s", a, argv[a]);

    if (argc >= 2 && strcmp(argv[1], "crash") == 0)
    {
        char *ptr = NULL;
        strcpy(ptr, argv[1]);
    }
}

When a crash occurs, previously recorded events are printed out on the console. (yes the crash is intentional, it's a demo bestie, do not ship that strcpy 😭)

The program below is an instrumented version of the classical recursive Fibonacci computation. It uses several recorders corresponding to different types of events, and activates warnings and errors in a way that can be configured by setting an environment variable.

#include <recorder/recorder.h>
#include <string.h>
#include <stdio.h>
#include <stdlib.h>

RECORDER(fib_main,    32, "Loops in fib function");
RECORDER(fib_loops,   32, "Loops in fib function");
RECORDER(fib_warning, 32, "Warnings in fib function");
RECORDER(fib_error,   32, "Errors in fib function");

int fib(int n)
{
    if (n <= 1) {
        if (n < 0)
            record(fib_error, "fib is undefined for negative value %d", n);
        return n;
    }
    record(fib_loops, "Computing fib(%d)", n);
    int result = fib(n-1) + fib(n-2);
    record(fib_loops, "Computed fib(%d) = %d", n, result);
    return result;
}

int main(int argc, char **argv)
{
    int a;
    recorder_dump_on_common_signals(0, 0);
    recorder_trace_set(".*_warning=35 .*_error");
    recorder_trace_set(getenv("FIB_TRACES"));
    for (a = 1; a < argc; a++) {
        int n = atoi(argv[a]);
        if (n >= RECORDER_TRACE(fib_warning))
            record(fib_warning, "Computing for %d may take a while", n);
        printf("fib(%d) = %d0, n, fib(n));
        if (n >= RECORDER_TRACE(fib_warning))
            record(fib_warning, "Computation for %d finally completed", n);
    }
}

This program will produce an output similar to the following:

% fib 1 2 3 4 10 20 30 35 10 40 -1
fib(1) = 1
fib(2) = 1
fib(3) = 2
fib(4) = 3
fib(10) = 55
fib(20) = 6765
fib(30) = 832040
[2714667 0.177725] fib_warning: Computing for 35 may take a while
fib(35) = 9227465
[32575370 1.859156] fib_warning: Computation for 35 finally completed
fib(10) = 55
[32575547 1.859171] fib_warning: Computing for 40 may take a while
fib(40) = 102334155
[363735828 20.527882] fib_warning: Computation for 40 finally completed
[363735829 20.527887] fib_error: fib is undefined for negative value -1
fib(-1) = -1

The first column in trace outputs is the number of events that were recorded. THe second column is the time in seconds since the program started. (yes, "THe", the original said it like that and we respect the lore 🙈)

The same program can also be run with additional tracing or warnings, for example:

% FIB_TRACES="recorder_location fib_loops fib_warning=3" /tmp/fib 3 4
/tmp/fib.c:33:[82 0.000496] fib_warning: Computing for 3 may take a while
/tmp/fib.c:18:[83 0.000561] fib_loops: Computing fib(3)
/tmp/fib.c:18:[84 0.000570] fib_loops: Computing fib(2)
/tmp/fib.c:20:[85 0.000575] fib_loops: Computed fib(2) = 1
/tmp/fib.c:20:[86 0.000581] fib_loops: Computed fib(3) = 2
fib(3) = 2
/tmp/fib.c:36:[87 0.000590] fib_warning: Computation for 3 finally completed
/tmp/fib.c:33:[88 0.000596] fib_warning: Computing for 4 may take a while
/tmp/fib.c:18:[89 0.000601] fib_loops: Computing fib(4)
/tmp/fib.c:18:[90 0.000607] fib_loops: Computing fib(3)
/tmp/fib.c:18:[91 0.000612] fib_loops: Computing fib(2)
/tmp/fib.c:20:[92 0.000619] fib_loops: Computed fib(2) = 1
/tmp/fib.c:20:[93 0.000625] fib_loops: Computed fib(3) = 2
/tmp/fib.c:18:[94 0.000664] fib_loops: Computing fib(2)
/tmp/fib.c:20:[95 0.000707] fib_loops: Computed fib(2) = 1
/tmp/fib.c:20:[96 0.000724] fib_loops: Computed fib(4) = 3
fib(4) = 3
/tmp/fib.c:36:[97 0.000741] fib_warning: Computation for 4 finally completed

💀 BUGS 💀

When a recorder is shared, incorrect data can be fetched by the client graphing program if the types and number of arguments is not consistent for all entries in the recorder. so like… keep your arg types consistent fr fr, that's the whole assignment 😤

Bugs should be reported using https://github.com/c3d/recorder/issues.

🫶 SEE ALSO 🫶

Additional documentation and tutorials can be found at https://github.com/c3d/recorder. go read it, it's giving educational 💖

👑 AUTHOR 👑

Written by Christophe de Dinechin

and that's the whole page bestie 💅 this beauty is version 1.0, dated 2019-03-09, and it's the recorder_trace_set(3) page — now go forth and trace responsibly ✨🎀🦋

📦 where this page comes from