166 lines
9.2 KiB
Markdown
166 lines
9.2 KiB
Markdown
|
# 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-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 |
|