Skip to content

Collector: per-app network usage (mobile, metered and unmetered Wi-Fi) from NetworkStatsManager #8

Open

Description

@groupsky

Why

A device on a metered link (a car head unit on a SIM or a phone hotspot, a tablet on a data plan) can quietly start using a lot of mobile data: a self-updating app, a log stream, maps. Android already counts bytes per app and per network, but you only see it if you look on the device. The agent should send it, so a dashboard can show mobile data per app per day and an alert can fire on a new big user.

Real case (2026-11-13): one head unit used about 2 GB of mobile data in a month. In the next weeks a log pull and an app's self-update doubled some apps' use, and nobody saw it until someone read dumpsys netstats by hand.

What to do

Add a collector app network usage:

  • Source: NetworkStatsManager.querySummary(...) for mobile and for Wi-Fi (public API). Each NetworkStats.Bucket gives uid, rxBytes, txBytes, start/end, and getMetered() (API 28+), so Wi-Fi splits into metered (hotspot, tethered phone) and unmetered.
  • Permission: Usage access (android.permission.PACKAGE_USAGE_STATS, an app-op). The app cannot ask for it with a dialog: document both ways to grant it, the Settings screen (Special app access → Usage access) and adb shell appops set <package> GET_USAGE_STATS allow. Without it, the collector reports itself as off (a status metric or log line), it does not crash and does not block the other collectors.
  • uid → app: PackageManager.getPackagesForUid(uid) (several packages can share a uid; join them). Also handle the special uids (UID_REMOVED, UID_TETHERING, root 0, system 1000) with fixed names.
  • Android keeps buckets of about 2 h. Send one point per bucket, with the bucket start as the time. Send a bucket only when it is complete (its end is in the past). Remember the last sent bucket so a restart does not send it twice.
  • Backfill: on first start, send history from a configurable date (default: 30 days back).
  • Do not count VPN traffic twice: query the real networks (mobile, Wi-Fi), not the VPN's.
  • Metric: a counter or a gauge per bucket, name per OpenTelemetry semantic conventions if one fits (check system.network.io and the network.io.direction attribute), else device.app.network.io. Attributes: app (package names), uid, network type (cellular, wifi), metered (true/false), direction (receive/transmit). Write the choice and the reason in the metrics reference.
  • Config: on/off, backfill start, the poll interval (default 1 h; the data only changes per 2 h bucket).
  • Data cost of the collector itself: a few hundred points per day. Measure it.

Done when

  • Unit tests: bucket → points mapping (metered split, VPN not counted, shared uid, special uids, open bucket not sent, restart sends nothing twice); a missing Usage access gives the "off" status, no crash.
  • Metrics reference lists the metric, its attributes, and the two ways to grant Usage access.
  • On an emulator with Usage access granted: points arrive at an OTLP receiver (VictoriaMetrics test container is fine), and a query for "bytes per app per day on metered networks" works (paste the query and output).
  • (Owner, real device) On a device with a SIM: the month total from the agent matches dumpsys netstats within 5 % (paste both).

Activity

  1. groupsky commented on Nov 13, 2026

    @groupsky
    ContributorAuthor

    Not queued yet: it waits for the MVP (#2, blocked-by link set), like #3 and #4. It is queued when #2 closes.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions