Skip to content
makambo13Public

About

See every network call your Mac, simulator and iPhone apps make, from Apple's unified log. No proxy needed.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

1 Commit

Folders and files

Repository files navigation

NetMon

See every network call your apps make, read straight from Apple's unified log. No proxy, no certificates, no code changes.

Swift macOS 14+ SwiftUI Tests


NetMon showing a list of network calls, with a failed DNS lookup selected and explained in the inspector

A failed call: the inspector shows which phase failed and what to check.



NetMon with a successful HTTP/3 call selected, showing its DNS, TLS, waiting and download times

A successful HTTP/3 call with its timing breakdown. Both screenshots use built-in sample data.

About

NetMon is a Mac app and command-line tool for debugging networking in Apple apps. It reads the logs that CFNetwork and Network.framework already write for every URLSession task, joins them per request, and shows what you need when something is slow or failing.

It works with any app on your Mac, apps in the iOS Simulator, and iPhones or iPads connected over USB. You don't need to add a library, install a certificate, or route traffic through a proxy.

Features

  • Live list of calls with app, host, status, protocol, total time, time to first byte and response size.
  • Timing breakdown for each call: DNS lookup, TCP connect, TLS handshake, waiting and download, with the failed phase marked.
  • Plain-English hints for HTTP errors and URL error codes such as -1003 cannotFindHost or -1001 timedOut.
  • Connection details: reuse, interface (Wi-Fi, cellular, wired), TLS version, HTTP/3, iCloud Private Relay and cache hits.
  • Filters for errors, 4xx, 5xx, slow calls and cellular, plus search by host or app.
  • A summary per app and host with call counts, error rate, p50 and p95.
  • Export what's on screen as JSON or CSV.

Getting started

You need macOS 14 and Xcode 15 or later (Swift 5.9+).

git clone https://github.com/makambo13/NetMon.git
cd NetMon
./scripts/make-app.sh
open build/NetMon.app

The script builds a release version and puts NetMon.app in build/. The bundle ID is com.example.netmon. Change it in scripts/make-app.sh if you want your own.

To try it without real traffic, launch it with sample data:

open -n --env NETMON_DEMO=1 build/NetMon.app

Using it

  1. Pick a source in the sidebar: this Mac, a running simulator, or a connected device.
  2. Use any app that makes network calls. Calls appear within a second, or about 3 seconds behind for a USB device.
  3. Click a call to see its timing, transfer size and connection in the inspector.

For a USB device, click Authorize the first time. macOS asks for an administrator password because log collect needs it. NetMon never sees or stores the password.

Command line

swift build -c release
.build/release/netmon --list                      # sources NetMon can read
.build/release/netmon --mac --errors              # failing calls on this Mac
.build/release/netmon --sim booted --slow 1000    # calls slower than 1 s in the booted simulator
.build/release/netmon --mac --csv calls.csv       # also write every call to a CSV file

How it works

CFNetwork logs a summary line when each URLSession task finishes, with its status, timings and byte counts. Network.framework logs when connections start, which interface they use, and the TLS version. Both are written at the default log level, so log stream can read them without extra setup. NetMon streams those lines as NDJSON, matches each task to its connection, and turns them into one record per request.

Diagram: this Mac, simulators and USB devices feed log lines into NetworkMonitor. The Correlator joins CFNetwork task summaries with Network.framework connections into RequestRecords, which the NetMon app and the netmon CLI display and export as JSON or CSV.

Tests

There are 32 unit tests. They run against a recorded log fixture, and one checks that the log tool accepts NetMon's predicate.

swift test

Limits and help

  • Apple hides hostnames in these logs by default, so some calls show a hash like #942fff27:443. To see names, install Apple's CFNetwork logging profile or set CFNETWORK_DIAGNOSTICS in your Xcode scheme.
  • Only URLSession and Network.framework traffic shows up. Tools that use their own networking, such as curl, don't appear.
  • The log doesn't include the HTTP method or URL path, so NetMon exports JSON and CSV but not HAR.
  • Reading a USB device can fail over Wi-Fi. Use a cable, unlock the device, and trust this Mac.

If something doesn't work, please open an issue on GitHub.

About

See every network call your Mac, simulator and iPhone apps make, from Apple's unified log. No proxy needed.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages