..
  This file is part of GNU TALER.
  Copyright (C) 2014-2023 Taler Systems SA

  TALER is free software; you can redistribute it and/or modify it under the
  terms of the GNU Affero General Public License as published by the Free Software
  Foundation; either version 2.1, or (at your option) any later version.

  TALER is distributed in the hope that it will be useful, but WITHOUT ANY
  WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
  A PARTICULAR PURPOSE.  See the GNU Affero General Public License for more details.

  You should have received a copy of the GNU Affero General Public License along with
  TALER; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>

  @author Javier Sepulveda

Installation of Prometheus
##########################

.. contents:: Table of Contents
   :depth: 1
   :local:

Download Prometheus
===================

* Download
* Extract
* Copy files to /usr/local/bin
* Set ownership and permissions

.. code-block:: console

   $ wget https://github.com/prometheus/prometheus/releases/download/v2.52.0/prometheus-2.52.0.linux-amd64.tar.gz -O /tmp/prometheus.tar.gz
   $ cd /tmp
   $ tar -xvzf prometheus.tar.gz
   $ mkdir /etc/prometheus
   $ mkdir /var/lib/prometheus

.. code-block:: console

   $ chown prometheus:prometheus /etc/prometheus
   $ chown prometheus:prometheus /var/lib/prometheus/
   $ cp prometheus promtool /usr/local/bin/
   $ chown prometheus:prometheus /usr/local/bin/prometheus
   $ chown prometheus:prometheus /usr/local/bin/promtool
   $ cp -R consoles console_libraries /etc/prometheus/
   $ chown -R prometheus:prometheus /etc/prometheus/consoles
   $ chown -R prometheus:prometheus /etc/prometheus/console_libraries
   $ chown prometheus:prometheus /etc/prometheus/prometheus.yml 


Create a system user
====================

.. code-block:: console

   $ useradd --no-create-home --shell /bin/false prometheus


Configuring Prometheus
======================

The main configuration file of Prometheus is in the YAML format, and it is located
on /etc/prometheus/prometheus.yml. Please be aware YAML, is a very sensitive format,
where white spaces matter.

.. note::
   If you find that your prometheus service is not working properly,
   please always check the prometheus.yml configuration file, or the systemd prometheus.service file,
   as in most of occasions, these are the main source of errors.


Prometheus main configuration file
----------------------------------

.. code-block:: yaml

   # Path: /etc/prometheus/prometheus.yml

   global:
      scrape_interval:     15s
      evaluation_interval: 15s

   scrape_configs:
     - job_name: prometheus
        static_configs:
        - targets: ['localhost:9090']

Prometheus Systemd service file
===============================

.. code-block:: systemd

   # Path: /etc/systemd/system/prometheus.service

   [Unit]
   Description=Prometheus
   Wants=network-online.target
   After=network-online.target

   [Service]
   User=prometheus
   Group=prometheus
   Type=simple
   ExecStart=/usr/local/bin/prometheus \
      --config.file /etc/prometheus/prometheus.yml \
      --storage.tsdb.path /var/lib/prometheus/ \
      --web.console.templates=/etc/prometheus/consoles \
      --web.console.libraries=/etc/prometheus/console_libraries

   [Install]
   WantedBy=multi-user.target


Refresh systemd file and restart Prometheus
-------------------------------------------

.. code-block:: console

   # systemctl daemon-reload
   # systemctl start prometheus
   # systemctl status prometheus
   # systemctl enable prometheus.service


Check
------

The prometheus service should be listening on the 9090 port, check this with your Internet browser,
by typing http://ip:9090.

.. note::

   If you find any problem to start the prometheus service, use the "journalctl -u prometheus" command
   to find any errors. Always check twice the prometheus.yml and the prometheus.service files.


Close the 9090 port with Nginx
==============================

.. note::

   This is optional, but increases security, by closing your server 9090 listening port.

In order to reverse proxy the Prometheus default port (9090) to loopback with NGINX,
you need to undertake 3 actions:

- Modify the current systemd service file
- Create a new Nginx virtualhost file to loopback port 9090 to prometheus
- Restart the Prometheus systemd service file


Modify the Prometheus systemd service file
------------------------------------------

.. code-block:: systemd

   ExecStart=/usr/local/bin/prometheus \
      --config.file=/etc/prometheus/prometheus.yml \
      --storage.tsdb.path=/var/lib/prometheus \
      --web.console.templates=/etc/prometheus/consoles \
      --web.console.libraries=/etc/prometheus/console_libraries \
      --web.listen-address=127.0.0.1:9090 \ # Add this line ****
      --web.external-url=/prometheus/ # Add this line ****


Nginx configuration
-------------------

.. code-block:: nginx

   # Path: /etc/nginx/sites-available/prometheus.conf

   server {
      listen 80;
      listen [::]:80;
      server_name name.domain.tld;
      root /dev/null;

      location /prometheus/ {
         proxy_pass http://localhost:9090;
      }
   }

.. code-block:: console

   ## Create the Nginx symbolic link to enable the virtualhost file
   # ln -s /etc/nginx/sites-available/prometheus.conf /etc/nginx/sites-enabled/prometheus
   # nginx -t
   # systemctl reload nginx


Restart the Prometheus service
------------------------------

.. code-block:: console

   # systemctl daemon-reload
   # systemctl restart prometheus

Check
-----

If you have done all steps explained above you won't be able to reach Prometheus
anymore from your web browser (http://ip:9090).
To reach the prometheus program from your web browser you will have to access through
the subdomain or domain name, that you specified on the nginx virtualhost file. 


Grafana control panel (GUI)
===========================

To add the server prometheus connector or datasource, to the `Taler grafana server <https://grafana.taler.net>`_
go to "Connections->Add new connection" and search for "Prometheus" in the search text field. Once you have found and selected the Prometheus connection type, just press the blue button "Add new data source".The main 2 fields required to specify are the name of the connector, and the URL. Then just press "Save and test", and you are done.

.. note::

   Please find the main official documentation in `Prometheus official documentation <https://prometheus.io/>`_