Coding standards
Security in ResourceSpace
Developer reference
Database
Action functions
Admin functions
Ajax functions
Annotation functions
API functions
Collections functions
Comment functions
Config functions
CSV export functions
Dash functions
Debug functions
Encryption functions
Facial recognition functions
File functions
General functions
Language functions
Log functions
Login functions
Message functions
Migration functions
Node functions
PDF functions
Plugin functions
Render functions
Reporting functions
Request functions
Research functions
Slideshow functions
Theme permission functions
User functions
Video functions
Database functions
Metadata functions
Resource functions
Search functions
Map functions
Job functions
Tab functions
Test 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_var, SENSITIVE_VARIABLE_NAMES))
            {
            log_activity('Security: tracking sensitive variables', LOG_CODE_SYSTEM, $tracked_var, null, null, null, null, null, $userref, false);
            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.