JS: Traces

Traces¶

The trace is the execution log of the framework. The machine level writes every event that enters a state machine, so it shows what occurred and in which order. It is the first tool for a browser application, and not the last.

Source code: src/gobj.js

A gobj traces at the union of three masks: the global mask, the mask of its gclass, and its own mask. Each of the three has a silencing partner, and the silencing side wins.

Levels¶

trace_level_t¶

The global levels, with the name that every function below accepts.

Every function accepts three forms for level: the name from this table, a bit mask as a string of digits, or an empty value, which means every global level.

Global¶

gobj_set_global_trace(level, set)¶

Turns a level on or off for every gclass. Returns 0, or -1 when the level name does not exist.

gobj_set_global_trace("machine", true);

gobj_set_global_no_trace(level, set)¶

Silences a level for every gclass. It wins against gobj_set_global_trace().

gobj_global_trace_level()¶

Gives the global mask, as a number.

gobj_global_trace_no_level()¶

Gives the global silencing mask, as a number.

gobj_set_global_trace2(bitmask, set)¶

Turns global levels on or off by bit mask instead of by name, like the C function of the same name. 0xFFFFFFFF with set false clears every global level. Returns 0.

gobj_set_global_trace2(trace_level_t.TRACE_MACHINE | trace_level_t.TRACE_EV_KW, true);

gobj_set_global_no_trace2(bitmask, set)¶

The silencing partner of gobj_set_global_trace2().

gobj_get_global_trace_level()¶

Gives the global levels in force, as a list of names. It is what the yuno saves for the global scope.

gobj_get_global_trace_level();    // ["machine", "start_stop"]

gobj_get_global_trace_no_level()¶

Gives the global silencing levels in force, as a list of names.

gobj_repr_global_trace_levels()¶

Gives the catalog of the global levels, as a list of records with name, bit, description and set. A development panel builds its list of switches from it.

gobj_set_deep_trace(value)¶

Turns everything on at the same time, for a session that hunts something. Returns 0.

Per gclass¶

gobj_set_gclass_trace(gclass, level, set)¶

Turns a level on or off for one gclass. gclass accepts the gclass itself or its name, so a caller that holds no handle gives the name. Returns 0, or -1 when the gclass or the level does not exist.

gobj_get_gclass_trace_level(gclass)¶

Gives the levels in force for a gclass, as a list of names: its own levels and the global ones, as in the C kernel. The names of the gclass’s own levels come from the s_user_trace_level it gives to gclass_create(), a list of [name, description] in bit order.

gobj_get_gclass_trace_level2(gclass)¶

Gives the gclass’s own levels only, without the global ones. It is what the yuno saves for the scope of a gclass.

gobj_set_gclass_trace("C_IEVENT_CLI", "ievents", true);
gobj_get_gclass_trace_level2("C_IEVENT_CLI");   // ["ievents"]

gobj_get_gclass_trace_no_level(gclass)¶

Gives the silencing levels of a gclass, as a list of names.

gobj_set_gclass_no_trace(gclass, level, set)¶

Silences a level for one gclass.

This is the pair that keeps a machine trace readable:

gobj_set_gclass_no_trace("C_TIMER", "machine", true);
gobj_set_global_no_trace("timer_periodic", true);

The machine level traces every event by design, and a timer is an event. A tick of one second buries what you follow, so silence the timers first.

Per gobj¶

gobj_set_gobj_trace(gobj, level, set)¶

Turns a level on or off for one gobj. Returns 0, or -1 when gobj is empty.

gobj_set_gobj_no_trace(gobj, level, set)¶

Silences a level for one gobj.

gobj_trace_level(gobj)¶

Gives the mask in force for a gobj: the union of the global mask, the mask of its gclass and its own. The C kernel computes it in the same way.

gobj_trace_no_level(gobj)¶

Gives the silencing mask in force for a gobj.

Persisted by the yuno¶

C_YUNO keeps the levels that a user sets, in its persistent attributes trace_levels and no_trace_levels, and restores them in its mt_create. It is the model of the C kernel: the same attributes, the same commands and the same keys.

get-global-trace, get-global-no-trace, get-gclass-trace and get-gclass-no-trace read the same levels. set accepts 1 / 0, true / false and set / reset.

gobj_command(gobj_yuno(), "set-gclass-trace",
    {gclass_name: "C_IEVENT_CLI", level: "ievents", set: 1}, gobj_yuno());

A command saves its whole scope, from the levels in force, and an empty scope is saved as []. At start up, a saved scope replaces what main() set before it created the yuno. A scope that was never saved keeps the default of main().

// main.js: the defaults
gobj_set_global_no_trace("timer_periodic", true);

// the user turns the periodic timer back on, once
gobj_command(gobj_yuno(), "set-global-no-trace",
    {level: "timer_periodic", set: 0}, gobj_yuno());
// saved: no_trace_levels = {"__global_no_trace__": []}
// every later start up: timer_periodic is NOT silenced

The yuno persists through the functions that the app gives to gobj_start_up(). An app that gives none keeps the levels until the page reloads.

The traffic of the websocket is the level ievents (or ievents2) of C_IEVENT_CLI. Its lines go to the function in the yuno attribute trace_ievent_callback, or to the console when that attribute is empty.

The format of the machine trace¶

gobj_set_trace_machine_format(format)¶

Chooses the format of the lines of the machine trace.

gobj_trace_machine_format()¶

Gives the format that is in force.

Write a trace¶

The four writers are in Logging: trace_msg() and trace_json() write a line and an object.