ios-usage-prometheus-exporter is a Prometheus Exporter, written in Golang that allows metrics from certain actions in iOS 13 to be exported into Prometheus. It centres around a HTTP RESTful API, that can be called using the new Shortcuts application available in iOS 13 based on certain triggers. Metrics are exported via the
/metrics endpoint, that listens on a different port to the main API.
It operates in a very similar fashion to Prometheus Pushgateway, however, due to the fact that Pushgateway is only "vaguely REST-like", the iOS
Get Contents of URL doesn't play nicely with it. It also has no authentication which makes it challenging to expose externally (which is essential for a roaming iOS device).
What possible use case could you have for this?
I created this as a fun little side project, primarily because I was bored. But I also wanted to track my usage of social media and make a conscious effort to reduce the amount of times I was opening my social media apps. I use these metrics to graph my usage in Grafana.
Currently there is only one supported function type which is the
incTotalAppOpens endpoint that tracks how many times an application is opened. This will be expanded with other useful metrics over time.
incTotalAppOpens endpoint is used for incrementing a Prometheus Counter each time an application (or group of applications) are opened. Counter increments are performed by making a HTTP Get request via the iOS 13
Get Contents of URL action.
These are exported via the
ios_app_open_total Prometheus Counter Metric. This metric has two labels:
deviceName: Derived from the
deviceNameHTTP header, used for aggregating stats across multiple devices.
appName: Derived from the
appNameHTTP header, used for identifying individual, or groups of applications.
|apiKey||The API key that you defined in your configuration for authentication.||None||true|
|deviceName||The Device Name that the metrics are for. Used in the
|appName||The App Name (e.g Instagram) or group name (e.g. Social). Used in the
Example Usage - Instagram
- Create a new Personal Automation in iOS 13
- Define a trigger of "Open App" and select Instagram
- Add the
Get contents of URLAction
- Enter the FQDN of your instance of ios-usage-prometheus-exporter, followed by the
incTotalAppOpensAPI endpoint. For example:
- Add the 3 headers:
appNameand their associated values.
- Save and ensure the "Ask Before Running" option is not selected.
- Open Instagram
- Validate success by running the
- iOS 13 does not allow you to get the name of the application as a variable which can be used in a HTTP Request. Consequently you need to create a trigger for each application (or group of applications) that you wish to track.
Deployment and Configuration
ios-usage-prometheus-exporter is designed to be deployed in Kubernetes.
You do not need to build this container, it is available in the maynard-io-public Google Container Repository: gcr.io/maynard-io-public/ios-usage-prometheus-exporter
The API Webserver Port (defined by the
WEBSERVER_PORT environment variable) should be exposed externally so that your iOS device can make API calls based on your defined triggers. It is strongly recommended that expose ios-usage-prometheus-exporter using HTTPS. SSL/TLS should be configured on your Load Balancer (or ingress if using something like ingress-nginx).
Service discovery in Kubernetes should be used for scraping the metrics, which are exposed via a separate port (defined by the
PROMETHEUS_PORT environment variable). This should not be exposed externally.
The following environment variables are used by ios-usage-prometheus-exporter for configuration:
|API_KEY||A secure API Key that will be validated against the
|PROMETHEUS_PORT||The port to use for the webserver that exposes the
|WEBSERVER_PORT||The port to use for the webserver that exposes the ios-usage-prometheus-exporter REST API||80||false|
A docker-compose.yml file is contained in this repository for testing on your local machine.