diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 0000000..a4f1d0c
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,32 @@
+name: CI
+
+on:
+ pull_request:
+ push:
+ branches: [main]
+
+permissions:
+ contents: read
+
+jobs:
+ build:
+ name: Build and unit tests
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v5
+
+ - uses: actions/setup-java@v5
+ with:
+ distribution: temurin
+ java-version: "17"
+
+ - uses: gradle/actions/setup-gradle@v5
+
+ - name: Unit tests
+ run: ./gradlew :app:testDebugUnitTest
+
+ - name: Build debug APK
+ run: ./gradlew :app:assembleDebug
+
+ - name: Lint release
+ run: ./gradlew :app:lintVitalRelease
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
new file mode 100644
index 0000000..533b9e6
--- /dev/null
+++ b/.github/workflows/release.yml
@@ -0,0 +1,55 @@
+# Builds a signed release APK and puts it on GitHub Releases. Runs on a tag v1.2.3.
+# The signing key comes from the repo secrets (docs/release.md). Without them the job fails:
+# it never publishes an unsigned APK.
+name: Release
+
+on:
+ push:
+ tags: ["v*"]
+
+permissions:
+ contents: write
+
+jobs:
+ release:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v5
+
+ - uses: actions/setup-java@v5
+ with:
+ distribution: temurin
+ java-version: "17"
+
+ - uses: gradle/actions/setup-gradle@v5
+
+ - name: Decode the keystore
+ env:
+ KEYSTORE_B64: ${{ secrets.KEYSTORE_B64 }}
+ run: |
+ if [ -z "$KEYSTORE_B64" ]; then echo "::error::KEYSTORE_B64 is not set (docs/release.md)"; exit 1; fi
+ echo "$KEYSTORE_B64" | base64 -d > "$RUNNER_TEMP/release.jks"
+ echo "KEYSTORE_FILE=$RUNNER_TEMP/release.jks" >> "$GITHUB_ENV"
+
+ - name: Test and build
+ env:
+ KEYSTORE_PASSWORD: ${{ secrets.KEYSTORE_PASSWORD }}
+ KEY_ALIAS: ${{ secrets.KEY_ALIAS }}
+ KEY_PASSWORD: ${{ secrets.KEY_PASSWORD }}
+ run: |
+ VERSION="${GITHUB_REF_NAME#v}"
+ ./gradlew :app:testDebugUnitTest :app:assembleRelease -PversionName="$VERSION"
+ cp app/build/outputs/apk/release/app-release.apk "android-otel-device-agent-$VERSION.apk"
+
+ - name: Check the signature
+ run: |
+ APKSIGNER=$(ls "$ANDROID_HOME"/build-tools/*/apksigner | sort -V | tail -1)
+ "$APKSIGNER" verify --print-certs "android-otel-device-agent-${GITHUB_REF_NAME#v}.apk"
+
+ - name: Publish
+ env:
+ GH_TOKEN: ${{ github.token }}
+ run: |
+ APK="android-otel-device-agent-${GITHUB_REF_NAME#v}.apk"
+ sha256sum "$APK" > "$APK.sha256"
+ gh release create "$GITHUB_REF_NAME" "$APK" "$APK.sha256" --title "$GITHUB_REF_NAME" --generate-notes
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..4c5ae9e
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,9 @@
+.gradle/
+build/
+app/build/
+local.properties
+*.apk
+*.jks
+*.keystore
+signing.properties
+.idea/
diff --git a/README.md b/README.md
index e24af62..291ff8e 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,243 @@
# android-otel-device-agent
-Android app that sends device health (battery, power, network, storage, thermal) over OTLP. Configurable; remote config over OpAMP.
+
+An Android app that reads **device health** (battery, power, boot, network,
+memory and storage, thermal) and sends it over **OTLP/HTTP** (OpenTelemetry)
+to any OTLP receiver. It keeps the data on disk while the network is down,
+and sends it later, in order.
+
+Where to send, what to send and how often are settings, not code.
+
+- One foreground service with a timer reads the collectors (default every 60 s).
+- Each reading goes to a **disk queue** first (one OTLP request body per file).
+ A sender posts the files in order and deletes a file only after a 2xx answer.
+ The queue lives through network cuts and app restarts.
+- Settings come from built-in defaults and a **local config file** (JSON). The
+ same JSON shape will be used for managed configurations and OpAMP later (#3).
+
+Status: MVP (issue #2). The design came from a spike: [`docs/spike.md`](docs/spike.md).
+
+## Install
+
+Download the signed APK from [GitHub Releases](https://github.com/code6x/android-otel-device-agent/releases)
+and install it. Android 8.0 (API 26) or newer. Then:
+
+1. Import a config (see [Config](#config)) with at least `exporter.endpoint`.
+2. Press **Start** in the app.
+3. Go through the [setup checklist](#setup-checklist) on the same screen.
+
+The service starts again by itself after a reboot and after an app update,
+if it was running before.
+
+## What it collects
+
+Each collector can be turned on or off, and has its own interval (default 60 s).
+All metrics are **gauges**: each point is one reading, with the wall-clock time
+of the reading. So a gap in the data is a gap in the readings.
+
+Names follow the OpenTelemetry semantic conventions where they exist
+(`hw.battery.*`, `system.memory.*`, `system.filesystem.*`, `system.uptime`),
+else `device.*`.
+
+| Collector | Name | Unit | Attributes | What |
+|---|---|---|---|---|
+| battery | `hw.battery.charge` | `1` | | Battery level, 0 to 1 (0.87 = 87 %) |
+| battery | `device.battery.voltage` | `V` | | Battery voltage |
+| battery | `device.battery.temperature` | `Cel` | | Battery temperature, °C |
+| battery | `device.battery.current` | `A` | | Battery current. Positive is into the battery on most phones; some phones use the other sign |
+| battery | `device.battery.charge_counter` | `A.h` | | Remaining charge |
+| battery | `device.battery.cycle_count` | `{cycle}` | | Charge cycles (Android 14+, when the phone reports it) |
+| battery | `device.battery.status` | `1` | `battery.status`: `charging`, `discharging`, `not_charging`, `full`, `unknown` | 1 for the current status, 0 for the others |
+| battery | `device.battery.plug` | `1` | `battery.plug`: `ac`, `usb`, `wireless`, `dock`, `none` | 1 for the current power source, 0 for the others |
+| battery | `device.battery.health` | `1` | `battery.health`: `good`, `overheat`, `dead`, `over_voltage`, `failure`, `cold`, `unknown` | 1 for the current health, 0 for the others |
+| power | `device.screen.on` | `1` | | 1 when the screen is on |
+| power | `device.power.save_mode` | `1` | | 1 when battery saver is on |
+| power | `device.power.idle` | `1` | | 1 in idle (Doze) mode |
+| boot | `system.uptime` | `s` | | Time since boot, deep sleep included |
+| boot | `device.boot.count` | `{boot}` | | Boots since the phone was set up (`Settings.Global.BOOT_COUNT`) |
+| boot | `device.boot.time` | `s` | | Time of the last boot, Unix seconds |
+| boot | log record `device.boot` | | `device.boot.count`, `device.boot.time` | One OTLP log record per boot, at the boot time (needs `exporter.logs_endpoint`) |
+| network | `device.network.connected` | `1` | | 1 when there is an active network |
+| network | `device.network.type` | `1` | `network.connection.type`: `wifi`, `cell`, `wired`, `vpn`, `bluetooth` | 1 for each transport of the active network (a VPN over Wi-Fi is both `vpn` and `wifi`) |
+| network | `device.wifi.connected` | `1` | | 1 when Wi-Fi is connected |
+| network | `device.wifi.rssi` | `dBm` | | Wi-Fi signal strength |
+| network | `device.wifi.link_speed` | `Mbit/s` | | Wi-Fi link speed |
+| device | `system.memory.limit` | `By` | | Total RAM |
+| device | `system.memory.usage` | `By` | `system.memory.state`: `free` (available to apps), `used` | RAM |
+| device | `device.memory.low` | `1` | | 1 when the system is low on memory |
+| device | `system.filesystem.limit` | `By` | `system.filesystem.mountpoint`: `/data` | Size of `/data` |
+| device | `system.filesystem.usage` | `By` | `system.filesystem.mountpoint`: `/data`; `system.filesystem.state`: `free`, `used` | Space on `/data` |
+| thermal | `device.thermal.status` | `1` | | 0 none, 1 light, 2 moderate, 3 severe, 4 critical, 5 emergency, 6 shutdown (Android 10+) |
+| thermal | `device.thermal.headroom` | `1` | | Thermal headroom; 1.0 is where severe throttling starts (Android 11+, when the phone reports it) |
+| (always) | `device.agent.start_time` | `s` | | Start time of the app process, Unix seconds. A new value means a new process |
+| (always) | `device.agent.queue.size` | `By` | | Bytes waiting in the disk queue |
+| (always) | `device.agent.queue.dropped` | `{file}` | | Queue files dropped by the size cap or max age since the process started |
+| (always) | `device.agent.wake` | `1` | | 1 when the timer wakes the CPU for readings (see `wake_policy`) |
+
+The `device.agent.*` metrics are sent with every reading.
+
+The app does **not** collect the Wi-Fi name (SSID) or BSSID: Android needs the
+location permission for them.
+
+**Resource attributes** (on every metric and log record): `service.name`
+(`android-otel-device-agent`), `service.version`, `device.id` (from the
+config; left out when empty), `device.model.identifier`, `device.manufacturer`,
+`os.name`, `os.type`, `os.version`, `telemetry.sdk.*`, and the free-form
+attributes from `resource.attributes` in the config. There is **no**
+`app.installation.id` (a random id per install: it is private, and it makes a
+new series after each reinstall).
+
+### Notes for VictoriaMetrics
+
+VictoriaMetrics takes OTLP at `/opentelemetry/v1/metrics`. It keeps the names
+as they are, with dots, so a query must quote them:
+`{__name__="hw.battery.charge", device.id="phone-1"}`. It drops the units, so
+use the table above. Every resource attribute becomes a label.
+
+## Config
+
+One JSON document. Every key is optional: a key that is not set keeps its
+default. Example (all keys):
+
+```json
+{
+ "exporter": {
+ "endpoint": "https://otlp.example.com/v1/metrics",
+ "logs_endpoint": "https://otlp.example.com/v1/logs",
+ "protocol": "http/protobuf",
+ "headers": { "Authorization": "Bearer REPLACE_ME" },
+ "timeout": 10
+ },
+ "resource": {
+ "device.id": "tablet-1",
+ "attributes": { "location": "lobby" }
+ },
+ "collectors": {
+ "battery": { "enabled": true, "interval": 60 },
+ "power": { "enabled": true, "interval": 60 },
+ "boot": { "enabled": true, "interval": 300 },
+ "network": { "enabled": true, "interval": 60 },
+ "device": { "enabled": true, "interval": 300 },
+ "thermal": { "enabled": false }
+ },
+ "buffer": {
+ "max_bytes": 20971520,
+ "max_age": 604800
+ },
+ "wake_policy": "when_charging"
+}
+```
+
+| Key | Default | What |
+|---|---|---|
+| `exporter.endpoint` | empty | Full URL of the OTLP/HTTP **metrics** endpoint (for VictoriaMetrics: `http://HOST:8428/opentelemetry/v1/metrics`). Empty: the data stays in the queue until an endpoint is set |
+| `exporter.logs_endpoint` | empty | Full URL of the OTLP/HTTP **logs** endpoint, for the boot log record. Empty: no log records |
+| `exporter.protocol` | `http/protobuf` | The only value supported now |
+| `exporter.headers` | none | HTTP headers for both endpoints, for example a token. The app does not show their values |
+| `exporter.timeout` | `10` | Seconds, 1–300 |
+| `resource.device.id` | empty | The `device.id` resource attribute |
+| `resource.attributes` | none | More resource attributes (text values) |
+| `collectors.NAME.enabled` | `true` | NAME is `battery`, `power`, `boot`, `network`, `device` or `thermal` |
+| `collectors.NAME.interval` | `60` | Seconds, 10–86400 |
+| `buffer.max_bytes` | `20971520` (20 MiB) | Disk queue size cap. When it is full, the oldest file is dropped first |
+| `buffer.max_age` | `604800` (7 days) | Seconds. Older queue files are dropped |
+| `wake_policy` | `when_charging` | `never`, `when_charging` or `always`; see below |
+
+A wrong value (a bad type, a number out of range, an unknown `wake_policy`)
+rejects the whole import, and the config in use stays as it was. An unknown
+key is ignored with a warning.
+
+The app screen shows the config in use, each value with where it came from
+(`default` or `local file`).
+
+### Import the config
+
+**By file.** In the app: **Import config file**, then pick the JSON file. Or
+open a `.json` file from a file manager or share it to the app ("Open with" /
+share sheet). The app asks before it uses a config from another app.
+
+**By QR code.** Put the JSON text in a QR code. Scan it with any QR scanner
+app, then share the text to this app. The app shows it and asks before it
+uses it.
+
+**By adb** (scripted setup). Encode the file in base64, so the shell does not
+break the JSON:
+
+```bash
+adb shell am broadcast -a dev.code6x.otelagent.SET_CONFIG \
+ -n dev.code6x.otelagent/.ConfigReceiver \
+ --es json_b64 "$(base64 -w0 config.json)" --ez start true
+```
+
+The answer is in the `data` of the result line, for example
+`Broadcast completed: result=-1, data="ok: config imported; applied"`
+(`result=0` and `data="error: …"` when the config is wrong). Other extras:
+
+- `--es json '{"wake_policy":"always"}'`: the JSON as text (mind the quotes);
+- `--ez reset true`: remove the local config file and go back to the defaults;
+- `--ez start true`: start the service too, if it does not run. Android lets
+ a background app start a foreground service only in some cases. If the app
+ is on the battery optimisation allow-list (setup checklist) it works; else
+ the answer says `service NOT started`, and you press **Start** in the app.
+
+Only the adb shell can send this broadcast: the receiver asks for the
+`android.permission.DUMP` permission, which normal apps cannot get.
+
+A new config takes effect at once: all collectors read again with the new
+settings. A collector that is turned off sends nothing from then on.
+
+## `wake_policy`: waking the CPU
+
+When the phone is on battery with the screen off, the CPU sleeps, and a
+plain timer stops with it. In the spike, a 60 s timer then came 2–3 minutes
+apart. On the charger, every reading came on time.
+
+So `wake_policy` decides whether the timer wakes the CPU:
+
+| Value | On the charger | On battery | Battery cost |
+|---|---|---|---|
+| `never` | does not wake the CPU | does not wake the CPU | None from waking. Readings may come late (minutes apart) when the screen is off |
+| `when_charging` (**default**) | wakes the CPU for each reading | does not wake the CPU | None on battery (the charger pays for the wakes). On battery, readings may come late |
+| `always` | wakes the CPU for each reading | wakes the CPU for each reading | The CPU wakes once per interval (60 s by default) for a short time. This keeps the readings on time, but uses more battery than the other values. A longer interval costs less. |
+
+How the app wakes the CPU: an exact alarm (`setExactAndAllowWhileIdle`) for
+each reading, and a short wake lock until the reading is sent. Without the
+"Alarms & reminders" permission (Android 12+ may not grant it), it holds a
+partial wake lock between readings instead. When it does not wake the CPU,
+the app sets no alarm and holds no wake lock.
+
+On battery, Android's Doze mode allows such alarms only about once in 9
+minutes, unless the app is on the battery optimisation allow-list (setup
+checklist).
+
+## Setup checklist
+
+The app screen shows this list with the current state, and buttons that open
+the Android screen for each item where one exists.
+
+- **Notifications allowed** (Android 13+). The service shows a quiet notification.
+- **Battery optimisation off** for this app. Lets it run and send in the
+ background, and start again after an update.
+- **Alarms & reminders** (exact alarms) allowed, when `wake_policy` is not
+ `never` (Android 12+; on Android 14+ the user must allow it).
+- **OnePlus / OPPO** (OxygenOS, ColorOS): App info → Battery → **Allow
+ background activity**. Without it the spike's app was frozen 2 minutes after
+ start, even with a foreground service; the Doze allow-list did not help.
+- **Xiaomi** (HyperOS / MIUI): **Autostart** on, and battery saver **No
+ restrictions** (App info → Battery saver).
+- **A VPN with per-app split tunneling**: **include this app**, or the
+ receiver may not be reachable. The queue keeps the data meanwhile.
+
+## Build and test
+
+```bash
+./gradlew :app:testDebugUnitTest # unit tests
+./gradlew :app:assembleDebug # app/build/outputs/apk/debug/app-debug.apk
+```
+
+The `spike/` folder is the separate spike project of issue #1; it is not
+part of the app build. Releases: [`docs/release.md`](docs/release.md).
+Test results of the MVP: [`docs/mvp-tests.md`](docs/mvp-tests.md).
+
+## License
+
+Apache-2.0, see [LICENSE](LICENSE).
diff --git a/app/build.gradle.kts b/app/build.gradle.kts
new file mode 100644
index 0000000..5b7fe73
--- /dev/null
+++ b/app/build.gradle.kts
@@ -0,0 +1,82 @@
+plugins {
+ id("com.android.application")
+ id("org.jetbrains.kotlin.android")
+}
+
+// Release version: -PversionName=0.1.0 (the release workflow passes the tag).
+// versionCode is made from it: 0.1.0 -> 100, 1.2.3 -> 10203.
+val appVersionName = (findProperty("versionName") as String?) ?: "0.1.0-dev"
+val appVersionCode = appVersionName.substringBefore('-').split('.').let { p ->
+ (p.getOrNull(0)?.toIntOrNull() ?: 0) * 10000 + (p.getOrNull(1)?.toIntOrNull() ?: 0) * 100 +
+ (p.getOrNull(2)?.toIntOrNull() ?: 0)
+}.coerceAtLeast(1)
+
+// Release signing comes only from the environment (see docs/release.md). No key is in git.
+val keystoreFile: String? = System.getenv("KEYSTORE_FILE")
+
+android {
+ namespace = "dev.code6x.otelagent"
+ compileSdk = 36
+
+ defaultConfig {
+ applicationId = "dev.code6x.otelagent"
+ minSdk = 26
+ targetSdk = 35
+ versionCode = appVersionCode
+ versionName = appVersionName
+ }
+
+ signingConfigs {
+ if (keystoreFile != null) {
+ create("release") {
+ storeFile = file(keystoreFile)
+ storePassword = System.getenv("KEYSTORE_PASSWORD")
+ keyAlias = System.getenv("KEY_ALIAS")
+ keyPassword = System.getenv("KEY_PASSWORD")
+ }
+ }
+ }
+
+ buildTypes {
+ release {
+ isMinifyEnabled = false
+ if (keystoreFile != null) signingConfig = signingConfigs.getByName("release")
+ }
+ }
+
+ compileOptions {
+ sourceCompatibility = JavaVersion.VERSION_17
+ targetCompatibility = JavaVersion.VERSION_17
+ isCoreLibraryDesugaringEnabled = true
+ }
+
+ buildFeatures { buildConfig = true }
+
+ packaging {
+ resources.excludes += setOf("META-INF/versions/9/OSGI-INF/MANIFEST.MF")
+ }
+
+ testOptions {
+ unitTests.isReturnDefaultValues = true
+ }
+}
+
+kotlin {
+ jvmToolchain(17)
+}
+
+dependencies {
+ coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.5")
+ // All OpenTelemetry core artifacts are held at one version (the spike: mixed versions
+ // crashed at start). 1.66.0 is the version opentelemetry-android 1.8.1 is built on.
+ implementation(enforcedPlatform("io.opentelemetry:opentelemetry-bom:1.66.0"))
+ implementation("io.opentelemetry:opentelemetry-sdk-metrics")
+ implementation("io.opentelemetry:opentelemetry-sdk-logs")
+ // The OTLP protobuf marshalers, for the own file queue.
+ implementation("io.opentelemetry:opentelemetry-exporter-otlp-common")
+
+ testImplementation("junit:junit:4.13.2")
+ // Android's org.json is a stub in unit tests; use the real one there.
+ testImplementation("org.json:json:20240303")
+ testImplementation("io.opentelemetry.proto:opentelemetry-proto:1.8.0-alpha")
+}
diff --git a/app/src/main/AndroidManifest.xml b/app/src/main/AndroidManifest.xml
new file mode 100644
index 0000000..dd60e8c
--- /dev/null
+++ b/app/src/main/AndroidManifest.xml
@@ -0,0 +1,75 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/app/src/main/java/dev/code6x/otelagent/AgentService.kt b/app/src/main/java/dev/code6x/otelagent/AgentService.kt
new file mode 100644
index 0000000..f2b5b4c
--- /dev/null
+++ b/app/src/main/java/dev/code6x/otelagent/AgentService.kt
@@ -0,0 +1,383 @@
+package dev.code6x.otelagent
+
+import android.app.AlarmManager
+import android.app.Notification
+import android.app.NotificationChannel
+import android.app.NotificationManager
+import android.app.PendingIntent
+import android.app.Service
+import android.content.BroadcastReceiver
+import android.content.Context
+import android.content.Intent
+import android.content.IntentFilter
+import android.content.pm.ServiceInfo
+import android.net.ConnectivityManager
+import android.net.Network
+import android.os.Build
+import android.os.Handler
+import android.os.HandlerThread
+import android.os.IBinder
+import android.os.PowerManager
+import android.os.SystemClock
+import android.util.Log
+import dev.code6x.otelagent.collect.BatteryCollector
+import dev.code6x.otelagent.collect.BootCollector
+import dev.code6x.otelagent.collect.Collector
+import dev.code6x.otelagent.collect.Collectors
+import dev.code6x.otelagent.collect.Metrics
+import dev.code6x.otelagent.collect.Reading
+import dev.code6x.otelagent.config.ConfigStore
+import dev.code6x.otelagent.config.LoadedConfig
+import dev.code6x.otelagent.export.FileQueue
+import dev.code6x.otelagent.export.OtlpEncoder
+import dev.code6x.otelagent.export.QueueSender
+import dev.code6x.otelagent.export.Target
+import java.io.File
+import java.util.concurrent.Executors
+import java.util.concurrent.ScheduledExecutorService
+import java.util.concurrent.TimeUnit
+
+/**
+ * The one foreground service. A timer reads the due collectors, writes one OTLP body to the
+ * disk queue and wakes the sender. Whether the timer wakes the CPU is `wake_policy`:
+ * - waking: an exact alarm (setExactAndAllowWhileIdle) and a short wake lock for each tick;
+ * without the exact-alarm permission, a partial wake lock held between ticks instead.
+ * - not waking: a Handler timer; it stops while the CPU sleeps, so readings may come late.
+ * No alarm and no wake lock then.
+ */
+class AgentService : Service() {
+ private lateinit var thread: HandlerThread
+ private lateinit var handler: Handler
+ private lateinit var sendExecutor: ScheduledExecutorService
+ private lateinit var store: ConfigStore
+ private lateinit var loaded: LoadedConfig
+ private lateinit var encoder: OtlpEncoder
+ private lateinit var metricQueue: FileQueue
+ private lateinit var logQueue: FileQueue
+ private lateinit var metricSender: QueueSender
+ private lateinit var logSender: QueueSender
+ private lateinit var collectors: List
+ private lateinit var tickLock: PowerManager.WakeLock
+ private lateinit var holdLock: PowerManager.WakeLock
+ private lateinit var alarmIntent: PendingIntent
+ private val plan = TickPlan()
+
+ /** Set in onDestroy; a tick still running then must not set an alarm or take a lock. */
+ @Volatile private var destroyed = false
+
+ private val tickRunnable = Runnable { tick() }
+
+ private val powerReceiver = object : BroadcastReceiver() {
+ override fun onReceive(context: Context, intent: Intent) {
+ val charging = intent.action == Intent.ACTION_POWER_CONNECTED
+ handler.post { reschedule(charging) }
+ }
+ }
+
+ private val networkCallback = object : ConnectivityManager.NetworkCallback() {
+ override fun onAvailable(network: Network) = sendNow(null)
+ }
+
+ override fun onCreate() {
+ super.onCreate()
+ instance = this
+ startInForeground()
+ thread = HandlerThread("agent-tick").apply { start() }
+ handler = Handler(thread.looper)
+ sendExecutor = Executors.newSingleThreadScheduledExecutor()
+ val pm = getSystemService(PowerManager::class.java)
+ tickLock = pm.newWakeLock(PowerManager.PARTIAL_WAKE_LOCK, "otelagent:tick").apply { setReferenceCounted(false) }
+ holdLock = pm.newWakeLock(PowerManager.PARTIAL_WAKE_LOCK, "otelagent:hold").apply { setReferenceCounted(false) }
+ alarmIntent = PendingIntent.getBroadcast(
+ this, 0, Intent(this, TickReceiver::class.java),
+ PendingIntent.FLAG_IMMUTABLE or PendingIntent.FLAG_UPDATE_CURRENT,
+ )
+ store = ConfigStore(this)
+ collectors = Collectors.create(this)
+ val queueRoot = File(filesDir, "queue")
+ metricQueue = FileQueue(File(queueRoot, "metrics"), 0, 0)
+ logQueue = FileQueue(File(queueRoot, "logs"), 0, 0)
+ metricSender = QueueSender(metricQueue)
+ logSender = QueueSender(logQueue)
+ applyConfig(store.load())
+
+ registerReceiver(powerReceiver, IntentFilter().apply {
+ addAction(Intent.ACTION_POWER_CONNECTED)
+ addAction(Intent.ACTION_POWER_DISCONNECTED)
+ })
+ try {
+ getSystemService(ConnectivityManager::class.java)?.registerDefaultNetworkCallback(networkCallback)
+ } catch (e: RuntimeException) {
+ Log.w(TAG, "no network callback: ${e.message}")
+ }
+ sendExecutor.scheduleWithFixedDelay({ drainAll() }, 30, 30, TimeUnit.SECONDS)
+ handler.post { checkBoot() }
+ handler.post(tickRunnable)
+ Log.i(TAG, "service created, pid=${android.os.Process.myPid()}")
+ }
+
+ override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
+ startInForeground()
+ if (intent?.action == ACTION_RELOAD) reload()
+ return START_STICKY
+ }
+
+ override fun onDestroy() {
+ Log.w(TAG, "service destroyed")
+ destroyed = true
+ instance = null
+ cancelAlarm()
+ handler.removeCallbacksAndMessages(null)
+ try {
+ unregisterReceiver(powerReceiver)
+ getSystemService(ConnectivityManager::class.java)?.unregisterNetworkCallback(networkCallback)
+ } catch (_: RuntimeException) {
+ }
+ sendExecutor.shutdown()
+ thread.quitSafely()
+ synchronized(this) {
+ // A schedule() that ran before `destroyed` was set may have set these again.
+ cancelAlarm()
+ if (tickLock.isHeld) tickLock.release()
+ if (holdLock.isHeld) holdLock.release()
+ }
+ AgentState.timerMode = "stopped"
+ super.onDestroy()
+ }
+
+ override fun onBind(intent: Intent?): IBinder? = null
+
+ /** Read the config file again and use it from the next tick (which is now). */
+ fun reload() {
+ handler.post {
+ applyConfig(store.load())
+ tick()
+ }
+ }
+
+ private fun applyConfig(c: LoadedConfig) {
+ loaded = c
+ val cfg = c.config
+ encoder = OtlpEncoder(
+ OtlpEncoder.resource(
+ BuildConfig.VERSION_NAME, Build.MODEL, Build.MANUFACTURER, Build.VERSION.RELEASE,
+ cfg.deviceId, cfg.attributes,
+ ),
+ BuildConfig.VERSION_NAME,
+ )
+ for (q in listOf(metricQueue, logQueue)) {
+ q.maxBytes = cfg.buffer.maxBytes
+ q.maxAgeMs = cfg.buffer.maxAgeSeconds * 1000
+ }
+ plan.reset()
+ Log.i(TAG, "config: endpoint ${if (cfg.exporter.endpoint.isEmpty()) "not set" else "set"}, " +
+ "wake_policy=${cfg.wakePolicy.key}, collectors on: " +
+ cfg.collectors.filter { it.value.enabled }.keys.joinToString())
+ }
+
+ private fun intervals(): Map =
+ loaded.config.collectors.filter { it.value.enabled }.mapValues { it.value.intervalSeconds }
+
+ private fun tick() {
+ handler.removeCallbacks(tickRunnable)
+ val now = SystemClock.elapsedRealtime()
+ val wall = System.currentTimeMillis()
+ val charging = BatteryCollector.isCharging(this)
+ val wake = loaded.config.wakePolicy.wakes(charging)
+ val due = plan.due(now, intervals())
+ if (due.isNotEmpty()) {
+ val readings = mutableListOf()
+ for (c in collectors.filter { it.name in due }) {
+ try {
+ val r = c.collect()
+ readings += r
+ AgentState.collectors[c.name] = AgentState.CollectorState(wall, r, null)
+ } catch (e: Exception) {
+ Log.e(TAG, "collector ${c.name} failed", e)
+ AgentState.collectors[c.name] = AgentState.CollectorState(wall, emptyList(), e.toString())
+ }
+ }
+ readings += Reading(Metrics.AGENT_START_TIME, (AgentState.processStartMs / 1000).toDouble())
+ readings += Reading(Metrics.AGENT_QUEUE_SIZE, metricQueue.sizeBytes().toDouble())
+ readings += Reading(Metrics.AGENT_QUEUE_DROPPED, (metricQueue.dropped + logQueue.dropped).toDouble())
+ readings += Reading(Metrics.AGENT_WAKE, if (wake) 1.0 else 0.0)
+ try {
+ metricQueue.add(encoder.metrics(readings, wall))
+ } catch (e: Exception) {
+ Log.e(TAG, "queue write failed", e)
+ }
+ AgentState.lastReadingMs = wall
+ Log.i(TAG, "tick: read ${due.joinToString()}; charging=$charging wake=$wake")
+ }
+ // Keep the CPU awake (if this tick came by alarm) until the send is done.
+ sendNow(if (tickLock.isHeld) ({ if (tickLock.isHeld) tickLock.release() }) else null)
+ schedule(plan.nextDelay(now, intervals()), wake)
+ }
+
+ private fun reschedule(charging: Boolean) {
+ val now = SystemClock.elapsedRealtime()
+ schedule(plan.nextDelay(now, intervals()), loaded.config.wakePolicy.wakes(charging))
+ }
+
+ @Synchronized
+ private fun schedule(delay: Long?, wake: Boolean) {
+ if (destroyed) return
+ cancelAlarm()
+ handler.removeCallbacks(tickRunnable)
+ if (delay == null) {
+ if (holdLock.isHeld) holdLock.release()
+ AgentState.timerMode = "no collector on"
+ return
+ }
+ if (wake && canExact()) {
+ if (holdLock.isHeld) holdLock.release()
+ val am = getSystemService(AlarmManager::class.java)
+ try {
+ am.setExactAndAllowWhileIdle(AlarmManager.ELAPSED_REALTIME_WAKEUP, SystemClock.elapsedRealtime() + delay, alarmIntent)
+ // Backup, in case the alarm does not come: runs only while the CPU is awake.
+ handler.postDelayed(tickRunnable, delay + 30_000)
+ AgentState.timerMode = "wakes the CPU (exact alarm)"
+ return
+ } catch (e: SecurityException) {
+ Log.w(TAG, "exact alarm not allowed: ${e.message}")
+ }
+ }
+ if (wake) {
+ // No exact alarms allowed: keep the CPU awake between ticks instead.
+ holdLock.acquire(delay + 60_000)
+ AgentState.timerMode = "wakes the CPU (wake lock; exact alarms not allowed)"
+ } else {
+ if (holdLock.isHeld) holdLock.release()
+ AgentState.timerMode = "does not wake the CPU (timer)"
+ }
+ handler.postDelayed(tickRunnable, delay)
+ }
+
+ private fun canExact(): Boolean =
+ Build.VERSION.SDK_INT < 31 || getSystemService(AlarmManager::class.java).canScheduleExactAlarms()
+
+ private fun cancelAlarm() {
+ getSystemService(AlarmManager::class.java).cancel(alarmIntent)
+ }
+
+ /** Called by [TickReceiver] when the exact alarm fires; the system holds a wake lock until we take ours. */
+ fun onAlarm() {
+ if (destroyed) return
+ tickLock.acquire(60_000)
+ handler.post(tickRunnable)
+ }
+
+ private fun checkBoot() {
+ val prefs = getSharedPreferences(PREFS, MODE_PRIVATE)
+ val now = BootCollector.read(this)
+ val lastCount = if (prefs.contains("boot_count")) prefs.getInt("boot_count", 0) else null
+ val lastTime = if (prefs.contains("boot_time")) prefs.getLong("boot_time", 0) else null
+ if (!BootCollector.isNewBoot(lastCount, lastTime, now)) return
+ val cfg = loaded.config
+ if (cfg.collectors["boot"]?.enabled == true && cfg.exporter.logsEndpoint.isNotEmpty()) {
+ val attrs = mutableMapOf("device.boot.time" to now.bootTimeS.toString())
+ now.bootCount?.let { attrs["device.boot.count"] = it.toString() }
+ try {
+ logQueue.add(encoder.log("device.boot", "device boot", attrs, now.bootTimeS * 1000, System.currentTimeMillis()))
+ Log.i(TAG, "boot record queued (boot count ${now.bootCount})")
+ } catch (e: Exception) {
+ Log.e(TAG, "boot record not queued", e)
+ }
+ }
+ prefs.edit().apply {
+ if (now.bootCount != null) putInt("boot_count", now.bootCount) else remove("boot_count")
+ putLong("boot_time", now.bootTimeS)
+ }.apply()
+ }
+
+ private fun target(url: String): Target? =
+ if (url.isEmpty()) null else Target(url, loaded.config.exporter.headers, loaded.config.exporter.timeoutSeconds)
+
+ private fun sendNow(after: (() -> Unit)?) {
+ try {
+ sendExecutor.execute {
+ try {
+ drainAll()
+ } finally {
+ after?.invoke()
+ }
+ }
+ } catch (e: java.util.concurrent.RejectedExecutionException) {
+ after?.invoke()
+ }
+ }
+
+ private fun drainAll() {
+ try {
+ val cfg = loaded.config
+ val r = metricSender.drain(target(cfg.exporter.endpoint))
+ if (r.sent > 0 || r.dropped > 0 || r.error != null) {
+ AgentState.lastExportMs = System.currentTimeMillis()
+ AgentState.lastExportResult = if (r.error == null) "ok, sent ${r.sent}" else "sent ${r.sent}, then: ${r.error}"
+ Log.i(TAG, "send: ${AgentState.lastExportResult}, ${r.left} files wait")
+ }
+ if (cfg.exporter.logsEndpoint.isNotEmpty()) {
+ logSender.drain(target(cfg.exporter.logsEndpoint))
+ }
+ AgentState.queueFiles = metricQueue.files().size
+ AgentState.queueBytes = metricQueue.sizeBytes()
+ } catch (e: Exception) {
+ Log.e(TAG, "send failed", e)
+ }
+ }
+
+ private fun startInForeground() {
+ val nm = getSystemService(NotificationManager::class.java)
+ nm.createNotificationChannel(NotificationChannel(CHANNEL, getString(R.string.channel_name), NotificationManager.IMPORTANCE_MIN))
+ val open = PendingIntent.getActivity(
+ this, 0, Intent(this, MainActivity::class.java), PendingIntent.FLAG_IMMUTABLE,
+ )
+ val n = Notification.Builder(this, CHANNEL)
+ .setContentTitle(getString(R.string.app_name))
+ .setContentText(getString(R.string.notification_text))
+ .setSmallIcon(android.R.drawable.stat_notify_sync)
+ .setContentIntent(open)
+ .setOngoing(true)
+ .build()
+ if (Build.VERSION.SDK_INT >= 34) {
+ startForeground(NOTIFICATION_ID, n, ServiceInfo.FOREGROUND_SERVICE_TYPE_SPECIAL_USE)
+ } else {
+ startForeground(NOTIFICATION_ID, n)
+ }
+ }
+
+ companion object {
+ const val TAG = "OtelAgent"
+ const val PREFS = "agent"
+ const val CHANNEL = "agent"
+ const val NOTIFICATION_ID = 1
+ const val ACTION_RELOAD = "dev.code6x.otelagent.RELOAD"
+
+ @Volatile var instance: AgentService? = null
+ private set
+
+ fun wanted(context: Context) = context.getSharedPreferences(PREFS, MODE_PRIVATE).getBoolean("enabled", false)
+
+ /** Starts the service and remembers that it should run (also after a reboot). */
+ fun start(context: Context) {
+ context.getSharedPreferences(PREFS, MODE_PRIVATE).edit().putBoolean("enabled", true).apply()
+ context.startForegroundService(Intent(context, AgentService::class.java))
+ }
+
+ fun stop(context: Context) {
+ context.getSharedPreferences(PREFS, MODE_PRIVATE).edit().putBoolean("enabled", false).apply()
+ context.stopService(Intent(context, AgentService::class.java))
+ }
+
+ /** Applies a new config: at once when the service runs. Returns false when it is not running. */
+ fun reload(): Boolean {
+ val s = instance ?: return false
+ s.reload()
+ return true
+ }
+
+ fun queueBytes(): Long? = instance?.metricQueue?.sizeBytes()
+ fun queueFiles(): Int? = instance?.metricQueue?.files()?.size
+ fun currentConfig(): LoadedConfig? = instance?.loaded
+ }
+}
diff --git a/app/src/main/java/dev/code6x/otelagent/AgentState.kt b/app/src/main/java/dev/code6x/otelagent/AgentState.kt
new file mode 100644
index 0000000..9f38719
--- /dev/null
+++ b/app/src/main/java/dev/code6x/otelagent/AgentState.kt
@@ -0,0 +1,21 @@
+package dev.code6x.otelagent
+
+import dev.code6x.otelagent.collect.Reading
+import java.util.concurrent.ConcurrentHashMap
+
+/** What the status screen shows. Lives in the app process. */
+object AgentState {
+ data class CollectorState(val timeMs: Long, val readings: List, val error: String?)
+
+ val collectors = ConcurrentHashMap()
+
+ /** Start of this process (wall clock). */
+ val processStartMs: Long = System.currentTimeMillis()
+
+ @Volatile var lastReadingMs = 0L
+ @Volatile var lastExportMs = 0L
+ @Volatile var lastExportResult = ""
+ @Volatile var timerMode = ""
+ @Volatile var queueBytes = 0L
+ @Volatile var queueFiles = 0
+}
diff --git a/app/src/main/java/dev/code6x/otelagent/MainActivity.kt b/app/src/main/java/dev/code6x/otelagent/MainActivity.kt
new file mode 100644
index 0000000..2c38394
--- /dev/null
+++ b/app/src/main/java/dev/code6x/otelagent/MainActivity.kt
@@ -0,0 +1,239 @@
+package dev.code6x.otelagent
+
+import android.Manifest
+import android.app.Activity
+import android.app.AlertDialog
+import android.content.ActivityNotFoundException
+import android.content.Intent
+import android.net.Uri
+import android.os.Build
+import android.os.Bundle
+import android.os.Handler
+import android.os.Looper
+import android.text.format.DateFormat
+import android.view.View
+import android.widget.Button
+import android.widget.LinearLayout
+import android.widget.ScrollView
+import android.widget.TextView
+import android.widget.Toast
+import dev.code6x.otelagent.config.ConfigException
+import dev.code6x.otelagent.config.ConfigLoader
+import dev.code6x.otelagent.config.ConfigStore
+import java.util.Date
+
+/**
+ * The only screen: status, setup checklist and the config in use. Also the share target
+ * for config files and text (for example from a QR code scanner).
+ */
+class MainActivity : Activity() {
+ private val ui = Handler(Looper.getMainLooper())
+ private lateinit var status: TextView
+ private lateinit var setupBox: LinearLayout
+ private lateinit var configText: TextView
+ private lateinit var startStop: Button
+ private val refresher = object : Runnable {
+ override fun run() {
+ refresh()
+ ui.postDelayed(this, 2000)
+ }
+ }
+
+ override fun onCreate(savedInstanceState: Bundle?) {
+ super.onCreate(savedInstanceState)
+ val pad = (16 * resources.displayMetrics.density).toInt()
+ val root = LinearLayout(this).apply {
+ orientation = LinearLayout.VERTICAL
+ setPadding(pad, pad, pad, pad)
+ }
+ fun header(t: String) = TextView(this).apply {
+ text = t
+ textSize = 20f
+ setPadding(0, pad, 0, pad / 2)
+ }
+ startStop = Button(this).apply { setOnClickListener { toggleService() } }
+ status = TextView(this).apply { setTextIsSelectable(true) }
+ setupBox = LinearLayout(this).apply { orientation = LinearLayout.VERTICAL }
+ configText = TextView(this).apply {
+ setTextIsSelectable(true)
+ typeface = android.graphics.Typeface.MONOSPACE
+ textSize = 12f
+ }
+ root.addView(header("Status"))
+ root.addView(startStop)
+ root.addView(status)
+ root.addView(header("Setup checklist"))
+ root.addView(setupBox)
+ root.addView(header("Config in use"))
+ root.addView(Button(this).apply {
+ text = "Import config file"
+ setOnClickListener { pickFile() }
+ })
+ root.addView(Button(this).apply {
+ text = "Back to defaults"
+ setOnClickListener { confirmReset() }
+ })
+ root.addView(configText)
+ setContentView(ScrollView(this).apply { addView(root) })
+ if (Build.VERSION.SDK_INT >= 33) requestPermissions(arrayOf(Manifest.permission.POST_NOTIFICATIONS), 1)
+ handleShare(intent)
+ }
+
+ override fun onNewIntent(intent: Intent) {
+ super.onNewIntent(intent)
+ handleShare(intent)
+ }
+
+ override fun onResume() {
+ super.onResume()
+ ui.post(refresher)
+ }
+
+ override fun onPause() {
+ ui.removeCallbacks(refresher)
+ super.onPause()
+ }
+
+ private fun time(ms: Long) = if (ms == 0L) "never" else DateFormat.format("yyyy-MM-dd HH:mm:ss", Date(ms)).toString()
+
+ private fun refresh() {
+ val running = AgentService.instance != null
+ startStop.text = if (running) "Stop" else "Start"
+ val loaded = AgentService.currentConfig() ?: ConfigStore(this).load()
+ val sb = StringBuilder()
+ sb.append("Service: ").append(if (running) "running since ${time(AgentState.processStartMs)}" else "stopped").append('\n')
+ sb.append("Timer: ").append(AgentState.timerMode.ifEmpty { "-" }).append('\n')
+ sb.append("Endpoint: ").append(if (loaded.config.exporter.endpoint.isEmpty()) "not set (data stays in the queue)" else loaded.config.exporter.endpoint).append('\n')
+ sb.append("Last export: ").append(time(AgentState.lastExportMs))
+ if (AgentState.lastExportResult.isNotEmpty()) sb.append(" (").append(AgentState.lastExportResult).append(')')
+ sb.append('\n')
+ val files = AgentService.queueFiles()
+ val bytes = AgentService.queueBytes()
+ sb.append("Queue: ").append(if (files == null) "-" else "$files files, ${bytes!! / 1024} KiB").append('\n')
+ sb.append("Last reading: ").append(time(AgentState.lastReadingMs)).append("\n\n")
+ for (name in dev.code6x.otelagent.config.AgentConfig.COLLECTORS) {
+ val on = loaded.config.collector(name)
+ sb.append(name).append(if (on.enabled) " (every ${on.intervalSeconds} s)" else " (off)")
+ val st = AgentState.collectors[name]
+ if (st == null) {
+ sb.append(": no reading yet\n")
+ continue
+ }
+ sb.append(" at ").append(time(st.timeMs)).append('\n')
+ st.error?.let { sb.append(" error: ").append(it).append('\n') }
+ for (r in st.readings.filter { it.attributes.isEmpty() || it.value != 0.0 }) {
+ sb.append(" ").append(r.def.name)
+ if (r.attributes.isNotEmpty()) sb.append(r.attributes.values.joinToString(",", "{", "}"))
+ sb.append(" = ").append(fmt(r.value))
+ if (r.def.unit != "1") sb.append(' ').append(r.def.unit)
+ sb.append('\n')
+ }
+ }
+ status.text = sb.toString()
+
+ setupBox.removeAllViews()
+ for (item in Setup.items(this, loaded.config.wakePolicy)) {
+ val mark = when (item.done) {
+ true -> "[ok] "
+ false -> "[ ! ] "
+ null -> "[ ? ] "
+ }
+ setupBox.addView(TextView(this).apply { text = mark + item.title + "\n" + item.help })
+ item.open?.let { open ->
+ setupBox.addView(Button(this).apply {
+ text = "Open"
+ setOnClickListener {
+ try {
+ startActivity(open)
+ } catch (e: ActivityNotFoundException) {
+ Toast.makeText(this@MainActivity, "This phone has no such screen", Toast.LENGTH_LONG).show()
+ }
+ }
+ })
+ }
+ }
+ val c = StringBuilder()
+ loaded.entries.forEach { c.append(ConfigLoader.display(it)).append('\n') }
+ loaded.warnings.forEach { c.append("warning: ").append(it).append('\n') }
+ configText.text = c.toString()
+ }
+
+ private fun fmt(v: Double) = if (v == Math.floor(v) && kotlin.math.abs(v) < 1e15) v.toLong().toString() else String.format(java.util.Locale.ROOT, "%.3f", v)
+
+ private fun toggleService() {
+ if (AgentService.instance != null) AgentService.stop(this) else AgentService.start(this)
+ ui.postDelayed({ refresh() }, 500)
+ }
+
+ private fun pickFile() {
+ val i = Intent(Intent.ACTION_OPEN_DOCUMENT).addCategory(Intent.CATEGORY_OPENABLE).setType("*/*")
+ startActivityForResult(i, PICK)
+ }
+
+ @Deprecated("Deprecated in Java")
+ override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
+ super.onActivityResult(requestCode, resultCode, data)
+ if (requestCode == PICK && resultCode == RESULT_OK) data?.data?.let { readUri(it)?.let(::importText) }
+ }
+
+ private fun readUri(uri: Uri): String? = try {
+ contentResolver.openInputStream(uri)?.use { s ->
+ val bytes = s.readBytes()
+ if (bytes.size > MAX_BYTES) throw ConfigException("file larger than ${MAX_BYTES / 1024} KiB")
+ String(bytes, Charsets.UTF_8)
+ }
+ } catch (e: Exception) {
+ Toast.makeText(this, "Could not read the file: ${e.message}", Toast.LENGTH_LONG).show()
+ null
+ }
+
+ /** A config from another app (share sheet, QR scanner, file manager): ask before using it. */
+ private fun handleShare(i: Intent?) {
+ if (i == null) return
+ val text = when (i.action) {
+ Intent.ACTION_SEND -> i.getStringExtra(Intent.EXTRA_TEXT)
+ ?: @Suppress("DEPRECATION") (i.getParcelableExtra(Intent.EXTRA_STREAM))?.let { readUri(it) }
+ Intent.ACTION_VIEW -> i.data?.let { readUri(it) }
+ else -> null
+ } ?: return
+ setIntent(Intent(this, MainActivity::class.java))
+ AlertDialog.Builder(this)
+ .setTitle("Use this config?")
+ .setMessage(text.take(4000))
+ .setPositiveButton("Import") { _, _ -> importText(text) }
+ .setNegativeButton("Cancel", null)
+ .show()
+ }
+
+ private fun importText(text: String) {
+ try {
+ val loaded = ConfigStore(this).import(text)
+ AgentService.reload()
+ val w = if (loaded.warnings.isEmpty()) "" else "\n" + loaded.warnings.joinToString("\n")
+ Toast.makeText(this, "Config imported$w", Toast.LENGTH_LONG).show()
+ } catch (e: ConfigException) {
+ AlertDialog.Builder(this).setTitle("Config not imported").setMessage(e.message).setPositiveButton("OK", null).show()
+ } catch (e: java.io.IOException) {
+ Toast.makeText(this, "Could not save: ${e.message}", Toast.LENGTH_LONG).show()
+ }
+ refresh()
+ }
+
+ private fun confirmReset() {
+ AlertDialog.Builder(this)
+ .setTitle("Back to defaults?")
+ .setMessage("The local config file is removed. The endpoint is then not set.")
+ .setPositiveButton("Reset") { _, _ ->
+ ConfigStore(this).reset()
+ AgentService.reload()
+ refresh()
+ }
+ .setNegativeButton("Cancel", null)
+ .show()
+ }
+
+ companion object {
+ private const val PICK = 2
+ private const val MAX_BYTES = 64 * 1024
+ }
+}
diff --git a/app/src/main/java/dev/code6x/otelagent/Receivers.kt b/app/src/main/java/dev/code6x/otelagent/Receivers.kt
new file mode 100644
index 0000000..fbb37d7
--- /dev/null
+++ b/app/src/main/java/dev/code6x/otelagent/Receivers.kt
@@ -0,0 +1,83 @@
+package dev.code6x.otelagent
+
+import android.app.Activity
+import android.content.BroadcastReceiver
+import android.content.Context
+import android.content.Intent
+import android.util.Log
+import dev.code6x.otelagent.config.ConfigException
+import dev.code6x.otelagent.config.ConfigStore
+
+/** The exact alarm of a waking timer. */
+class TickReceiver : BroadcastReceiver() {
+ override fun onReceive(context: Context, intent: Intent) {
+ AgentService.instance?.onAlarm()
+ }
+}
+
+/** Starts the service after a reboot or an app update, when the user had started it. */
+class BootReceiver : BroadcastReceiver() {
+ override fun onReceive(context: Context, intent: Intent) {
+ if (intent.action != Intent.ACTION_BOOT_COMPLETED && intent.action != Intent.ACTION_MY_PACKAGE_REPLACED) return
+ if (!AgentService.wanted(context)) return
+ try {
+ AgentService.start(context)
+ } catch (e: IllegalStateException) {
+ Log.e(AgentService.TAG, "could not start the service after ${intent.action}", e)
+ }
+ }
+}
+
+/**
+ * Scripted setup: `adb shell am broadcast -a dev.code6x.otelagent.SET_CONFIG ...` (README).
+ * Only senders with the DUMP permission get here (the adb shell has it; normal apps do not).
+ * Extras: `json` (the config), or `json_b64` (the same, base64), or `reset` (true: back to the
+ * defaults); `start` (true: start the service too).
+ */
+class ConfigReceiver : BroadcastReceiver() {
+ override fun onReceive(context: Context, intent: Intent) {
+ if (intent.action != ACTION) return
+ val store = ConfigStore(context)
+ val msg = try {
+ val json = intent.getStringExtra("json") ?: intent.getStringExtra("json_b64")?.let { ConfigStore.decodeBase64(it) }
+ val text = when {
+ intent.getBooleanExtra("reset", false) -> {
+ store.reset()
+ "ok: local config removed, defaults in use"
+ }
+ json != null -> {
+ val loaded = store.import(json)
+ "ok: config imported" + if (loaded.warnings.isEmpty()) "" else "; warnings: " + loaded.warnings.joinToString("; ")
+ }
+ else -> throw ConfigException("give the config as extra json or json_b64, or reset true")
+ }
+ val applied = AgentService.reload()
+ var started = ""
+ if (!applied && intent.getBooleanExtra("start", false)) {
+ started = try {
+ AgentService.start(context)
+ "; service started"
+ } catch (e: IllegalStateException) {
+ "; service NOT started (${e.javaClass.simpleName}): open the app and press Start"
+ }
+ }
+ resultCode = Activity.RESULT_OK
+ text + (if (applied) "; applied" else "") + started
+ } catch (e: ConfigException) {
+ resultCode = Activity.RESULT_CANCELED
+ "error: ${e.message}"
+ } catch (e: IllegalArgumentException) {
+ resultCode = Activity.RESULT_CANCELED
+ "error: ${e.message}"
+ } catch (e: java.io.IOException) {
+ resultCode = Activity.RESULT_CANCELED
+ "error: could not save: ${e.message}"
+ }
+ resultData = msg
+ Log.i(AgentService.TAG, "config broadcast: $msg")
+ }
+
+ companion object {
+ const val ACTION = "dev.code6x.otelagent.SET_CONFIG"
+ }
+}
diff --git a/app/src/main/java/dev/code6x/otelagent/Setup.kt b/app/src/main/java/dev/code6x/otelagent/Setup.kt
new file mode 100644
index 0000000..8fb8b61
--- /dev/null
+++ b/app/src/main/java/dev/code6x/otelagent/Setup.kt
@@ -0,0 +1,80 @@
+package dev.code6x.otelagent
+
+import android.Manifest
+import android.app.AlarmManager
+import android.content.ComponentName
+import android.content.Context
+import android.content.Intent
+import android.content.pm.PackageManager
+import android.net.Uri
+import android.os.Build
+import android.os.PowerManager
+import android.provider.Settings
+import dev.code6x.otelagent.config.WakePolicy
+
+/** One line of the setup checklist. [done] is null when the app cannot read the setting. */
+data class SetupItem(val title: String, val help: String, val done: Boolean?, val open: Intent?)
+
+/** The setup checklist: the phone settings that keep the service alive and on time. */
+object Setup {
+ fun items(context: Context, wakePolicy: WakePolicy): List {
+ val pkg = context.packageName
+ val appInfo = Intent(Settings.ACTION_APPLICATION_DETAILS_SETTINGS, Uri.parse("package:$pkg"))
+ val out = mutableListOf()
+ if (Build.VERSION.SDK_INT >= 33) {
+ out += SetupItem(
+ "Notifications allowed",
+ "The service shows a quiet notification while it runs.",
+ context.checkSelfPermission(Manifest.permission.POST_NOTIFICATIONS) == PackageManager.PERMISSION_GRANTED,
+ Intent(Settings.ACTION_APP_NOTIFICATION_SETTINGS).putExtra(Settings.EXTRA_APP_PACKAGE, pkg),
+ )
+ }
+ val pm = context.getSystemService(PowerManager::class.java)
+ out += SetupItem(
+ "Battery optimisation off",
+ "Lets the service run and send in the background.",
+ pm.isIgnoringBatteryOptimizations(pkg),
+ @Suppress("BatteryLife")
+ Intent(Settings.ACTION_REQUEST_IGNORE_BATTERY_OPTIMIZATIONS, Uri.parse("package:$pkg")),
+ )
+ if (Build.VERSION.SDK_INT >= 31 && wakePolicy != WakePolicy.NEVER) {
+ val am = context.getSystemService(AlarmManager::class.java)
+ out += SetupItem(
+ "Alarms & reminders allowed",
+ "Exact alarms wake the CPU for each reading (wake_policy). Without them the app holds a wake lock instead.",
+ am.canScheduleExactAlarms(),
+ Intent(Settings.ACTION_REQUEST_SCHEDULE_EXACT_ALARM, Uri.parse("package:$pkg")),
+ )
+ }
+ val maker = Build.MANUFACTURER.lowercase()
+ if (maker in setOf("oneplus", "oppo", "realme")) {
+ out += SetupItem(
+ "OnePlus / OPPO: Allow background activity",
+ "App info > Battery > Allow background activity. Without it the system freezes the app a few minutes after start, even with a foreground service.",
+ null, appInfo,
+ )
+ }
+ if (maker in setOf("xiaomi", "redmi", "poco")) {
+ val autostart = Intent().setComponent(
+ ComponentName("com.miui.securitycenter", "com.miui.permcenter.autostart.AutoStartManagementActivity"),
+ )
+ out += SetupItem(
+ "Xiaomi: Autostart on",
+ "Security > Autostart: turn it on for this app, or it is not started after a reboot and may be killed.",
+ null,
+ if (autostart.resolveActivity(context.packageManager) != null) autostart else appInfo,
+ )
+ out += SetupItem(
+ "Xiaomi: Battery saver \"No restrictions\"",
+ "App info > Battery saver > No restrictions.",
+ null, appInfo,
+ )
+ }
+ out += SetupItem(
+ "VPN with split tunneling: include this app",
+ "If a VPN sends only some apps through it, include this app, or the receiver may not be reachable. The queue keeps the data meanwhile.",
+ null, Intent(Settings.ACTION_VPN_SETTINGS),
+ )
+ return out
+ }
+}
diff --git a/app/src/main/java/dev/code6x/otelagent/TickPlan.kt b/app/src/main/java/dev/code6x/otelagent/TickPlan.kt
new file mode 100644
index 0000000..0c184cf
--- /dev/null
+++ b/app/src/main/java/dev/code6x/otelagent/TickPlan.kt
@@ -0,0 +1,33 @@
+package dev.code6x.otelagent
+
+/**
+ * Which collectors read on a tick, and when the next tick is. Each collector has its own
+ * interval; one timer runs to the next due time. Times are elapsedRealtime milliseconds.
+ */
+class TickPlan {
+ private val nextDue = HashMap()
+
+ /** Forget all due times: every enabled collector reads on the next tick. */
+ fun reset() = nextDue.clear()
+
+ /**
+ * The collectors due at [now], from [intervals] (enabled collectors only, seconds).
+ * A collector is due a little early ([SLACK_MS]), so a timer that fires early still reads.
+ */
+ fun due(now: Long, intervals: Map): List {
+ nextDue.keys.retainAll(intervals.keys)
+ val due = intervals.keys.filter { k -> nextDue[k].let { it == null || now >= it - SLACK_MS } }
+ due.forEach { nextDue[it] = now + intervals.getValue(it) * 1000L }
+ return due
+ }
+
+ /** Milliseconds to the next tick, or null when no collector is enabled. */
+ fun nextDelay(now: Long, intervals: Map): Long? {
+ val times = intervals.keys.map { nextDue[it] ?: now }
+ return times.minOrNull()?.let { maxOf(0L, it - now) }
+ }
+
+ companion object {
+ const val SLACK_MS = 2000L
+ }
+}
diff --git a/app/src/main/java/dev/code6x/otelagent/collect/BatteryCollector.kt b/app/src/main/java/dev/code6x/otelagent/collect/BatteryCollector.kt
new file mode 100644
index 0000000..bd7f224
--- /dev/null
+++ b/app/src/main/java/dev/code6x/otelagent/collect/BatteryCollector.kt
@@ -0,0 +1,107 @@
+package dev.code6x.otelagent.collect
+
+import android.content.Context
+import android.content.Intent
+import android.content.IntentFilter
+import android.os.BatteryManager
+import android.os.Build
+
+/** Raw values as Android gives them; null when the phone does not report one. */
+data class BatterySnapshot(
+ val level: Int,
+ val scale: Int,
+ val voltageMv: Int?,
+ val temperatureTenthsC: Int?,
+ val status: Int,
+ val plugged: Int,
+ val health: Int,
+ val currentMicroA: Long?,
+ val chargeCounterMicroAh: Long?,
+ val cycleCount: Int?,
+)
+
+class BatteryCollector(private val context: Context) : Collector {
+ override val name = "battery"
+
+ override fun collect(): List = map(read(context) ?: return emptyList())
+
+ companion object {
+ val STATUSES = listOf("charging", "discharging", "not_charging", "full", "unknown")
+ val PLUGS = listOf("ac", "usb", "wireless", "dock", "none")
+ val HEALTHS = listOf("good", "overheat", "dead", "over_voltage", "failure", "cold", "unknown")
+
+ // Values of BatteryManager.BATTERY_STATUS_*, BATTERY_PLUGGED_* and BATTERY_HEALTH_*.
+ fun status(v: Int) = when (v) {
+ 2 -> "charging"
+ 3 -> "discharging"
+ 4 -> "not_charging"
+ 5 -> "full"
+ else -> "unknown"
+ }
+
+ /** The plug is a bit mask; more than one bit is rare. 0 is "none". */
+ fun plugs(mask: Int): Set {
+ if (mask == 0) return setOf("none")
+ val out = mutableSetOf()
+ if (mask and 1 != 0) out += "ac"
+ if (mask and 2 != 0) out += "usb"
+ if (mask and 4 != 0) out += "wireless"
+ if (mask and 8 != 0) out += "dock"
+ return out
+ }
+
+ fun health(v: Int) = when (v) {
+ 2 -> "good"
+ 3 -> "overheat"
+ 4 -> "dead"
+ 5 -> "over_voltage"
+ 6 -> "failure"
+ 7 -> "cold"
+ else -> "unknown"
+ }
+
+ fun map(s: BatterySnapshot): List {
+ val out = mutableListOf()
+ if (s.level >= 0 && s.scale > 0) out += Reading(Metrics.BATTERY_CHARGE, s.level.toDouble() / s.scale)
+ s.voltageMv?.takeIf { it > 0 }?.let { out += Reading(Metrics.BATTERY_VOLTAGE, it / 1000.0) }
+ s.temperatureTenthsC?.let { out += Reading(Metrics.BATTERY_TEMPERATURE, it / 10.0) }
+ s.currentMicroA?.let { out += Reading(Metrics.BATTERY_CURRENT, it / 1_000_000.0) }
+ s.chargeCounterMicroAh?.takeIf { it > 0 }?.let { out += Reading(Metrics.BATTERY_CHARGE_COUNTER, it / 1_000_000.0) }
+ s.cycleCount?.takeIf { it >= 0 }?.let { out += Reading(Metrics.BATTERY_CYCLES, it.toDouble()) }
+ out += states(Metrics.BATTERY_STATUS, "battery.status", STATUSES, setOf(status(s.status)))
+ out += states(Metrics.BATTERY_PLUG, "battery.plug", PLUGS, plugs(s.plugged))
+ out += states(Metrics.BATTERY_HEALTH, "battery.health", HEALTHS, setOf(health(s.health)))
+ return out
+ }
+
+ fun stickyIntent(context: Context): Intent? =
+ context.registerReceiver(null, IntentFilter(Intent.ACTION_BATTERY_CHANGED))
+
+ /** True when the phone is on any charger. */
+ fun isCharging(context: Context): Boolean =
+ (stickyIntent(context)?.getIntExtra(BatteryManager.EXTRA_PLUGGED, 0) ?: 0) != 0
+
+ fun read(context: Context): BatterySnapshot? {
+ val i = stickyIntent(context) ?: return null
+ val bm = context.getSystemService(BatteryManager::class.java)
+ fun intExtra(key: String) = i.getIntExtra(key, Int.MIN_VALUE).takeIf { it != Int.MIN_VALUE }
+ val current = bm?.getLongProperty(BatteryManager.BATTERY_PROPERTY_CURRENT_NOW)
+ ?.takeIf { it != Long.MIN_VALUE && it != Int.MIN_VALUE.toLong() }
+ val counter = bm?.getIntProperty(BatteryManager.BATTERY_PROPERTY_CHARGE_COUNTER)
+ ?.takeIf { it != Int.MIN_VALUE }?.toLong()
+ val cycles = if (Build.VERSION.SDK_INT >= 34) intExtra(BatteryManager.EXTRA_CYCLE_COUNT) else null
+ return BatterySnapshot(
+ level = i.getIntExtra(BatteryManager.EXTRA_LEVEL, -1),
+ scale = i.getIntExtra(BatteryManager.EXTRA_SCALE, 100),
+ voltageMv = intExtra(BatteryManager.EXTRA_VOLTAGE),
+ temperatureTenthsC = intExtra(BatteryManager.EXTRA_TEMPERATURE),
+ status = i.getIntExtra(BatteryManager.EXTRA_STATUS, 1),
+ plugged = i.getIntExtra(BatteryManager.EXTRA_PLUGGED, 0),
+ health = i.getIntExtra(BatteryManager.EXTRA_HEALTH, 1),
+ currentMicroA = current,
+ chargeCounterMicroAh = counter,
+ cycleCount = cycles,
+ )
+ }
+ }
+}
diff --git a/app/src/main/java/dev/code6x/otelagent/collect/BootCollector.kt b/app/src/main/java/dev/code6x/otelagent/collect/BootCollector.kt
new file mode 100644
index 0000000..6219322
--- /dev/null
+++ b/app/src/main/java/dev/code6x/otelagent/collect/BootCollector.kt
@@ -0,0 +1,46 @@
+package dev.code6x.otelagent.collect
+
+import android.content.Context
+import android.os.SystemClock
+import android.provider.Settings
+
+data class BootSnapshot(val elapsedMs: Long, val wallMs: Long, val bootCount: Int?) {
+ /** Wall-clock time of the boot, in Unix seconds. */
+ val bootTimeS: Long get() = (wallMs - elapsedMs) / 1000
+}
+
+class BootCollector(private val context: Context) : Collector {
+ override val name = "boot"
+
+ override fun collect(): List = map(read(context))
+
+ companion object {
+ fun map(s: BootSnapshot): List {
+ val out = mutableListOf(
+ Reading(Metrics.UPTIME, s.elapsedMs / 1000.0),
+ Reading(Metrics.BOOT_TIME, s.bootTimeS.toDouble()),
+ )
+ s.bootCount?.let { out += Reading(Metrics.BOOT_COUNT, it.toDouble()) }
+ return out
+ }
+
+ fun read(context: Context): BootSnapshot {
+ val count = try {
+ Settings.Global.getInt(context.contentResolver, Settings.Global.BOOT_COUNT)
+ } catch (e: Settings.SettingNotFoundException) {
+ null
+ }
+ return BootSnapshot(SystemClock.elapsedRealtime(), System.currentTimeMillis(), count)
+ }
+
+ /**
+ * True when [now] is a boot the app has not reported yet. The boot count decides when the
+ * phone has one; else the boot time (it moves a little with clock changes, so 2 min slack).
+ */
+ fun isNewBoot(lastCount: Int?, lastBootTimeS: Long?, now: BootSnapshot): Boolean {
+ if (lastBootTimeS == null) return true
+ if (now.bootCount != null && lastCount != null) return now.bootCount != lastCount
+ return kotlin.math.abs(now.bootTimeS - lastBootTimeS) > 120
+ }
+ }
+}
diff --git a/app/src/main/java/dev/code6x/otelagent/collect/Collector.kt b/app/src/main/java/dev/code6x/otelagent/collect/Collector.kt
new file mode 100644
index 0000000..79763bb
--- /dev/null
+++ b/app/src/main/java/dev/code6x/otelagent/collect/Collector.kt
@@ -0,0 +1,23 @@
+package dev.code6x.otelagent.collect
+
+import android.content.Context
+
+/** A group of readings that can be turned on or off, with its own interval. */
+interface Collector {
+ val name: String
+ fun collect(): List
+}
+
+object Collectors {
+ fun create(context: Context): List {
+ val c = context.applicationContext
+ return listOf(
+ BatteryCollector(c),
+ PowerCollector(c),
+ BootCollector(c),
+ NetworkCollector(c),
+ DeviceCollector(c),
+ ThermalCollector(c),
+ )
+ }
+}
diff --git a/app/src/main/java/dev/code6x/otelagent/collect/DeviceCollector.kt b/app/src/main/java/dev/code6x/otelagent/collect/DeviceCollector.kt
new file mode 100644
index 0000000..7eef47d
--- /dev/null
+++ b/app/src/main/java/dev/code6x/otelagent/collect/DeviceCollector.kt
@@ -0,0 +1,43 @@
+package dev.code6x.otelagent.collect
+
+import android.app.ActivityManager
+import android.content.Context
+import android.os.Environment
+import android.os.StatFs
+
+data class DeviceSnapshot(
+ val memTotal: Long,
+ val memAvailable: Long,
+ val lowMemory: Boolean,
+ val dataTotal: Long,
+ val dataFree: Long,
+)
+
+/** RAM and the space on /data. */
+class DeviceCollector(private val context: Context) : Collector {
+ override val name = "device"
+
+ override fun collect(): List {
+ val am = context.getSystemService(ActivityManager::class.java) ?: return emptyList()
+ val mi = ActivityManager.MemoryInfo().also { am.getMemoryInfo(it) }
+ val fs = StatFs(Environment.getDataDirectory().path)
+ return map(DeviceSnapshot(mi.totalMem, mi.availMem, mi.lowMemory, fs.totalBytes, fs.availableBytes))
+ }
+
+ companion object {
+ const val MOUNT = "/data"
+
+ fun map(s: DeviceSnapshot): List {
+ val mount = mapOf("system.filesystem.mountpoint" to MOUNT)
+ return listOf(
+ Reading(Metrics.MEMORY_LIMIT, s.memTotal.toDouble()),
+ Reading(Metrics.MEMORY_USAGE, s.memAvailable.toDouble(), mapOf("system.memory.state" to "free")),
+ Reading(Metrics.MEMORY_USAGE, (s.memTotal - s.memAvailable).toDouble(), mapOf("system.memory.state" to "used")),
+ Reading(Metrics.MEMORY_LOW, flag(s.lowMemory)),
+ Reading(Metrics.FS_LIMIT, s.dataTotal.toDouble(), mount),
+ Reading(Metrics.FS_USAGE, s.dataFree.toDouble(), mount + ("system.filesystem.state" to "free")),
+ Reading(Metrics.FS_USAGE, (s.dataTotal - s.dataFree).toDouble(), mount + ("system.filesystem.state" to "used")),
+ )
+ }
+ }
+}
diff --git a/app/src/main/java/dev/code6x/otelagent/collect/Metrics.kt b/app/src/main/java/dev/code6x/otelagent/collect/Metrics.kt
new file mode 100644
index 0000000..58e451a
--- /dev/null
+++ b/app/src/main/java/dev/code6x/otelagent/collect/Metrics.kt
@@ -0,0 +1,72 @@
+package dev.code6x.otelagent.collect
+
+/** One metric: name, unit (UCUM, as OpenTelemetry uses) and description. All are gauges. */
+data class MetricDef(val name: String, val unit: String, val description: String)
+
+/** One value read by a collector. */
+data class Reading(val def: MetricDef, val value: Double, val attributes: Map = emptyMap())
+
+/** Every metric the app sends. The README has the same table. */
+object Metrics {
+ // battery
+ val BATTERY_CHARGE = MetricDef("hw.battery.charge", "1", "Battery level, 0 to 1")
+ val BATTERY_VOLTAGE = MetricDef("device.battery.voltage", "V", "Battery voltage")
+ val BATTERY_TEMPERATURE = MetricDef("device.battery.temperature", "Cel", "Battery temperature")
+ val BATTERY_CURRENT = MetricDef("device.battery.current", "A", "Battery current; positive is into the battery on most phones")
+ val BATTERY_CHARGE_COUNTER = MetricDef("device.battery.charge_counter", "A.h", "Remaining battery charge")
+ val BATTERY_CYCLES = MetricDef("device.battery.cycle_count", "{cycle}", "Battery charge cycles (Android 14+)")
+ val BATTERY_STATUS = MetricDef("device.battery.status", "1", "1 for the current battery status, 0 for the others")
+ val BATTERY_PLUG = MetricDef("device.battery.plug", "1", "1 for the current power source, 0 for the others")
+ val BATTERY_HEALTH = MetricDef("device.battery.health", "1", "1 for the current battery health, 0 for the others")
+
+ // power
+ val SCREEN_ON = MetricDef("device.screen.on", "1", "1 when the screen is on")
+ val POWER_SAVE = MetricDef("device.power.save_mode", "1", "1 when battery saver is on")
+ val IDLE = MetricDef("device.power.idle", "1", "1 when the device is in idle (Doze) mode")
+
+ // boot
+ val UPTIME = MetricDef("system.uptime", "s", "Time since boot, deep sleep included")
+ val BOOT_COUNT = MetricDef("device.boot.count", "{boot}", "Boots since the phone was set up")
+ val BOOT_TIME = MetricDef("device.boot.time", "s", "Time of the last boot, Unix seconds")
+
+ // network
+ val NETWORK_CONNECTED = MetricDef("device.network.connected", "1", "1 when there is an active network")
+ val NETWORK_TYPE = MetricDef("device.network.type", "1", "1 for each transport of the active network, 0 for the others")
+ val WIFI_CONNECTED = MetricDef("device.wifi.connected", "1", "1 when Wi-Fi is connected")
+ val WIFI_RSSI = MetricDef("device.wifi.rssi", "dBm", "Wi-Fi signal strength")
+ val WIFI_LINK_SPEED = MetricDef("device.wifi.link_speed", "Mbit/s", "Wi-Fi link speed")
+
+ // device
+ val MEMORY_LIMIT = MetricDef("system.memory.limit", "By", "Total RAM")
+ val MEMORY_USAGE = MetricDef("system.memory.usage", "By", "RAM by state: free (available to apps) and used")
+ val MEMORY_LOW = MetricDef("device.memory.low", "1", "1 when the system is low on memory")
+ val FS_LIMIT = MetricDef("system.filesystem.limit", "By", "Total size of the file system")
+ val FS_USAGE = MetricDef("system.filesystem.usage", "By", "File system space by state: free and used")
+
+ // thermal
+ val THERMAL_STATUS = MetricDef("device.thermal.status", "1", "Thermal status: 0 none, 1 light, 2 moderate, 3 severe, 4 critical, 5 emergency, 6 shutdown")
+ val THERMAL_HEADROOM = MetricDef("device.thermal.headroom", "1", "Thermal headroom; 1.0 is where severe throttling starts")
+
+ // the agent itself (sent with every reading)
+ val AGENT_START_TIME = MetricDef("device.agent.start_time", "s", "Start time of the app process, Unix seconds; a new value is a new process")
+ val AGENT_QUEUE_SIZE = MetricDef("device.agent.queue.size", "By", "Bytes waiting in the disk queue")
+ val AGENT_QUEUE_DROPPED = MetricDef("device.agent.queue.dropped", "{file}", "Queue files dropped (size cap or max age) since the process started")
+ val AGENT_WAKE = MetricDef("device.agent.wake", "1", "1 when the timer wakes the CPU for readings (wake_policy)")
+
+ val ALL = listOf(
+ BATTERY_CHARGE, BATTERY_VOLTAGE, BATTERY_TEMPERATURE, BATTERY_CURRENT, BATTERY_CHARGE_COUNTER,
+ BATTERY_CYCLES, BATTERY_STATUS, BATTERY_PLUG, BATTERY_HEALTH,
+ SCREEN_ON, POWER_SAVE, IDLE,
+ UPTIME, BOOT_COUNT, BOOT_TIME,
+ NETWORK_CONNECTED, NETWORK_TYPE, WIFI_CONNECTED, WIFI_RSSI, WIFI_LINK_SPEED,
+ MEMORY_LIMIT, MEMORY_USAGE, MEMORY_LOW, FS_LIMIT, FS_USAGE,
+ THERMAL_STATUS, THERMAL_HEADROOM,
+ AGENT_START_TIME, AGENT_QUEUE_SIZE, AGENT_QUEUE_DROPPED, AGENT_WAKE,
+ )
+}
+
+internal fun flag(b: Boolean) = if (b) 1.0 else 0.0
+
+/** A state metric: one point per possible state, 1 for the current one, 0 for the others. */
+internal fun states(def: MetricDef, attr: String, all: List, current: Set): List =
+ all.map { Reading(def, flag(it in current), mapOf(attr to it)) }
diff --git a/app/src/main/java/dev/code6x/otelagent/collect/NetworkCollector.kt b/app/src/main/java/dev/code6x/otelagent/collect/NetworkCollector.kt
new file mode 100644
index 0000000..be03912
--- /dev/null
+++ b/app/src/main/java/dev/code6x/otelagent/collect/NetworkCollector.kt
@@ -0,0 +1,62 @@
+package dev.code6x.otelagent.collect
+
+import android.content.Context
+import android.net.ConnectivityManager
+import android.net.NetworkCapabilities
+import android.net.wifi.SupplicantState
+import android.net.wifi.WifiManager
+
+data class NetworkSnapshot(
+ val connected: Boolean,
+ val types: Set,
+ val wifiConnected: Boolean,
+ val rssiDbm: Int?,
+ val linkSpeedMbps: Int?,
+)
+
+/** Wi-Fi signal and link speed, active network and its transports. No SSID or BSSID: they need location. */
+class NetworkCollector(private val context: Context) : Collector {
+ override val name = "network"
+
+ override fun collect(): List = map(read())
+
+ private fun read(): NetworkSnapshot {
+ val cm = context.getSystemService(ConnectivityManager::class.java)
+ val caps = cm?.activeNetwork?.let { cm.getNetworkCapabilities(it) }
+ val types = mutableSetOf()
+ if (caps != null) {
+ if (caps.hasTransport(NetworkCapabilities.TRANSPORT_WIFI)) types += "wifi"
+ if (caps.hasTransport(NetworkCapabilities.TRANSPORT_CELLULAR)) types += "cell"
+ if (caps.hasTransport(NetworkCapabilities.TRANSPORT_ETHERNET)) types += "wired"
+ if (caps.hasTransport(NetworkCapabilities.TRANSPORT_VPN)) types += "vpn"
+ if (caps.hasTransport(NetworkCapabilities.TRANSPORT_BLUETOOTH)) types += "bluetooth"
+ }
+ val wm = context.getSystemService(WifiManager::class.java)
+ @Suppress("DEPRECATION")
+ val info = if (wm?.isWifiEnabled == true) wm.connectionInfo else null
+ // Without location permission Android hides networkId (always -1), so "connected"
+ // comes from the network's transports and the supplicant state. RSSI -127: no value.
+ @Suppress("DEPRECATION")
+ val wifiConnected = "wifi" in types || info?.supplicantState == SupplicantState.COMPLETED
+ return NetworkSnapshot(
+ connected = caps != null,
+ types = types,
+ wifiConnected = wifiConnected,
+ rssiDbm = info?.rssi?.takeIf { wifiConnected && it > -127 },
+ linkSpeedMbps = info?.linkSpeed?.takeIf { wifiConnected && it > 0 },
+ )
+ }
+
+ companion object {
+ val TYPES = listOf("wifi", "cell", "wired", "vpn", "bluetooth")
+
+ fun map(s: NetworkSnapshot): List {
+ val out = mutableListOf(Reading(Metrics.NETWORK_CONNECTED, flag(s.connected)))
+ out += states(Metrics.NETWORK_TYPE, "network.connection.type", TYPES, s.types)
+ out += Reading(Metrics.WIFI_CONNECTED, flag(s.wifiConnected))
+ s.rssiDbm?.let { out += Reading(Metrics.WIFI_RSSI, it.toDouble()) }
+ s.linkSpeedMbps?.let { out += Reading(Metrics.WIFI_LINK_SPEED, it.toDouble()) }
+ return out
+ }
+ }
+}
diff --git a/app/src/main/java/dev/code6x/otelagent/collect/PowerCollector.kt b/app/src/main/java/dev/code6x/otelagent/collect/PowerCollector.kt
new file mode 100644
index 0000000..95b31a9
--- /dev/null
+++ b/app/src/main/java/dev/code6x/otelagent/collect/PowerCollector.kt
@@ -0,0 +1,23 @@
+package dev.code6x.otelagent.collect
+
+import android.content.Context
+import android.os.PowerManager
+
+data class PowerSnapshot(val screenOn: Boolean, val powerSave: Boolean, val idle: Boolean)
+
+class PowerCollector(private val context: Context) : Collector {
+ override val name = "power"
+
+ override fun collect(): List {
+ val pm = context.getSystemService(PowerManager::class.java) ?: return emptyList()
+ return map(PowerSnapshot(pm.isInteractive, pm.isPowerSaveMode, pm.isDeviceIdleMode))
+ }
+
+ companion object {
+ fun map(s: PowerSnapshot) = listOf(
+ Reading(Metrics.SCREEN_ON, flag(s.screenOn)),
+ Reading(Metrics.POWER_SAVE, flag(s.powerSave)),
+ Reading(Metrics.IDLE, flag(s.idle)),
+ )
+ }
+}
diff --git a/app/src/main/java/dev/code6x/otelagent/collect/ThermalCollector.kt b/app/src/main/java/dev/code6x/otelagent/collect/ThermalCollector.kt
new file mode 100644
index 0000000..1061ef7
--- /dev/null
+++ b/app/src/main/java/dev/code6x/otelagent/collect/ThermalCollector.kt
@@ -0,0 +1,29 @@
+package dev.code6x.otelagent.collect
+
+import android.content.Context
+import android.os.Build
+import android.os.PowerManager
+
+data class ThermalSnapshot(val status: Int?, val headroom: Float?)
+
+/** Thermal status (Android 10+) and headroom (Android 11+), from PowerManager. */
+class ThermalCollector(private val context: Context) : Collector {
+ override val name = "thermal"
+
+ override fun collect(): List {
+ val pm = context.getSystemService(PowerManager::class.java) ?: return emptyList()
+ val status = if (Build.VERSION.SDK_INT >= 29) pm.currentThermalStatus else null
+ val headroom = if (Build.VERSION.SDK_INT >= 30) pm.getThermalHeadroom(0) else null
+ return map(ThermalSnapshot(status, headroom))
+ }
+
+ companion object {
+ fun map(s: ThermalSnapshot): List {
+ val out = mutableListOf()
+ s.status?.takeIf { it >= 0 }?.let { out += Reading(Metrics.THERMAL_STATUS, it.toDouble()) }
+ // NaN: the phone has no value (or it was asked too often).
+ s.headroom?.takeIf { !it.isNaN() }?.let { out += Reading(Metrics.THERMAL_HEADROOM, it.toDouble()) }
+ return out
+ }
+ }
+}
diff --git a/app/src/main/java/dev/code6x/otelagent/config/AgentConfig.kt b/app/src/main/java/dev/code6x/otelagent/config/AgentConfig.kt
new file mode 100644
index 0000000..5b84f1f
--- /dev/null
+++ b/app/src/main/java/dev/code6x/otelagent/config/AgentConfig.kt
@@ -0,0 +1,53 @@
+package dev.code6x.otelagent.config
+
+/** When the timer may wake the CPU for a reading. See the README for what each value costs. */
+enum class WakePolicy(val key: String) {
+ NEVER("never"),
+ WHEN_CHARGING("when_charging"),
+ ALWAYS("always"),
+ ;
+
+ /** True when this policy wakes the CPU, given whether the phone is on a charger. */
+ fun wakes(charging: Boolean): Boolean = when (this) {
+ NEVER -> false
+ WHEN_CHARGING -> charging
+ ALWAYS -> true
+ }
+
+ companion object {
+ fun parse(key: String): WakePolicy? = entries.firstOrNull { it.key == key }
+ }
+}
+
+data class ExporterConfig(
+ /** Full URL of the OTLP/HTTP metrics endpoint. Empty: data stays in the queue. */
+ val endpoint: String,
+ /** Full URL of the OTLP/HTTP logs endpoint (boot records). Empty: no log records. */
+ val logsEndpoint: String,
+ val protocol: String,
+ val headers: Map,
+ val timeoutSeconds: Int,
+)
+
+data class CollectorConfig(val enabled: Boolean, val intervalSeconds: Int)
+
+data class BufferConfig(val maxBytes: Long, val maxAgeSeconds: Long)
+
+data class AgentConfig(
+ val exporter: ExporterConfig,
+ val deviceId: String,
+ val attributes: Map,
+ val collectors: Map,
+ val buffer: BufferConfig,
+ val wakePolicy: WakePolicy,
+) {
+ fun collector(name: String): CollectorConfig =
+ collectors[name] ?: CollectorConfig(enabled = false, intervalSeconds = DEFAULT_INTERVAL)
+
+ companion object {
+ const val DEFAULT_INTERVAL = 60
+ val COLLECTORS = listOf("battery", "power", "boot", "network", "device", "thermal")
+ }
+}
+
+class ConfigException(message: String) : Exception(message)
diff --git a/app/src/main/java/dev/code6x/otelagent/config/ConfigLoader.kt b/app/src/main/java/dev/code6x/otelagent/config/ConfigLoader.kt
new file mode 100644
index 0000000..ff1501c
--- /dev/null
+++ b/app/src/main/java/dev/code6x/otelagent/config/ConfigLoader.kt
@@ -0,0 +1,186 @@
+package dev.code6x.otelagent.config
+
+import org.json.JSONArray
+import org.json.JSONException
+import org.json.JSONObject
+
+/** Where a config value came from. Later sources win. */
+enum class Source(val label: String) {
+ DEFAULT("default"),
+ LOCAL_FILE("local file"),
+}
+
+/** One value of the merged config, with its source. The path is the list of JSON keys. */
+data class ConfigEntry(val path: List, val value: Any, val source: Source) {
+ val key: String get() = path.joinToString(" > ")
+}
+
+/** The config in use: the typed config, every value with its source, and warnings. */
+data class LoadedConfig(
+ val config: AgentConfig,
+ val entries: List,
+ val warnings: List,
+)
+
+/**
+ * Reads config documents (JSON), merges them over the built-in defaults and builds the
+ * typed [AgentConfig]. The same document shape is meant for managed configurations and
+ * OpAMP later (#3): each source is one more layer.
+ */
+object ConfigLoader {
+ val DEFAULTS_JSON = """
+ {
+ "exporter": {
+ "endpoint": "",
+ "logs_endpoint": "",
+ "protocol": "http/protobuf",
+ "headers": {},
+ "timeout": 10
+ },
+ "resource": {
+ "device.id": "",
+ "attributes": {}
+ },
+ "collectors": {
+ "battery": {"enabled": true, "interval": 60},
+ "power": {"enabled": true, "interval": 60},
+ "boot": {"enabled": true, "interval": 60},
+ "network": {"enabled": true, "interval": 60},
+ "device": {"enabled": true, "interval": 60},
+ "thermal": {"enabled": true, "interval": 60}
+ },
+ "buffer": {
+ "max_bytes": 20971520,
+ "max_age": 604800
+ },
+ "wake_policy": "when_charging"
+ }
+ """.trimIndent()
+
+ /** Objects whose keys are free (any name, text values). */
+ private val FREE_MAPS = setOf(listOf("exporter", "headers"), listOf("resource", "attributes"))
+
+ private val defaultsLayer: Map, Any> by lazy { flatten(DEFAULTS_JSON) }
+
+ const val MIN_INTERVAL = 10
+ const val MAX_INTERVAL = 86400
+
+ /** Turns one JSON document into leaf values by path. Throws [ConfigException]. */
+ fun flatten(json: String): Map, Any> {
+ val root = try {
+ JSONObject(json)
+ } catch (e: JSONException) {
+ throw ConfigException("not valid JSON: ${e.message}")
+ }
+ val out = LinkedHashMap, Any>()
+ walk(root, emptyList(), out)
+ return out
+ }
+
+ private fun walk(obj: JSONObject, path: List, out: MutableMap, Any>) {
+ for (k in obj.keys()) {
+ val p = path + k
+ when (val v = obj.get(k)) {
+ is JSONObject -> walk(v, p, out)
+ is JSONArray -> throw ConfigException("${p.joinToString(" > ")}: a list is not allowed here")
+ JSONObject.NULL -> {}
+ else -> out[p] = v
+ }
+ }
+ }
+
+ /** Merges the layers over the defaults (later layers win) and builds the config. */
+ fun load(layers: List>): LoadedConfig {
+ val merged = LinkedHashMap, ConfigEntry>()
+ defaultsLayer.forEach { (p, v) -> merged[p] = ConfigEntry(p, v, Source.DEFAULT) }
+ val warnings = mutableListOf()
+ for ((source, json) in layers) {
+ for ((p, v) in flatten(json)) {
+ if (!known(p)) {
+ warnings += "${p.joinToString(" > ")} (${source.label}): unknown key, not used"
+ continue
+ }
+ merged[p] = ConfigEntry(p, v, source)
+ }
+ }
+ val config = build(merged.mapValues { it.value.value })
+ return LoadedConfig(config, merged.values.toList(), warnings)
+ }
+
+ private fun known(p: List): Boolean {
+ if (FREE_MAPS.any { p.size == it.size + 1 && p.subList(0, it.size) == it }) return true
+ if (p.size == 3 && p[0] == "collectors") return p[1] in AgentConfig.COLLECTORS && p[2] in setOf("enabled", "interval")
+ return p in defaultsLayer.keys
+ }
+
+ private fun build(m: Map, Any>): AgentConfig {
+ fun name(p: List) = p.joinToString(" > ")
+ fun str(vararg p: String): String = when (val v = m[p.toList()]) {
+ is String -> v.trim()
+ null -> ""
+ else -> throw ConfigException("${name(p.toList())}: must be text")
+ }
+ fun long(vararg p: String, min: Long, max: Long): Long {
+ val v = m[p.toList()]
+ val n = (v as? Number) ?: throw ConfigException("${name(p.toList())}: must be a number")
+ if (n.toDouble() != Math.floor(n.toDouble())) throw ConfigException("${name(p.toList())}: must be a whole number")
+ val l = n.toLong()
+ if (l < min || l > max) throw ConfigException("${name(p.toList())}: must be from $min to $max")
+ return l
+ }
+ fun bool(vararg p: String): Boolean =
+ m[p.toList()] as? Boolean ?: throw ConfigException("${name(p.toList())}: must be true or false")
+ fun freeMap(prefix: List): Map {
+ val out = LinkedHashMap()
+ for ((p, v) in m) {
+ if (p.size == prefix.size + 1 && p.subList(0, prefix.size) == prefix) {
+ out[p.last()] = v as? String ?: throw ConfigException("${name(p)}: must be text")
+ }
+ }
+ return out
+ }
+
+ val endpoint = str("exporter", "endpoint")
+ val logsEndpoint = str("exporter", "logs_endpoint")
+ for ((key, url) in listOf("endpoint" to endpoint, "logs_endpoint" to logsEndpoint)) {
+ if (url.isNotEmpty() && !url.startsWith("http://") && !url.startsWith("https://")) {
+ throw ConfigException("exporter > $key: must start with http:// or https://")
+ }
+ }
+ val protocol = str("exporter", "protocol")
+ if (protocol != "http/protobuf") throw ConfigException("exporter > protocol: only http/protobuf is supported")
+ val wakeKey = str("wake_policy")
+ val wake = WakePolicy.parse(wakeKey)
+ ?: throw ConfigException("wake_policy: must be one of ${WakePolicy.entries.joinToString { it.key }}")
+ val collectors = AgentConfig.COLLECTORS.associateWith { c ->
+ CollectorConfig(
+ enabled = bool("collectors", c, "enabled"),
+ intervalSeconds = long("collectors", c, "interval", min = MIN_INTERVAL.toLong(), max = MAX_INTERVAL.toLong()).toInt(),
+ )
+ }
+ return AgentConfig(
+ exporter = ExporterConfig(
+ endpoint = endpoint,
+ logsEndpoint = logsEndpoint,
+ protocol = protocol,
+ headers = freeMap(listOf("exporter", "headers")),
+ timeoutSeconds = long("exporter", "timeout", min = 1, max = 300).toInt(),
+ ),
+ deviceId = str("resource", "device.id"),
+ attributes = freeMap(listOf("resource", "attributes")),
+ collectors = collectors,
+ buffer = BufferConfig(
+ maxBytes = long("buffer", "max_bytes", min = 64L * 1024, max = 1024L * 1024 * 1024),
+ maxAgeSeconds = long("buffer", "max_age", min = 60, max = 90L * 86400),
+ ),
+ wakePolicy = wake,
+ )
+ }
+
+ /** Text for the screen: header values are hidden, as they often hold a token. */
+ fun display(entry: ConfigEntry): String {
+ val hidden = entry.path.size == 3 && entry.path[0] == "exporter" && entry.path[1] == "headers"
+ val value = if (hidden) "(hidden)" else if (entry.value is String) "\"${entry.value}\"" else entry.value.toString()
+ return "${entry.key} = $value [${entry.source.label}]"
+ }
+}
diff --git a/app/src/main/java/dev/code6x/otelagent/config/ConfigStore.kt b/app/src/main/java/dev/code6x/otelagent/config/ConfigStore.kt
new file mode 100644
index 0000000..1652f31
--- /dev/null
+++ b/app/src/main/java/dev/code6x/otelagent/config/ConfigStore.kt
@@ -0,0 +1,47 @@
+package dev.code6x.otelagent.config
+
+import android.content.Context
+import android.util.Base64
+import android.util.Log
+import java.io.File
+
+/** The local config file (imported by file, share sheet, QR code text or adb broadcast). */
+class ConfigStore(context: Context) {
+ private val file = File(context.filesDir, "config.json")
+
+ /** The config in use. A broken local file is ignored (with a warning), so the app still runs. */
+ fun load(): LoadedConfig {
+ val local = if (file.exists()) file.readText() else null
+ if (local != null) {
+ try {
+ return ConfigLoader.load(listOf(Source.LOCAL_FILE to local))
+ } catch (e: ConfigException) {
+ Log.e(TAG, "local config not used: ${e.message}")
+ val d = ConfigLoader.load(emptyList())
+ return d.copy(warnings = d.warnings + "local file not used: ${e.message}")
+ }
+ }
+ return ConfigLoader.load(emptyList())
+ }
+
+ /** Checks the JSON and saves it as the local file. Throws [ConfigException]; nothing changes then. */
+ fun import(json: String): LoadedConfig {
+ val loaded = ConfigLoader.load(listOf(Source.LOCAL_FILE to json))
+ val tmp = File(file.parentFile, "config.json.tmp")
+ tmp.writeText(json)
+ if (!tmp.renameTo(file)) throw ConfigException("could not save the config file")
+ Log.i(TAG, "local config imported (${loaded.warnings.size} warnings)")
+ return loaded
+ }
+
+ fun reset() {
+ file.delete()
+ Log.i(TAG, "local config removed, defaults in use")
+ }
+
+ companion object {
+ const val TAG = "OtelAgent"
+
+ fun decodeBase64(text: String): String = String(Base64.decode(text.trim(), Base64.DEFAULT), Charsets.UTF_8)
+ }
+}
diff --git a/app/src/main/java/dev/code6x/otelagent/export/FileQueue.kt b/app/src/main/java/dev/code6x/otelagent/export/FileQueue.kt
new file mode 100644
index 0000000..6c35364
--- /dev/null
+++ b/app/src/main/java/dev/code6x/otelagent/export/FileQueue.kt
@@ -0,0 +1,85 @@
+package dev.code6x.otelagent.export
+
+import java.io.File
+
+/**
+ * The own disk queue (from the spike, docs/spike.md): one file per OTLP/HTTP request body,
+ * named by the time it was written, so the files sort in order. A sender posts them in order
+ * and deletes a file only after a 2xx answer. The files live through network cuts and app
+ * restarts. A size cap and a max age drop the oldest files first.
+ */
+class FileQueue(
+ val dir: File,
+ @Volatile var maxBytes: Long,
+ @Volatile var maxAgeMs: Long,
+ private val clock: () -> Long = System::currentTimeMillis,
+) {
+ /** Files dropped by the cap or the age limit since this object was made. */
+ @Volatile var dropped: Long = 0
+ private set
+
+ init {
+ dir.mkdirs()
+ // A crash between write and rename leaves a .tmp file; it is not complete.
+ dir.listFiles { f -> f.name.endsWith(".tmp") }?.forEach { it.delete() }
+ }
+
+ @Synchronized
+ fun add(body: ByteArray): File {
+ val now = clock()
+ var seq = 0
+ var target: File
+ do {
+ target = File(dir, String.format(java.util.Locale.ROOT, "%013d-%04d.pb", now, seq++))
+ } while (target.exists())
+ val tmp = File(dir, target.name + ".tmp")
+ tmp.writeBytes(body)
+ if (!tmp.renameTo(target)) {
+ tmp.delete()
+ throw java.io.IOException("could not rename ${tmp.name}")
+ }
+ trim()
+ return target
+ }
+
+ /** Queued files, oldest first. */
+ @Synchronized
+ fun files(): List = dir.listFiles { f -> f.name.endsWith(".pb") }?.sortedBy { it.name } ?: emptyList()
+
+ @Synchronized
+ fun sizeBytes(): Long = files().sumOf { it.length() }
+
+ /** Drops files older than the max age, then the oldest files until the queue fits the cap. */
+ @Synchronized
+ fun trim(): Int {
+ var n = 0
+ val files = files().toMutableList()
+ val oldest = clock() - maxAgeMs
+ val it = files.iterator()
+ while (it.hasNext()) {
+ val f = it.next()
+ if (timeOf(f) < oldest) {
+ if (f.delete()) n++
+ it.remove()
+ }
+ }
+ var total = files.sumOf { it.length() }
+ for (f in files) {
+ if (total <= maxBytes) break
+ total -= f.length()
+ if (f.delete()) n++
+ }
+ dropped += n
+ return n
+ }
+
+ @Synchronized
+ fun remove(f: File) {
+ f.delete()
+ }
+
+ companion object {
+ /** Write time of a queue file, from its name (milliseconds). */
+ fun timeOf(f: File): Long = f.name.substringBefore('-').toLongOrNull() ?: 0
+ }
+}
diff --git a/app/src/main/java/dev/code6x/otelagent/export/OtlpEncoder.kt b/app/src/main/java/dev/code6x/otelagent/export/OtlpEncoder.kt
new file mode 100644
index 0000000..6fa7ef7
--- /dev/null
+++ b/app/src/main/java/dev/code6x/otelagent/export/OtlpEncoder.kt
@@ -0,0 +1,103 @@
+package dev.code6x.otelagent.export
+
+import dev.code6x.otelagent.collect.Reading
+import io.opentelemetry.api.common.Attributes
+import io.opentelemetry.api.common.AttributesBuilder
+import io.opentelemetry.api.logs.Severity
+import io.opentelemetry.api.trace.SpanContext
+import io.opentelemetry.exporter.internal.otlp.logs.LogsRequestMarshaler
+import io.opentelemetry.exporter.internal.otlp.metrics.MetricsRequestMarshaler
+import io.opentelemetry.sdk.common.InstrumentationScopeInfo
+import io.opentelemetry.sdk.logs.data.Body
+import io.opentelemetry.sdk.logs.data.LogRecordData
+import io.opentelemetry.sdk.metrics.internal.data.ImmutableDoublePointData
+import io.opentelemetry.sdk.metrics.internal.data.ImmutableGaugeData
+import io.opentelemetry.sdk.metrics.internal.data.ImmutableMetricData
+import io.opentelemetry.sdk.resources.Resource
+import java.io.ByteArrayOutputStream
+
+/**
+ * Builds OTLP/HTTP protobuf request bodies. The readings are turned into gauge points by hand
+ * (not through a MeterProvider), so each point carries the wall-clock time of its reading,
+ * and a collector that is turned off sends nothing at once.
+ */
+class OtlpEncoder(val resource: Resource, version: String) {
+ private val scope = InstrumentationScopeInfo.builder(SCOPE).setVersion(version).build()
+
+ fun metrics(readings: List, epochMs: Long): ByteArray {
+ val nanos = epochMs * 1_000_000
+ val data = readings.groupBy { it.def }.map { (def, rs) ->
+ val points = rs.map { ImmutableDoublePointData.create(nanos, nanos, attributes(it.attributes), it.value) }
+ ImmutableMetricData.createDoubleGauge(resource, scope, def.name, def.description, def.unit, ImmutableGaugeData.create(points))
+ }
+ val out = ByteArrayOutputStream()
+ MetricsRequestMarshaler.create(data).writeBinaryTo(out)
+ return out.toByteArray()
+ }
+
+ fun log(eventName: String, body: String, attrs: Map, epochMs: Long, observedMs: Long): ByteArray {
+ val record = SimpleLog(resource, scope, eventName, body, attributes(attrs), epochMs * 1_000_000, observedMs * 1_000_000)
+ val out = ByteArrayOutputStream()
+ LogsRequestMarshaler.create(listOf(record)).writeBinaryTo(out)
+ return out.toByteArray()
+ }
+
+ companion object {
+ const val SCOPE = "dev.code6x.otelagent"
+
+ fun attributes(map: Map): Attributes {
+ val b: AttributesBuilder = Attributes.builder()
+ map.forEach { (k, v) -> b.put(k, v) }
+ return b.build()
+ }
+
+ /** The resource: fixed device facts, then the attributes from config, then device.id. */
+ fun resource(
+ serviceVersion: String,
+ model: String,
+ manufacturer: String,
+ osVersion: String,
+ deviceId: String,
+ extra: Map,
+ ): Resource {
+ val m = linkedMapOf(
+ "service.name" to "android-otel-device-agent",
+ "service.version" to serviceVersion,
+ "device.model.identifier" to model,
+ "device.manufacturer" to manufacturer,
+ "os.name" to "Android",
+ "os.type" to "linux",
+ "os.version" to osVersion,
+ "telemetry.sdk.language" to "java",
+ "telemetry.sdk.name" to "opentelemetry",
+ )
+ m.putAll(extra)
+ if (deviceId.isNotEmpty()) m["device.id"] = deviceId
+ return Resource.create(attributes(m))
+ }
+ }
+}
+
+private class SimpleLog(
+ private val resource: Resource,
+ private val scope: InstrumentationScopeInfo,
+ private val event: String,
+ private val text: String,
+ private val attrs: Attributes,
+ private val ts: Long,
+ private val observed: Long,
+) : LogRecordData {
+ override fun getResource() = resource
+ override fun getInstrumentationScopeInfo() = scope
+ override fun getTimestampEpochNanos() = ts
+ override fun getObservedTimestampEpochNanos() = observed
+ override fun getSpanContext(): SpanContext = SpanContext.getInvalid()
+ override fun getSeverity() = Severity.INFO
+ override fun getSeverityText() = "INFO"
+
+ @Deprecated("Deprecated in Java")
+ override fun getBody(): Body = Body.string(text)
+ override fun getAttributes() = attrs
+ override fun getTotalAttributeCount() = attrs.size()
+ override fun getEventName() = event
+}
diff --git a/app/src/main/java/dev/code6x/otelagent/export/QueueSender.kt b/app/src/main/java/dev/code6x/otelagent/export/QueueSender.kt
new file mode 100644
index 0000000..5c2fd54
--- /dev/null
+++ b/app/src/main/java/dev/code6x/otelagent/export/QueueSender.kt
@@ -0,0 +1,93 @@
+package dev.code6x.otelagent.export
+
+import java.io.IOException
+import java.net.HttpURLConnection
+import java.net.URL
+
+/** Where and how to send. */
+data class Target(val url: String, val headers: Map, val timeoutSeconds: Int)
+
+fun interface Poster {
+ /** Posts one OTLP/HTTP protobuf body; returns the HTTP status. Throws IOException on a network error. */
+ fun post(target: Target, body: ByteArray): Int
+}
+
+data class SendResult(val sent: Int, val dropped: Int, val left: Int, val error: String?)
+
+/**
+ * Sends the queue in order, oldest first. Stops at the first failure, so the order is kept
+ * and nothing is lost; the next call tries again.
+ */
+class QueueSender(private val queue: FileQueue, private val poster: Poster = HttpPoster) {
+ @Synchronized
+ fun drain(target: Target?): SendResult {
+ queue.trim()
+ if (target == null || target.url.isEmpty()) {
+ return SendResult(0, 0, queue.files().size, "no endpoint set")
+ }
+ var sent = 0
+ var dropped = 0
+ var error: String? = null
+ for (f in queue.files()) {
+ val code = try {
+ poster.post(target, f.readBytes())
+ } catch (e: IOException) {
+ error = "${e.javaClass.simpleName}: ${e.message}"
+ break
+ }
+ when {
+ code in 200..299 -> {
+ queue.remove(f)
+ sent++
+ }
+ // The receiver says the body itself is bad and will never take it: drop it, or
+ // it blocks the queue for ever. Any other answer (3xx, 401, 403, 404, 408, 415, 429,
+ // 5xx) may be a passing problem of the receiver or the network: keep the file.
+ code in DROP_CODES -> {
+ queue.remove(f)
+ dropped++
+ error = "HTTP $code, file dropped"
+ }
+ else -> {
+ error = "HTTP $code"
+ break
+ }
+ }
+ }
+ return SendResult(sent, dropped, queue.files().size, error)
+ }
+
+ companion object {
+ /** 400 Bad Request, 413 Content Too Large, 422: this body can never be taken. (415 is about the
+ * endpoint, not one body: every body has the same type, so it is kept.) */
+ val DROP_CODES = setOf(400, 413, 422)
+ }
+}
+
+object HttpPoster : Poster {
+ override fun post(target: Target, body: ByteArray): Int {
+ val c = URL(target.url).openConnection() as HttpURLConnection
+ try {
+ c.requestMethod = "POST"
+ // A redirect would turn the POST into a GET without the body (a captive portal
+ // could answer 200 and the file would be lost). A 3xx stays a failure instead.
+ c.instanceFollowRedirects = false
+ c.doOutput = true
+ c.connectTimeout = target.timeoutSeconds * 1000
+ c.readTimeout = target.timeoutSeconds * 1000
+ c.setRequestProperty("Content-Type", "application/x-protobuf")
+ target.headers.forEach { (k, v) -> c.setRequestProperty(k, v) }
+ c.setFixedLengthStreamingMode(body.size)
+ c.outputStream.use { it.write(body) }
+ val code = c.responseCode
+ // Read the answer so the connection can be reused.
+ try {
+ (if (code >= 400) c.errorStream else c.inputStream)?.use { it.readBytes() }
+ } catch (_: IOException) {
+ }
+ return code
+ } finally {
+ c.disconnect()
+ }
+ }
+}
diff --git a/app/src/main/res/values/strings.xml b/app/src/main/res/values/strings.xml
new file mode 100644
index 0000000..4abdbad
--- /dev/null
+++ b/app/src/main/res/values/strings.xml
@@ -0,0 +1,6 @@
+
+
+ OTel device agent
+ Telemetry service
+ Reads device health and sends it over OTLP
+
diff --git a/app/src/test/java/dev/code6x/otelagent/CollectorMappingTest.kt b/app/src/test/java/dev/code6x/otelagent/CollectorMappingTest.kt
new file mode 100644
index 0000000..88ddae0
--- /dev/null
+++ b/app/src/test/java/dev/code6x/otelagent/CollectorMappingTest.kt
@@ -0,0 +1,141 @@
+package dev.code6x.otelagent
+
+import dev.code6x.otelagent.collect.BatteryCollector
+import dev.code6x.otelagent.collect.BatterySnapshot
+import dev.code6x.otelagent.collect.BootCollector
+import dev.code6x.otelagent.collect.BootSnapshot
+import dev.code6x.otelagent.collect.DeviceCollector
+import dev.code6x.otelagent.collect.DeviceSnapshot
+import dev.code6x.otelagent.collect.Metrics
+import dev.code6x.otelagent.collect.NetworkCollector
+import dev.code6x.otelagent.collect.NetworkSnapshot
+import dev.code6x.otelagent.collect.PowerCollector
+import dev.code6x.otelagent.collect.PowerSnapshot
+import dev.code6x.otelagent.collect.Reading
+import dev.code6x.otelagent.collect.ThermalCollector
+import dev.code6x.otelagent.collect.ThermalSnapshot
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+class CollectorMappingTest {
+ private fun List.value(name: String, vararg attrs: Pair): Double? =
+ firstOrNull { it.def.name == name && it.attributes == attrs.toMap() }?.value
+
+ private fun List.current(name: String, attr: String): Set =
+ filter { it.def.name == name && it.value == 1.0 }.map { it.attributes.getValue(attr) }.toSet()
+
+ @Test fun battery() {
+ val r = BatteryCollector.map(
+ BatterySnapshot(
+ level = 87, scale = 100, voltageMv = 4123, temperatureTenthsC = 312, status = 2, plugged = 1,
+ health = 2, currentMicroA = -250_000, chargeCounterMicroAh = 3_100_000, cycleCount = 42,
+ ),
+ )
+ assertEquals(0.87, r.value("hw.battery.charge")!!, 1e-9)
+ assertEquals(4.123, r.value("device.battery.voltage")!!, 1e-9)
+ assertEquals(31.2, r.value("device.battery.temperature")!!, 1e-9)
+ assertEquals(-0.25, r.value("device.battery.current")!!, 1e-9)
+ assertEquals(3.1, r.value("device.battery.charge_counter")!!, 1e-9)
+ assertEquals(42.0, r.value("device.battery.cycle_count")!!, 0.0)
+ assertEquals(setOf("charging"), r.current("device.battery.status", "battery.status"))
+ assertEquals(setOf("ac"), r.current("device.battery.plug", "battery.plug"))
+ assertEquals(setOf("good"), r.current("device.battery.health", "battery.health"))
+ // Every state is sent, so a state that ends goes to 0 at once.
+ assertEquals(0.0, r.value("device.battery.plug", "battery.plug" to "none")!!, 0.0)
+ assertEquals(5, r.count { it.def.name == "device.battery.plug" })
+ }
+
+ @Test fun batteryWithoutOptionalValues() {
+ val r = BatteryCollector.map(
+ BatterySnapshot(50, 100, null, null, 3, 0, 1, null, null, null),
+ )
+ assertNull(r.value("device.battery.voltage"))
+ assertNull(r.value("device.battery.current"))
+ assertNull(r.value("device.battery.cycle_count"))
+ assertEquals(setOf("discharging"), r.current("device.battery.status", "battery.status"))
+ assertEquals(setOf("none"), r.current("device.battery.plug", "battery.plug"))
+ assertEquals(setOf("unknown"), r.current("device.battery.health", "battery.health"))
+ }
+
+ @Test fun batteryPlugTypes() {
+ assertEquals(setOf("usb"), BatteryCollector.plugs(2))
+ assertEquals(setOf("wireless"), BatteryCollector.plugs(4))
+ assertEquals(setOf("dock"), BatteryCollector.plugs(8))
+ assertEquals(setOf("none"), BatteryCollector.plugs(0))
+ assertEquals("full", BatteryCollector.status(5))
+ assertEquals("not_charging", BatteryCollector.status(4))
+ assertEquals("overheat", BatteryCollector.health(3))
+ assertEquals("cold", BatteryCollector.health(7))
+ }
+
+ @Test fun power() {
+ val r = PowerCollector.map(PowerSnapshot(screenOn = true, powerSave = false, idle = true))
+ assertEquals(1.0, r.value("device.screen.on")!!, 0.0)
+ assertEquals(0.0, r.value("device.power.save_mode")!!, 0.0)
+ assertEquals(1.0, r.value("device.power.idle")!!, 0.0)
+ }
+
+ @Test fun boot() {
+ val s = BootSnapshot(elapsedMs = 3_600_500, wallMs = 1_800_000_000_000, bootCount = 12)
+ val r = BootCollector.map(s)
+ assertEquals(3600.5, r.value("system.uptime")!!, 1e-9)
+ assertEquals(12.0, r.value("device.boot.count")!!, 0.0)
+ assertEquals(1_799_996_399.0, r.value("device.boot.time")!!, 0.0)
+ assertNull(BootCollector.map(s.copy(bootCount = null)).value("device.boot.count"))
+ }
+
+ @Test fun newBoot() {
+ val s = BootSnapshot(1000, 1_800_000_000_000, 12)
+ assertTrue(BootCollector.isNewBoot(null, null, s))
+ assertFalse(BootCollector.isNewBoot(12, s.bootTimeS, s))
+ assertTrue(BootCollector.isNewBoot(11, s.bootTimeS, s))
+ val noCount = s.copy(bootCount = null)
+ assertFalse(BootCollector.isNewBoot(null, noCount.bootTimeS + 30, noCount))
+ assertTrue(BootCollector.isNewBoot(null, noCount.bootTimeS - 3600, noCount))
+ }
+
+ @Test fun network() {
+ val r = NetworkCollector.map(NetworkSnapshot(true, setOf("wifi", "vpn"), true, -61, 433))
+ assertEquals(1.0, r.value("device.network.connected")!!, 0.0)
+ assertEquals(setOf("wifi", "vpn"), r.current("device.network.type", "network.connection.type"))
+ assertEquals(0.0, r.value("device.network.type", "network.connection.type" to "cell")!!, 0.0)
+ assertEquals(1.0, r.value("device.wifi.connected")!!, 0.0)
+ assertEquals(-61.0, r.value("device.wifi.rssi")!!, 0.0)
+ assertEquals(433.0, r.value("device.wifi.link_speed")!!, 0.0)
+ // Nothing that names the network.
+ assertTrue(r.none { it.def.name.contains("ssid") })
+ }
+
+ @Test fun networkDown() {
+ val r = NetworkCollector.map(NetworkSnapshot(false, emptySet(), false, null, null))
+ assertEquals(0.0, r.value("device.network.connected")!!, 0.0)
+ assertEquals(emptySet(), r.current("device.network.type", "network.connection.type"))
+ assertNull(r.value("device.wifi.rssi"))
+ }
+
+ @Test fun device() {
+ val r = DeviceCollector.map(DeviceSnapshot(8_000, 3_000, false, 100_000, 40_000))
+ assertEquals(8000.0, r.value("system.memory.limit")!!, 0.0)
+ assertEquals(3000.0, r.value("system.memory.usage", "system.memory.state" to "free")!!, 0.0)
+ assertEquals(5000.0, r.value("system.memory.usage", "system.memory.state" to "used")!!, 0.0)
+ assertEquals(0.0, r.value("device.memory.low")!!, 0.0)
+ val m = "system.filesystem.mountpoint" to "/data"
+ assertEquals(100_000.0, r.value("system.filesystem.limit", m)!!, 0.0)
+ assertEquals(40_000.0, r.value("system.filesystem.usage", m, "system.filesystem.state" to "free")!!, 0.0)
+ assertEquals(60_000.0, r.value("system.filesystem.usage", m, "system.filesystem.state" to "used")!!, 0.0)
+ }
+
+ @Test fun thermal() {
+ val r = ThermalCollector.map(ThermalSnapshot(2, 0.45f))
+ assertEquals(2.0, r.value("device.thermal.status")!!, 0.0)
+ assertEquals(0.45, r.value("device.thermal.headroom")!!, 1e-6)
+ assertTrue(ThermalCollector.map(ThermalSnapshot(null, Float.NaN)).isEmpty())
+ }
+
+ @Test fun metricNamesAreUnique() {
+ assertEquals(Metrics.ALL.size, Metrics.ALL.map { it.name }.toSet().size)
+ }
+}
diff --git a/app/src/test/java/dev/code6x/otelagent/ConfigLoaderTest.kt b/app/src/test/java/dev/code6x/otelagent/ConfigLoaderTest.kt
new file mode 100644
index 0000000..43a6e8d
--- /dev/null
+++ b/app/src/test/java/dev/code6x/otelagent/ConfigLoaderTest.kt
@@ -0,0 +1,111 @@
+package dev.code6x.otelagent
+
+import dev.code6x.otelagent.config.ConfigException
+import dev.code6x.otelagent.config.ConfigLoader
+import dev.code6x.otelagent.config.Source
+import dev.code6x.otelagent.config.WakePolicy
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertTrue
+import org.junit.Assert.fail
+import org.junit.Test
+
+class ConfigLoaderTest {
+ private fun local(json: String) = ConfigLoader.load(listOf(Source.LOCAL_FILE to json))
+
+ private fun assertRejected(json: String, part: String) {
+ try {
+ local(json)
+ fail("not rejected: $json")
+ } catch (e: ConfigException) {
+ assertTrue("message '${e.message}' has '$part'", e.message!!.contains(part))
+ }
+ }
+
+ @Test fun defaults() {
+ val c = ConfigLoader.load(emptyList()).config
+ assertEquals(WakePolicy.WHEN_CHARGING, c.wakePolicy)
+ assertEquals("", c.exporter.endpoint)
+ assertEquals("http/protobuf", c.exporter.protocol)
+ assertEquals(10, c.exporter.timeoutSeconds)
+ assertEquals(listOf("battery", "power", "boot", "network", "device", "thermal"), c.collectors.keys.toList())
+ c.collectors.values.forEach {
+ assertTrue(it.enabled)
+ assertEquals(60, it.intervalSeconds)
+ }
+ assertEquals(20L * 1024 * 1024, c.buffer.maxBytes)
+ assertEquals(7L * 86400, c.buffer.maxAgeSeconds)
+ assertTrue(c.attributes.isEmpty())
+ }
+
+ @Test fun localFileOverridesDefaultsAndKeepsSources() {
+ val l = local(
+ """
+ {"exporter": {"endpoint": "https://otlp.example.com/v1/metrics", "headers": {"Authorization": "Bearer x"}},
+ "resource": {"device.id": "phone-1", "attributes": {"location": "lobby"}},
+ "collectors": {"thermal": {"enabled": false}, "battery": {"interval": 30}},
+ "wake_policy": "always"}
+ """,
+ )
+ val c = l.config
+ assertEquals("https://otlp.example.com/v1/metrics", c.exporter.endpoint)
+ assertEquals(mapOf("Authorization" to "Bearer x"), c.exporter.headers)
+ assertEquals("phone-1", c.deviceId)
+ assertEquals(mapOf("location" to "lobby"), c.attributes)
+ assertFalse(c.collector("thermal").enabled)
+ assertEquals(60, c.collector("thermal").intervalSeconds)
+ assertEquals(30, c.collector("battery").intervalSeconds)
+ assertTrue(c.collector("battery").enabled)
+ assertEquals(WakePolicy.ALWAYS, c.wakePolicy)
+
+ fun source(vararg p: String) = l.entries.first { it.path == p.toList() }.source
+ assertEquals(Source.LOCAL_FILE, source("exporter", "endpoint"))
+ assertEquals(Source.DEFAULT, source("exporter", "timeout"))
+ assertEquals(Source.LOCAL_FILE, source("collectors", "battery", "interval"))
+ assertEquals(Source.DEFAULT, source("collectors", "battery", "enabled"))
+ assertEquals(Source.LOCAL_FILE, source("resource", "device.id"))
+ assertTrue(l.warnings.isEmpty())
+ }
+
+ @Test fun wakePolicyValues() {
+ assertEquals(WakePolicy.NEVER, local("""{"wake_policy": "never"}""").config.wakePolicy)
+ assertEquals(WakePolicy.WHEN_CHARGING, local("""{"wake_policy": "when_charging"}""").config.wakePolicy)
+ assertEquals(WakePolicy.ALWAYS, local("""{"wake_policy": "always"}""").config.wakePolicy)
+ assertRejected("""{"wake_policy": "sometimes"}""", "wake_policy")
+ }
+
+ @Test fun wakePolicyWakes() {
+ assertFalse(WakePolicy.NEVER.wakes(true))
+ assertFalse(WakePolicy.NEVER.wakes(false))
+ assertTrue(WakePolicy.WHEN_CHARGING.wakes(true))
+ assertFalse(WakePolicy.WHEN_CHARGING.wakes(false))
+ assertTrue(WakePolicy.ALWAYS.wakes(true))
+ assertTrue(WakePolicy.ALWAYS.wakes(false))
+ }
+
+ @Test fun unknownKeysAreWarnedNotUsed() {
+ val l = local("""{"colectors": {"battery": {"enabled": false}}, "collectors": {"gps": {"enabled": true}}}""")
+ assertEquals(2, l.warnings.size)
+ assertTrue(l.config.collector("battery").enabled)
+ }
+
+ @Test fun badValuesAreRejected() {
+ assertRejected("not json", "not valid JSON")
+ assertRejected("""{"collectors": {"battery": {"interval": 5}}}""", "from 10 to 86400")
+ assertRejected("""{"collectors": {"battery": {"interval": 60.5}}}""", "whole number")
+ assertRejected("""{"collectors": {"battery": {"interval": "60"}}}""", "must be a number")
+ assertRejected("""{"collectors": {"battery": {"enabled": "yes"}}}""", "true or false")
+ assertRejected("""{"exporter": {"protocol": "grpc"}}""", "http/protobuf")
+ assertRejected("""{"exporter": {"endpoint": "otlp.example.com"}}""", "http://")
+ assertRejected("""{"exporter": {"headers": {"X-Token": 5}}}""", "must be text")
+ assertRejected("""{"resource": {"attributes": ["a"]}}""", "list")
+ assertRejected("""{"buffer": {"max_bytes": 10}}""", "buffer > max_bytes")
+ }
+
+ @Test fun headerValuesAreHiddenOnScreen() {
+ val l = local("""{"exporter": {"headers": {"Authorization": "Bearer secret"}}}""")
+ val text = l.entries.joinToString("\n") { ConfigLoader.display(it) }
+ assertFalse(text.contains("secret"))
+ assertTrue(text.contains("exporter > headers > Authorization = (hidden) [local file]"))
+ }
+}
diff --git a/app/src/test/java/dev/code6x/otelagent/OtlpEncoderTest.kt b/app/src/test/java/dev/code6x/otelagent/OtlpEncoderTest.kt
new file mode 100644
index 0000000..b596d93
--- /dev/null
+++ b/app/src/test/java/dev/code6x/otelagent/OtlpEncoderTest.kt
@@ -0,0 +1,62 @@
+package dev.code6x.otelagent
+
+import dev.code6x.otelagent.collect.Metrics
+import dev.code6x.otelagent.collect.Reading
+import dev.code6x.otelagent.export.OtlpEncoder
+import io.opentelemetry.proto.collector.logs.v1.ExportLogsServiceRequest
+import io.opentelemetry.proto.collector.metrics.v1.ExportMetricsServiceRequest
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Test
+
+class OtlpEncoderTest {
+ private val resource = OtlpEncoder.resource("1.2.3", "Model X", "Maker", "15", "phone-1", mapOf("location" to "lobby"))
+ private val encoder = OtlpEncoder(resource, "1.2.3")
+
+ private fun attrs(list: List) =
+ list.associate { it.key to it.value.stringValue }
+
+ @Test fun resourceHasTheConfiguredAttributesAndNoInstallationId() {
+ val req = ExportMetricsServiceRequest.parseFrom(encoder.metrics(listOf(Reading(Metrics.SCREEN_ON, 1.0)), 1000))
+ val r = attrs(req.getResourceMetrics(0).resource.attributesList)
+ assertEquals("android-otel-device-agent", r["service.name"])
+ assertEquals("1.2.3", r["service.version"])
+ assertEquals("phone-1", r["device.id"])
+ assertEquals("Model X", r["device.model.identifier"])
+ assertEquals("15", r["os.version"])
+ assertEquals("lobby", r["location"])
+ assertFalse(r.containsKey("app.installation.id"))
+ }
+
+ @Test fun noDeviceIdWhenNotSet() {
+ val res = OtlpEncoder.resource("1", "m", "x", "15", "", emptyMap())
+ assertFalse(res.attributes.asMap().keys.any { it.key == "device.id" })
+ }
+
+ @Test fun gaugesCarryTheReadingTime() {
+ val readings = listOf(
+ Reading(Metrics.BATTERY_CHARGE, 0.5),
+ Reading(Metrics.BATTERY_PLUG, 1.0, mapOf("battery.plug" to "ac")),
+ Reading(Metrics.BATTERY_PLUG, 0.0, mapOf("battery.plug" to "none")),
+ )
+ val req = ExportMetricsServiceRequest.parseFrom(encoder.metrics(readings, 1_700_000_000_123))
+ val metrics = req.getResourceMetrics(0).getScopeMetrics(0).metricsList
+ assertEquals("dev.code6x.otelagent", req.getResourceMetrics(0).getScopeMetrics(0).scope.name)
+ assertEquals(listOf("hw.battery.charge", "device.battery.plug"), metrics.map { it.name })
+ assertEquals("1", metrics[0].unit)
+ val plug = metrics[1].gauge.dataPointsList
+ assertEquals(2, plug.size)
+ assertEquals(1_700_000_000_123_000_000, plug[0].timeUnixNano)
+ assertEquals("ac", attrs(plug[0].attributesList)["battery.plug"])
+ assertEquals(1.0, plug[0].asDouble, 0.0)
+ }
+
+ @Test fun bootLogRecord() {
+ val req = ExportLogsServiceRequest.parseFrom(encoder.log("device.boot", "device boot", mapOf("device.boot.count" to "3"), 5000, 6000))
+ val rec = req.getResourceLogs(0).getScopeLogs(0).getLogRecords(0)
+ assertEquals("device boot", rec.body.stringValue)
+ assertEquals("device.boot", rec.eventName)
+ assertEquals(5_000_000_000, rec.timeUnixNano)
+ assertEquals("3", attrs(rec.attributesList)["device.boot.count"])
+ }
+}
diff --git a/app/src/test/java/dev/code6x/otelagent/QueueTest.kt b/app/src/test/java/dev/code6x/otelagent/QueueTest.kt
new file mode 100644
index 0000000..767dfe2
--- /dev/null
+++ b/app/src/test/java/dev/code6x/otelagent/QueueTest.kt
@@ -0,0 +1,141 @@
+package dev.code6x.otelagent
+
+import dev.code6x.otelagent.export.FileQueue
+import dev.code6x.otelagent.export.Poster
+import dev.code6x.otelagent.export.QueueSender
+import dev.code6x.otelagent.export.Target
+import org.junit.Assert.assertArrayEquals
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNotNull
+import org.junit.Assert.assertNull
+import org.junit.Rule
+import org.junit.Test
+import org.junit.rules.TemporaryFolder
+import java.io.File
+import java.io.IOException
+
+class QueueTest {
+ @get:Rule val tmp = TemporaryFolder()
+
+ private var now = 1_000_000L
+ private fun queue(maxBytes: Long = 1_000_000, maxAgeMs: Long = 3_600_000) =
+ FileQueue(tmp.newFolder(), maxBytes, maxAgeMs) { now }
+
+ private val target = Target("http://example.com/v1/metrics", emptyMap(), 5)
+
+ @Test fun filesKeepTheirOrder() {
+ val q = queue()
+ q.add(byteArrayOf(1))
+ q.add(byteArrayOf(2)) // same millisecond
+ now += 10
+ q.add(byteArrayOf(3))
+ assertEquals(listOf(1, 2, 3), q.files().map { it.readBytes()[0] })
+ }
+
+ @Test fun sizeCapDropsOldestFirst() {
+ val q = queue(maxBytes = 250)
+ repeat(5) {
+ q.add(ByteArray(100) { _ -> it.toByte() })
+ now += 1000
+ }
+ // 5 x 100 bytes over a 250 byte cap: the 3 oldest are dropped.
+ assertEquals(listOf(3, 4), q.files().map { it.readBytes()[0] })
+ assertEquals(200, q.sizeBytes())
+ assertEquals(3, q.dropped)
+ }
+
+ @Test fun maxAgeDropsOldFiles() {
+ val q = queue(maxAgeMs = 60_000)
+ q.add(byteArrayOf(1))
+ now += 30_000
+ q.add(byteArrayOf(2))
+ now += 31_000 // the first is now 61 s old
+ assertEquals(1, q.trim())
+ assertEquals(listOf(2), q.files().map { it.readBytes()[0] })
+ now += 60_000
+ q.add(byteArrayOf(3)) // add trims too
+ assertEquals(listOf(3), q.files().map { it.readBytes()[0] })
+ assertEquals(2, q.dropped)
+ }
+
+ @Test fun halfWrittenFilesAreRemovedAtStart() {
+ val dir = tmp.newFolder()
+ File(dir, "0000000000001-0000.pb.tmp").writeBytes(byteArrayOf(9))
+ File(dir, "0000000000002-0000.pb").writeBytes(byteArrayOf(1))
+ val q = FileQueue(dir, 1000, 1_000_000_000_000) { now }
+ assertEquals(1, q.files().size)
+ assertEquals(1, dir.listFiles()!!.size)
+ }
+
+ @Test fun senderDeletesOnlyAfter2xxAndKeepsOrder() {
+ val q = queue()
+ repeat(3) { q.add(byteArrayOf(it.toByte())) }
+ val posted = mutableListOf()
+ val codes = ArrayDeque(listOf(200, 503))
+ val sender = QueueSender(q, Poster { _, body -> posted += body[0]; codes.removeFirst() })
+ val r = sender.drain(target)
+ assertEquals(1, r.sent)
+ assertEquals(2, r.left)
+ assertEquals("HTTP 503", r.error)
+ assertEquals(listOf(0, 1), posted)
+ assertEquals(listOf(1, 2), q.files().map { it.readBytes()[0] })
+ }
+
+ @Test fun networkErrorKeepsEverything() {
+ val q = queue()
+ repeat(2) { q.add(byteArrayOf(it.toByte())) }
+ val sender = QueueSender(q, Poster { _, _ -> throw IOException("timeout") })
+ val r = sender.drain(target)
+ assertEquals(0, r.sent)
+ assertEquals(2, r.left)
+ assertNotNull(r.error)
+ }
+
+ @Test fun rejectedBodyIsDroppedSoItDoesNotBlock() {
+ val q = queue()
+ repeat(2) { q.add(byteArrayOf(it.toByte())) }
+ val codes = ArrayDeque(listOf(400, 204))
+ val r = QueueSender(q, Poster { _, _ -> codes.removeFirst() }).drain(target)
+ assertEquals(1, r.sent)
+ assertEquals(1, r.dropped)
+ assertEquals(0, r.left)
+ }
+
+ @Test fun authErrorsNotFoundAndRedirectsKeepTheQueue() {
+ for (code in listOf(301, 302, 401, 403, 404, 405, 408, 415, 500, 502)) {
+ val q = queue()
+ repeat(3) { q.add(byteArrayOf(it.toByte())) }
+ var posts = 0
+ val r = QueueSender(q, Poster { _, _ -> posts++; code }).drain(target)
+ assertEquals("HTTP $code keeps all files", 3, r.left)
+ assertEquals("HTTP $code stops at the first file", 1, posts)
+ assertEquals(0, r.dropped)
+ }
+ }
+
+ @Test fun tooManyRequestsIsRetried() {
+ val q = queue()
+ q.add(byteArrayOf(7))
+ val r = QueueSender(q, Poster { _, _ -> 429 }).drain(target)
+ assertEquals(1, r.left)
+ assertEquals("HTTP 429", r.error)
+ }
+
+ @Test fun noEndpointKeepsTheQueue() {
+ val q = queue()
+ q.add(byteArrayOf(1))
+ val r = QueueSender(q, Poster { _, _ -> error("must not post") }).drain(null)
+ assertEquals(1, r.left)
+ assertEquals("no endpoint set", r.error)
+ }
+
+ @Test fun bodyIsPostedUnchanged() {
+ val q = queue()
+ val body = byteArrayOf(10, 20, 30)
+ q.add(body)
+ var got: ByteArray? = null
+ QueueSender(q, Poster { _, b -> got = b; 200 }).drain(target)
+ assertArrayEquals(body, got)
+ assertNull(q.files().firstOrNull())
+ }
+}
diff --git a/app/src/test/java/dev/code6x/otelagent/TickPlanTest.kt b/app/src/test/java/dev/code6x/otelagent/TickPlanTest.kt
new file mode 100644
index 0000000..7d75e72
--- /dev/null
+++ b/app/src/test/java/dev/code6x/otelagent/TickPlanTest.kt
@@ -0,0 +1,40 @@
+package dev.code6x.otelagent
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNull
+import org.junit.Test
+
+class TickPlanTest {
+ @Test fun eachCollectorHasItsOwnInterval() {
+ val p = TickPlan()
+ val iv = mapOf("battery" to 30, "device" to 60)
+ assertEquals(listOf("battery", "device"), p.due(0, iv))
+ assertEquals(30_000L, p.nextDelay(0, iv))
+ assertEquals(listOf("battery"), p.due(30_000, iv))
+ assertEquals(listOf("battery", "device"), p.due(60_000, iv))
+ }
+
+ @Test fun aTimerThatFiresALittleEarlyStillReads() {
+ val p = TickPlan()
+ val iv = mapOf("battery" to 60)
+ p.due(0, iv)
+ assertEquals(listOf("battery"), p.due(59_000, iv))
+ assertEquals(emptyList(), p.due(100_000, iv)) // next due 119 000
+ }
+
+ @Test fun aCollectorTurnedOffIsNotRead() {
+ val p = TickPlan()
+ p.due(0, mapOf("battery" to 60, "thermal" to 60))
+ assertEquals(listOf("battery"), p.due(60_000, mapOf("battery" to 60)))
+ assertNull(p.nextDelay(60_000, emptyMap()))
+ }
+
+ @Test fun resetReadsAllAtOnce() {
+ val p = TickPlan()
+ val iv = mapOf("battery" to 60)
+ p.due(0, iv)
+ p.reset()
+ assertEquals(0L, p.nextDelay(1000, iv))
+ assertEquals(listOf("battery"), p.due(1000, iv))
+ }
+}
diff --git a/build.gradle.kts b/build.gradle.kts
new file mode 100644
index 0000000..16b7270
--- /dev/null
+++ b/build.gradle.kts
@@ -0,0 +1,4 @@
+plugins {
+ id("com.android.application") version "8.10.0" apply false
+ id("org.jetbrains.kotlin.android") version "2.4.21" apply false
+}
diff --git a/docs/mvp-tests.md b/docs/mvp-tests.md
new file mode 100644
index 0000000..38ff5a3
--- /dev/null
+++ b/docs/mvp-tests.md
@@ -0,0 +1,277 @@
+# MVP tests (issue #2)
+
+Receiver: a VictoriaMetrics container (OTLP at `/opentelemetry/v1/metrics`)
+and a VictoriaLogs container (OTLP logs), both throw-away. Times are UTC.
+
+## Emulator (Android 15, API 35, x86_64), 2026-11-13
+
+Config: the defaults plus `exporter.endpoint`, `exporter.logs_endpoint`,
+`resource.device.id` = `emu-1` and one attribute `location=test`. So
+`wake_policy` is the default, `when_charging`.
+
+### All six collectors send
+
+Instant queries, `{__name__="NAME", device.id="emu-1"}`, 2026-11-13 ~11:48:
+
+```
+hw.battery.charge => 1
+device.screen.on => 0
+system.uptime => 2626.577
+device.boot.count => 1
+device.network.type {'network.connection.type': 'bluetooth'} => 0
+device.network.type {'network.connection.type': 'cell'} => 0
+device.network.type {'network.connection.type': 'vpn'} => 0
+device.network.type {'network.connection.type': 'wifi'} => 1
+device.network.type {'network.connection.type': 'wired'} => 0
+system.memory.usage {'system.memory.state': 'free'} => 1771495424
+system.memory.usage {'system.memory.state': 'used'} => 821710848
+system.filesystem.usage {'system.filesystem.mountpoint': '/data', 'system.filesystem.state': 'free'} => 5788688384
+system.filesystem.usage {'system.filesystem.mountpoint': '/data', 'system.filesystem.state': 'used'} => 439427072
+device.thermal.status => 0
+device.thermal.headroom => 0.426666647196
+device.battery.voltage => 5
+device.battery.plug {'battery.plug': 'ac'} => 1
+device.battery.plug {'battery.plug': 'dock'} => 0
+device.battery.plug {'battery.plug': 'none'} => 0
+device.battery.plug {'battery.plug': 'usb'} => 0
+device.battery.plug {'battery.plug': 'wireless'} => 0
+device.power.idle => 0
+device.memory.low => 0
+device.wifi.connected => 1
+device.wifi.rssi => -50
+device.wifi.link_speed => 1
+```
+
+(battery: `hw.battery.charge`, `device.battery.voltage`, `device.battery.plug`;
+power: `device.screen.on`, `device.power.idle`; boot: `system.uptime`,
+`device.boot.count`; network: `device.network.type`, `device.wifi.*`;
+device: `system.memory.usage`, `system.filesystem.usage`, `device.memory.low`;
+thermal: `device.thermal.status`, `device.thermal.headroom`.) The emulator
+reports a Wi-Fi link speed of 1 Mbit/s and a fixed battery; the values are
+the emulator's.
+
+Labels of one series (no `app.installation.id`):
+
+```
+{'__name__': 'hw.battery.charge', 'device.id': 'emu-1', 'device.manufacturer': 'unknown', 'device.model.identifier': 'Android SDK built for x86_64', 'location': 'test', 'os.name': 'Android', 'os.type': 'linux', 'os.version': '15', 'scope.name': 'dev.code6x.otelagent', 'scope.version': '0.1.0-dev', 'service.name': 'android-otel-device-agent', 'service.version': '0.1.0-dev', 'telemetry.sdk.language': 'java', 'telemetry.sdk.name': 'opentelemetry'}
+```
+
+The boot log record in VictoriaLogs:
+
+```
+{'_msg': 'device boot', '_time': '2026-11-13T11:02:45Z', 'device.boot.count': '1', 'device.id': 'emu-1', 'event_name': 'device.boot'}
+```
+
+### Turning a collector off
+
+At 11:12:24 a config with `"collectors": {"thermal": {"enabled": false}}`
+was imported by `adb shell am broadcast` (answer:
+`data="ok: config imported; applied"`). Raw points (Unix seconds):
+
+```
+device.thermal.status 1794568244, 1794568304 <- none after 1794568344 (11:12:24)
+device.screen.on 1794568244, 1794568304, 1794568344, ...
+```
+
+The thermal metrics stopped at once (the import makes a new reading
+straight away, without thermal); the other collectors went on.
+
+### `wake_policy=when_charging` on battery, screen off
+
+`adb shell dumpsys battery unplug` and `input keyevent KEYCODE_SLEEP` at
+11:13:23. After the next reading:
+
+```
+2026-11-13T11:14:29Z
+ AC powered: false
+ USB powered: false
+ mWakefulness=Asleep
+Wake Locks: size=0
+Wake Locks: size=0
+
+Suspend Blockers: size=5
+ PowerManagerService.Booting: ref count=0 []
+ Pending alarms per uid: [1000:14, 1002:1, 1073:3, u0a79:1]
+11-13 13:14:20.001 2399 2418 I OtelAgent: tick: read battery, power, boot, network, device, thermal; charging=false wake=false
+```
+
+The app's uid is `u0a148` (10148): it holds no wake lock
+(`Wake Locks: size=0`) and has no pending alarm (it is not in
+`Pending alarms per uid`). After `dumpsys battery reset` (on the charger
+again) the exact alarm is back:
+
+```
+2026-11-13T11:15:20Z
+ Pending alarms per uid: [1000:15, 1002:1, 1073:3, u0a79:1, u0a148:1]
+ type=ELAPSED_WAKEUP origWhen=+59s961ms window=0 exactAllowReason=allow-listed repeatInterval=0 count=0 flags=0x9
+ type=ELAPSED_WAKEUP tag=*walarm*:dev.code6x.otelagent/.TickReceiver
+11-13 13:15:20.003 2399 2418 I OtelAgent: tick: read battery, power, boot, network, device, thermal; charging=true wake=true
+```
+
+### The other `wake_policy` values
+
+`always` on battery sets the exact alarm (uid `u0a148` is in the pending
+list); `never` on the charger sets none, and the app holds no wake lock (the
+one listed is the system's audio, uid 1041):
+
+```
+Broadcast completed: result=-1, data="ok: config imported; applied"
+== always (battery) 11:52:11
+ Pending alarms per uid: [1000:13, 1002:1, 1073:3, u0a79:1, u0a148:1]
+Wake Locks: size=0
+
+11-13 13:52:08.924 2960 2977 I OtelAgent: tick: read battery, power, boot, network, device, thermal; charging=false wake=true
+Broadcast completed: result=-1, data="ok: config imported; applied"
+== never (charger) 11:52:15
+ Pending alarms per uid: [1000:14, 1002:1, 1073:3, u0a79:1]
+Wake Locks: size=1
+ PARTIAL_WAKE_LOCK 'AudioMix' ACQ=-222ms (uid=1041)
+11-13 13:52:12.068 2960 2977 I OtelAgent: tick: read battery, power, boot, network, device, thermal; charging=true wake=false
+```
+
+### Config import by file and by share sheet
+
+- **File:** the JSON file was put in the emulator's Downloads. In the app:
+ **Import config file**, then the file in the system file picker. Log:
+ `local config imported (0 warnings)`, and the receiver got the new
+ attribute (`count by (location)` of `hw.battery.charge` showed
+ `location="from-file"`).
+- **Share sheet / QR text:** `am start -a android.intent.action.SEND -t text/plain
+ --es android.intent.extra.TEXT ''` to the app: it showed "Use this
+ config?" with Import / Cancel; after Import the local file had the new
+ value (`from-share`).
+- **adb broadcast:** used for every test above (answer
+ `data="ok: config imported; applied"`).
+
+### 30 min network cut with an app restart in it
+
+```
+2026-11-13T11:15:30Z cut start: docker pause (receiver does not answer)
+2026-11-13T11:25:30Z restart 1: kill -9 of the app process 2399 (system-style kill; START_STICKY restarts it)
+2026-11-13T11:26:30Z pid after restart 1: 2608
+2026-11-13T11:35:30Z restart 2: am force-stop, then start again by adb broadcast
+2026-11-13T11:36:30Z pid after restart 2:
+2026-11-13T11:45:30Z cut end: docker unpause
+2026-11-13T11:47:30Z done; queue files: 0
+```
+
+`docker pause` makes the receiver accept TCP and then not answer, like a lost
+network. Restart 1 killed the process with `kill -9` (as the system does);
+Android started the service again (`START_STICKY`) one second later. The
+force-stop step (restart 2) did not run: the adb command gave no output and
+the process stayed the same (pid 2608 until the next install). So this test
+has one restart in the cut.
+
+`tools/vm_report.py` over 11:05–11:50 (raw points of `device.screen.on`):
+
+```
+window 2026-11-13 11:05:00 -> 2026-11-13 11:50:00 UTC
+readings: 39, first 2026-11-13 11:10:44, last 2026-11-13 11:47:31 UTC
+process starts (distinct device.agent.start_time): 2: 2026-11-13 11:10:44, 2026-11-13 11:25:31
+readings on the charger: 38, on battery: 1
+screen on: 0.10 of the readings
+timer wakes the CPU: 0.97 of the readings
+largest gap: 60 s
+gaps over 120 s on the charger: 0
+gaps over 120 s on the battery: 0
+readings per hour: 39
+```
+
+No reading is lost: one reading per minute from 11:10:44 to 11:47:31,
+largest gap 60 s, over the 30 min cut and the restart in it. The two
+`device.agent.start_time` values are the two processes. After the cut the
+queue sent all 30 files in order and was empty.
+
+### Unit tests
+
+`./gradlew :app:testDebugUnitTest`: 37 tests, 0 failures: config parsing and
+merging (`ConfigLoaderTest`), queue size cap, max age, order and the sender
+rules (`QueueTest`), each collector's mapping (`CollectorMappingTest`), the
+OTLP bodies (`OtlpEncoderTest`) and the timer plan (`TickPlanTest`).
+
+## Redmi Note 12S on HyperOS 2 (Android 15), 2026-11-14
+
+The phone runs a kiosk app and stays on the charger. The kiosk
+turns the screen on when it sees motion and off 60 s after the last motion.
+The signed release APK 0.1.0 was installed with `pm install` (the owner
+tapped Install). Config: the defaults plus `exporter.endpoint`,
+`exporter.logs_endpoint` and `resource.device.id`, imported by adb
+broadcast, so `wake_policy` is the default, `when_charging`.
+
+Phone settings changed for this app only (undo them in the same screens):
+
+- Security → Autostart: on.
+- App info → Battery saver: **No restrictions** (the app is now on the Doze
+ allow-list: `dumpsys deviceidle whitelist`; standby bucket 5 = exempted).
+- Alarms & reminders: allowed.
+
+The notification permission was not given: the foreground service runs
+without it, its notification is only hidden.
+
+### On the charger, screen off, `when_charging`, 1 h
+
+The service started at 07:10:45. The phone was off the charger for the first
+three readings, so the window starts at the first reading on the charger.
+`tools/vm_report.py` over 07:13:45–08:13:45:
+
+```
+window 2026-11-14 07:13:45 -> 2026-11-14 08:13:45 UTC
+readings: 60, first 2026-11-14 07:13:45, last 2026-11-14 08:12:48 UTC
+process starts (distinct device.agent.start_time): 1: 2026-11-14 07:10:45
+readings on the charger: 60, on battery: 0
+screen on: 0.07 of the readings
+timer wakes the CPU: 1.00 of the readings
+largest gap: 60 s
+gaps over 120 s on the charger: 0
+gaps over 120 s on the battery: 0
+readings per hour: 60
+```
+
+No gap over 120 s. The screen was on in about 7 % of the readings (4 of 60); the kiosk
+wakes it on motion. At the end, `dumpsys alarm` shows the app's exact alarm for
+the next reading:
+
+```
+ELAPSED_WAKEUP #4: Alarm{... dev.code6x.otelagent}
+ tag=*walarm*:dev.code6x.otelagent/.TickReceiver
+ type=ELAPSED_WAKEUP origWhen=+22s229ms window=0 exactAllowReason=allow-listed ...
+```
+
+`dumpsys power` "Wake Locks" lists only the kiosk app's locks: the app holds
+none between readings. Its short `otelagent:tick` lock (about 70 ms for each
+reading) shows only in the wake lock history.
+
+### 24 h, screen off most of the time, default `wake_policy`
+
+`tools/vm_report.py` over 24 h from the first reading (2026-11-14 07:10:45 to
+2026-11-15 07:10:45 UTC):
+
+```
+window 2026-11-14 07:10:45 -> 2026-11-15 07:10:45 UTC
+readings: 1439, first 2026-11-14 07:10:45, last 2026-11-15 07:09:50 UTC
+process starts (distinct device.agent.start_time): 1: 2026-11-14 07:10:45
+readings on the charger: 1436, on battery: 3
+screen on: 0.10 of the readings
+timer wakes the CPU: 1.00 of the readings
+largest gap: 60 s
+gaps over 120 s on the charger: 0
+gaps over 120 s on the battery: 0
+readings per hour: 60 60 60 60 60 60 60 60 60 60 60 60 60 60 60 60 60 60 60 60 60 60 59 60
+```
+
+- **One process start**: the service was not killed in 24 h. The same
+ process was still running on 2026-11-15 19:50 UTC.
+- **Gaps over 120 s**: none, on the charger (1436 readings) and on battery
+ (3 readings). The largest gap is 60 s. The one hour with 59 readings is
+ only where the window starts and ends between two readings.
+- The phone was on battery only for the first three readings (07:10:45 to
+ 07:12:46), then on the charger. In those three readings
+ `device.agent.wake` is 0: with `when_charging` the timer did not wake the
+ CPU on battery. "1.00" above is 1436 of 1439, rounded.
+- The screen was on in about 10 % of the readings (the kiosk turns it on
+ when it sees motion).
+
+At the end, `dumpsys alarm` still shows the app's exact alarm for the next
+reading (`ELAPSED_WAKEUP ... dev.code6x.otelagent/.TickReceiver ...
+exactAllowReason=allow-listed`), and `dumpsys power` "Wake Locks" lists only
+the system's `dream:doze` lock and the kiosk app's lock: none from the app.
diff --git a/docs/release.md b/docs/release.md
new file mode 100644
index 0000000..7ca02d2
--- /dev/null
+++ b/docs/release.md
@@ -0,0 +1,43 @@
+# Releases
+
+A release is a signed APK on GitHub Releases, made by the `Release` workflow
+(`.github/workflows/release.yml`) when a tag `vX.Y.Z` is pushed:
+
+```bash
+git tag v0.1.0 && git push origin v0.1.0
+```
+
+The workflow runs the unit tests, builds `assembleRelease` with
+`-PversionName=X.Y.Z` (versionCode = X·10000 + Y·100 + Z), checks the
+signature with `apksigner`, and publishes the APK and its sha256.
+
+## Signing key
+
+The key is never in git (`*.jks` and `*.keystore` are in `.gitignore`). The
+workflow reads it from four repository secrets:
+
+| Secret | What |
+|---|---|
+| `KEYSTORE_B64` | The keystore file, base64 (`base64 -w0 release.jks`) |
+| `KEYSTORE_PASSWORD` | Keystore password |
+| `KEY_ALIAS` | Key alias |
+| `KEY_PASSWORD` | Key password |
+
+Without `KEYSTORE_B64` the workflow stops with an error; it never publishes an
+unsigned APK. Keep a backup of the keystore outside GitHub: a lost key means
+users must uninstall the app before they can install a new version.
+
+To make a key:
+
+```bash
+keytool -genkeypair -v -keystore release.jks -alias release \
+ -keyalg RSA -keysize 4096 -validity 10000
+```
+
+Set the secrets with `gh secret set NAME -R code6x/android-otel-device-agent`
+(it reads the value from stdin).
+
+A local signed build works the same way: set `KEYSTORE_FILE`,
+`KEYSTORE_PASSWORD`, `KEY_ALIAS` and `KEY_PASSWORD` in the environment and run
+`./gradlew :app:assembleRelease -PversionName=X.Y.Z`. Without `KEYSTORE_FILE`
+the release APK is unsigned.
diff --git a/gradle.properties b/gradle.properties
new file mode 100644
index 0000000..bac900b
--- /dev/null
+++ b/gradle.properties
@@ -0,0 +1,3 @@
+org.gradle.jvmargs=-Xmx2560m -Dfile.encoding=UTF-8
+android.useAndroidX=true
+kotlin.code.style=official
diff --git a/gradle/wrapper/gradle-wrapper.jar b/gradle/wrapper/gradle-wrapper.jar
new file mode 100644
index 0000000..e644113
Binary files /dev/null and b/gradle/wrapper/gradle-wrapper.jar differ
diff --git a/gradle/wrapper/gradle-wrapper.properties b/gradle/wrapper/gradle-wrapper.properties
new file mode 100644
index 0000000..e2847c8
--- /dev/null
+++ b/gradle/wrapper/gradle-wrapper.properties
@@ -0,0 +1,7 @@
+distributionBase=GRADLE_USER_HOME
+distributionPath=wrapper/dists
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.11.1-bin.zip
+networkTimeout=10000
+validateDistributionUrl=true
+zipStoreBase=GRADLE_USER_HOME
+zipStorePath=wrapper/dists
diff --git a/gradlew b/gradlew
new file mode 100755
index 0000000..1aa94a4
--- /dev/null
+++ b/gradlew
@@ -0,0 +1,249 @@
+#!/bin/sh
+
+#
+# Copyright © 2015-2021 the original authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+##############################################################################
+#
+# Gradle start up script for POSIX generated by Gradle.
+#
+# Important for running:
+#
+# (1) You need a POSIX-compliant shell to run this script. If your /bin/sh is
+# noncompliant, but you have some other compliant shell such as ksh or
+# bash, then to run this script, type that shell name before the whole
+# command line, like:
+#
+# ksh Gradle
+#
+# Busybox and similar reduced shells will NOT work, because this script
+# requires all of these POSIX shell features:
+# * functions;
+# * expansions «$var», «${var}», «${var:-default}», «${var+SET}»,
+# «${var#prefix}», «${var%suffix}», and «$( cmd )»;
+# * compound commands having a testable exit status, especially «case»;
+# * various built-in commands including «command», «set», and «ulimit».
+#
+# Important for patching:
+#
+# (2) This script targets any POSIX shell, so it avoids extensions provided
+# by Bash, Ksh, etc; in particular arrays are avoided.
+#
+# The "traditional" practice of packing multiple parameters into a
+# space-separated string is a well documented source of bugs and security
+# problems, so this is (mostly) avoided, by progressively accumulating
+# options in "$@", and eventually passing that to Java.
+#
+# Where the inherited environment variables (DEFAULT_JVM_OPTS, JAVA_OPTS,
+# and GRADLE_OPTS) rely on word-splitting, this is performed explicitly;
+# see the in-line comments for details.
+#
+# There are tweaks for specific operating systems such as AIX, CygWin,
+# Darwin, MinGW, and NonStop.
+#
+# (3) This script is generated from the Groovy template
+# https://github.com/gradle/gradle/blob/HEAD/subprojects/plugins/src/main/resources/org/gradle/api/internal/plugins/unixStartScript.txt
+# within the Gradle project.
+#
+# You can find Gradle at https://github.com/gradle/gradle/.
+#
+##############################################################################
+
+# Attempt to set APP_HOME
+
+# Resolve links: $0 may be a link
+app_path=$0
+
+# Need this for daisy-chained symlinks.
+while
+ APP_HOME=${app_path%"${app_path##*/}"} # leaves a trailing /; empty if no leading path
+ [ -h "$app_path" ]
+do
+ ls=$( ls -ld "$app_path" )
+ link=${ls#*' -> '}
+ case $link in #(
+ /*) app_path=$link ;; #(
+ *) app_path=$APP_HOME$link ;;
+ esac
+done
+
+# This is normally unused
+# shellcheck disable=SC2034
+APP_BASE_NAME=${0##*/}
+# Discard cd standard output in case $CDPATH is set (https://github.com/gradle/gradle/issues/25036)
+APP_HOME=$( cd "${APP_HOME:-./}" > /dev/null && pwd -P ) || exit
+
+# Use the maximum available, or set MAX_FD != -1 to use that value.
+MAX_FD=maximum
+
+warn () {
+ echo "$*"
+} >&2
+
+die () {
+ echo
+ echo "$*"
+ echo
+ exit 1
+} >&2
+
+# OS specific support (must be 'true' or 'false').
+cygwin=false
+msys=false
+darwin=false
+nonstop=false
+case "$( uname )" in #(
+ CYGWIN* ) cygwin=true ;; #(
+ Darwin* ) darwin=true ;; #(
+ MSYS* | MINGW* ) msys=true ;; #(
+ NONSTOP* ) nonstop=true ;;
+esac
+
+CLASSPATH=$APP_HOME/gradle/wrapper/gradle-wrapper.jar
+
+
+# Determine the Java command to use to start the JVM.
+if [ -n "$JAVA_HOME" ] ; then
+ if [ -x "$JAVA_HOME/jre/sh/java" ] ; then
+ # IBM's JDK on AIX uses strange locations for the executables
+ JAVACMD=$JAVA_HOME/jre/sh/java
+ else
+ JAVACMD=$JAVA_HOME/bin/java
+ fi
+ if [ ! -x "$JAVACMD" ] ; then
+ die "ERROR: JAVA_HOME is set to an invalid directory: $JAVA_HOME
+
+Please set the JAVA_HOME variable in your environment to match the
+location of your Java installation."
+ fi
+else
+ JAVACMD=java
+ if ! command -v java >/dev/null 2>&1
+ then
+ die "ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH.
+
+Please set the JAVA_HOME variable in your environment to match the
+location of your Java installation."
+ fi
+fi
+
+# Increase the maximum file descriptors if we can.
+if ! "$cygwin" && ! "$darwin" && ! "$nonstop" ; then
+ case $MAX_FD in #(
+ max*)
+ # In POSIX sh, ulimit -H is undefined. That's why the result is checked to see if it worked.
+ # shellcheck disable=SC2039,SC3045
+ MAX_FD=$( ulimit -H -n ) ||
+ warn "Could not query maximum file descriptor limit"
+ esac
+ case $MAX_FD in #(
+ '' | soft) :;; #(
+ *)
+ # In POSIX sh, ulimit -n is undefined. That's why the result is checked to see if it worked.
+ # shellcheck disable=SC2039,SC3045
+ ulimit -n "$MAX_FD" ||
+ warn "Could not set maximum file descriptor limit to $MAX_FD"
+ esac
+fi
+
+# Collect all arguments for the java command, stacking in reverse order:
+# * args from the command line
+# * the main class name
+# * -classpath
+# * -D...appname settings
+# * --module-path (only if needed)
+# * DEFAULT_JVM_OPTS, JAVA_OPTS, and GRADLE_OPTS environment variables.
+
+# For Cygwin or MSYS, switch paths to Windows format before running java
+if "$cygwin" || "$msys" ; then
+ APP_HOME=$( cygpath --path --mixed "$APP_HOME" )
+ CLASSPATH=$( cygpath --path --mixed "$CLASSPATH" )
+
+ JAVACMD=$( cygpath --unix "$JAVACMD" )
+
+ # Now convert the arguments - kludge to limit ourselves to /bin/sh
+ for arg do
+ if
+ case $arg in #(
+ -*) false ;; # don't mess with options #(
+ /?*) t=${arg#/} t=/${t%%/*} # looks like a POSIX filepath
+ [ -e "$t" ] ;; #(
+ *) false ;;
+ esac
+ then
+ arg=$( cygpath --path --ignore --mixed "$arg" )
+ fi
+ # Roll the args list around exactly as many times as the number of
+ # args, so each arg winds up back in the position where it started, but
+ # possibly modified.
+ #
+ # NB: a `for` loop captures its iteration list before it begins, so
+ # changing the positional parameters here affects neither the number of
+ # iterations, nor the values presented in `arg`.
+ shift # remove old arg
+ set -- "$@" "$arg" # push replacement arg
+ done
+fi
+
+
+# Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.
+DEFAULT_JVM_OPTS='"-Xmx64m" "-Xms64m"'
+
+# Collect all arguments for the java command:
+# * DEFAULT_JVM_OPTS, JAVA_OPTS, JAVA_OPTS, and optsEnvironmentVar are not allowed to contain shell fragments,
+# and any embedded shellness will be escaped.
+# * For example: A user cannot expect ${Hostname} to be expanded, as it is an environment variable and will be
+# treated as '${Hostname}' itself on the command line.
+
+set -- \
+ "-Dorg.gradle.appname=$APP_BASE_NAME" \
+ -classpath "$CLASSPATH" \
+ org.gradle.wrapper.GradleWrapperMain \
+ "$@"
+
+# Stop when "xargs" is not available.
+if ! command -v xargs >/dev/null 2>&1
+then
+ die "xargs is not available"
+fi
+
+# Use "xargs" to parse quoted args.
+#
+# With -n1 it outputs one arg per line, with the quotes and backslashes removed.
+#
+# In Bash we could simply go:
+#
+# readarray ARGS < <( xargs -n1 <<<"$var" ) &&
+# set -- "${ARGS[@]}" "$@"
+#
+# but POSIX shell has neither arrays nor command substitution, so instead we
+# post-process each arg (as a line of input to sed) to backslash-escape any
+# character that might be a shell metacharacter, then use eval to reverse
+# that process (while maintaining the separation between arguments), and wrap
+# the whole thing up as a single "set" statement.
+#
+# This will of course break if any of these variables contains a newline or
+# an unmatched quote.
+#
+
+eval "set -- $(
+ printf '%s\n' "$DEFAULT_JVM_OPTS $JAVA_OPTS $GRADLE_OPTS" |
+ xargs -n1 |
+ sed ' s~[^-[:alnum:]+,./:=@_]~\\&~g; ' |
+ tr '\n' ' '
+ )" '"$@"'
+
+exec "$JAVACMD" "$@"
diff --git a/settings.gradle.kts b/settings.gradle.kts
new file mode 100644
index 0000000..90f66b0
--- /dev/null
+++ b/settings.gradle.kts
@@ -0,0 +1,18 @@
+pluginManagement {
+ repositories {
+ google()
+ mavenCentral()
+ gradlePluginPortal()
+ }
+}
+
+dependencyResolutionManagement {
+ repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
+ repositories {
+ google()
+ mavenCentral()
+ }
+}
+
+rootProject.name = "android-otel-device-agent"
+include(":app")
diff --git a/tools/vm_report.py b/tools/vm_report.py
new file mode 100755
index 0000000..369b36c
--- /dev/null
+++ b/tools/vm_report.py
@@ -0,0 +1,77 @@
+#!/usr/bin/env python3
+"""Report of one device's readings in VictoriaMetrics: gaps, charger, screen, process starts.
+
+Usage: vm_report.py VM_URL DEVICE_ID START END [MAX_GAP]
+ VM_URL base URL of VictoriaMetrics (not in the repo: pass it in)
+ DEVICE_ID the device.id resource attribute
+ START, END Unix seconds
+ MAX_GAP seconds (default 120): gaps longer than this are listed
+
+It reads raw points from /api/v1/export (no step), so a gap here is a real gap in
+the stored data. The reading times come from device.screen.on (power collector).
+A gap is put under "charger" or "battery" by the plug state of the reading before it.
+"""
+import json
+import sys
+import urllib.parse
+import urllib.request
+from datetime import datetime, timezone
+
+
+def export(url, sel, start, end):
+ q = urllib.parse.urlencode({"match[]": sel, "start": start, "end": end})
+ with urllib.request.urlopen(f"{url}/api/v1/export?{q}") as r:
+ return [json.loads(x) for x in r.read().decode().splitlines() if x.strip()]
+
+
+def points(series):
+ out = {}
+ for s in series:
+ for t, v in zip(s["timestamps"], s["values"]):
+ out[t] = v
+ return sorted(out.items())
+
+
+def ts(ms):
+ return datetime.fromtimestamp(ms / 1000, timezone.utc).strftime("%Y-%m-%d %H:%M:%S")
+
+
+def main():
+ url, dev, start, end = sys.argv[1].rstrip("/"), sys.argv[2], int(sys.argv[3]), int(sys.argv[4])
+ max_gap = float(sys.argv[5]) if len(sys.argv) > 5 else 120
+ d = f'device.id="{dev}"'
+ screen = points(export(url, f'{{__name__="device.screen.on",{d}}}', start, end))
+ on_battery = dict(points(export(url, f'{{__name__="device.battery.plug",battery.plug="none",{d}}}', start, end)))
+ starts = sorted({v for _, v in points(export(url, f'{{__name__="device.agent.start_time",{d}}}', start, end))})
+ wake = points(export(url, f'{{__name__="device.agent.wake",{d}}}', start, end))
+ if not screen:
+ print("no readings")
+ return
+ times = [t for t, _ in screen]
+ print(f"window {ts(start * 1000)} -> {ts(end * 1000)} UTC")
+ print(f"readings: {len(times)}, first {ts(times[0])}, last {ts(times[-1])} UTC")
+ print(f"process starts (distinct device.agent.start_time): {len(starts)}: " +
+ ", ".join(ts(s * 1000) for s in starts))
+ n_batt = sum(1 for t in times if on_battery.get(t) == 1)
+ print(f"readings on the charger: {len(times) - n_batt}, on battery: {n_batt}")
+ print(f"screen on: {sum(v for _, v in screen) / len(screen):.2f} of the readings")
+ if wake:
+ print(f"timer wakes the CPU: {sum(v for _, v in wake) / len(wake):.2f} of the readings")
+ gaps = [(a, b) for a, b in zip(times, times[1:]) if (b - a) / 1000 > max_gap]
+ all_gaps = [(b - a) / 1000 for a, b in zip(times, times[1:])]
+ print(f"largest gap: {max(all_gaps or [0]):.0f} s")
+ for where in ("charger", "battery"):
+ sel = [(a, b) for a, b in gaps if (on_battery.get(a) == 1) == (where == "battery")]
+ print(f"gaps over {max_gap:.0f} s on the {where}: {len(sel)}")
+ for a, b in sel:
+ print(f" {(b - a) / 1000:.0f} s: {ts(a)} -> {ts(b)} UTC")
+ # Readings per hour, from the start of the window.
+ hours = {}
+ for t in times:
+ h = (t // 1000 - start) // 3600
+ hours[h] = hours.get(h, 0) + 1
+ print("readings per hour: " + " ".join(str(hours.get(h, 0)) for h in range((end - start + 3599) // 3600)))
+
+
+if __name__ == "__main__":
+ main()