Tracking Variable Changes with LOGVARS

Understanding Variable Audit Trails

The LOGVARS system variable controls variable activity logging in Xi-Batch. When enabled, Xi-Batch records every variable modification, creating a detailed audit trail of variable operations and job-driven state changes.

What Gets Logged

Variable logging captures these events:

Value assignments : When variable values change

Variable creation : When new variables are created

Variable deletion : When variables are removed

Ownership changes : When variable owner changes

Group changes : When variable group changes

Comment changes : When variable comments are modified

Variable renaming : When variable names change

Enabling Variable Logging

Set the LOGVARS variable to specify log destination:

Log to file:

bash

btvar -s LOGVARS varaudit.log

File path is relative to spool directory (default /var/spool/xi/batch). Full path varaudit.log becomes /var/spool/xi/batch/varaudit.log.

Log to program/script:

bash

btvar -s 'LOGVARS |/usr/local/bin/var-logger.sh'

Program name must start with | character.

Disable logging:

bash

btvar -s 'LOGVARS '

Empty string turns off logging.

Log File Permissions

Like LOGJOBS, log file permissions match LOGVARS variable settings:

File owner : Same as LOGVARS variable owner

File group : Same as LOGVARS variable group

File modes : Read/write permissions from LOGVARS variable

Log Entry Format

Each log entry is a single line with pipe-delimited fields:

05/01/99|09:52:43|cnt|assign|Job start|jmc|users|2011|86742|myjob

Field order:

1. Date - dd/mm/yy or mm/dd/yy (depends on timezone)
2. Time - HH:MM:SS
3. Variable Name - Name of the affected variable
4. Status Code - Type of change (see below)
5. Event Code - Why the change occurred (see below)
6. User - Username that made the change
7. Group - Group name
8. Value - New value (numeric or string)
9. Job Number - Job that made the change (if applicable)
10. Job Title - Title of job that made the change (if applicable)

Status codes and event codes prefixed with machine: for remote host operations.

Status Codes

assign : Variable value was assigned or changed

chcomment : Variable comment was changed

chgrp : Variable group was changed

chown : Variable owner was changed

create : Variable was created

delete : Variable was deleted

rename : Variable was renamed

Event Codes

Event codes indicate the context of the change:

manual : Set via user command (btvar, btq, xbtq, etc.)

Job start : Assigned by job at start (from assignment list)

Job completed : Assigned by job at successful completion

Job error : Assigned by job at error exit

Job abort : Assigned by job when aborted

Job cancel : Assigned by job when cancelled

Understanding Job-Driven Changes

Variables are frequently modified by job assignments:

Example job with assignments:

bash

btr -t "Process data" \
    -A "cnt += 1 @ Job start" \
    -A "STATUS = Done @ Job completed" \
    -A "STATUS = Failed @ Job error" \
    process-script.sh

Resulting log entries:

06/02/26|10:15:22|cnt|assign|Job start|jmc|users|2012|87001|Process data
06/02/26|10:18:45|STATUS|assign|Job completed|jmc|users|Done|87001|Process data

This shows variable modifications driven by job lifecycle events.

Processing Log Files

Parse variable logs to track state changes:

Count changes by variable:

bash

awk -F'|' '{print $3}' /var/spool/xi/batch/varaudit.log | sort | uniq -c

Find manual changes:

bash

grep '|manual|' /var/spool/xi/batch/varaudit.log

Track specific variable:

bash

awk -F'|' '$3 == "STATUS"' /var/spool/xi/batch/varaudit.log

Job-driven assignments:

bash

awk -F'|' '$5 !~ /manual/ && $9 != ""' /var/spool/xi/batch/varaudit.log

Variables changed by specific job:

bash

awk -F'|' '$10 == "Daily backup"' /var/spool/xi/batch/varaudit.log

Logging to Programs

When LOGVARS specifies a program, each log line is sent to the program's standard input:

Example state monitor:

bash

#!/bin/bash
# /usr/local/bin/var-logger.sh

while IFS='|' read -r date time varname status event user group value jobnum jobtitle; do
    # Alert on critical state changes
    if [[ "$varname" == "SYSTEM_STATUS" && "$value" == "ERROR" ]]; then
        mail -s "System status critical" admin@example.com <<EOF
Variable: $varname
New value: $value
Changed by: $user
Event: $event
Job: $jobtitle ($jobnum)
Time: $date $time
EOF
    fi
    
    # Log all changes
    echo "$date|$time|$varname|$status|$event|$user|$group|$value|$jobnum|$jobtitle" \
        >> /var/log/xibatch-vars.log
done

Use Cases

Workflow debugging : Trace variable state changes through complex job dependencies

State machine monitoring : Track workflow state transitions for analysis

Audit compliance : Record who changed critical control variables

Race condition detection : Identify conflicting variable updates from concurrent jobs

Performance analysis : Monitor variable usage patterns to optimize conditions

Integration verification : Confirm external systems are setting variables correctly

Correlating Job and Variable Logs

Combine LOGJOBS and LOGVARS for complete workflow picture:

Example correlation script:

bash

#!/bin/bash
# Show job and related variable changes

JOBNUM=$1
JOBTITLE=$2

echo "=== Job Activity ==="
grep "|$JOBNUM|" /var/spool/xi/batch/jobaudit.log

echo ""
echo "=== Variable Changes ==="
grep "|$JOBNUM|" /var/spool/xi/batch/varaudit.log

Output shows:

=== Job Activity ===
06/02/26|10:15:22|87001|Process data|Started|jmc|users|150|1000
06/02/26|10:18:45|87001|Process data|Completed|jmc|users|150|1000

=== Variable Changes ===
06/02/26|10:15:22|cnt|assign|Job start|jmc|users|2012|87001|Process data
06/02/26|10:18:45|STATUS|assign|Job completed|jmc|users|Done|87001|Process data

This reveals complete job lifecycle with state changes.

Monitoring Critical Variables

Implement alerting for important variables:

Monitor system control variables:

bash

#!/bin/bash
# Alert on LOADLEVEL changes

while IFS='|' read -r date time varname status event user group value jobnum jobtitle; do
    if [[ "$varname" == "LOADLEVEL" ]]; then
        logger -t xibatch "LOADLEVEL changed to $value by $user ($event)"
        
        # Alert if set too low
        if [[ "$value" -lt 1000 ]]; then
            echo "LOADLEVEL critically low: $value" | \
                mail -s "Xi-Batch Alert" ops@example.com
        fi
    fi
done

Log Rotation

Variable logs also grow continuously:

Using logrotate:

bash

# /etc/logrotate.d/xibatch-vars
/var/spool/xi/batch/varaudit.log {
    weekly
    rotate 52
    compress
    delaycompress
    missingok
    notifempty
    create 0640 batch batch
}

Analysing Variable Usage Patterns

Identify frequently-changed variables:

bash

#!/bin/bash
# Variable change frequency report

echo "Variable Change Frequency (Last 7 Days)"
echo "========================================"

# Get last 7 days of logs
WEEK_AGO=$(date -d '7 days ago' +%d/%m/%y)

awk -F'|' -v start="$WEEK_AGO" '
    $1 >= start {
        vars[$3]++
    }
    END {
        for (v in vars) {
            printf "%-20s %d\n", v, vars[v]
        }
    }
' /var/spool/xi/batch/varaudit.log | sort -k2 -rn

Network-Wide Variable Tracking

In networked environments, track cross-host variable operations:

Identify remote changes:

bash

# Find variables changed from remote hosts
grep -E '\|[a-z0-9-]+:' /var/spool/xi/batch/varaudit.log

Track exported variable synchronization:

bash

# Show all changes to exported variables
btvlist -e | awk '{print $1}' | while read var; do
    grep "|$var|" /var/spool/xi/batch/varaudit.log
done

Verifying Logging is Active

Check LOGVARS value:

bash

btvar -v LOGVARS

Test logging:

bash

# Create test variable
btvar -c test_var 100

# Modify it
btvar -s test_var 200

# Delete it
btvar -d test_var

# Check log
tail /var/spool/xi/batch/varaudit.log

Should see entries for create, assign, and delete.

Troubleshooting

No variable changes logged : Verify LOGVARS is set. Check file/program permissions. Review scheduler log for errors.

Incomplete log entries : Ensure logging program processes entire line. Check for line buffering issues.

Missing job information in logs : Job number/title only present for job-driven changes. Manual changes won't have these fields.

Log file permissions errors : LOGVARS variable modes control log file access. Adjust variable permissions if needed.

Combining LOGJOBS and LOGVARS

Enable both for comprehensive auditing:

bash

# Enable job logging
btvar -s LOGJOBS jobaudit.log

# Enable variable logging
btvar -s LOGVARS varaudit.log

# Verify both active
btvar -v LOGJOBS LOGVARS

This creates complete audit trail of all scheduling activity and state changes.

Best Practices

Set appropriate permissions : Ensure LOGJOBS and LOGVARS variables have restrictive modes to protect log files

Implement rotation : Prevent disk space exhaustion with regular log rotation

Monitor log programs : Ensure logging programs don't block scheduler operations

Correlate logs : Use job numbers to link job events with variable changes

Archive logs : Retain logs for compliance requirements (90 days, 1 year, etc.)

Filter important events : When logging to programs, focus on significant changes to reduce noise

Test logging : Verify logging works after enabling by submitting test jobs and checking logs

Document log format : Ensure operations team understands log structure for troubleshooting