Skip to content

MVP: battery, power, boot, network, device and thermal collectors; local config; OTLP export with disk buffer #2

Closed

Description

@groupsky

Depends on the spike (#1, done 2026-11-12). Its report is docs/spike.md; the decisions it made for this issue are in "From the spike" below.

Goal

The first usable version: collect device health, keep it on disk while offline, send it over OTLP. Settings come from built-in defaults and a local config file.

From the spike (#1)

  • Buffer: our own file queue, not the library's disk buffering. opentelemetry-android's disk buffering keeps metrics over a network cut, but loses what it has not sent when the app restarts during the cut. Use the spike's OwnQueue.kt (spike/): the SDK's periodic reader exports into a folder of files, one OTLP/HTTP protobuf body per file; a sender posts them in order and deletes a file only after a 2xx answer. Add a size cap and a max age (drop the oldest file first).
  • Service model: one foreground service with a timer. The foreground service lived 24 h, but a Handler tick without a wake lock came late, 2–3 min apart, on battery with the screen off. On the charger every tick came on time. Whether the timer wakes the CPU is a setting: wake_policy (see Config). Store the wall-clock time of each reading, so gaps show. WorkManager stays out (15 min minimum).
  • Versions. Pin the OpenTelemetry core artifacts to the version opentelemetry-android is built on (enforcedPlatform); mixed versions crashed at start in the spike.
  • Resource. Drop app.installation.id (random per install: private, and a new series on each reinstall), or make it optional and off by default.
  • Units. VictoriaMetrics drops OTLP units and keeps names with dots as they are. The README keeps a table of each metric's name, type and unit.
  • OpAMP works on Android over WebSocket; it is for Remote config: Android managed configurations and OpAMP #3, not this issue.

Collectors

Each collector can be turned on or off and has its own interval (default 60 s).

Collector Values Source
battery level %, voltage mV, temperature °C, current mA, charge counter µAh, status, plug type (ac/usb/wireless/dock/none), health, cycle count (Android 14+) ACTION_BATTERY_CHANGED, BatteryManager
power screen on/off, power-save mode, idle (doze) mode PowerManager
boot uptime s, boot count; a log record on each boot SystemClock, BOOT_COMPLETED, Settings.Global.BOOT_COUNT
network Wi-Fi RSSI dBm, link speed, connected; transport (Wi-Fi / cell / VPN) WifiManager, ConnectivityManager (no SSID/BSSID: they need location permission)
device free and total RAM, low-memory flag, free and total storage on /data ActivityManager.MemoryInfo, StatFs
thermal thermal status, headroom PowerManager, or the opentelemetry-android thermal module

Names follow OpenTelemetry semantic conventions where they exist (hw.battery.*, system.memory.*, system.filesystem.*), else device.* (for example device.battery.voltage, because hw.battery.* has no voltage). Resource attributes: device.id (from config), device.model.identifier, os.version, service.name, service.version, plus free-form attributes from config.

Config

One JSON document; the same shape is used later for managed configurations and OpAMP (#3):

  • exporter: endpoint, protocol (http/protobuf), headers, timeout
  • resource: device.id and extra attributes
  • collectors: per collector enabled, interval, options
  • buffer: max disk size, max age (oldest dropped first)
  • wake_policy: never | when_charging | always. Default when_charging (Geno's decision, 2026-11-12).
    • when_charging: on the charger the timer wakes the CPU for each reading (exact alarm with setExactAndAllowWhileIdle, or a short wake lock). On battery it does not wake the CPU, and readings may come late.
    • always: wakes the CPU on battery too. Readings on time, more battery use.
    • never: never wakes the CPU.
    • The key is in the local config now, and in managed configurations and OpAMP in Remote config: Android managed configurations and OpAMP #3.

Sources in this issue: defaults, and a local file imported by the share sheet, a QR code, or adb shell am broadcast with the JSON (for scripted setup). The app shows the config in use and where each value came from.

App screens

  • Status: last export time and result, buffer size, each collector's last value, time of the last reading.
  • Setup checklist, with buttons that open each Android screen where one exists:
    • notification permission;
    • battery optimisation off;
    • "Alarms & reminders" (exact alarms) allowed, on Android 14+, when wake_policy is not never;
    • OnePlus / OPPO (OxygenOS, ColorOS): App info → Battery → Allow background activity. Without it the spike's app was frozen 2 min after start, even with a foreground service; the Doze allow-list did not help;
    • Xiaomi (HyperOS / MIUI): Autostart on, and battery saver No restrictions;
    • a VPN with per-app split tunneling: include this app, or the receiver may not be reachable (the queue keeps the data meanwhile).

Done when

  • All six collectors send to an OTLP receiver; a query result for each is in the PR.
  • The own file queue: a 30 min network cut loses no samples, and neither does an app restart during a cut (queries in the PR).
  • The queue's size cap and max age work (unit test).
  • Turning a collector off in the config stops its metrics within one interval.
  • wake_policy exists with the three values. Default when_charging.
  • On the charger with the screen off and when_charging: no gap over 120 s for 1 h.
  • On battery with the screen off and when_charging: the app holds no wake lock (dumpsys power shows none from the app) and does not set an exact alarm.
  • 24 h on a Xiaomi phone with HyperOS 2 (Android 15), screen off, default wake_policy: the service is not killed (one process start), and the gaps over 120 s are listed in the PR, split into on the charger and on battery. (Moved here from Spike: OTel disk buffer for metrics, 24 h on HyperOS, OpAMP on Android, OTLP into VictoriaMetrics #1.)
  • Config import works by file and by adb shell am broadcast; the README shows both.
  • Unit tests for config parsing and merging, and for each collector's mapping.
  • app.installation.id is not sent by default.
  • README: what it collects (a table with name, type, unit), the config format with an example (example.com endpoint), wake_policy and what each value costs in battery, and the setup checklist above.
  • A signed release APK on GitHub Releases.

Activity

  1. groupsky commented on Nov 12, 2026

    @groupsky
    ContributorAuthor

    Owner decision (Geno, 2026-11-12): waking the CPU is a setting.

    The spike (#1) showed that a 60 s timer without a wake lock slips to 2–3 min on battery with the screen off. On the charger every tick came on time.

    So waking the phone must be configurable, not always on:

    • New config key, for example wake_policy: never | when_charging | always.
    • Default: when_charging. On the charger the timer wakes the CPU (exact alarm or short wake lock). On battery the timer does not wake it, and ticks may come late.
    • The key is in the local config, in Android managed configurations, and later in OpAMP (Remote config: Android managed configurations and OpAMP #3).
    • The setup docs say what each value costs in battery.

    Add to "Done when":

    • wake_policy exists with the three values. Default when_charging.
    • On the charger with the screen off and when_charging: no gap over 120 s for 1 h.
    • On battery with the screen off and when_charging: the app holds no wake lock (dumpsys power shows none from the app) and does not set an exact alarm.
  2. groupsky commented on Nov 13, 2026

    @groupsky
    ContributorAuthor

    Queued for work on 2026-11-13. The body now has the spike's decisions (#1, docs/spike.md): own file queue, one foreground service with wake_policy (default when_charging), the setup checklist per phone maker, and the 24 h HyperOS test moved here from #1.

  3. added a commit that references this issue on Nov 13, 2026
  4. groupsky commented on Nov 13, 2026

    @groupsky
    ContributorAuthor

    hq-jobs aoda-2-build (run r-20261113-130003-bdec)

    Progress (2026-11-13): the MVP is in PR #7 (draft, CI green).

    Done, with evidence in docs/mvp-tests.md (emulator, Android 15):

    • All six collectors send; a query for each.
    • 30 min network cut with an app restart in it: no reading lost (largest gap 60 s).
    • Queue size cap and max age: unit tests.
    • A collector turned off stops at once.
    • wake_policy never | when_charging | always, default when_charging. On battery with the screen off and when_charging: no wake lock and no alarm from the app.
    • Config import by file, share sheet and adb shell am broadcast; README shows them.
    • No app.installation.id. README with the metric table, config, wake_policy costs and the setup checklist.

    The release signing key is made and in the repo secrets.

    Left, for a follow-up job on 2026-11-14: the 1 h charger test and the 24 h test on a Redmi Note 12S on HyperOS 2 (the install needs a tap at the phone), then the merge and the signed v0.1.0 release.

  5. groupsky commented on Nov 14, 2026

    @groupsky
    ContributorAuthor

    hq-jobs aoda-2-phone (run r-20261114-090004-b7c1)

    Real phone test started (2026-11-14). The signed release APK 0.1.0 runs on a Redmi Note 12S with HyperOS 2 (Android 15), default wake_policy (when_charging).

  6. groupsky commented on Nov 15, 2026

    @groupsky
    ContributorAuthor

    hq-jobs aoda-2-collect-fallback (run r-20261115-215004-8956)

    24 h test done; PR #7 merged; v0.1.0 released.

    24 h on a Redmi Note 12S on HyperOS 2 (Android 15), default wake_policy (when_charging), 2026-11-14 07:10:45 → 2026-11-15 07:10:45 UTC (tools/vm_report.py, full output in docs/mvp-tests.md):

    • One process start: the service was not killed. The same process was still running on 2026-11-15 19:50 UTC.
    • 1439 readings, 60 per hour (one hour has 59 only because of where the window ends). Largest gap 60 s.
    • Gaps over 120 s: on the charger 0 (1436 readings), on battery 0 (3 readings; the phone was on battery only for the first 2 min).
    • On battery device.agent.wake was 0 (the timer did not wake the CPU); on the charger 1.
    • Screen on in about 10 % of the readings (the kiosk turns it on with motion).
    • At the end: dumpsys alarm shows the app's exact alarm (ELAPSED_WAKEUP … TickReceiver); dumpsys power lists no wake lock from the app.

    1 h on the charger (07:13:45–08:13:45): 60 readings, no gap over 120 s (already in the PR).

    Release: https://github.com/code6x/android-otel-device-agent/releases/tag/v0.1.0 has android-otel-device-agent-0.1.0.apk and its .sha256. The checksum matches, and apksigner shows signer certificate SHA-256 206747b5d1d1198b6776a480735e16ab48d6dc5f5f3a5d5fe015ae682abb1220.

    All "Done when" boxes are now ticked.

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