Tutorial

macOS provides a powerful unified logging system that captures detailed information about system processes, applications, and user activities. This tutorial shows how to effectively collect and analyze device logs across your Roundfleet for troubleshooting, security monitoring, and performance analysis.

Understanding macOS Logging

macOS uses the unified logging system introduced in macOS 10.12, which consolidates various log sources:

• System logs - Kernel, system services, and daemons
• Application logs - User applications and background processes
• Security logs - Authentication, authorization, and security events
• Network logs - Network activity and connectivity

Basic Log Commands

View Recent System Logs

#!/bin/bash

# Show logs from the last minute
sudo log show --last 1m

# Show logs from the last hour
sudo log show --last 1h

# Show logs from the last day
sudo log show --last 1d

Live Log Streaming

#!/bin/bash

# Stream live logs
sudo log stream

# Stream with timestamp
sudo log stream --info --debug

Application-Specific Logs

Get Logs for Specific Application

#!/bin/bash

# Basic app log query
log show --predicate 'processImagePath CONTAINS[c] "safari"'

# Query with time range
log show --predicate 'processImagePath CONTAINS[c] "Finder"' --last 30m

# Save app logs to file
log show --predicate 'processImagePath CONTAINS[c] "Mail"' --last 1h > ~/Desktop/mail_logs.txt

Enterprise Log Collection Script

#!/bin/bash

# Device Log Collection Script for Roundfleet
# Compatible with macOS 10.14+

# Configuration
LOG_DIR="/var/log/roundfleet_logs"
TIMESTAMP=$(date '+%Y%m%d_%H%M%S')
HOSTNAME=$(hostname -s)
OUTPUT_DIR="$LOG_DIR/${HOSTNAME}_${TIMESTAMP}"
ARCHIVE_NAME="${HOSTNAME}_logs_${TIMESTAMP}.tar.gz"

# Function to log messages
log_message() {
    echo "$(date '+%Y-%m-%d %H:%M:%S') - $1" | tee -a "$LOG_DIR/collection.log"
}

# Function to create output directory
setup_directories() {
    if mkdir -p "$OUTPUT_DIR"; then
        log_message "✓ Created output directory: $OUTPUT_DIR"
        return 0
    else
        log_message "✗ Failed to create output directory"
        return 1
    fi
}

# Function to collect system logs
collect_system_logs() {
    log_message "Collecting system logs..."
    
    # Recent system logs (last 24 hours)
    if log show --last 24h > "$OUTPUT_DIR/system_logs_24h.log"; then
        log_message "✓ System logs collected (24h)"
    else
        log_message "✗ Failed to collect system logs"
    fi
    
    # Critical and error logs only
    if log show --last 24h --predicate 'messageType == 16 OR messageType == 17' > "$OUTPUT_DIR/critical_errors.log"; then
        log_message "✓ Critical/Error logs collected"
    else
        log_message "✗ Failed to collect critical logs"
    fi
    
    # Boot logs
    if log show --predicate 'process == "kernel"' --last 7d > "$OUTPUT_DIR/kernel_logs.log"; then
        log_message "✓ Kernel logs collected"
    else
        log_message "✗ Failed to collect kernel logs"
    fi
}

# Function to collect application logs
collect_app_logs() {
    log_message "Collecting application logs..."
    
    # Common applications to monitor
    local apps=("Safari" "Finder" "Mail" "Calendar" "Contacts" "Notes" "Spotlight" "WindowServer")
    
    for app in "${apps[@]}"; do
        local output_file="$OUTPUT_DIR/${app,,}_logs.log"
        if log show --predicate "processImagePath CONTAINS[c] \"$app\"" --last 24h > "$output_file" 2>/dev/null; then
            # Only keep file if it has content
            if [[ -s "$output_file" ]]; then
                log_message "✓ $app logs collected"
            else
                rm -f "$output_file"
                log_message "! No logs found for $app"
            fi
        else
            log_message "✗ Failed to collect $app logs"
        fi
    done
}

# Function to collect security logs
collect_security_logs() {
    log_message "Collecting security logs..."
    
    # Authentication logs
    if log show --predicate 'category == "authorization" OR process == "authd"' --last 7d > "$OUTPUT_DIR/auth_logs.log"; then
        log_message "✓ Authentication logs collected"
    else
        log_message "✗ Failed to collect auth logs"
    fi
    
    # Login/logout events
    if log show --predicate 'eventMessage CONTAINS "login" OR eventMessage CONTAINS "logout"' --last 7d > "$OUTPUT_DIR/login_events.log"; then
        log_message "✓ Login events collected"
    else
        log_message "✗ Failed to collect login events"
    fi
}

# Function to collect system information
collect_system_info() {
    log_message "Collecting system information..."
    
    {
        echo "=== System Information ==="
        echo "Hostname: $(hostname)"
        echo "macOS Version: $(sw_vers -productVersion)"
        echo "Build: $(sw_vers -buildVersion)"
        echo "Uptime: $(uptime)"
        echo "Date: $(date)"
        echo ""
        
        echo "=== Hardware Information ==="
        system_profiler SPHardwareDataType
        echo ""
        
        echo "=== Disk Usage ==="
        df -h
        echo ""
        
        echo "=== Memory Usage ==="
        vm_stat
        echo ""
        
        echo "=== Running Processes ==="
        ps aux | head -20
        
    } > "$OUTPUT_DIR/system_info.txt"
    
    log_message "✓ System information collected"
}

# Function to create archive
create_archive() {
    log_message "Creating archive..."
    
    cd "$LOG_DIR" || return 1
    
    if tar -czf "$ARCHIVE_NAME" "$(basename "$OUTPUT_DIR")"; then
        log_message "✓ Archive created: $LOG_DIR/$ARCHIVE_NAME"
        
        # Clean up temporary directory
        rm -rf "$OUTPUT_DIR"
        log_message "✓ Temporary files cleaned up"
        
        # Show archive size
        local size
        size=$(du -h "$LOG_DIR/$ARCHIVE_NAME" | cut -f1)
        log_message "Archive size: $size"
        
        return 0
    else
        log_message "✗ Failed to create archive"
        return 1
    fi
}

# Function to upload archive (placeholder for enterprise integration)
upload_archive() {
    local archive_path="$LOG_DIR/$ARCHIVE_NAME"
    
    # Example: Upload to central logging server
    # Replace with your actual upload mechanism
    log_message "Archive ready for collection: $archive_path"
    
    # Placeholder for upload logic
    # scp "$archive_path" user@logserver:/logs/
    # curl -F "file=@$archive_path" https://logserver.company.com/upload
    
    return 0
}

# Main execution function
main() {
    log_message "=== Starting Roundfleet log collection ==="
    
    # Setup
    if ! setup_directories; then
        exit 1
    fi
    
    # Collect logs
    collect_system_logs
    collect_app_logs
    collect_security_logs
    collect_system_info
    
    # Create archive
    if create_archive; then
        upload_archive
        log_message "=== Log collection completed successfully ==="
        exit 0
    else
        log_message "=== Log collection failed ==="
        exit 1
    fi
}

# Execute main function
main "$@"

Quick Log Collection Scripts

Collect Logs for Specific Time Period

#!/bin/bash

# Collect logs between specific dates
START_DATE="2025-01-01"
END_DATE="2025-01-02"
OUTPUT_FILE="~/Desktop/logs_${START_DATE}_to_${END_DATE}.txt"

log show --start "$START_DATE" --end "$END_DATE" > "$OUTPUT_FILE"
echo "Logs saved to: $OUTPUT_FILE"

Collect Application Crash Logs

#!/bin/bash

# Collect crash reports
CRASH_DIR="~/Library/Logs/DiagnosticReports"
OUTPUT_DIR="~/Desktop/crash_logs"

mkdir -p "$OUTPUT_DIR"
find "$CRASH_DIR" -name "*.crash" -mtime -7 -exec cp {} "$OUTPUT_DIR/" \;

echo "Recent crash logs copied to: $OUTPUT_DIR"

Monitor Specific Events

#!/bin/bash

# Monitor USB device connections
log stream --predicate 'eventMessage CONTAINS "USB"' --info

# Monitor network changes
log stream --predicate 'subsystem == "com.apple.network"' --info

# Monitor file system events
log stream --predicate 'subsystem == "com.apple.filesystem"' --debug

Log Analysis Scripts

Parse Authentication Events

#!/bin/bash

# Extract failed login attempts
log show --predicate 'eventMessage CONTAINS "authentication failure"' --last 7d \
    | grep -E "(authentication failure|failed)" \
    | sort | uniq -c | sort -nr > ~/Desktop/failed_logins.txt

echo "Failed login analysis saved to ~/Desktop/failed_logins.txt"

Application Usage Statistics

#!/bin/bash

# Analyze application launches
log show --predicate 'process == "launchd" AND eventMessage CONTAINS "spawn"' --last 24h \
    | grep -oE '"[^"]*\.app"' \
    | sort | uniq -c | sort -nr > ~/Desktop/app_usage.txt

echo "Application usage statistics saved to ~/Desktop/app_usage.txt"

Log Archive Management

Create System Log Archive

#!/bin/bash

# Create complete system log archive
ARCHIVE_PATH="~/Desktop/SystemLogs_$(date +%Y%m%d_%H%M%S).logarchive"

log collect --output "$ARCHIVE_PATH" --last 24h

echo "System log archive created: $ARCHIVE_PATH"

View Archived Logs

#!/bin/bash

# View logs from archive
ARCHIVE_PATH="~/Desktop/SystemLogs.logarchive"

if [[ -f "$ARCHIVE_PATH" ]]; then
    log show --archive "$ARCHIVE_PATH" --last 1h
else
    echo "Archive not found: $ARCHIVE_PATH"
fi

Troubleshooting Common Issues

Log Filtering Examples

Filter by Log Level

# Error messages only
log show --predicate 'messageType == 16' --last 1h

# Info and debug messages
log show --predicate 'messageType >= 1' --last 30m

# Critical errors only
log show --predicate 'messageType == 17' --last 24h

Filter by Process

# System processes
log show --predicate 'process == "kernel" OR process == "launchd"' --last 1h

# User processes
log show --predicate 'processImagePath BEGINSWITH "/Applications"' --last 1h

# Background daemons
log show --predicate 'processImagePath CONTAINS "daemon"' --last 1h

Security Considerations

• Privacy - Be mindful of user data in logs
• Retention - Implement log rotation and cleanup
• Access Control - Restrict log access to authorized personnel
• Encryption - Encrypt log archives before transmission
• Compliance - Follow data retention policies

Performance Tips

• Use specific time ranges to limit data volume
• Filter by process or category to reduce noise
• Stream logs in real-time for immediate analysis
• Compress archives to save storage space
• Schedule regular log collection during off-hours

Important Notes

• System logs may contain sensitive information
• Large time ranges can generate massive log files
• Some logs require admin privileges to access
• Log collection can impact system performance
• Test scripts on individual devices before fleet deployment