.. _logs:

Logging
=====================================

Consulting logs is one of the first things you should do to identify a cause of a problem. By default, the FindFace Multi processes are logged to `Docker container logs <https://docs.docker.com/config/containers/logging/>`__,  which can be accessed via the ``docker logs`` and ``docker service logs`` commands. In addition, Docker uses the `json-file logging driver <https://docs.docker.com/config/containers/logging/json-file/>`__, which caches container logs in JSON.  You can configure Docker to use another logging driver, choosing from the `multiple logging mechanisms available <https://docs.docker.com/config/containers/logging/configure/>`__.

This section describes how to set up Docker to use the ``journald`` logging driver, which sends container logs to the ``systemd`` journal. In this case, log entries are retrieved using the ``journalctl`` command, through the ``journal API``, or the ``docker logs`` command. You can configure the ``systemd`` journal as well by using the instructions below. 

.. rubric:: In this section:

.. contents::
   :local:

Configure Journald
-----------------------------------------

To configure the ``systemd-journal`` service, do the following:

#. Check whether the ``/var/log/journal`` directory already exists. If not, create it by executing the following command:

   .. code::

      sudo mkdir /var/log/journal
      sudo chmod 2755 /var/log/journal

#. Open the ``/etc/systemd/journald.conf`` configuration file. Enable saving ``journald`` logs to your hard drive by uncommenting the ``Storage`` parameter and changing its value to ``persistent``. Disable filtering in ``systemd-journal`` as well:

   .. code::

      sudo vi /etc/systemd/journald.conf 

      [Journal]
      ...
      Storage=persistent
      ...
      RateLimitInterval=0
      RateLimitBurst=0
      ...

   If necessary, uncomment and edit the ``SystemMaxUse`` parameter. This parameter determines the maximum volume of log files on your hard drive. Specify its value in bytes or use K, M, G, T, P, E as units for the specified size (equal to :math:`1024`, :math:`1024^2`, ... bytes).

   .. code::

      ...
      SystemMaxUse=3G

#. Restart the ``journald`` service.

   .. code::

      sudo systemctl restart systemd-journald.service 

Enabling Journald Logging Driver
------------------------------------- 

To enable Docker to use the ``journald`` logging driver, do the following:

#. Add the following line to the ``/etc/docker/daemon.json`` configuration file.

   .. tip::
      This file may not be present on your system. Check whether it exists and if it does not, create the ``/etc/docker`` directory first and then the file.

      .. code::

         sudo mkdir /etc/docker
         sudo touch /etc/docker/daemon.json


   .. code::

      sudo vi /etc/docker/daemon.json

      {
        "log-driver": "journald"
      }

#. Stop all Docker containers.

   .. code::

      sudo docker stop $(sudo docker ps -a -q) 

#. Restart the Docker service.

   .. code::

      sudo systemctl restart docker

#. Start all Docker containers.

   .. code::

      sudo docker start $(sudo docker ps -a -q)
   

Consult Logs
-----------------------------

Use any convenient method to work with the ``journald`` logs. The following commands are a good place to start:

* Display all logs:

  .. code::

     journalctl -fa

* Display logs by container ID:

  .. code::
 
     journalctl CONTAINER_ID=<container_id> -f

* Display logs by container name:

  .. code::
 
     journalctl CONTAINER_NAME=<container-name> -f 


.. seealso::
   :ref:`audit-logs`