# friendica-exporter A [prometheus](https://prometheus.io) exporter for getting some metrics of a [Friendica](https://friendi.ca/) server instance. ## Installation ### Docker image The preferred way to use `friendica-exporter` is by running the provided Docker image. It is currently provided on Docker Hub: - [`friendica/friendica-exporter`](https://hub.docker.com/r/friendica/friendica-exporter/) The following tags are available: - `x.y.z` pointing to the release with that version - `latest` pointing to the most recent released version - `stable` pointing to the latest build from the default branch ### Pre-built binaries The [releases](https://git.friendi.ca/friendica/friendica-exporter/releases) page contains pre-built binaries for AMD64 and ARM64 linux. ### Build from Source If you have a recent Go installation (see `go.mod` for the minimum version), Git and GNU Make, the following commands will check out the repository and compile the binary from source: ```bash git clone https://git.friendi.ca/friendica/friendica-exporter.git cd friendica-exporter make ``` After this there should be a `friendica-exporter` binary in your current directory. ### Token authentication Frienidca only supports using a `system.stats_token` to access the `/stats` endpoint. You can set the token to anything you like, but teh recommendation is to set it to along random number: ```bash # Generate random value (for example using openssl) TOKEN=$(openssl rand -hex 32) # Set token (using the occ console application) bin/console.php config system stats_config "$TOKEN" ``` ## Usage ```plain $ friendica-exporter --help Usage of friendica-exporter: -a, --addr string Address to listen on for connections. (default ":9205") -c, --config-file string Path to YAML configuration file. -s, --server string URL to Friendica server. -u, --statsToken string Token for statistics Endpoint of Friendica. -t, --timeout duration Timeout for getting server info document. (default 5s) --tls-skip-verify Skip certificate verification of Friendica server. -V, --version Show version information and exit. ``` After starting the server will offer the metrics on the `/metrics` endpoint, which can be used as a target for prometheus. ### Example Dashboard The repository contains an [example Grafana dashboard](contrib/grafana-dashboard.json) that can be imported into Grafana. ### Configuration methods There are three methods of configuring the friendica-exporter (higher methods take precedence over lower ones): - Environment variables - Configuration file - Command-line parameters #### Environment variables All settings can also be specified through environment variables: | Environment variable | Flag equivalent | |----------------------------:|:---------------------| | `FRIENDICA_SERVER` | --server | | `FRIENDICA_STATS_TOKEN` | --stats-token | | `FRIENDICA_LISTEN_ADDRESS` | --addr | | `FRIENDICA_TIMEOUT` | --timeout | | `FRIENDICA_TLS_SKIP_VERIFY` | --tls-skip-verify | #### Configuration file The `--config-file` option can be used to read the configuration options from a YAML file: ```yaml # required server: "https://example.com" # required for token authentication statsToken: "example-token" # optional listenAddress: ":9205" timeout: "5s" tlsSkipVerify: false ``` ### Loading Credentials from Files The stats token can optionally be read from a separate file instead of directly from the input methods above. This can be achieved by setting the value to the path of the file prefixed with an "@", for example: ```bash # Authentication token friendica-exporter -c config-without-token.yml --stats-token @/path/to/tokenfile ``` This also works when token token is set using one of the other configuration modes (configuration file or environment variables). ## Other information ### Info URL The exporter reads the metrics from the Friendica server using its "stats" endpoint. It should look something like this: ```plain https://example.com/stats ``` The path will be automatically added to the server URL you provide, so in the above example setting `--server https://example.com` would be sufficient. If you open this URL in a browser you should see an XML structure with the information that will be used by the exporter. ### Scrape configuration The exporter will query the friendica server every time it is scraped by prometheus. If you want to reduce load on the friendica server you need to change the scrape interval accordingly: ```yml scrape_configs: - job_name: 'friendica' scrape_interval: 90s static_configs: - targets: ['friendica:9205'] ``` ### Exported metrics These metrics are exported by `friendica-exporter`: | name | description | |----------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | friendica_cron_last_execution | Contains information about the last execution of cron of this Instance | | friendica_exporter_info | Information about the friendica-exporter | | friendica_up | Indicates if the metrics could be scraped by the exporter | | friendica_update_available | Contains information whether a system update is available (0 = no, 1 = yes). The available_version level contains the latest available Friendica version, whereas the version level contains the current installed Friendica version. | | friendica_update_db_status | Contains information whether a database update was successful (0 = no, 1 = yes) | | friendica_update_status | Contains information whether a system update was successful (1 = no, 0 = yes) | | friendica_users_active_half_year | Number of active users of the last half year | | friendica_users_active_month | Number of active users of the last month | | friendica_users_active_week | Number of active users of the last week | | friendica_users_pending | Number of pending users | | friendica_users_total | Number of total users of this Instance | | friendica_worker_jpm | Number of jobs per Minute | | friendica_worker_last_execution | Contains information about the last execution of worker of this Instance | | friendica_worker_tasks_active | Number of active worker tasks of this Instance | | friendica_worker_tasks_total | Number of worker tasks of this Instance | # Thanks Special thanks goes to https://github.com/xperimental and his contributors, because a lot of code is based on https://github.com/xperimental/nextcloud-exporter