Repository navigation
Description
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
Handlertick 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, timeoutresource:device.idand extra attributescollectors: per collectorenabled,interval, optionsbuffer: max disk size, max age (oldest dropped first)wake_policy:never|when_charging|always. Defaultwhen_charging(Geno's decision, 2026-11-12).when_charging: on the charger the timer wakes the CPU for each reading (exact alarm withsetExactAndAllowWhileIdle, 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_policyis notnever; - 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_policyexists with the three values. Defaultwhen_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 powershows 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.idis not sent by default. - README: what it collects (a table with name, type, unit), the config format with an example (
example.comendpoint),wake_policyand what each value costs in battery, and the setup checklist above. - A signed release APK on GitHub Releases.
Activity
Spike report: Q1, Q3, Q4 answers with evidence (#1)
Spike report: Q2 (24 h on OxygenOS) and the decision for #2
Spike: OTel disk buffer, staying alive, OpAMP, VictoriaMetrics (#1) (#6)
groupsky commentedon Nov 12, 2026
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:
wake_policy:never|when_charging|always.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.Add to "Done when":
wake_policyexists with the three values. Defaultwhen_charging.when_charging: no gap over 120 s for 1 h.when_charging: the app holds no wake lock (dumpsys powershows none from the app) and does not set an exact alarm.groupsky commentedon Nov 13, 2026
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 withwake_policy(defaultwhen_charging), the setup checklist per phone maker, and the 24 h HyperOS test moved here from #1.docs: emulator test results for #2
groupsky commentedon Nov 13, 2026
hq-jobs
aoda-2-build(runr-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):wake_policynever|when_charging|always, defaultwhen_charging. On battery with the screen off andwhen_charging: no wake lock and no alarm from the app.adb shell am broadcast; README shows them.app.installation.id. README with the metric table, config,wake_policycosts 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.0release.groupsky commentedon Nov 14, 2026
hq-jobs
aoda-2-phone(runr-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).when_charging, 1 h: passed. 60 readings in 1 h, largest gap 60 s, no gap over 120 s, one process. The screen was on in about 7 % of the readings (the kiosk on the phone wakes it on motion).dumpsys alarmshows the app's exact alarm;dumpsys powershows no wake lock held by the app between readings. Details:docs/mvp-tests.mdin MVP: six collectors, local config, own disk queue, wake_policy (#2) #7 (commit e0148ae).docs/mvp-tests.mdso they can be undone.MVP: six collectors, local config, own disk queue, wake_policy (#2) (#7)
groupsky commentedon Nov 15, 2026
hq-jobs
aoda-2-collect-fallback(runr-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 indocs/mvp-tests.md):device.agent.wakewas 0 (the timer did not wake the CPU); on the charger 1.dumpsys alarmshows the app's exact alarm (ELAPSED_WAKEUP … TickReceiver);dumpsys powerlists 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.apkand its.sha256. The checksum matches, andapksignershows signer certificate SHA-256206747b5d1d1198b6776a480735e16ab48d6dc5f5f3a5d5fe015ae682abb1220.All "Done when" boxes are now ticked.