readme draft

README.md

@@ -2,14 +2,16 @@
 
 [![CircleCI](https://dl.circleci.com/status-badge/img/gh/birdthedeveloper/prometheus-android-exporter/tree/master.svg?style=svg&circle-token=6a31d132a46fd4e7cf04dd49ef390f1776e38cfc)](https://dl.circleci.com/status-badge/redirect/gh/birdthedeveloper/prometheus-android-exporter/tree/master)
 
-Prometheus Exporter for Android phones. It is not yet available in Google Play. 
+Prometheus exporter for Android phones. It is not yet available on Google Play.
-Apart from simply exporting available metrics on default HTTP port 10101, it can also traverse NAT
+Prometheus Android Exporter is implemented in Kotlin in Jetpack Compose.
+Apart from simply exporting available metrics on the default HTTP port 10101, it can also traverse NAT
 by connecting to the PushProx proxy.
 It also supports scraping metrics locally and storing them in memory while offline and
-exporting them later while online.
+exporting them later while online using the Prometheus remote write protocol.
+
 
 ## Operation
-This application can operate in three modes:
+This application can operate in three modes (simultaneously):
 - as a Prometheus exporter by exposing metrics on HTTP port 10101
 - as a PushProx proxy client, to traverse NAT and other network barriers while still following
     the pull model
@@ -18,26 +20,13 @@ This application can operate in three modes:
 
 Application is configurable either via its UI or via YAML configuration file.
 
-# Repository contents
+### UI configuration
-- Folder ./client contains Jetpack Compose android Prometheus exporter written in kotlin.
+Each tab on the homepage of the application corresponds to one application mode.
-- Folder ./server contains ansible playbook for simple deployment of prometheus monitoring stack
+For example, to configure PushProx client to traverse NAT while still following the pull model,
-    on a virtual private server, that is deployment of prometheus database itself, grafana
+I can open the application, go to tab "PushProx", fill out FQDN - fully qualified domain name and PushProx
-    monitoring dashboard and pushprox, a prometheus proxy used to traverse NAT while still following
+URL, switch this mode on by tapping on the switch, and tap "Start".
-    the pull model.
-- Folder ./local contains simple docker-compose.yaml to spin up prometheus database on localhost
-    quickly.
 
-# Not public
+### File configuration
-143.42.59.63:9090 - prometheus
-
-# Client
-
-## To format code in android studio
-```
-CTRL + SHIFT + ALT + L
-```
-
-## File configuration
 Client application is configurable via a configuration file.
 Place such file on your android device at a following path:
 ```
@@ -45,30 +34,73 @@ data/user/0/com.birdthedeveloper.prometheus.android.exporter/files/
 ```
 The name of such configuration file can be either `config.yaml` or `config.yml`
 
-Configurable fields are described in `./config_file_structure.yaml`, all
+Configurable fields are described in `./config_file_structure.yaml`, most fields are optional.
-fields are optional.
 
-## ADB port forwarding
+After configuring the application via configuration file, one has to still start the exporter manually by
+opening the app and hitting "Start" button.
+
+
+## Repository contents
+- `.circleci` contains configuration file for continuous integration pipeline, that runs
+  on the CircleCI platform. This CI pipeline runs linter, unit tests, and builds the project for each commit.
+- Folder `client` contains Jetpack Compose Android Prometheus Exporter written in Kotlin.
+  This is a Android Studio project.
+  Inside the Android project, inside the java/com/birdthedeveloper/prometheus/android/exporter 
+  folder are the following Kotlin files:
+    - `compose/Configuration.kt`: parser of the YAML file.
+    - `compose/HomeActivity.kt`: homepage UI, all three tabs are defined here.
+    - `compose/MainActivity.kt`: main activity, application navigation is defined here.
+    - `compose/PromViewModel.kt`: View model, global state management of the application.
+    - `compose/SettingsActivity.kt`: The settings page with attribution and license notice.
+    - `ui/*`: these files were generated with the project.
+    - `worker/AndroidCustomExporter.kt`: here is implemented a custom collector for metrics along with all the functions that collect various hardware and software metrics from the device.
+    - `worker/ExponentialBackoff.kt`: here is implemented a simple exponential backoff strategy, used when sending HTTP requests using either batch exporter or PushProx client mode.
+    - `worker/MetricsEngine.kt`: functions for accessing hardware sensors and other metrics.
+    - `worker/PrometheusServer.kt`: implementation of the Prometheus exporter - HTTP server via Ktor.
+    - `worker/PromWorker.kt`: implementation of the Android WorkManager worker. This worker consumes configuration from either 
+    - `worker/PushProxClient.kt`: in the file is implemented the PushProx client mode
+    - `worker/RemoteWriteSender.kt`: in this file is implemented the batch exporter mode.
+    - `worker/RemoteWriteSenderMemStorage.kt`: memory store for metrics when the device is offline. Used by the batch exporter.
+    - `worker/RemoteWriteSenderStorage.kt`: abstract class that serves as a contract for the batch exporter storage.
+       If you want to add persistent storage to metrics, extend this class.
+    - `worker/Util.kt`: this file contains utility functions used accross the whole app, such as function to determine whether a network is available.
+- Folder `server` contains ansible playbook for simple deployment of prometheus monitoring stack
+    on a virtual private server, that is deployment of prometheus database itself, grafana
+    monitoring dashboard and pushprox, a prometheus proxy used to traverse NAT while still following
+    the pull model.
+- Folder `local` contains simple docker-compose.yaml files to spin up prometheus database on localhost
+    quickly for testing purposes with desired configuration.
+- Configuration options for the YAML file are described in `config_file_structure.yaml`.
+
+
+## Some helpful information for development
+
+### ADB port forwarding
 ADB port forwarding is usefull when running the client application 
-on android emulator and prometheus database on the host
+on an android emulator and prometheus database on the host
 ADB port forwarding allows to map specific host's port to emulator's port
 Syntax is as follows (for port 8080)
 ```
 $ adb forward tcp:8080 tcp:8080
 ```
 
-# Server configuration for PushProx proxy
+## Server configuration for PushProx proxy
+To configure new VPS linux server for Prometheus with PushProx proxy, you can use the provided 
+ansible playbook. 
+This playbook is meant to be use against freshly provisioned RedHat Linux or Rocky Linux or Alma Linux server. 
 
-## TL;DR
+To run locally, just use the included docker-compose.yaml file as a template.
+
+### TL;DR
 ```
-cd ./server
+$ cd ./server
 
-# edit ansible_inventory
+# edit ansible_inventory to add your own linux server
 
 # To apply ansible playbook
 $ ansible-playbook ansible_playbook.yaml
 
-# To only apply changed configuration
+# To only apply changed configuration (for example change prometheus.yaml file)
 $ ansible-playbook ansible_playbook.yaml --tags config
 ```