Collections functions
General functions
Node functions
Render functions
Theme permission functions
User functions
Resource functions

debug_track_vars()

Description

Debug log tracked variables (as configured in System > System console).

IMPORTANT: the debug log will contain the JSON encoded version of the tracked variable. For further analysis, just copy
the value (ie. everything within double quotes) and prettyfi it in your IDE.

Partially implements structured data from RFC 5424 @see https://tools.ietf.org/html/rfc5424

after), the @ sign and then the function name (e.g end@include_plugin_config). In other cases it
might be better to record the line "e.g line-59@include/db.php".
IMPORTANT: it is important to keep the location format consistent to help developers filter faster
when processing the debug log for tracked vars.
Used to provide extra information (for an example @see process_config_options())

Parameters

ColumnTypeDefaultDescription
$place string The place/entity this is being logged at. For functions use a position keyword (before, begin, end,
$vars array Defined variables within the scope the function was called from
$ctx_sd array [] Contextual structured data. Array keys will be used as a PARAM-NAME and its values as a PARAM-VALUE.

Location

include/debug_functions.php lines 223 to 293

Definition

 
function debug_track_vars(string $place, array $vars, array $ctx_sd = [])
    {
    global 
$debug_log;
    if(!
$debug_log)
        {
        return;
        }

    
$pid getmypid() ?: 'Undefined';
    
$rid md5(sprintf('%s-%s'$_SERVER['REQUEST_URI'] ?? serialize($_SERVER['argv']), serialize($_POST)));
    
$userref $GLOBALS['userref'] ?? 0;
    
$user $userref ?: 'System';

    
// Log message formats
    
$format          'tracking var: [pid="%s" rid="%s" user="%s" place="%s"]%s[%s="%s"]';
    
$format_json_err 'tracking var: [pid="%s" rid="%s" user="%s" place="%s"]%s JSON error "%s" when $%s = %s';

    
// Process contextual structured data (if any are valid)
    
$ctx_sd_str '';
    foreach(
$ctx_sd as $param_name => $param_value)
        {
        if(
is_string($param_name) && (is_string($param_value) || is_numeric($param_value)))
            {
            
$ctx_sd_str .= {$param_name}=\"{$param_value}\"";
            }
        }
    
$ctx_sd_str trim($ctx_sd_str);
    
$ctx_structured_data $ctx_sd_str !== '' "[info@context {$ctx_sd_str}]" '';

    
// For readability reasons, we show each tracked var on a new line in the debug log. If performance is badly affected,
    // we can switch to combine all tracked vars in the last SD-ELEMENT (ie [var1="value" var2="value"])
    
$tracked_vars get_tracked_vars($userref);
    foreach(
$tracked_vars as $tracked_var)
        {
        if(!isset(
$vars[$tracked_var]))
            {
            continue;
            }

        if(
in_array($tracked_varSENSITIVE_VARIABLE_NAMES))
            {
            
log_activity('Security: tracking sensitive variables'LOG_CODE_SYSTEM$tracked_varnullnullnullnullnull$userreffalse);
            continue;
            }

        
// JSON encode the tracked variables' value. If it fails, attempt to log this event (failure) in the debug log.
        
$tracked_var_value json_encode($vars[$tracked_var], JSON_NUMERIC_CHECK);
        if(
json_last_error() !== JSON_ERROR_NONE)
            {
            
$json_last_error_msg json_last_error_msg();

            
debug(
                
sprintf(
                    
$format_json_err,
                    
$pid,
                    
$rid,
                    
$user,
                    
$place,
                    
$ctx_structured_data,
                    
json_last_error_msg(),
                    
$tracked_var,
                    
debug_stringify($vars[$tracked_var])
                )
            );

            continue;
            }

        
debug(sprintf($format$pid$rid$user$place$ctx_structured_data$tracked_var$tracked_var_value));
        }
    }

This article was last updated 24th May 2023 09:05 Europe/London time based on the source file dated 28th June 2022 15:27 Europe/London time.