recorder_scope(1)

✨ NAME ✨

record_scope — a real-time graphing tool for recorded data. yes bestie, it literally draws your data live, main character energy fr fr 💅

---

🌸 SYNOPSIS 🌸

recorder_scope [options] channels

---

🦋 DESCRIPTION 🦋

okay so here's the vibe: recorder_scope graphs the data that your program collected through the record(3) statements you picked out. and not just that — it can also update your recorder configuration in real-time while the instrumented program is still running. live tweaking?? iconic. 👑

The channels you wanna see are picked using regular expressions. but listen — they must have already been shared by the instrumented program using recorder_trace_set(3), typically by setting the RECORDER_TRACES environment variable, or literally any other method your program uses to pass a recorder configuration string to the recorder_trace_set(3) function. no shared channels, no graph, that's the rule 💀

---

🎀 NOTES 🎀

Channel metadata strings (name, description, unit) live in the shared-memory mapping. and here's the important part, bestie, do not skip this: any pointers returned by the channel access APIs become invalid if the mapping is resized or recreated — for example when new channels are added. so if you need to hold onto them, copy them. periodt. 📌

---

💅 OPTIONS 💅

The program accepts the following options:

• -c config — send the configuration command to the instrumented program. this is how you dynamically adjust tracing options and stuff, for example. 🫶
• -s slider — set up a slider on the user interface that can control a specific trace value, see RECORDER_TRACE(3). the slider syntax is name=initial:min:max where name is the name of the recorder you're configuring, initial is its initial value, min is the lowest possible value on the slider, and max is the highest possible value on the slider. so cute, so functional ✨
• -d duration — set the maximum duration in seconds for the data displayed on the window. anything older than this duration just will not be shown. gone. bye 👋
• -w samples — set the sample window, aka the maximum number of samples displayed simultaneously. a value of 0 will automatically select the window width in pixels. magic ✨
• -t — toggle timing display in the graphs. same effect while the program is running: just hit the 't' key.
• -m — toggle display of minimum and maximum values in the graphs. same effect while running: the 'm' key.
• -a — toggle display of running average values in the graphs. same effect while running: the 'a' key.
• -n — toggle display of the normal values in the graphs (for example if you're only interested in min and max values, this is your girl). same effect while running: the 'n' key.
• -r ratio — set averaging ratio for -m and -a options, in percent.
• -b basename — set the basename for file when saving data or screen shots.
• -g WxH@XxY — set the window geometry to W x H pixels at position (X, Y)

---

🔥 EXAMPLES 🔥

If the instrumented program contains the following recorder instrumentation:

int rate = RECORDER_TWEAK(rate);
record(my_recorder, "The value of %d is %d", x, y * rate);

then the values of x and y can be exported by running the program instrumented. For example, setting the environment variable RECORDER_TRACES to the value my_recorder=x_value,y_value will export the first two data values in recorder my_recorder under the names x_value and y_value for use by recorder_scope.

To graph these values, you would use:

% recorder_scope x_value y_value

To enable tracing for all recorders whose names end in "error":

% recorder_scope -c '.*error'

To set the 'rate' tweak to 10, giving the value of RECORDER_TRACE(rate) or RECORDER_TWEAK(rate) the value 10:

% recorder_scope -c 'rate=10'

To adjust the value of 'rate' using a slider starting at value 10 and where the values can be set between 10 and 39:

% recorder_scope -s 'rate=10:2:39'

---

🌈 ENVIRONMENT VARIABLES 🌈

The path to the shared memory file can be specified using the RECORDER_SHARE environment variable. and bestie, that variable should be set consistently between the instrumented program and the recorder_scope application. both sides gotta be on the same page, no cap 🤝

---

💀 BUGS 💀

The recorder_scope program normally attempts to use OpenGL for faster rendering. this may not be convenient, for example over a remote X11 connexion. In that case, you should set the environment variable RECORDER_NOGL=1 — and heads up, you will have significantly lower performance. trade-offs, we hate to see it 😭

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

---

👑 SEE ALSO 👑

record(3), recorder_trace_set(3)

Additional documentation and tutorials can be found at https://github.com/c3d/recorder.

---

⭐ AUTHOR ⭐

Written by Christophe de Dinechin 🫶

---

and that's the whole thing bestie, you're officially a recorder_scope girly now 🌸 this was the Recorder Library version 1.0, dated 2019-03-09 — go forth and graph, mwah 💖🎀🦋