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()