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

Grafana Promtail
################

Official documentation website can be found `here <https://grafana.com/docs/loki/latest/send-data/promtail/>`_.

Promtail can read two different types of logs. Regular log files, or information from the Systemd journald.

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


Download promtail
=================

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

.. code-block::

   # cd /tmp
   # wget https://github.com/grafana/loki/releases/download/v3.0.0/promtail-linux-amd64.zip
   # unzip promtail-linux-amd64.zip -d .
   # mv promtail-linux-amd64 promtail
   # cp promtail /usr/local/bin

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

.. code-block:: console

   # useradd --system --no-create-home --shell /bin/false promtail
   # usermod -G adm -a promtail # Add the "promtail" user, to the "adm" group if necessary.

Promtail configuration file
===========================

.. code-block:: yaml

   # Path: /etc/promtail/config.yml

   server:
     http_listen_port: 9080
     grpc_listen_port: 0

   positions:
     filename: /tmp/positions.yaml

   clients:
     - url: http://localhost:3100/loki/api/v1/push

   # Example for log file

   scrape_configs:
   - job_name: system
     static_configs:
     - targets:
         - localhost
       labels:
         job: nginx
         __path__: /var/log/nginx/*log # List here your log files

   # Example for Systemd journald

   scrape_configs:
   - job_name: journal
     journal:
      json: true
      path: /var/log/journal
      labels:
        job: systemd-journal
    relabel_configs:
      - source_labels: ['__journal__systemd_unit']
        target_label: 'unit'

Promtail systemd service file
=============================

.. code-block:: systemd

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

   [Unit]
   Description=Promtail service
   After=network.target

   [Service]
   Type=simple
   User=promtail
   ExecStart=/usr/local/bin/promtail -config.file /etc/promtail/config.yml
   # Give a reasonable amount of time for promtail to start up/shut down
   TimeoutSec = 60
   Restart = on-failure
   RestartSec = 2

   [Install]
   WantedBy=multi-user.target


Start and enable Promtail
-------------------------

.. code-block:: console

    # systemctl enable --now promtail.service
    # systemctl status promtail.service


Promtail temporary files
========================

.. code-block:: console

   # cd /tmp
   # touch positions.yaml
   # chown promtail:promtail /tmp/positions.yaml

Grafana control panel
=====================

To check if Promtail is reading properly either your log files or the systemd journald units, you can click on the "Explore" section in the Grafana control panel, choose the right Loki connector, choose your desired log file or journald unit, and execute the query.
If you see this is working (you can see the chunks of the big log files),
you can convert this temporary query into a real Grafana "dashboard", to continue working later with additional filtering options.