Troubleshooting

Log Files

Log file locations, rotation, and configuration

Network Weather maintains local log files on each client for troubleshooting and diagnostics. This guide covers log locations, file formats, rotation policies, and configuration options.

Log File Locations

macOS

Log files are stored in:

~/Library/Logs/NetworkWeather/

Files:

  • nwx_debug_YYYY-MM-DDTHH-MM-SS-MMMZ.log — Timestamped log file for each session
  • latest.log — Symbolic link to the current active log file

macOS also writes to the unified logging system (os.log), viewable via Console.app or:

log stream --predicate 'subsystem == "com.networkweather.NWX"' --level debug

Windows

Log files are stored in:

%LOCALAPPDATA%\NetworkWeather\Logs\

This typically resolves to:

C:\Users\<username>\AppData\Local\NetworkWeather\Logs\

Files:

  • nwxwin_YYYYMMDD_HHMMSS.log — Timestamped log file

Observation Data Archives

In addition to human-readable logs, Network Weather maintains JSONL (JSON Lines) archives of network measurements for historical analysis.

macOS

Observation archives are stored alongside logs:

~/Library/Logs/NetworkWeather/

Files:

  • ping_samples.jsonl — Current ping measurement archive
  • ping_samples_<timestamp>.jsonl — Rotated archives
  • burst_events.jsonl — Network impairment events

Rotation:

  • Archives rotate when they reach 10 MB
  • Rotated files are retained for 7 days, then automatically deleted

Windows

Observation archives are stored in a separate data directory:

%LOCALAPPDATA%\NetworkWeather\Data\

Files:

  • ping_samples_YYYYMMDD.jsonl — Daily ping measurement archive

Rotation:

  • New file created each day
  • Maximum file size: 100 MB

JSONL Format

Each line is a self-contained JSON object:

{"ts":"2025-01-15T10:30:45.123Z","hop":"192.168.1.1","ttl":1,"rtt":2.5}
{"ts":"2025-01-15T10:30:45.234Z","hop":"10.0.0.1","ttl":2,"rtt":15.3}
{"ts":"2025-01-15T10:30:45.345Z","hop":"172.16.0.1","ttl":3,"timeout":true}
Field Description
ts ISO 8601 UTC timestamp
hop IP address of the network hop
ttl Time-to-live (hop distance from client)
rtt Round-trip time in milliseconds
timeout Present and true if packet was lost
net Network context hash (macOS only)

Log File Format

Both platforms use a similar human-readable format:

[2025-01-15T10:30:45.123Z] [INFO] [PathMonitor.swift:42] Network path changed
[2025-01-15T10:30:45.456Z] [DEBUG] [WiFiMonitor.swift:128] RSSI: -52 dBm, noise: -95 dBm
[2025-01-15T10:30:46.789Z] [WARN] [HopPingMonitor.swift:95] Gateway timeout after 2000ms

Format: [timestamp] [level] [location] message [metadata]

Field Description
timestamp ISO 8601 UTC timestamp with milliseconds
level Log severity: TRACE, DEBUG, INFO, NOTICE, WARN, ERROR, CRITICAL
location Source file and line number (debug builds) or file only (release)
message Human-readable log message
metadata Optional key-value pairs with additional context

Encoding: UTF-8 (Windows includes BOM for compatibility)

Log Rotation

macOS

The macOS client creates a new log file each time the application launches. There is no size-based rotation.

  • Trigger: Application launch
  • Retention: Log files are not automatically deleted

Windows

The Windows client rotates logs based on file size.

Setting Value
Maximum file size 10 MB
Maximum log files 5
Rotation trigger Current file exceeds 10 MB

When rotation occurs:

  1. Current log file is closed
  2. A new timestamped log file is created
  3. If more than 5 log files exist, the oldest is deleted

Example Log Contents

Application Startup

[2025-01-15T08:00:01.123Z] [INFO] Logging initialized {"telemetry": "enabled"}
[2025-01-15T08:00:01.234Z] [INFO] Network Weather starting {"version": "1.1.7", "os": "macOS 15.2"}
[2025-01-15T08:00:01.456Z] [INFO] C2 check-in successful {"interval": "3600s"}

Network Monitoring

[2025-01-15T08:00:02.789Z] [INFO] WiFi connected {"ssid": "[SSID:8chars]", "bssid": "AA:BB:CC:xx:xx:xx"}
[2025-01-15T08:00:03.012Z] [DEBUG] Gateway discovered {"ip": "192.168.1.xxx", "vendor": "NETGEAR"}
[2025-01-15T08:00:03.234Z] [INFO] Traceroute complete {"hops": 12, "destination": "api.networkweather.com"}

Connectivity Issues

[2025-01-15T08:05:45.678Z] [WARN] High latency to gateway {"latency_ms": 450, "threshold_ms": 100}
[2025-01-15T08:05:46.890Z] [ERROR] DNS resolution failed {"query": "api.networkweather.com", "error": "timeout"}
[2025-01-15T08:05:47.123Z] [WARN] C2 check-in failed {"status": 503, "retry_after": "60s"}

Log Level Configuration

macOS

Configure the log level in ~/.nwx/config.json:

{
  "logLevel": "debug"
}

Available levels (least to most verbose):

  • critical — Fatal errors only
  • error — Errors and critical
  • warning — Warnings and above
  • notice — Notable events and above
  • info — General information (default for release builds)
  • debug — Detailed debugging
  • trace — Maximum verbosity (default for debug builds)

Windows

Log level configuration via config file is not yet available on Windows. The default level is Info.

Planned: Windows will support the same config.json format in a future release.

Accessing Logs for Troubleshooting

macOS

# View latest log
cat ~/Library/Logs/NetworkWeather/latest.log

# Follow log in real-time
tail -f ~/Library/Logs/NetworkWeather/latest.log

# Search for errors
grep -i error ~/Library/Logs/NetworkWeather/*.log

# View via Console.app (includes system events)
log show --predicate 'subsystem == "com.networkweather.NWX"' --last 1h

Windows

# View latest log (PowerShell)
Get-Content "$env:LOCALAPPDATA\NetworkWeather\Logs\*.log" | Select-Object -Last 100

# Find the most recent log file
Get-ChildItem "$env:LOCALAPPDATA\NetworkWeather\Logs" | Sort-Object LastWriteTime -Descending | Select-Object -First 1

# Search for errors
Select-String -Path "$env:LOCALAPPDATA\NetworkWeather\Logs\*.log" -Pattern "ERROR"

Collecting Logs for Support

When contacting support, include the most recent log files:

macOS:

zip ~/Desktop/nwx-logs.zip ~/Library/Logs/NetworkWeather/*.log

Windows:

Compress-Archive -Path "$env:LOCALAPPDATA\NetworkWeather\Logs\*.log" -DestinationPath "$env:USERPROFILE\Desktop\nwx-logs.zip"

Privacy and Local Data

Log files stored on the device contain network diagnostic information including IP addresses, MAC addresses, and network identifiers. This data remains local to the device unless you explicitly share log files with support.

Note: Automatic log upload to Network Weather servers is not currently implemented.

FAQ

Can I disable logging to disk entirely?

Not yet. Local logging cannot currently be disabled. This feature is planned for a future release.

As a workaround, you can periodically delete log files or use a cleanup script:

# macOS - delete logs older than 7 days
find ~/Library/Logs/NetworkWeather -name "*.log" -mtime +7 -delete

Can I send logs to a syslog server?

Not yet. Syslog forwarding is planned for enterprise deployments. Currently, logs are written to local files and uploaded to Network Weather servers (with PII redaction).

If you need syslog integration, please contact support@networkweather.com to discuss your requirements.

Can I customize the log format?

Not yet. The log format is fixed to ensure consistency for automated analysis. Custom formats (JSON, CEF, etc.) are planned for enterprise deployments.

Are logs sent to Network Weather automatically?

No. Log files remain local to your device. They are not automatically uploaded to Network Weather servers. You may be asked to share log files when contacting support.

How much disk space do logs use?

Disk usage varies based on log level and activity. See the rotation settings above for maximum file sizes:

  • macOS: New file each session, no automatic cleanup
  • Windows: 10 MB per file, maximum 5 files

Can I increase the log retention on Windows?

Not yet. The 5-file rotation limit is hardcoded. Configurable retention is planned.

Where can I find crash logs?

Crash reports are handled separately from application logs:

macOS:

  • ~/Library/Logs/DiagnosticReports/ — User crash reports
  • Console.app → Crash Reports

Windows:

  • Event Viewer → Windows Logs → Application
  • %LOCALAPPDATA%\CrashDumps\ (if Windows Error Reporting is enabled)

Related Documentation