.. Copyright (C) 2020 Maciej Delmanowski <drybjed@gmail.com>
.. Copyright (C) 2020 DebOps <https://debops.org/>
.. SPDX-License-Identifier: GPL-3.0-only

Getting started
===============

.. only:: html

   .. contents::
      :local:


Default configuration
---------------------

The ``filebeat`` role includes a basic configuration for Filebeat which will by
default enable inputs for :file:`/var/log/*.log` files, as well as the
``system`` module. Several other Filebeat modules and input log configurations
will be enabled conditionally, based on the presence of various Ansible local
facts.

The role will also configure Filebeat to read input configuration from the
:file:`/etc/filebeat/inputs.d/` directory, where other applications can add
their own configuration. The directory will not be created by default unless
configuration snippets placed in it are configured or enabled conditionally.

The default output is directed at an Elasticsearch database installed on the
same host as Filebeat. To change it, you can define in the Ansible inventory:

.. code-block:: yaml

   filebeat__configuration:

     - name: 'output_elasticsearch'
       config:
         output.elasticsearch:
           hosts: [ 'elasticsearch.example.org:9200' ]

See the :ref:`filebeat__ref_configuration` documentation for more details.
Elasticsearch database can be installed using the :ref:`debops.elasticsearch`
role.

Check the `Filebeat configuration`__ upstream documentation to learn more about
configuring Filebeat for your environment and requirements.

.. __: https://www.elastic.co/guide/en/beats/filebeat/current/configuring-howto-filebeat.html


Role debugging tips
-------------------

Most of the configuration files generated by the role are protected by the
Ansible ``no_log`` keyword. To make debugging easier, you can use the
:envvar:`debops__no_log` variable in an inventory (in the development
environment) or with Ansible ``--extra-vars`` parameter (one time, for
production environment) to disable log protection. See the variable
documentation for more details.


Example inventory
-----------------

To install and configure Filebeat on a host, it needs to be included in the
``[debops_service_filebeat]`` Ansible inventory group:

.. code-block:: none

   [debops_all_hosts]
   hostname

   [debops_service_filebeat]
   hostname


Example playbook
----------------

If you are using this role without DebOps, here's an example Ansible playbook
that uses the ``debops.filebeat`` role:

.. literalinclude:: ../../../../ansible/playbooks/service/filebeat.yml
   :language: yaml
   :lines: 1,5-


Ansible tags
------------

You can use Ansible ``--tags`` or ``--skip-tags`` parameters to limit what
tasks are performed during Ansible run. This can be used after host is first
configured to speed up playbook execution, when you are sure that most of the
configuration has not been changed.

Available role tags:

``role::filebeat``
  Main role tag, should be used in the playbook to execute all of the role
  tasks as well as role dependencies.
