Dashboard GitHub

macOS System Log Integration

Collect macOS system logs via unified logging system with LogFlux Agent

macOS

The LogFlux macOS System Log integration captures logs from Apple’s unified logging system in real-time, enabling centralized log analysis from your macOS systems. This plugin provides comprehensive integration with macOS’s native logging infrastructure, supporting advanced filtering, subsystem monitoring, and rich metadata extraction.

Overview

The macOS System Log plugin provides:

  • Unified Logging Integration: Direct integration with macOS unified logging system (macOS 10.12+)
  • Real-Time Streaming: Live system log monitoring with structured JSON processing
  • Advanced Filtering: Filter by subsystem, category, process, log level, and custom predicates
  • Rich Metadata: Extract comprehensive macOS-specific metadata (subsystem, process, activity)
  • Performance Optimization: Batch processing and configurable flush intervals
  • Security Focus: Safe command execution with argument validation and injection prevention
  • Native macOS Integration: Uses macOS log stream command for authentic system log access
  • NSPredicate Support: Complex filtering using native macOS predicate syntax

Installation

The macOS System Log plugin is included with the LogFlux Agent for macOS but disabled by default.

Prerequisites

  • LogFlux Agent installed on macOS system (see Installation Guide)
  • macOS 10.12 (Sierra) or later (unified logging system requirement)
  • Access to macOS log command (part of system tools)
  • Appropriate permissions to read system logs
  • Network connectivity to LogFlux Agent socket

Enable the Plugin

1
2
3
4
5
6

# Enable and start the macOS System Log plugin
sudo launchctl enable system/com.logflux.agent.oslog
sudo launchctl kickstart system/com.logflux.agent.oslog

# Check status
sudo launchctl print system/com.logflux.agent.oslog

Configuration

Basic Configuration

Create or edit the macOS System Log plugin configuration:

1

sudo nano /usr/local/etc/logflux-agent/plugins/oslog.yaml

Basic configuration:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

# macOS System Log Plugin Configuration
name: oslog
version: 1.0.0
source: oslog-plugin

# Agent connection
agent:
  socket_path: /tmp/logflux-agent.sock

# Log filtering
filters:
  # Log levels: debug, info, default, error, fault
  levels:
    - "error"
    - "fault"
    - "default"
  
  # Time window
  since: "30 minutes ago"
  
  # Process filtering
  processes:
    include: []
    exclude:
      - "mdworker"      # Spotlight indexing
      - "mds"           # Metadata server
      - "com.apple.TimeSync"

# Metadata and labeling
metadata:
  labels:
    plugin: oslog
    os: macos
  
  # Include macOS metadata
  include_metadata: true

# Batching for efficiency
batch:
  enabled: true
  size: 100
  flush_interval: 5s

Advanced Configuration

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126

# Advanced macOS System Log Configuration
name: oslog
version: 1.0.0
source: oslog-plugin

# Enhanced agent settings
agent:
  socket_path: /tmp/logflux-agent.sock
  connect_timeout: 30s
  max_retries: 5
  retry_delay: 10s

# Comprehensive filtering
filters:
  # Log level filtering
  levels:
    - "fault"         # Critical system errors
    - "error"         # Application errors
    - "default"       # Important notices
    - "info"          # Informational messages
    # - "debug"       # Uncomment for verbose debugging
  
  # Time-based filtering
  since: "1 hour ago"
  
  # Subsystem filtering (Apple's app organization)
  subsystems:
    include:
      - "com.apple.SecurityServer"
      - "com.apple.loginwindow"
      - "com.apple.Mail"
      - "com.apple.Safari"
      - "com.apple.networkd"
    exclude:
      - "com.apple.Spotlight"
      - "com.apple.TimeMachine"
  
  # Category filtering
  categories:
    include:
      - "security"
      - "network"
      - "authentication"
    exclude:
      - "spotlight"
      - "indexing"
  
  # Process filtering
  processes:
    include:
      - "Safari"
      - "Mail"
      - "loginwindow"
      - "SecurityServer"
    exclude:
      - "mdworker"
      - "mds"
      - "mds_stores"
      - "com.apple.metadata.mds"
      - "com.apple.Spotlight"
  
  # NSPredicate for complex filtering
  predicate: 'subsystem == "com.apple.SecurityServer" AND messageType >= 16'
  
  # Content filtering
  content_patterns:
    include:
      - "Authentication"
      - "Network"
      - "Security"
    exclude:
      - "routine"
      - "periodic"

# Performance optimization
performance:
  # Batch processing
  batch_size: 200
  flush_interval: 10s
  
  # Memory limits
  max_memory: "128MB"
  buffer_size: "1MB"
  queue_size: 5000
  
  # Message limits
  max_message_size: "64KB"
  min_message_size: 10

# Enhanced metadata
metadata:
  verbose: true
  labels:
    plugin: oslog
    os: macos
    environment: production
    datacenter: local
  
  # macOS-specific metadata
  include_metadata: true
  metadata_prefix: "macos_"
  
  # Custom field mapping
  field_mapping:
    subsystem: "macos_subsystem"
    category: "macos_category"
    process_name: "macos_process"
    process_id: "macos_pid"
    thread_id: "macos_tid"
    activity_id: "macos_activity"

# Resource limits
limits:
  max_goroutines: 20
  memory_limit: "256MB"
  cpu_limit: "1"
  
  # Rate limiting
  max_messages_per_second: 2000

# Health monitoring
health:
  check_interval: 60s
  max_parse_errors: 100
  alert_on_command_failure: true
  stats_collection: true

Usage Examples

System Administration

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# Monitor system errors and faults
logflux-agent-oslog -level error,fault

# Monitor specific subsystem
logflux-agent-oslog -subsystem com.apple.SecurityServer

# Monitor authentication events
logflux-agent-oslog -category authentication -since "1 hour ago"

# Monitor specific process
logflux-agent-oslog -process Safari -level error

Security Monitoring

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

# Security event monitoring
filters:
  levels:
    - "fault"
    - "error"
    - "default"
  
  subsystems:
    include:
      - "com.apple.SecurityServer"
      - "com.apple.authd"
      - "com.apple.opendirectoryd"
      - "com.apple.loginwindow"
  
  categories:
    include:
      - "security"
      - "authentication"
      - "authorization"
  
  predicate: 'category == "security" OR subsystem BEGINSWITH "com.apple.Security"'

metadata:
  labels:
    log_type: security
    monitoring: critical
    compliance: required

Application Monitoring

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

# Application-focused monitoring
filters:
  processes:
    include:
      - "Safari"
      - "Mail"
      - "Calendar"
      - "Messages"
      - "Finder"
  
  levels:
    - "error"
    - "fault"
    - "default"
  
  content_patterns:
    include:
      - "crash"
      - "exception"
      - "error"
      - "failed"

metadata:
  labels:
    monitoring_type: applications
    focus: user_applications

Network Monitoring

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

# Network and connectivity monitoring
filters:
  subsystems:
    include:
      - "com.apple.networkd"
      - "com.apple.WiFiAgent"
      - "com.apple.airport.wps"
      - "com.apple.networkserviceproxy"
  
  categories:
    include:
      - "network"
      - "wifi"
      - "ethernet"
  
  levels:
    - "error"
    - "fault"
    - "default"

metadata:
  labels:
    service: networking
    monitoring: connectivity

Command Line Usage

Basic Commands

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

# Monitor all system logs
logflux-agent-oslog

# Filter by log level
logflux-agent-oslog -level error,fault

# Filter by subsystem
logflux-agent-oslog -subsystem com.apple.Mail

# Filter by process
logflux-agent-oslog -process Safari

# Time-based filtering
logflux-agent-oslog -since "30 minutes ago"

Advanced Options

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

# Multiple filters combined
logflux-agent-oslog \
  -subsystem com.apple.SecurityServer \
  -level error,fault \
  -since "1 hour ago"

# Custom batch settings
logflux-agent-oslog \
  -batch-size 200 \
  -flush-interval 10s

# Disable batching for real-time
logflux-agent-oslog -no-batch

# Verbose output with statistics
logflux-agent-oslog -verbose

# Configuration file
logflux-agent-oslog -config /usr/local/etc/logflux-agent/plugins/oslog.yaml

Log Level Reference

macOS Log Levels

macOS Level SDK Level Description
fault Critical System unusable, critical failures
error Error Error conditions, recoverable problems
default Notice Significant but normal events
info Info Informational messages
debug Debug Debug-level messages, verbose output

Common Subsystems

Subsystem Description Typical Events
com.apple.SecurityServer Security and keychain Authentication, certificate validation
com.apple.loginwindow Login process User login/logout events
com.apple.authd Authentication daemon Authorization requests
com.apple.opendirectoryd Directory services LDAP, Active Directory integration
com.apple.networkd Network services Network configuration changes
com.apple.WiFiAgent WiFi management WiFi connection events
com.apple.Mail Mail application Email processing events
com.apple.Safari Safari browser Web browsing events

Metadata and Output Format

Metadata Fields

The plugin adds macOS-specific metadata:

Field Description Example
source_type Always “plugin” plugin
source_name Always “oslog” oslog
macos_subsystem macOS subsystem identifier com.apple.SecurityServer
macos_category Log category security
macos_process Process name SecurityServer
macos_pid Process ID 245
macos_tid Thread ID 0x1a3
macos_activity Activity identifier 0x12345
macos_trace_id Trace identifier 0x67890
macos_machine_id Machine UUID 12345678-1234-1234-1234-123456789012
macos_sender_image Binary path /System/Library/Frameworks/Security.framework/Versions/A/Security

LogFlux Output Format

Input macOS Log Entry:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

{
  "subsystem": "com.apple.SecurityServer",
  "category": "security",
  "processName": "SecurityServer",
  "processID": 245,
  "threadID": 419,
  "timestamp": "2024-01-20 14:30:50.123456-0800",
  "messageType": "Error",
  "eventMessage": "Authentication failed for user admin",
  "activityIdentifier": 74565,
  "traceID": 429496729600
}

Output LogFlux Log:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

{
  "timestamp": "2024-01-20T22:30:50.123Z",
  "level": "error",
  "message": "Authentication failed for user admin",
  "node": "MacBook-Pro.local",
  "metadata": {
    "source_type": "plugin",
    "source_name": "oslog",
    "macos_subsystem": "com.apple.SecurityServer",
    "macos_category": "security",
    "macos_process": "SecurityServer",
    "macos_pid": 245,
    "macos_tid": 419,
    "macos_activity": 74565,
    "macos_trace_id": 429496729600,
    "plugin": "oslog",
    "os": "macos"
  }
}

NSPredicate Filtering

Basic Predicates

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# Subsystem filtering
predicate: 'subsystem == "com.apple.SecurityServer"'

# Level-based filtering (16=error, 17=fault)
predicate: 'messageType >= 16'

# Process filtering
predicate: 'processName == "Safari"'

# Category filtering
predicate: 'category == "security"'

Advanced Predicates

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# Multiple conditions
predicate: 'subsystem == "com.apple.SecurityServer" AND messageType >= 16'

# Pattern matching
predicate: 'subsystem BEGINSWITH "com.apple.Security"'

# Content filtering
predicate: 'eventMessage CONTAINS "failed"'

# Time-based (with since parameter)
predicate: 'subsystem == "com.apple.networkd" AND category == "wifi"'

Predicate Operators

Operator Description Example
== Equality subsystem == "com.apple.Mail"
!= Inequality processName != "mdworker"
>, >=, <, <= Comparison messageType >= 16
BEGINSWITH String prefix subsystem BEGINSWITH "com.apple.Security"
ENDSWITH String suffix processName ENDSWITH "d"
CONTAINS String contains eventMessage CONTAINS "error"
AND, OR Logical operators level >= 16 AND subsystem == "com.apple.Mail"
NOT Negation NOT (processName == "mdworker")

Performance Optimization

High-Volume Configuration

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

# High-throughput settings
filters:
  levels: ["error", "fault"]  # Limit to important events
  since: "10 minutes ago"     # Shorter time window

performance:
  batch_size: 500
  flush_interval: 30s
  max_memory: "512MB"
  queue_size: 10000

# Focus on specific subsystems
filters:
  subsystems:
    include:
      - "com.apple.SecurityServer"
      - "com.apple.loginwindow"

Low-Resource Configuration

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# Resource-constrained settings
performance:
  batch_size: 50
  flush_interval: 60s
  max_memory: "64MB"
  queue_size: 1000
  max_message_size: "16KB"

filters:
  levels: ["fault", "error"]  # Only critical events
  since: "5 minutes ago"      # Very recent events only

Real-Time Configuration

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# Low-latency settings
performance:
  batch_size: 10
  flush_interval: 1s
  
batch:
  enabled: false  # Disable batching for immediate delivery

filters:
  levels: ["fault"]  # Only most critical events

Security Considerations

Command Injection Prevention

The plugin includes built-in security measures:

  • Argument validation: Only safe command arguments allowed
  • Character filtering: Blocks dangerous shell characters (;, |, &)
  • Predicate sanitization: Safe NSPredicate construction
  • Command isolation: Executes log stream in controlled environment

Permissions and Access

1
2
3
4
5
6
7
8

# Check system log access
log show --last 1m --info >/dev/null 2>&1 && echo "Access granted" || echo "Access denied"

# Grant full disk access if needed (System Preferences > Security & Privacy)
# Required for comprehensive system log access

# Verify log command availability
which log && log help stream

Monitoring and Alerting

Plugin Health Monitoring

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

#!/bin/bash
# check-oslog-plugin.sh

if ! launchctl print system/com.logflux.agent.oslog | grep -q "state = running"; then
    echo "CRITICAL: LogFlux macOS System Log plugin is not running"
    exit 2
fi

# Check log command access
if ! log show --last 1m --quiet >/dev/null 2>&1; then
    echo "CRITICAL: Cannot access system logs"
    exit 2
fi

# Check recent log processing
if ! log show --predicate 'subsystem == "com.logflux.agent"' --last 10m | grep -q "oslog"; then
    echo "WARNING: No recent log processing detected"
    exit 1
fi

echo "OK: LogFlux macOS System Log plugin is healthy"
exit 0

Performance Monitoring

1
2
3
4
5
6
7
8

# Monitor plugin resource usage
ps aux | grep logflux-agent-oslog

# Monitor log stream performance  
log show --style compact --last 1m | wc -l

# Check system log size
log show --info --last 1h | wc -l

Common Use Cases

Developer Workstation Monitoring

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

# Development environment monitoring
filters:
  processes:
    include:
      - "Xcode"
      - "xcodebuild"
      - "clang"
      - "swift"
      - "iOS Simulator"
  
  levels:
    - "error"
    - "fault"
    - "default"

metadata:
  labels:
    environment: development
    monitoring: xcode

Server Monitoring

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

# macOS Server monitoring
filters:
  subsystems:
    include:
      - "com.apple.server"
      - "com.apple.serverd"
      - "com.apple.SecurityServer"
      - "com.apple.networkd"
  
  levels:
    - "fault"
    - "error"
    - "default"

metadata:
  labels:
    server_role: macos_server
    monitoring: infrastructure

Security Audit

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

# Comprehensive security monitoring
filters:
  subsystems:
    include:
      - "com.apple.SecurityServer"
      - "com.apple.authd"
      - "com.apple.opendirectoryd"
      - "com.apple.loginwindow"
  
  categories:
    include:
      - "security"
      - "authentication"
      - "authorization"
  
  predicate: 'category == "security" OR eventMessage CONTAINS "Authentication"'

metadata:
  labels:
    log_type: security_audit
    compliance: required
    retention: long_term

Troubleshooting

Common Issues

Plugin Won’t Start:

1
2
3
4
5
6
7
8

# Check launchd configuration
sudo launchctl print system/com.logflux.agent.oslog

# Verify plugin binary
ls -la /usr/local/bin/logflux-agent-oslog

# Check permissions
sudo launchctl enable system/com.logflux.agent.oslog

No Logs Appearing:

1
2
3
4
5
6
7
8

# Test log command access
log show --last 1m --info

# Check system log permissions
log stream --level info --timeout 5s

# Verify predicate syntax
log stream --predicate 'subsystem == "com.apple.SecurityServer"' --timeout 5s

High CPU Usage:

1
2
3
4
5
6
7
8

# Reduce processing load
filters:
  levels: ["error", "fault"]  # Fewer log levels
  since: "5 minutes ago"      # Shorter time window

performance:
  batch_size: 200
  flush_interval: 30s

Memory Issues:

1
2
3
4
5
6
7
8

# Limit memory usage
performance:
  max_memory: "128MB"
  max_message_size: "32KB"
  queue_size: 2000

limits:
  memory_limit: "256MB"

Debugging

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

# Enable verbose logging
export LOGFLUX_LOG_LEVEL=debug
logflux-agent-oslog -verbose

# Test configuration
logflux-agent-oslog -config /usr/local/etc/logflux-agent/plugins/oslog.yaml -verbose

# Monitor plugin logs
log stream --predicate 'subsystem == "com.logflux.agent"' --level debug

# Test specific filters
log stream --subsystem com.apple.SecurityServer --level error --timeout 10s

Best Practices

Configuration Management

  1. Start with restrictive filtering to avoid log overflow
  2. Use subsystem filtering to focus on relevant applications
  3. Configure appropriate batch sizes based on log volume
  4. Monitor resource usage regularly

Security

  1. Grant minimal necessary permissions for log access
  2. Use Full Disk Access only when required for comprehensive monitoring
  3. Filter sensitive subsystems appropriately for compliance
  4. Regularly review access logs for security events

Performance

  1. Use level filtering to reduce processing overhead
  2. Limit time windows with since parameter
  3. Batch events appropriately for your throughput requirements
  4. Monitor memory usage and adjust limits as needed

Operational

  1. Test predicate syntax before deploying to production
  2. Monitor plugin health with automated checks
  3. Set up alerting for critical system events
  4. Document custom predicates and filtering rules

Disclaimer

macOS and the macOS logo are trademarks of Apple Inc. LogFlux is not affiliated with, endorsed by, or sponsored by Apple Inc. The macOS logo is used solely for identification purposes to indicate compatibility with macOS unified logging system.

Next Steps