friendica-exporter/README.md

friendica-exporter

A prometheus exporter for getting some metrics of a Friendica 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

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 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:

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:

# 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

$ 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 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:

# 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:

# 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:

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:

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