Skip to content

Latest commit

 

History

History
136 lines (102 loc) · 6.37 KB

README.md

File metadata and controls

136 lines (102 loc) · 6.37 KB
Raw

Wi-Fi Telemetry

This project provides a Wi-Fi telemetry library and daemon. It enables realtime collection and reporting of Wi-Fi related events. It can be used in conjunction with the the wifi-ztp project to analyze and collect Wi-Fi zero touch provisioning telemetry as well.

Building

Ubuntu (focal)

sudo apt install build-essential cmake git liblttng-ust-dev libpci-dev libssl-dev libsystemd-dev pkg-config

Checkout and build:

git clone [email protected]:microsoft/wifi-telemetry.git
cd wifi-telemetry
mkdir build && cd $_
cmake ..
make -j $(nproc)

Usage

The central concept is that of a telemetry monitor, represented as WifiTelemetryMonitor. A monitor passively tracks one or more Wi-Fi telemetry sources, represented as WifiTelemetrySource, each of which is optionally bound to a device interface (eg. wlan0) and Wi-Fi operational mode, either station or access-point. Event information is aggregated and translated to lttng events. All telemetry is local and never leaves the device.

The daemon accepts a series of flag tuples for each telemetry source:

Flag Presence Description Supported Values Examples
-s Required telemetry source identifier wpa, ztp -s wpa
-i Optional Wi-Fi device interface name Any valid Wi-Fi device name -i wlan0, -i wl01s9
-o Optional Wi-Fi operational mode sta, station, ap, access-point -o station, -o ap

Telemetry Sources

Wi-Fi Protected Access (WPA) Supplicant (wpa)

This source passively monitors basic Wi-Fi connectivity and Device Provisioning Protocol (DPP aka Wi-Fi EasyConnect) events originating from a wpa_supplicant control socket.

Zero Touch Provisioning Daemon (ztp)

This source passively monitors zero touch provisioning daemon (ztpd) events originating from the ztpd d-bus inteface. Some events are not bound to a specific interface.

lttng Providers and Tracepoints

Provider Tracepoint Source Description
wifi device_info wpa Interface, model, driver, subsystem and vendor info.
wifi-station connection-attempt wpa Result, bssid, signal, frequency, security, status.
wifi-station connection-drop wpa Reason, bssid, locally generated.
wifi-dpp dpp_exchange_enrollee wpa State, role, duration, failure details, frequencies.
wifi-dpp dpp_exchange_configurator wpa State, role, duration, failure details, frequency.
wifi-dpp dpp_device_roles_changed ztp Device role(s) changed.

Examples

Monitor basic Wi-Fi client connectivity on wlan0

$ wifi-telemetryd -s wpa -i wlan0 -o sta
activated telemetry source 'wpa'
telemetry monitor started with 1 of 1 telemetry sources

Monitor basic wifi-client connectivity and ztp events on wlan1

$ wifi-telemetryd -s wpa -i wlan1 -o station -s ztp
activated telemetry source 'wpa'
activated telemetry source 'ztpd'
telemetry monitor started with 2 of 2 telemetry sources

Monitor Wi-Fi client connectivity with systemd instantiated service unit on arbitrary interface (%i)

[email protected]:

[Unit]
Description=Wi-Fi Telemetry Daemon (WPA Station)
Requires=sys-subsystem-net-devices-%i.device
After=sys-subsystem-net-devices-%i.device

[Service]
Type=simple
Restart=on-failure
ExecStart=/usr/sbin/wifi-telemetryd -s wpa -o station -i %i

View all Wi-Fi telemetry in real-time with lttng

$ lttng create --live
Live session auto-20210610-220234 created.
Traces will be output to tcp4://127.0.0.1:5342/ [data: 5343]
Live timer interval set to 1000000 us
$ lttng enable-event -u "wifi:* wifi_station:* wifi_dpp:*"
UST event wifi:* wifi_station:* wifi_dpp:* created in channel channel0
$ lttng start
Tracing started for session auto-20210610-220234
$ lttng view
Trace directory: net://localhost/host/apd-d8c0a65935ed/auto-20210610-220234$ lttng create --live
<Wi-Fi tracepoint events...>

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.