Trace run

Purpose: Emit trace.

 trace-run [ <format>, <variable> [ , ... ] ]

trace-run formats a tracing message according to the <format> string and a list of <variable>s and then writes the result into current process' trace file.

trace-run can be used without any clauses, in which case a location (file name and line number) is recorded in the trace file - this is useful when you only want to know if the execution passed through your code.

If trace-run has any other clauses, then <format> string must be present and there must be at least one <variable> (it means if you want to trace a simple string literal you still have to use "%s" as format).

For tracing to have effect, debugging and tracing must be enabled (see "--debug" and "--trace" options in gg). For location of trace files, see directories.

Format

<format> string must be a literal. Variables must follow <format> separated by commas in the same order as placeholders. If you use any placeholders other than specified below, or the type of variables you use do not match the type of a correspoding placeholder in <format>, your program will error out. You can use the following placeholders in <format> (see trace-run for an example of usage):

%s for a string
%<number>s for a string output with a width of at least <number> (any excess filled with spaces to the left),
%ld for a number
%<number>ld for a number output with a width of at least <number> (any excess filled with spaces to the left)

Here's an example of using the format placeholders:

 %% /my-request
     @Hi
     trace-run "%s it's %ld degrees outside, or with minimum width: %20s it's %20ld outside", "yes", 90, "yes", 90
 %%

Create and make the application:

sudo mgrg -i -u $(whoami) test
gg --trace --debug

Run it:

gg -r --req="/my-request" --exec

The output is:

Hi

And to find the location of trace file:

gg -t 1

The line in the trace file output by your trace-run would be similar to:

2024-08-01-17-13-55 (my_request.gliim:4)| my_request yes it's 90 degrees outside, or with minimum width:                  yes it's                   90 outside

Examples

 // Trace information
 trace-run "Program wrote %ld bytes into file %s", num_bytes, file_name

 // Trace that program execution passed through here
 trace-run