TRACE Environment Variables

TRACE Environment Variables

TRACE is initially controlled by environment variables.
When no environment variables are set however, (the default is that)
TRACEs of levels 0-2 will be written to stdout.

The presence of some env.vars will be used to activate memory mapped TRACE-ing.
The values of a subset of these will only be used during the creation of the mapped file,
but will be ignored if the file already exists.

Explanation of environment variables

The tenv function lists the environment variables, indicates there presence in the environment
and displays their values, if any.

In the following list, setting one of the first seven to an appropriate value will activate memory tracing.

• TRACE_NAMTBLENTS
  Used to activate memory tracing. Value ignore if file exists.
• TRACE_NUMENTS
  Used to activate memory tracing. Value ignore if file exists. The maximum number depends on the values of
  TRACE_NAMTBLENTS, TRACE_ARGSMAX, and TRACE_MSGMAX.
  Example TRACE_NUMENTS maximums:
  TRACE_MSGMAX=128 TRACE_NUMENTS=8388319; TRACE_MSGMAX=192 TRACE_NUMENTS=6710655
• TRACE_ARGSMAX
  Used to activate memory tracing. Value ignore if file exists. The default is 10.
• TRACE_MSGMAX
  Used to activate memory tracing. Value ignore if file exists. The special case of setting this to 0 will cause
  the default value (128) to be used. This value, along with TRACE_ARGSMAX effects the entry size. With the default
  values, the entry size is 256 bytes - which is a cache line size multiple.
• TRACE_NAME
  Used to activate memory tracing.
  The TRACE and TRACE_ macros in files where the TRACE_NAME macro has not been defined will
  uses this name (instead of the default name “TRACE”) unless or until a TRACE_CNTL( “name”,) occurs. $ gcc -o TRACE_NAME_test{,.c} -I$TRACE_INC && ./TRACE_NAME_test && TRACE_NAME=NameFromEnv ./TRACE_NAME_test 11-16 13:32:30.686046 TRACE inf the default TRACE_NAME is "TRACE" 11-16 13:32:30.686185 TRACE_CNTRL_SET inf trace after TRACE_CNTL("name","TRACE_CNTRL_SET") 11-16 13:32:30.689122 NameFromEnv inf the default TRACE_NAME is "TRACE" 11-16 13:32:30.689231 TRACE_CNTRL_SET inf trace after TRACE_CNTL("name","TRACE_CNTRL_SET") $ gcc -o TRACE_NAME_test{,.c} -I$TRACE_INC -DTRACE_NAME="DEFINED_NAME" && ./TRACE_NAME_test && TRACE_NAME=NameFromEnv ./TRACE_NAME_test 11-16 13:32:33.255453 DEFINED_NAME inf the default TRACE_NAME is "TRACE" 11-16 13:32:33.255591 TRACE_CNTRL_SET inf trace after TRACE_CNTL("name","TRACE_CNTRL_SET") 11-16 13:32:33.258566 DEFINED_NAME inf the default TRACE_NAME is "TRACE" 11-16 13:32:33.258664 TRACE_CNTRL_SET inf trace after TRACE_CNTL("name","TRACE_CNTRL_SET")
• TRACE_FILE
  Used to activate memory tracing using the named file as opposed to the default which is /tmp/trace_buffer_%u where
  the “%u” is replace by the value of environment variable $LOGNAME or $USERNAME or $USER or “” (if no env.var. set);
• TRACE_LVLM
  Used to activate memory tracing, IFF non-zero, setting the memory levels mask for all names and future names
  to this value. The command line level adjusting functions can change this, but not for new names created by the
  processes/threads running in the environment where this env. var. is set.
• TRACE_ENDL
  If TRACE stdout (or TRACE_PRINT_FD) needs to have an end-of-message indicator, use this env.var.
• TRACE_LIMIT_MS
  Set this variable to a triplet “count,ms on,ms off” (e.g. export TRACE_LIMIT_MS=8,80,800).
  The stdout (or TRACE_PRINT_FD) TRACEs will be limited by these parameters. The first TRACE starts an on time span and if
  count messages occur before the span ends, “[RATE LIMIT] ” is prepended to the message and the off time span is started.
  Along with the first message after the off time span, the string “[RESUMING dropped: %u] ” is prepended.
• TRACE_LVLS
  This acts like TRACE_LVLM above except for the stdout (or TRACE_PRINT_FD) destination (and memory tracing is not activated).
• TRACE_MODE
  This variable is only checked when TRACE_NAMLVLSET is set. It sets the mode. If memory tracing is enabled, the mode
  will be set in the memory file.
• TRACE_NAMLVLSET
  Can be used to set the level masks for a list of names” $ tlvls mode: M=0 S=1 TID NAME maskM maskS maskT ---- ------- ------------------ ------------------ ------------------ 1021 TRACE 0x000000000000000f 0x0000000000000007 0x0000000000000000 1022 TRACE 0x000000000000000f 0x0000000000000007 0x0000000000000000 $ export TRACE_NAMLVLSET='apple -1 7 > bannana 0xff 3 > pear 0xf 7' $ tlvls mode: M=0 S=1 TID NAME maskM maskS maskT ---- ------- ------------------ ------------------ ------------------ 0 apple 0xffffffffffffffff 0x0000000000000007 0x00000000000000ba 1 bannana 0x00000000000000ff 0x0000000000000003 0x0000000000000000 2 pear 0x000000000000000f 0x0000000000000007 0x0000000000000000 1021 TRACE 0x000000000000000f 0x0000000000000007 0x0000000000000000 1022 TRACE 0x000000000000000f 0x0000000000000007 0x0000000000000000 $
• TRACE_PRINT_FD
  If TRACE_PRINT_FD is set to 2, stdout TRACEs become stderr. The program could also, before the TRACE is
  initialized, establish a pipe or open a file and set this env var to the associated fd.
• TRACE_SHOW
  Used to control the order and presence of items in the tshow output.
• TRACE_TIME_FMT
  Controls the time fmt for tshow and stdout (or TRACE_PRINT_FD) traces.