doc: improve the layout and gnocchi.xyz
This improves the doc layout a bit and adds support for a different theme that'll be used on http://gnocchi.xyz Change-Id: I32e627bc1f9ff6561e6498faa7c70f5797968ecf Signed-off-by: Julien Danjou <julien@danjou.info>
This commit is contained in:
Julien Danjou
@@ -1,44 +0,0 @@
|
||||
==================
|
||||
What is Gnocchi?
|
||||
==================
|
||||
|
||||
.. image:: gnocchi-logo.jpg
|
||||
|
||||
Gnocchi is a service for managing a set of resources and storing metrics about
|
||||
them. It allows its users to create resources (servers, images, volumes…)
|
||||
with properties (name, URL, flavors…) and to associate those resources with
|
||||
metrics (CPU usage, bandwidth…) that are going to metered.
|
||||
|
||||
The point of Gnocchi is to provide this service and its features in a scalable
|
||||
and resilient way. Its functionalities are exposed over an HTTP REST API.
|
||||
|
||||
============================
|
||||
A Brief History of Gnocchi
|
||||
============================
|
||||
|
||||
The Gnocchi project was started in 2014 as a spin-off of the `OpenStack
|
||||
Ceilometer`_ project to address the performance issues that Ceilometer
|
||||
encountered while using standard databases as a storage backends for metrics.
|
||||
More information are available on `Julien's blog post on Gnocchi
|
||||
<https://julien.danjou.info/blog/2014/openstack-ceilometer-the-gnocchi-experiment>`_.
|
||||
|
||||
.. _`OpenStack Ceilometer`: http://launchpad.net/ceilometer
|
||||
|
||||
======================
|
||||
Project Architecture
|
||||
======================
|
||||
|
||||
Gnocchi is built around 2 main components: a storage driver and an indexer
|
||||
driver. The REST API exposed to the user manipulates both these drivers to
|
||||
provide all the features that are needed to provide correct infrastructure
|
||||
measurement.
|
||||
|
||||
The *storage* is responsible for storing measures of created metrics. It
|
||||
receives timestamps and values and computes aggregations according to the
|
||||
defined archive policies.
|
||||
|
||||
The *indexer* is responsible for storing the index of all resources, along with
|
||||
their types and their properties. Gnocchi only knows resource types from the
|
||||
OpenStack project, but also provides a *generic* type so you can create basic
|
||||
resources and handle the resource properties yourself. The indexer is also
|
||||
responsible for linking resources with metrics.
|
||||
@@ -11,8 +11,12 @@
|
||||
# serve to show the default.
|
||||
|
||||
import datetime
|
||||
import os
|
||||
import subprocess
|
||||
|
||||
import oslosphinx
|
||||
import sphinx_bootstrap_theme
|
||||
|
||||
# If extensions (or modules to document with autodoc) are in another directory,
|
||||
# add these directories to sys.path here. If the directory is relative to the
|
||||
# documentation root, use os.path.abspath to make it absolute, like shown here.
|
||||
@@ -29,7 +33,6 @@ extensions = [
|
||||
'gnocchi.gendoc',
|
||||
'sphinxcontrib.httpdomain',
|
||||
'sphinx.ext.autodoc',
|
||||
'oslosphinx',
|
||||
]
|
||||
|
||||
# Add any paths that contain templates here, relative to this directory.
|
||||
@@ -98,15 +101,29 @@ pygments_style = 'sphinx'
|
||||
|
||||
# The theme to use for HTML and HTML Help pages. See the documentation for
|
||||
# a list of builtin themes.
|
||||
# html_theme = 'default'
|
||||
html_theme = 'openstack'
|
||||
|
||||
# Theme options are theme-specific and customize the look and feel of a theme
|
||||
# further. For a list of options available for each theme, see the
|
||||
# documentation.
|
||||
#html_theme_options = {}
|
||||
if html_theme == "bootstrap":
|
||||
html_theme_options = {
|
||||
'navbar_class': "navbar navbar-inverse",
|
||||
'navbar_site_name': "Documentation",
|
||||
'navbar_links': [
|
||||
("Launchpad project", "https://launchpad.net/gnocchi", True),
|
||||
("Bug tracking", "https://bugs.launchpad.net/gnocchi", True),
|
||||
("Git", "http://github.com/openstack/gnocchi", True),
|
||||
],
|
||||
'navbar_sidebarrel': False,
|
||||
'navbar_pagenav': False,
|
||||
'globaltoc_depth': 2,
|
||||
}
|
||||
|
||||
# Add any paths that contain custom themes here, relative to this directory.
|
||||
#html_theme_path = []
|
||||
html_theme_path = ([os.path.join(os.path.dirname(oslosphinx.__file__), 'theme')]
|
||||
+ sphinx_bootstrap_theme.get_html_theme_path())
|
||||
|
||||
# The name for this set of Sphinx documents. If None, it defaults to
|
||||
# "<project> v<release> documentation".
|
||||
@@ -122,7 +139,7 @@ pygments_style = 'sphinx'
|
||||
# The name of an image file (within the static path) to use as favicon of the
|
||||
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
|
||||
# pixels large.
|
||||
#html_favicon = None
|
||||
html_favicon = 'gnocchi-logo.jpg'
|
||||
|
||||
# Add any paths that contain custom static files (such as style sheets) here,
|
||||
# relative to this directory. They are copied after the builtin static files,
|
||||
|
||||
@@ -1,22 +1,53 @@
|
||||
===========================================
|
||||
Gnocchi -- Resource metering as a Service
|
||||
===========================================
|
||||
================================
|
||||
Gnocchi -- Metric as a Service
|
||||
================================
|
||||
|
||||
The Gnocchi project procdes a REST interface to catalog and measure resources.
|
||||
.. image:: gnocchi-logo.jpg
|
||||
|
||||
Gnocchi is a multi-tenant timeseries, metrics and resources database. It
|
||||
provides an `HTTP REST`_ interface to create and manipulate those data. It is
|
||||
designed to store metrics at a very large scale while providing access to
|
||||
metrics and resources information to operators and users.
|
||||
|
||||
Gnocchi is part of the `OpenStack` project. While Gnocchi has support for
|
||||
OpenStack, it is fully able to work stand-alone.
|
||||
|
||||
A Brief History of Gnocchi
|
||||
--------------------------
|
||||
|
||||
The Gnocchi project was started in 2014 as a spin-off of the `OpenStack
|
||||
Ceilometer`_ project to address the performance issues that Ceilometer
|
||||
encountered while using standard databases as a storage backends for metrics.
|
||||
More information are available on `Julien's blog post on Gnocchi
|
||||
<https://julien.danjou.info/blog/2014/openstack-ceilometer-the-gnocchi-experiment>`_.
|
||||
|
||||
.. _`OpenStack Ceilometer`: http://launchpad.net/ceilometer
|
||||
|
||||
Key Features
|
||||
============
|
||||
|
||||
- HTTP REST interface
|
||||
- Horizontal scalability
|
||||
- Metric aggregation
|
||||
- Archiving policy
|
||||
- Metric value search
|
||||
- Structured resources
|
||||
- Queryable resource indexer
|
||||
- Multi-tenant
|
||||
- Grafana support
|
||||
- Statsd protocol support
|
||||
|
||||
|
||||
Documentation
|
||||
=============
|
||||
|
||||
.. toctree::
|
||||
:glob:
|
||||
:maxdepth: 1
|
||||
|
||||
basic
|
||||
install
|
||||
devstack
|
||||
rest
|
||||
statsd
|
||||
resource_types
|
||||
|
||||
Indices and tables
|
||||
==================
|
||||
|
||||
* :ref:`genindex`
|
||||
* :ref:`modindex`
|
||||
* :ref:`search`
|
||||
.. _`HTTP REST`: https://en.wikipedia.org/wiki/Representational_state_transfer
|
||||
.. _`OpenStack`: http://openstack.org
|
||||
|
||||
@@ -2,11 +2,53 @@
|
||||
Installation
|
||||
==============
|
||||
|
||||
Project Architecture
|
||||
======================
|
||||
|
||||
Gnocchi is built around 2 main components: a storage driver and an indexer
|
||||
driver. The REST API exposed to the user manipulates both these drivers to
|
||||
provide all the features that are needed to provide correct infrastructure
|
||||
measurement.
|
||||
|
||||
The *storage* is responsible for storing measures of created metrics. It
|
||||
receives timestamps and values and computes aggregations according to the
|
||||
defined archive policies.
|
||||
|
||||
The *indexer* is responsible for storing the index of all resources, along with
|
||||
their types and their properties. Gnocchi only knows resource types from the
|
||||
OpenStack project, but also provides a *generic* type so you can create basic
|
||||
resources and handle the resource properties yourself. The indexer is also
|
||||
responsible for linking resources with metrics.
|
||||
|
||||
Installation Using Devstack
|
||||
===========================
|
||||
|
||||
To enable Gnocchi in devstack, add the following to local.conf:
|
||||
|
||||
::
|
||||
|
||||
enable_plugin gnocchi https://github.com/openstack/gnocchi master
|
||||
enable_service gnocchi-api,gnocchi-metricd
|
||||
|
||||
To enable Grafana support in devstack, you can also enable `gnocchi-grafana`::
|
||||
|
||||
enable_service gnocchi-grafana
|
||||
|
||||
Then, you can start devstack:
|
||||
|
||||
::
|
||||
|
||||
./stack.sh
|
||||
|
||||
|
||||
Installation Using Sources
|
||||
==========================
|
||||
|
||||
To install Gnocchi, run the standard Python installation procedure:
|
||||
|
||||
::
|
||||
|
||||
python setup.py install
|
||||
pip install -e .
|
||||
|
||||
|
||||
Configuration
|
||||
@@ -22,7 +64,8 @@ created by running:
|
||||
tox -e genconfig
|
||||
|
||||
This command will create an `etc/gnocchi/gnocchi.conf` file which can be used
|
||||
as a base for the default configuration file at `/etc/gnocchi/gnocchi.conf`.
|
||||
as a base for the default configuration file at `/etc/gnocchi/gnocchi.conf`. If
|
||||
you're using _devstack_, this file is already generated and put in place.
|
||||
|
||||
The configuration file should be pretty explicit, but here are some of the base
|
||||
options you want to change and configure:
|
||||
@@ -77,14 +120,13 @@ Once you have configured Gnocchi properly, you need to initialize the indexer:
|
||||
Running Gnocchi
|
||||
===============
|
||||
|
||||
To run Gnocchi, simply run the HTTP server:
|
||||
To run Gnocchi, simply run the HTTP server and metric daemon:
|
||||
|
||||
::
|
||||
|
||||
gnocchi-api
|
||||
gnocchi-metricd
|
||||
|
||||
You then need to run the `gnocchi-metricd` daemon to enable new measures
|
||||
processing and metrics expunge in the background.
|
||||
|
||||
Running As A WSGI Application
|
||||
=============================
|
||||
|
||||
@@ -33,3 +33,4 @@ pymysql
|
||||
# oslo config object, but once 2.2 will be released,
|
||||
# we can moved back this to test-requirements.txt
|
||||
keystonemiddleware>=1.5.0
|
||||
sphinx_bootstrap_theme
|
||||
|
||||
4
tox.ini
4
tox.ini
@@ -64,3 +64,7 @@ commands = {toxinidir}/generate-config-file.sh
|
||||
setenv = GNOCCHI_TEST_STORAGE_DRIVER=file
|
||||
commands = doc8 --ignore-path doc/source/rest.rst doc/source
|
||||
{toxinidir}/setup-postgresql-tests.sh python setup.py build_sphinx
|
||||
|
||||
[testenv:docs-gnocchi.xyz]
|
||||
setenv = GNOCCHI_TEST_STORAGE_DRIVER=file
|
||||
commands = {toxinidir}/setup-postgresql-tests.sh sphinx-build -D html_theme=bootstrap doc/source doc/build
|
||||
|
||||
Reference in New Issue
Block a user