Configuration documentation

Commits fills in the documentation part that touches
configuring monasca-log-api. With this documentation one
can learn about possible ways and options needed to
have own monasca-log-api properly configured.

Story: 2001058
Task: 4783

Change-Id: I8ae3531fff6d70450b187a4945ce68c472db63b6
This commit is contained in:
Tomasz Trębski 2017-07-10 13:24:10 +02:00 committed by Witold Bedyk
parent 86433df26f
commit d14e2abc17
6 changed files with 263 additions and 42 deletions

View File

@ -2,12 +2,12 @@
200:
la_up: |
API is up and running
API is up and running.
204:
default: |
Normal response error, everything went as expected (or even better).
Normal response code, everything went as expected (or even better).
la_up: |
API is up and running
API is up and running.
400:
default: |
Sent data was malformed.
@ -25,32 +25,32 @@
Sent body is too large to be processed.
422:
default: |
Send data could not be processed properly
Send data could not be processed properly.
no_dims: |
Dimension are required
Dimensions are required.
dim_name_too_long: |
Dimension name {name} must be 255 characters or less
Dimension name {name} must be 255 characters or less.
dim_name_underscore: |
Dimension name {name} cannot start with underscore (_)
Dimension name {name} cannot start with underscore (_).
dim_name_forbidden_chars: |
Dimension name {name} may not contain: "> < = { } ( ) \' " , ; &"
Dimension name {name} may not contain: "> < = { } ( ) \' " , ; &".
dim_name_empty: |
Dimension name cannot be empty
Dimension name cannot be empty.
dim_value_too_long: |
Dimension value {value} must be 255 characters or less
Dimension value {value} must be 255 characters or less.
dim_value_empty: |
Dimension value cannot be empty
Dimension value cannot be empty.
app_type_too_long: |
Application type {type} must be {length} characters or less
Application type {type} must be {length} characters or less.
log_no_msg: |
Log property should have message
Log property must have message.
bad_envelope: |
Failed to create Envelope
Failed to create an envelope.
503:
default: |
The server is currently unable to handle the request due to a
temporary overload or scheduled maintenance, which will likely be
alleviated after some delay.
temporary overload or scheduled maintenance.
This will likely be alleviated after some delay.
no_health:
API is running but problems with peripheral components have been spotted
API is running but there are problems with peripheral components.

View File

@ -1,4 +1,139 @@
.. _basic-configuration:
Basic Configuration
===================
-----------
Configuring
-----------
monasca-log-api has several configuration options. Some of them
are inherited from oslo libraries, others can be found in the monasca-log-api
codebase.
The entire configuration of monasca-log-api is defined in
configuration files.
.. note:: This is intended behaviour. One of possible ways to deploy
monasca-log-api is to use **gunicorn**. Unfortunately gunicorn's
argument parsing clashes with oslo's argument parsing.
This means that gunicorn reports the CLI options of
oslo as unknown, and vice versa.
There are 3 configuration files. For more details on the configuration
options, see :ref:`here <configuration-files>`.
Configuring Keystone Authorization
----------------------------------
Keystone authorization (i.e. verification of the token associated
with a request) is a critical part of monasca-log-api.
It prevents from unauthorized access and provides the isolation
needed for multi-tenancy.
The configuration for ``keystonemiddleware`` should either be provided in
``log-api.conf`` or in a file in one of the configuration directories.
For more details about configuration options, check
`here <https://docs.openstack.org/keystonemiddleware/latest/middlewarearchitecture.html#configuration>`_.
Configuring Log Publishing
--------------------------
monasca-log-api sends all logs to the Kafka Message Queue.
Proper configuration should include:
* ``kafka_url`` - comma-delimited list of Kafka brokers
* ``topics`` - names of the topics to which the logs will be pushed to
* ``max_message_size`` - maximum message size that can be posted a topic
The configuration for ``log_publisher`` should either be provided in
``log-api.conf`` or in a file in one of the configuration directories.
Configuring Healthcheck
-----------------------
Healthcheck is an essential part of monasca-log-api.
It allows sending HTTP requests and getting knowledge about the
availability of the API. Configuration of healthcheck includes:
* ``kafka_url`` - comma-delimited list of Kafka brokers
* ``kafka_topics`` - list of topics that existence is verified by healthcheck
The configuration for ``kafka_healthcheck`` should either be provided in
``log-api.conf`` or in a file in one of the configuration directories.
Configuring Monitoring
----------------------
monasca-log-api is capable of self-monitoring. This is achieved
through `monasca-statsd <https://github.com/openstack/monasca-statsd>`_.
It assumes that there is monasca-agent available on the system node and
that statsd-server has been launched.
There are several options you may want to tweak if necessary:
* ``statsd_host``- the host statsd-server is bound to
* ``statsd_port``- the port statsd-server is bound to
* ``statsd_buffer`` - the amount of metrics to buffer in memory before sending
any
* ``dimensions`` - additional dimensions to be sent with all
metrics for this monasca-log-api instance
The configuration for ``monitoring`` should either be provided in
``log-api.conf`` or in a file in one of the configuration directories.
Configuring RBAC
----------------
At the moment monasca-log-api does not feature RBAC with ``oslo.policies``.
It provides a custom mechanism, however, that can be configured as follows:
* ``path`` - list of URIs that RBAC applies to
* ``default_roles`` - list of roles that are permitted to access the API
* ``agent_roles`` - list of roles, that if present, means that requests come
from log-agent
* ``delegate_roles`` - list of roles required by log-agent for sending logs
on behalf of another project (tenant)
The configuration for ``roles_middleware`` should either be provided in
``log-api.conf`` or in a file in one of the configuration directories.
Configuring Logging
-------------------
Logging in monasca-log-api is controlled from the single
``log-api-logging.conf`` configuration file.
Here is a short list of several modifications you may want to apply,
based on your deployment:
* to log INFO to console::
[handler_console]
level = INFO
* to log DEBUG to file::
[handler_file]
level = DEBUG
* to change the log file location::
[handler_file]
args = ('/var/log/log-api.log', 'a')
* if you have an external script for log rotation::
[handler_file]
handler = logging.handlers.WatchedFileHandler
args = ('/var/log/log-api.log', 'a')
That will store up to 5 rotations (each having maximum size
of 100MBs)
The configuration of ``logging`` should be presented inside
``log-api-logging.conf`` file and referenced from ``log-api.conf`` using
``log_config_append`` option.
If you want to know more about possible ways to save monasca-log-api logs,
feel free to visit:
* `oslo.log <https://docs.openstack.org/oslo.log/latest/index.html>`_
* `Python HowTo <https://docs.python.org/2/howto/logging.html>`_
* `Logging handlers <https://docs.python.org/2/library/logging.handlers.html>`_

View File

@ -0,0 +1,85 @@
.. _configuration-files:
-------------------
Configuration files
-------------------
Overview of monasca-log-api's configuration files.
log-api.conf
------------
This is the main configuration file of monasca-log-api.
It can be located in several places. During startup,
monasca-log-api searches for it in the following directories:
* ``~/.monasca``
* ``~/``
* ``/etc/monasca``
* ``/etc``
Alternatively, you can roll with a multi-file-based configuration model.
In this case, monasca-log-api searches the configuration files
in the following directories:
* ``~/.monasca/monasca.conf.d/``
* ``~/.monasca/log-api.conf.d/``
* ``~/monasca.conf.d/``
* ``~/log-api.conf.d/``
* ``/etc/monasca/monasca.conf.d/``
* ``/etc/monasca/log-api.conf.d/``
* ``/etc/monasca.conf.d/``
* ``/etc/log-api.conf.d/``
Regardless of the location, the name of the main configuration file
should always be ``log-api.conf``. For files located
in ``.conf.d`` directories, the name is irrelevant, but it should
indicate the file content.
For example, when guring keystone communication. The
`keystonemiddleware <https://docs.openstack.org/keystonemiddleware/latest/>`_
configuration would be, therefore, located in, for example,
``/etc/log-api.conf.d/keystonemiddleware.conf``
A sample of this configuration file is also available
:ref:`here <sample-configuration-api>`
log-api-logging.conf
--------------------
This file contains the logging setup for monasca-log-api. It should be
referenced from ``log-api.conf`` using, for example,
the following code snippet::
[DEFAULT]
log_config_append = /etc/monasca/log-api-logging.conf
A sample of this configuration file is also available
:ref:`here <sample-configuration-logging>`
log-api-paste.ini
-----------------
This file contains the `PasteDeploy <http://pastedeploy.readthedocs.io/en/latest/>`_
configuration. It describes all pipelines that are running within a single
instance of monasca-log-api.
There is nothing you should try and modify in this file,
apart from enabling/disabling ``oslo_middleware.debug:Debug``.
To enable ``oslo_middleware.debug:Debug`` for ``Log v3`` pipeline,
``log-api-paste.ini`` should contain code similar to this one::
[composite:main]
use = egg:Paste#urlmap
/v3.0: la_api_v3
[pipeline:la_api_v3]
pipeline = debug {{ other pipeline members }}
[filter:debug]
paste.filter_factory = oslo_middleware.debug:Debug.factory
This particular filter might be useful for examining the
WSGI environment during troubleshooting or local development.

View File

@ -1,19 +1,17 @@
.. _configuring:
============
Cofiguration
============
=============
Configuration
=============
This section provides a list of all possible options for each
configuration file. Refer to :ref:`basic-configuration` for a
detailed guide in getting started with various option settings.
monasca-log-api uses the following configuration files
for its various services.
This section describes the configuration settings that can be specified.
Refer to :ref:`basic-configuration` for more details on the
available settings.
.. toctree::
:maxdepth: 1
configuring
monasca_log_api
files
options
sample

View File

@ -1,8 +1,8 @@
.. _monasca-log-api.conf:
--------------------
monasca-log-api.conf
--------------------
-------
Options
-------
.. show-options::
:config-file: config-generator/monasca-log-api.conf

View File

@ -1,25 +1,28 @@
.. _sample-configuration:
====================================
monasca-log-api sample configuration
====================================
-------
Samples
-------
The following are sample configuration files for monasca-log-api and
utilities. These are generated from code
(apart from logging conf and paste conf) and reflect the current state
The following sections show sample configuration files for monasca-log-api and
related utilities. These are generated from the code
(apart from the samples for logging and paster) and reflect the current state
of code in the monasca-log-api repository.
Sample configuration for monasca-log-api
----------------------------------------
.. _sample-configuration-api:
Sample Configuration For Application
------------------------------------
This sample configuration can also be viewed in `log-api.conf.sample
<../_static/log-api.conf.sample>`_.
.. literalinclude:: ../_static/log-api.conf.sample
.. _sample-configuration-logging:
Sample configuration for logging
Sample Configuration For Logging
--------------------------------
This sample configuration can also be viewed in `log-api-logging.conf
@ -28,7 +31,7 @@ This sample configuration can also be viewed in `log-api-logging.conf
.. literalinclude:: ../../../etc/monasca/log-api-logging.conf
Sample configuration for paste
Sample Configuration For Paste
------------------------------
This sample configuration can also be viewed in `log-api-paste.ini