friendica-exporter/README.md

# 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