openstack/monasca-log-api
Code Issues Proposed changes

Merge "Migrate documentation to Sphinx"

Browse Source
This commit is contained in:
Jenkins 2017-07-03 09:07:04 +00:00 committed by Gerrit Code Review
commit 7258d0b23f
48 changed files with 1713 additions and 296 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

259
api-guide/source/conf.py Normal file
View File

@ -0,0 +1,259 @@
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
# implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#
# Key Manager API documentation build configuration file
#
# All configuration values have a default; values that are commented out
# serve to show the default.
# -- General configuration ------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
needs_sphinx = '1.6'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
'openstackdocstheme'
]
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix of source filenames.
source_suffix = '.rst'
# The encoding of source files.
source_encoding = 'utf-8'
# The master toctree document.
master_doc = 'index'
# General details about project
repository_name = u'openstack/monasca-log-api'
project = u'Monasca Log API Guide'
bug_project = u'monasca-log-api'
bug_tag = u'api-guide'
copyright = u'2014, OpenStack Foundation'
from monasca_log_api.version import version_info
version = version_info.version_string()
release = version_info.release_string()
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
# language = None
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
# today = ''
# Else, today_fmt is used as the format for a strftime call.
# today_fmt = '%B %d, %Y'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = []
# The reST default role (used for this markup: `text`) to use for all
# documents.
# default_role = None
# If true, '()' will be appended to :func: etc. cross-reference text.
# add_function_parentheses = True
# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
# add_module_names = True
# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
# show_authors = False
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# A list of ignored prefixes for module index sorting.
# modindex_common_prefix = []
# If true, keep warnings as "system message" paragraphs in the built documents.
# keep_warnings = False
# -- Options for HTML output ----------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
html_theme = 'openstackdocs'
# 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 = {}
# A shorter title for the navigation bar. Default is the same as html_title.
html_short_title = 'API Guide'
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
# html_logo = None
# 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
# 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,
# so a file named "default.css" will overwrite the builtin "default.css".
# html_static_path = []
# Add any extra paths that contain custom files (such as robots.txt or
# .htaccess) here, relative to this directory. These files are copied
# directly to the root of the documentation.
# html_extra_path = []
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
html_last_updated_fmt = '%Y-%m-%d %H:%M'
# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
# html_use_smartypants = True
# Custom sidebar templates, maps document names to template names.
# html_sidebars = {}
# Additional templates that should be rendered to pages, maps page names to
# template names.
# html_additional_pages = {}
# If false, no module index is generated.
# html_domain_indices = True
# If false, no index is generated.
html_use_index = True
# If true, the index is split into individual pages for each letter.
# html_split_index = False
# If true, links to the reST sources are added to the pages.
# html_show_sourcelink = True
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
# html_show_sphinx = True
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
# html_show_copyright = True
# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it. The value of this option must be the
# base URL from which the finished HTML is served.
# html_use_opensearch = ''
# This is the file name suffix for HTML files (e.g. ".xhtml").
# html_file_suffix = None
# Output file base name for HTML help builder.
htmlhelp_basename = 'monascalogapi-api-guide'
# -- Options for LaTeX output ---------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
# 'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
# 'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
# 'preamble': '',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
('index', 'MonascaLogApiAPI.tex', u'Key Manager API Documentation',
u'OpenStack Foundation', 'manual'),
]
# The name of an image file (relative to this directory) to place at the top of
# the title page.
# latex_logo = None
# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
# latex_use_parts = False
# If true, show page references after internal links.
# latex_show_pagerefs = False
# If true, show URL addresses after external links.
# latex_show_urls = False
# Documents to append as an appendix to all manuals.
# latex_appendices = []
# If false, no module index is generated.
# latex_domain_indices = True
# -- Options for manual page output ---------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
('index', 'monascalogapiapi', u'Monasca Log API Documentation',
[u'OpenStack Foundation'], 1)
]
# If true, show URL addresses after external links.
# man_show_urls = False
# -- Options for Texinfo output -------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
('index', 'MonascaLogApiAPIGuide', u'Monasca Log API Guide',
u'OpenStack Foundation', 'APIGuide',
'This guide teaches OpenStack Monasca Log service users concepts about '
'managing keys in an OpenStack cloud with the Monasca Log API.',
'Miscellaneous'),
]
# Documents to append as an appendix to all manuals.
# texinfo_appendices = []
# If false, no module index is generated.
# texinfo_domain_indices = True
# How to display URL addresses: 'footnote', 'no', or 'inline'.
# texinfo_show_urls = 'footnote'
# If true, do not generate a @detailmenu in the "Top" node's menu.
# texinfo_no_detailmenu = False
# -- Options for Internationalization output ------------------------------
locale_dirs = ['locale/']
# -- Options for PDF output --------------------------------------------------
pdf_documents = [
('index', u'MonascaLogApiAPIGuide', u'Key Manager API Guide', u'OpenStack '
'contributors')
]

50
api-guide/source/general_info.rst Normal file
View File

@ -0,0 +1,50 @@
..
Copyright 2014-2017 Fujitsu LIMITED
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
========================
Monasca Log API Concepts
========================
The Monasca Log API is defined as a RESTful HTTP service. The API
takes advantage of all aspects of the HTTP protocol (methods, URIs,
media types, response codes, etc.) and providers are free to use
existing features of the protocol such as caching, persistent
connections, and content compression among others.
Providers can return information identifying requests in HTTP response
headers, for example, to facilitate communication between the provider
and client applications.
Monasca LOG is a service that provides log collection capabilities over cloud.
User Concepts
=============
To use the Monasca Log API effectively, you should understand several
key concepts:
- **Log**
- **Dimensions**
Relationship with Metric API
============================
The Monasca Log API follow similar concept as Monasca Metric API.
Both are using the same meta-like language to describie entities that are
sent over wire. Below list enumerates those meta properties:
- dimensions
- meta_value

70
api-guide/source/index.rst Normal file
View File

@ -0,0 +1,70 @@
..
Copyright 2014-2017 Fujitsu LIMITED
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
===============
Monasca Log API
===============
The monasca-log-api project has a RESTful HTTP service called the
Monasca Log API. Through this API users are able to send logs from entire
cloud.
This guide covers the concepts in the Monasca Log API.
For a full reference listing, please see:
`Monasca Log API Reference <http://developer.openstack.org/api-ref/monasca/#monasca-log-api>`__.
We welcome feedback, comments, and bug reports at
`storyboard/monasca <https://storyboard.openstack.org/#!/project_group/59>`__.
Intended audience
=================
This guide assists software developers who want to develop applications
using the Monasca Log API. To use this information, you should
have access to an account from an OpenStack Compute provider, or have
access to your own deployment, and you should also be familiar with the
following concepts:
* Monasca services
* RESTful HTTP services
* HTTP/1.1
* JSON data serialization formats
End User and Operator APIs
==========================
The Log API includes all end user and operator API calls.
The API works with keystone and, at the monent, uses custom RBAC to
enforce API security.
API Versions
============
Following the Newton release, every Nova deployment should have
the following endpoints:
* / - list of available versions
* /v2.0 - the first version, permitted only single log to be send per request
* /v3.0 - the next version, allows sending multiple logs at once
Contents
========
.. toctree::
:maxdepth: 2
general_info
logs

18
api-guide/source/logs.rst Normal file
View File

@ -0,0 +1,18 @@
..
Copyright 2014-2017 Fujitsu LIMITED
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
====
Logs
====

258
api-ref/source/conf.py Normal file
View File

@ -0,0 +1,258 @@
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
# implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#
# Key Manager API documentation build configuration file
#
# All configuration values have a default; values that are commented out
# serve to show the default.
# -- General configuration ------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
needs_sphinx = '1.6'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
'os_api_ref',
'openstackdocstheme'
]
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix of source filenames.
source_suffix = '.rst'
# The encoding of source files.
source_encoding = 'utf-8'
# The master toctree document.
master_doc = 'index'
# General details about project
repository_name = u'openstack/monasca-log-api'
project = u'Monasca Log Ref Guide'
bug_project = u'monasca-log-api'
bug_tag = u'api-ref'
copyright = u'2014, OpenStack Foundation'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
from monasca_log_api.version import version_info
version = version_info.version_string()
release = version_info.release_string()
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
# language = None
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
# today = ''
# Else, today_fmt is used as the format for a strftime call.
# today_fmt = '%B %d, %Y'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = []
# The reST default role (used for this markup: `text`) to use for all
# documents.
# default_role = None
# If true, '()' will be appended to :func: etc. cross-reference text.
# add_function_parentheses = True
# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
# add_module_names = True
# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
# show_authors = False
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# A list of ignored prefixes for module index sorting.
# modindex_common_prefix = []
# If true, keep warnings as "system message" paragraphs in the built documents.
# keep_warnings = False
# -- Options for HTML output ----------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
html_theme = 'openstackdocs'
# To use the API Reference sidebar dropdown menu,
# uncomment the html_theme_options parameter. The theme
# variable, sidebar_dropdown, should be set to `api_ref`.
# Otherwise, the list of links for the User and Ops docs
# appear in the sidebar dropdown menu.
html_theme_options = {"sidebar_dropdown": "api_ref",
"sidebar_mode": "toc"}
# A shorter title for the navigation bar. Default is the same as html_title.
html_short_title = 'API Ref'
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
# html_logo = None
# 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
# 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,
# so a file named "default.css" will overwrite the builtin "default.css".
# html_static_path = []
# Add any extra paths that contain custom files (such as robots.txt or
# .htaccess) here, relative to this directory. These files are copied
# directly to the root of the documentation.
# html_extra_path = []
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
html_last_updated_fmt = '%Y-%m-%d %H:%M'
# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
# html_use_smartypants = True
# Custom sidebar templates, maps document names to template names.
# html_sidebars = {}
# Additional templates that should be rendered to pages, maps page names to
# template names.
# html_additional_pages = {}
# If false, no module index is generated.
# html_domain_indices = True
# If false, no index is generated.
html_use_index = True
# If true, the index is split into individual pages for each letter.
# html_split_index = False
# If true, links to the reST sources are added to the pages.
# html_show_sourcelink = True
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
# html_show_sphinx = True
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
# html_show_copyright = True
# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it. The value of this option must be the
# base URL from which the finished HTML is served.
# html_use_opensearch = ''
# This is the file name suffix for HTML files (e.g. ".xhtml").
# html_file_suffix = None
# Output file base name for HTML help builder.
htmlhelp_basename = 'monascalogapi-api-ref'
# -- Options for LaTeX output ---------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
# 'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
# 'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
# 'preamble': '',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
(master_doc, 'MonascaLogApi.tex', u'Monasca Log API Documentation',
u'OpenStack Foundation', 'manual'),
]
# The name of an image file (relative to this directory) to place at the top of
# the title page.
# latex_logo = None
# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
# latex_use_parts = False
# If true, show page references after internal links.
# latex_show_pagerefs = False
# If true, show URL addresses after external links.
# latex_show_urls = False
# Documents to append as an appendix to all manuals.
# latex_appendices = []
# If false, no module index is generated.
# latex_domain_indices = True
# -- Options for manual page output ---------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
(master_doc, 'monascalogapi', u'Monasca Log API Documentation',
[u'OpenStack Foundation'], 1)
]
# If true, show URL addresses after external links.
# man_show_urls = False
# -- Options for Texinfo output -------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
(master_doc, 'MonascaLogAPI', u'Monasca Log API Documentation',
u'OpenStack Foundation', 'MonascaLogAPI', 'Monasca Log API',
'Miscellaneous'),
]
# Documents to append as an appendix to all manuals.
# texinfo_appendices = []
# If false, no module index is generated.
# texinfo_domain_indices = True
# How to display URL addresses: 'footnote', 'no', or 'inline'.
# texinfo_show_urls = 'footnote'
# If true, do not generate a @detailmenu in the "Top" node's menu.
# texinfo_no_detailmenu = False
# -- Options for Internationalization output ------------------------------
locale_dirs = ['locale/']

54
api-ref/source/healthcheck.inc Normal file
View File

@ -0,0 +1,54 @@
.. -*- rst -*-
..
Copyright 2017 Fujitsu LIMITED
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
===========
Healthcheck
===========
The *Monasca Log API* comes with a built-in health check mechanism.
It is available in two flavors (simple and complex).
Simple check
============
The simple check only returns response only if API is up
and running. It does not return any data because it is accessible only
for ```HEAD``` requests.
.. rest_method:: HEAD /healthcheck
.. rest_status_code:: success http_codes.yaml
- 204: la_up
Complex check
=============
# TODO(trebskit) add note to api-guide about peripheral checks
The complex check not only returns a response with success code if API
is up and running but it also verifies if peripheral components are
in expected condition.
.. rest_method:: GET /healthcheck
.. rest_status_code:: success http_codes.yaml
- 200: la_up
.. rest_status_code:: error http_codes.yaml
- 503: no_health

56
api-ref/source/http_codes.yaml Normal file
View File

@ -0,0 +1,56 @@
# Copyright 2017 Fujitsu LIMITED
200:
la_up: |
API is up and running
204:
default: |
Normal response error, everything went as expected (or even better).
la_up: |
API is up and running
400:
default: |
Sent data was malformed.
401:
default: |
User must authenticate before making a request.
403:
default: |
Policy does not allow current user to do this operation.
411:
default: |
Content-Length header was not found in request.
413:
default: |
Sent body is too large to be processed.
422:
default: |
Send data could not be processed properly
no_dims: |
Dimension are required
dim_name_too_long: |
Dimension name {name} must be 255 characters or less
dim_name_underscore: |
Dimension name {name} cannot start with underscore (_)
dim_name_forbidden_chars: |
Dimension name {name} may not contain: "> < = { } ( ) \' " , ; &"
dim_name_empty: |
Dimension name cannot be empty
dim_value_too_long: |
Dimension value {value} must be 255 characters or less
dim_value_empty: |
Dimension value cannot be empty
app_type_too_long: |
Application type {type} must be {length} characters or less
log_no_msg: |
Log property should have message
bad_envelope: |
Failed to create 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.
no_health:
API is running but problems with peripheral components have been spotted

35
api-ref/source/index.rst Normal file
View File

@ -0,0 +1,35 @@
:tocdepth: 2
..
Copyright 2014-2017 Fujitsu LIMITED
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
========================
Monasca Log Service APIs
========================
.. rest_expand_all::
.. include:: logs.inc
.. include:: version.inc
.. include:: healthcheck.inc
===============
Deprecated APIs
===============
This section contains the reference for APIs that are
depracted in the Monasca Log Service
.. include:: log.inc

0
api-ref/source/locale/.gitkeep Normal file
View File

73
api-ref/source/log.inc Normal file
View File

@ -0,0 +1,73 @@
.. -*- rst -*-
..
Copyright 2017 Fujitsu LIMITED
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
====
Log
====
Accepts just a single log entry sent from log-agent of another client.
Can work with logs specified as json (application/json) and text (text/plain)
Send logs
=========
.. rest_method:: POST /v2.0/log/single
Accepts single log entry.
.. rest_status_code:: success http_codes.yaml
- 204
.. rest_status_code:: error http_codes.yaml
- 422: no_dims
- 422: app_type_too_long
- 422: dim_name_too_long
- 422: dim_name_underscore
- 422: dim_name_forbidden_chars
- 422: dim_name_empty
- 422: dim_value_too_long
- 422: dim_value_empty
- 422: log_no_msg
- 422: bad_envelope
- 503
Request
-------
.. rest_parameters:: parameters.yaml
- log_json: log_json
- log_text: log_text
- X_Dimensions: X_Dimensions
- X_Application_Type: X_Application_Type
**Example 1: Simple request with single log (json)**
.. literalinclude:: ../../doc/api_samples/v2/req_json.json
:language: javascript
**Example 2: Simple request with single log (text)**
.. literalinclude:: ../../doc/api_samples/v2/req_text.txt
:language: text
Response
--------
No body content is returned on a successful POST

75
api-ref/source/logs.inc Normal file
View File

@ -0,0 +1,75 @@
.. -*- rst -*-
..
Copyright 2017 Fujitsu LIMITED
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
====
Logs
====
Accepts logs send from log-agents. Logs are basically raw lines,
as collected from physical resources, enriched with dimensions.
Send logs
=========
.. rest_method:: POST /v3.0/logs
Accepts multiple logs (i.e. bulk mode). Each log can be enriched with set
of dimensions. If necessary some of the dimensions can be specified as global
dimensions (that is particularly useful, to make request smaller,
if there is a lot of duplicates among each log entry dimensions)
.. rest_status_code:: success http_codes.yaml
- 204
.. rest_status_code:: error http_codes.yaml
- 400
- 401
- 403
- 411
- 413
- 422: log_no_msg
- 422: bad_envelope
- 503
Request
-------
.. rest_parameters:: parameters.yaml
- dimensions: dimensions
- logs: logs
**Example 1: Simple request with single log**
.. literalinclude:: ../../doc/api_samples/v3/req_single_log.json
:language: javascript
**Example 2: Send multiple logs at once**
.. literalinclude:: ../../doc/api_samples/v3/req_multiple_logs.json
:language: javascript
**Example 3: Specify global dimensions for each log entry**
.. literalinclude:: ../../doc/api_samples/v3/req_global_dims.json
:language: javascript
Response
--------
No body content is returned on a successful POST

50
api-ref/source/parameters.yaml Normal file
View File

@ -0,0 +1,50 @@
# Copyright 2017 Fujitsu LIMITED
# header params
X_Application_Type:
description: |
A single string value representing the application that has generated
given log entry
in: header
required: true
required: true
type: string
min_version: 2.0
X_Dimensions:
description: |
A dictionary consisting of (key, value) pairs used to uniquely
identify a log.
in: header
required: true
type: dict
min_version: 2.0
# body params
dimensions:
description: |
Dimensions sent in request body are known as global dimensions.
Each dimension applies to each log entry sent in a bulk request.
Dimensions are simple map (thus having key-value structure).
in: body
required: false
type: object
min_version: 3.0
log_json:
description: |
Single log entry specified as application/json
in: body
required: true
type: object
log_text:
description: |
Single log entry specified as text/plain
in: body
required: true
type: string
logs:
description: |
Array containing each log entry, sent in bulk request.
in: body
required: true
type: object
min_version: 3.0

19
api-ref/source/version.inc Normal file
View File

@ -0,0 +1,19 @@
.. -*- rst -*-
..
Copyright 2017 Fujitsu LIMITED
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
=======
Version
=======

4
doc/api_samples/v2/req_json.json Normal file
View File

@ -0,0 +1,4 @@
{
"message":"Hello World!"
}

1
doc/api_samples/v2/req_text.txt Normal file
View File

@ -0,0 +1 @@
Hello World

22
doc/api_samples/v3/req_global_dims.json Normal file
View File

@ -0,0 +1,22 @@
{
"dimensions":{
"hostname":"mini-mon",
"service":"monitoring"
},
"logs":[
{
"message":"msg1",
"dimensions":{
"component":"mysql",
"path":"/var/log/mysql.log"
}
},
{
"message":"msg2",
"dimensions":{
"component":"monasca-api",
"path":"/var/log/monasca/monasca-api.log"
}
}
]
}

26
doc/api_samples/v3/req_multiple_logs.json Normal file
View File

@ -0,0 +1,26 @@
{
"dimensions":{},
"logs":[
{
"message":"msg1",
"dimensions":{
"component":"mysql",
"path":"/var/log/mysql.log"
}
},
{
"message":"msg2",
"dimensions":{
"component":"monasca-api",
"path":"/var/log/monasca/monasca-api.log"
}
},
{
"message":"msg3",
"dimensions":{
"component":"monasca-log-api",
"path":"/var/log/monasca/monasca-log-api.log"
}
}
]
}

12
doc/api_samples/v3/req_single_log.json Normal file
View File

@ -0,0 +1,12 @@
{
"dimensions":{},
"logs":[
{
"message":"msg1",
"dimensions":{
"component":"mysql",
"path":"/var/log/mysql.log"
}
}
]
}

6
doc/source/admin/index.rst Normal file
View File

@ -0,0 +1,6 @@
======================
Administration guide
======================
.. toctree::
:maxdepth: 2

7
doc/source/cli/index.rst Normal file
View File

@ -0,0 +1,7 @@
========================
Command Line Interface
========================
.. toctree::
:glob:
:maxdepth: 1

115
doc/source/conf.py
View File

@ -13,72 +13,58 @@
# serve to show the default.
import os
import warnings
import sys
# 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.
#sys.path.insert(0, os.path.abspath('.'))
from monasca_log_api.version import version_info
sys.path = [
os.path.abspath('../..'),
os.path.abspath('../../bin')
] + sys.path
# -- General configuration ------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#needs_sphinx = '1.0'
needs_sphinx = '1.6'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.todo',
'sphinx.ext.coverage',
'sphinx.ext.viewcode',
'sphinx.ext.ifconfig',
'sphinx.ext.graphviz',
'oslosphinx',
'oslo_config.sphinxconfiggen'
# 'sphinx.ext.autodoc' causes gate failures, enable as soon as sorted out
# TODO(trebskit)
'sphinx.ext.viewcode',
# TODO(trebskit) enable as soon as we get configgen in place
# 'oslo_config.sphinxconfiggen'
# 'oslo_config.sphinxext',
'openstackdocstheme',
]
# geeneral information about project
repository_name = u'openstack/monasca-log-api'
project = u'Monasca Log Dev Docs'
version = version_info.version_string()
release = version_info.release_string()
bug_project = u'monasca-log-api'
bug_tag = u'doc'
copyright = u'2014-present, OpenStack Foundation'
author = u'OpenStack Foundation'
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
# source_suffix = ['.rst', '.md']
source_suffix = '.rst'
# The encoding of source files.
#source_encoding = 'utf-8-sig'
source_encoding = 'utf-8'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = u'monasca-log-api'
copyright = u'2015-present, OpenStack Foundation'
author = u'OpenStack'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = '1.3.0'
# The full version, including alpha/beta/rc tags.
release = 'stable/ocata'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = None
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
#today = ''
# Else, today_fmt is used as the format for a strftime call.
#today_fmt = '%B %d, %Y'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = [
@ -89,39 +75,28 @@ exclude_patterns = [
'java'
]
# The reST default role (used for this markup: `text`) to use for all
# documents.
#default_role = None
# If true, '()' will be appended to :func: etc. cross-reference text.
#add_function_parentheses = True
add_function_parentheses = True
# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
add_module_names = False
add_module_names = True
# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
show_authors = False
show_authors = True
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# A list of ignored prefixes for module index sorting.
modindex_common_prefix = ['monasca.']
# If true, keep warnings as "system message" paragraphs in the built documents.
#keep_warnings = False
# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = True
modindex_common_prefix = ['monasca_log_api.', 'monasca']
# -- Options for HTML output ----------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
# html_theme = 'sphinx_rtd_theme'
html_theme = 'openstackdocs'
# 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
@ -133,40 +108,33 @@ todo_include_todos = True
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
#html_title = None
# html_title = None
# A shorter title for the navigation bar. Default is the same as html_title.
#html_short_title = None
# html_short_title = None
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
#html_logo = None
# html_logo = None
# The name of an image file (within the static path) to use as favicon of the
# doc. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
#html_favicon = None
# html_favicon = None
# 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,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
# html_static_path = []
# Add any extra paths that contain custom files (such as robots.txt or
# .htaccess) here, relative to this directory. These files are copied
# directly to the root of the documentation.
#html_extra_path = []
# html_extra_path = []
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
#html_last_updated_fmt = '%b %d, %Y'
git_cmd = ["git", "log", "--pretty=format:'%ad, commit %h'", "--date=local",
"-n1"]
try:
html_last_updated_fmt = os.subprocess.check_output(git_cmd).decode('utf-8')
except Exception:
warnings.warn('Cannot get last updated time from git repository. '
'Not setting "html_last_updated_fmt".')
html_last_updated_fmt = '%Y-%m-%d %H:%M'
# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
@ -183,7 +151,10 @@ except Exception:
#html_domain_indices = True
# If false, no index is generated.
#html_use_index = True
html_use_index = True
# If false, no module index is generated.
html_use_modindex = True
# If true, the index is split into individual pages for each letter.
#html_split_index = False

4
doc/source/configuration/configuring.rst Normal file
View File

@ -0,0 +1,4 @@
.. _basic-configuration:
Basic Configuration
===================

18
doc/source/configuration/index.rst Normal file
View File

@ -0,0 +1,18 @@
.. _configuring:
=====================================
Monasca Log Api Configuration Options
=====================================
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.
.. toctree::
:glob:
:maxdepth: 1
*

1
doc/source/contributor/history.rst Normal file
View File

@ -0,0 +1 @@
.. include:: ../../../ChangeLog

36
doc/source/contributor/index.rst Normal file
View File

@ -0,0 +1,36 @@
Monasca Log Contribution Guidelines
===================================
In the Contributions Guide, you will find documented policies for
developing with monasca-log. This includes the processes we use for
blueprints and specs, bugs, contributor onboarding, core reviewer
memberships, and other procedural items.
monasca-log, as with all OpenStack projects, is written with the following
design guidelines in mind:
* **Component based architecture**: Quickly add new behaviors
* **Highly available**: Scale to very serious workloads
* **Fault tolerant**: Isolated processes avoid cascading failures
* **Recoverable**: Failures should be easy to diagnose, debug, and rectify
* **Open standards**: Be a reference implementation for a community-driven api
This documentation is generated by the Sphinx toolkit and lives in the source
tree. Additional documentation on monasca-log and other components of
OpenStack can be found on the `OpenStack wiki <http://wiki.openstack.org>`_.
Developer reference
-------------------
.. toctree::
:maxdepth: 1
tox
Changelog
---------
.. toctree::
:maxdepth: 1
history

77
doc/source/contributor/tox.rst Normal file
View File

@ -0,0 +1,77 @@
..
monasca-log-api documentation master file
Copyright 2017 FUJITSU LIMITED
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
.. _`tox`: https://tox.readthedocs.io/en/latest/
.. _`mandatory_tox_env`: https://github.com/openstack/monasca-log-api/blob/master/tox.ini#L2
===
Tox
===
**monasca-log-api** uses `tox`_ to wrap up all the activities around
testing and linting the codebase.
List of environments
====================
There is a rather large number of tox environments that **monasca-log-api**
is using. If necessary they can be enlisted with::
tox -a -v
An output will be similar to this::
default environments:
py27 -> Runs unit test using Python2.7
py35 -> Runs unit test using Python3.5
pep8 -> Runs set of linters against codebase (flake8, bandit,
bashate, checkniceness)
cover -> Calculates code coverage
additional environments:
api-guide -> Called from CI scripts to test and publish the API Guide
api-ref -> Called from CI scripts to test and publish the API Ref
apidocs -> Generates codebase documentation
bandit -> [no description]
bashate -> Validates (pep8-like) devstack plugins
checkjson -> Validates all json samples inside doc folder
checkniceness -> Validates (pep-like) documenation
debug -> Allows to run unit-test with debug mode enabled
docs -> Builds api-ref, api-guide, releasenotes and doc
flake8 -> [no description]
releasenotes -> Called from CI script to test and publish the Release Notes
venv -> [no description]
Running tox
===========
Running tox is as simple as::
tox
That will run all **mandatory** (for details refer to `mandatory_tox_env`_)
environments. Having them passed is *a must have*.
Running specific environments
=============================
If you require to run specific environments, please use::
tox -e api-ref,api-guide,releasenotes
Result of which will be having all documentations sub-components generated
and ready in local dev environment.

6
doc/source/deprecation_note.inc Normal file
View File

@ -0,0 +1,6 @@
.. note:: The Log API v2 has been DEPRECATED in the Mitaka release. The
migration path is to use the `Log API v2
<http://developer.openstack.org/api-ref/monasca-log-api/v3/>`_ instead of version 2
of the API. The Log API v1 will ultimately be removed, following the
`OpenStack standard deprecation policy
<https://governance.openstack.org/reference/tags/assert_follows-standard-deprecation.html>`_.

3
doc/source/glossary.rst Normal file
View File

@ -0,0 +1,3 @@
========
Glossary
========

54
doc/source/index.rst
View File

@ -1,22 +1,50 @@
.. monasca-log-api documentation master file, created by
sphinx-quickstart on Wed Nov 18 12:02:03 2015.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
..
monasca-log-api documentation master file
Copyright 2016-2017 FUJITSU LIMITED
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
===========================================
Welcome to monasca-log-api's documentation!
===========================================
Contents:
monasca-log-api is a RESTful API server acting as gateway for
logs collected from log-agents.
.. include:: deprecation_note.inc
The developer documentation provided here is continually kept up-to-date
based on the latest code, and may not represent the state of the project at
any specific prior release.
.. note:: This is documentation for developers, if you are looking for more
general documentation including API, install, operator and user
guides see `docs.openstack.org`_
.. _`docs.openstack.org`: http://docs.openstack.org
.. toctree::
:maxdepth: 2
user/index
admin/index
install/index
configuration/index
cli/index
contributor/index
.. toctree::
:maxdepth: 1
monasca_log_api
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
glossary

6
doc/source/install/index.rst Normal file
View File

@ -0,0 +1,6 @@
==============
Installation
==============
.. toctree::
:maxdepth: 2

45
doc/source/monasca_log_api.api.rst
View File

@ -1,45 +0,0 @@
monasca_log_api.api package
===========================
Submodules
----------
monasca_log_api.api.exceptions module
-------------------------------------
.. automodule:: monasca_log_api.api.exceptions
:members:
:undoc-members:
:show-inheritance:
monasca_log_api.api.headers module
----------------------------------
.. automodule:: monasca_log_api.api.headers
:members:
:undoc-members:
:show-inheritance:
monasca_log_api.api.healthcheck_api module
------------------------------------------
.. automodule:: monasca_log_api.api.healthcheck_api
:members:
:undoc-members:
:show-inheritance:
monasca_log_api.api.logs_api module
-----------------------------------
.. automodule:: monasca_log_api.api.logs_api
:members:
:undoc-members:
:show-inheritance:
monasca_log_api.api.versions_api module
---------------------------------------
.. automodule:: monasca_log_api.api.versions_api
:members:
:undoc-members:
:show-inheritance:

21
doc/source/monasca_log_api.healthcheck.rst
View File

@ -1,21 +0,0 @@
monasca_log_api.healthcheck package
===================================
Submodules
----------
monasca_log_api.healthcheck.kafka_check module
----------------------------------------------
.. automodule:: monasca_log_api.healthcheck.kafka_check
:members:
:undoc-members:
:show-inheritance:
monasca_log_api.healthcheck.keystone_protocol module
----------------------------------------------------
.. automodule:: monasca_log_api.healthcheck.keystone_protocol
:members:
:undoc-members:
:show-inheritance:

13
doc/source/monasca_log_api.middleware.rst
View File

@ -1,13 +0,0 @@
monasca_log_api.middleware package
==================================
Submodules
----------
monasca_log_api.middleware.role_middleware module
-------------------------------------------------
.. automodule:: monasca_log_api.middleware.role_middleware
:members:
:undoc-members:
:show-inheritance:

18
doc/source/monasca_log_api.monitoring.rst
View File

@ -1,18 +0,0 @@
monasca_log_api.monitoring package
==================================
Submodules
----------
monasca_log_api.monitoring.client module
----------------------------------------
.. automodule:: monasca_log_api.monitoring.client
:members:
:undoc-members:
:show-inheritance:
.. automodule:: monasca_log_api.monitoring.metrics
:members:
:undoc-members:
:show-inheritance:

36
doc/source/monasca_log_api.reference.common.rst
View File

@ -1,36 +0,0 @@
monasca_log_api.v2.common package
=================================
Submodules
----------
monasca_log_api.v2.common.error_handlers module
-----------------------------------------------
.. automodule:: monasca_log_api.reference.common.error_handlers
:members:
:undoc-members:
:show-inheritance:
monasca_log_api.v2.common.log_publisher module
----------------------------------------------
.. automodule:: monasca_log_api.reference.common.log_publisher
:members:
:undoc-members:
:show-inheritance:
monasca_log_api.v2.common.model module
--------------------------------------
.. automodule:: monasca_log_api.reference.common.model
:members:
:undoc-members:
:show-inheritance:
monasca_log_api.v2.common.validation module
-------------------------------------------
.. automodule:: monasca_log_api.reference.common.validation
:members:
:undoc-members:
:show-inheritance:

18
doc/source/monasca_log_api.reference.v2.rst
View File

@ -1,18 +0,0 @@
monasca_log_api.reference.v2 package
====================================
monasca_log_api.reference.v2 module
-----------------------------------
.. automodule:: monasca_log_api.reference.v2.logs
:members:
:undoc-members:
:show-inheritance:
monasca_log_api.reference.v2 module
-----------------------------------
.. automodule:: monasca_log_api.reference.v2.common.service
:members:
:undoc-members:
:show-inheritance:

24
doc/source/monasca_log_api.reference.v3.rst
View File

@ -1,24 +0,0 @@
monasca_log_api.reference.v3 package
====================================
monasca_log_api.reference.v3 module
-----------------------------------
.. automodule:: monasca_log_api.reference.v3.logs
:members:
:undoc-members:
:show-inheritance:
monasca_log_api.reference.v3 module
-----------------------------------
.. automodule:: monasca_log_api.reference.v3.common.helpers
:members:
:undoc-members:
:show-inheritance:
.. automodule:: monasca_log_api.reference.v3.common.bulk_processor
:members:
:undoc-members:
:show-inheritance:

26
doc/source/monasca_log_api.rst
View File

@ -1,26 +0,0 @@
monasca_log_api package
=======================
Subpackages
-----------
.. toctree::
monasca_log_api.api
monasca_log_api.reference.v2
monasca_log_api.reference.v3
monasca_log_api.reference.common
monasca_log_api.middleware
monasca_log_api.monitoring
monasca_log_api.healthcheck
Submodules
----------
monasca_log_api.server module
-----------------------------
.. automodule:: monasca_log_api.server
:members:
:undoc-members:
:show-inheritance:

6
doc/source/user/index.rst Normal file
View File

@ -0,0 +1,6 @@
============
User guide
============
.. toctree::
:maxdepth: 2

2
monasca_log_api/middleware/role_middleware.py
View File

@ -70,7 +70,7 @@ class RoleMiddleware(om.ConfigurableMiddleware):
exits silently (that is considered a success). Otherwise
middleware produces JSON response according to following schema
.. code-block:: json
.. code-block:: javascript
{
'title': u'Unauthorized',

9
releasenotes/notes/os-docs-bf79803595ac884b.yaml Normal file
View File

@ -0,0 +1,9 @@
---
deprecations:
- Usage of Markdown based documentation has been deprecated.
It will not be maintained and in future removed from the project
upgrade:
- Documentation handling of monasca-log-api has been migrated
to match OpenStack process

258
releasenotes/source/conf.py Normal file
View File

@ -0,0 +1,258 @@
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
# implied.
# See the License for the specific language governing permissions and
# limitations under the License.
# -- General configuration ------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
needs_sphinx = '1.6'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
'openstackdocstheme',
'reno.sphinxext'
]
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix of source filenames.
source_suffix = '.rst'
# The encoding of source files.
source_encoding = 'utf-8'
# The master toctree document.
master_doc = 'index'
# General information about the project.
repository_name = u'openstack/monasca-log-api'
project = u'Monasca Log Release Notes'
bug_project = u'monasca-log-api'
bug_tag = u'releasenotes'
copyright = u'2014, OpenStack Foundation'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
from monasca_log_api.version import version_info
version = version_info.canonical_version_string()
release = version_info.version_string_with_vcs()
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
# language = None
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
# today = ''
# Else, today_fmt is used as the format for a strftime call.
# today_fmt = '%B %d, %Y'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = []
# The reST default role (used for this markup: `text`) to use for all
# documents.
# default_role = None
# If true, '()' will be appended to :func: etc. cross-reference text.
# add_function_parentheses = True
# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
# add_module_names = True
# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
# show_authors = False
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# A list of ignored prefixes for module index sorting.
# modindex_common_prefix = []
# If true, keep warnings as "system message" paragraphs in the built documents.
# keep_warnings = False
# -- Options for HTML output ----------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
html_theme = 'openstackdocs'
# 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 = {}
# Add any paths that contain custom themes here, relative to this directory.
# html_theme_path = []
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
# html_title = None
# A shorter title for the navigation bar. Default is the same as html_title.
# html_short_title = None
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
# html_logo = None
# 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
# 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,
# so a file named "default.css" will overwrite the builtin "default.css".
# html_static_path = []
# Add any extra paths that contain custom files (such as robots.txt or
# .htaccess) here, relative to this directory. These files are copied
# directly to the root of the documentation.
# html_extra_path = []
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
html_last_updated_fmt = '%Y-%m-%d %H:%M'
# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
# html_use_smartypants = True
# Custom sidebar templates, maps document names to template names.
# html_sidebars = {}
# Additional templates that should be rendered to pages, maps page names to
# template names.
# html_additional_pages = {}
# If false, no module index is generated.
# html_domain_indices = True
# If false, no index is generated.
# html_use_index = True
# If true, the index is split into individual pages for each letter.
# html_split_index = False
# If true, links to the reST sources are added to the pages.
# html_show_sourcelink = True
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
# html_show_sphinx = True
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
# html_show_copyright = True
# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it. The value of this option must be the
# base URL from which the finished HTML is served.
# html_use_opensearch = ''
# This is the file name suffix for HTML files (e.g. ".xhtml").
# html_file_suffix = None
# Output file base name for HTML help builder.
htmlhelp_basename = 'MonascaLogApiReleaseNotesdoc'
# -- Options for LaTeX output ---------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
# 'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
# 'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
# 'preamble': '',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
('index', 'MonascaLogApiReleaseNotes.tex',
u'MonascaLogApi Release Notes Documentation', u'OpenStack Foundation',
'manual'),
]
# The name of an image file (relative to this directory) to place at the top of
# the title page.
# latex_logo = None
# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
# latex_use_parts = False
# If true, show page references after internal links.
# latex_show_pagerefs = False
# If true, show URL addresses after external links.
# latex_show_urls = False
# Documents to append as an appendix to all manuals.
# latex_appendices = []
# If false, no module index is generated.
# latex_domain_indices = True
# -- Options for manual page output ---------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
('index', 'barbicanreleasenotes', u'MonascaLogApi Release Notes Documentation',
[u'OpenStack Foundation'], 1)
]
# If true, show URL addresses after external links.
# man_show_urls = False
# -- Options for Texinfo output -------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
('index', 'MonascaLogApiReleaseNotes', u'MonascaLogApi Release Notes Documentation',
u'OpenStack Foundation', 'MonascaLogApiReleaseNotes',
'MonascaLogApi Release Notes Documentation.', 'Miscellaneous'),
]
# Documents to append as an appendix to all manuals.
# texinfo_appendices = []
# If false, no module index is generated.
# texinfo_domain_indices = True
# How to display URL addresses: 'footnote', 'no', or 'inline'.
# texinfo_show_urls = 'footnote'
# If true, do not generate a @detailmenu in the "Top" node's menu.
# texinfo_no_detailmenu = False
# -- Options for Internationalization output ------------------------------
locale_dirs = ['locale/']

10
releasenotes/source/index.rst Normal file
View File

@ -0,0 +1,10 @@
===========================
MonascaLogApi Release Notes
===========================
Contents:
.. toctree::
:maxdepth: 1
unreleased

0
releasenotes/source/locale/.gitkeep Normal file
View File

5
releasenotes/source/unreleased.rst Normal file
View File

@ -0,0 +1,5 @@
==============================
Current Series Release Notes
==============================
.. release-notes::

31
setup.cfg
View File

@ -45,9 +45,36 @@ tempest.test_plugins =
all_files = 1
build-dir = doc/build
source-dir = doc/source
warning-is-error = 1
[build_apiguide]
all_files = 1
build-dir = api-guide/build
source-dir = api-guide/source
[build_apiref]
all_files = 1
build-dir = api-ref/build
source-dir = api-ref/source
[build_releasenotes]
all_files = 1
build-dir = releasenotes/build
source-dir = releasenotes/source
[egg_info]
tag_build =
tag_date = 0
tag_svn_revision = 0
[wheel]
universal = 1
[pbr]
warnerrors = True
# NOTE(trebskit) autodoc is failling in gate for now
# enable that as soon as bug is sorted out
# [pbr]
# autodoc_index_modules = True
# autodoc_exclude_modules =
# monasca_log_api.tests.*
# monasca_log_api_tempest.*
# api_doc_dir = contributor/api

8
test-requirements.txt
View File

@ -9,9 +9,13 @@ bandit>=1.1.0 # Apache-2.0
fixtures>=3.0.0 # Apache-2.0/BSD
coverage!=4.4,>=4.0 # Apache-2.0
mock>=2.0 # BSD
sphinx>=1.6.2 # BSD
oslosphinx>=4.7.0 # Apache-2.0
oslotest>=1.10.0 # Apache-2.0
os-testr>=0.8.0 # Apache-2.0
simplejson>=2.2.0 # MIT
# documentation
doc8 # Apache-2.0
sphinx>=1.6.2 # BSD
os-api-ref>=1.0.0 # Apache-2.0
reno!=2.3.1,>=1.8.0 # Apache-2.0
openstackdocstheme>=1.11.0 # Apache-2.0

64
tox.ini
View File

@ -18,25 +18,27 @@ whitelist_externals = bash
find
rm
install_command = {toxinidir}/tools/tox_install.sh {env:UPPER_CONSTRAINTS_FILE:https://git.openstack.org/cgit/openstack/requirements/plain/upper-constraints.txt} {opts} {packages}
deps = -r{toxinidir}/requirements.txt
-r{toxinidir}/test-requirements.txt
deps = -r{toxinidir}/test-requirements.txt
commands =
find ./ -type f -name '*.pyc' -delete
rm -Rf .testrepository/times.dbm
[testenv:py27]
description = Runs unit test using Python2.7
basepython = python2.7
commands =
{[testenv]commands}
ostestr {posargs}
[testenv:py35]
description = Runs unit test using Python3.5
basepython = python3.5
commands =
{[testenv]commands}
ostestr {posargs}
[testenv:cover]
description = Calculates code coverage
basepython = python2.7
commands =
{[testenv]commands}
@ -45,17 +47,19 @@ commands =
coverage report
[testenv:debug]
description = Allows to run unit-test with debug mode enabled
commands =
{[testenv]commands}
oslo_debug_helper -t ./monasca_log_api/tests {posargs}
oslo_debug_helper -t {toxinidir}/monasca_log_api/tests {posargs}
[testenv:bashate]
description = Validates (pep8-like) devstack plugins
deps = bashate
whitelist_externals = bashate
commands =
# Ignore too long lines error E006 from bashate and treat
# E005, E042 as errors.
bashate -v -iE006 -eE005,E042 devstack/plugin.sh
bashate -v -iE006 -eE005,E042 {toxinidir}/devstack/plugin.sh
[testenv:bandit]
commands =
@ -67,6 +71,7 @@ commands =
flake8 monasca_log_api
[testenv:pep8]
description = Runs set of linters against codebase (flake8, bandit, bashate, checkniceness)
deps =
{[testenv]deps}
{[testenv:bashate]deps}
@ -74,17 +79,66 @@ commands =
{[testenv:flake8]commands}
{[testenv:bandit]commands}
{[testenv:bashate]commands}
{[testenv:checkniceness]commands}
[testenv:docs]
description = Builds api-ref, api-guide, releasenotes and devdocs
commands =
{[testenv:devdocs]commands}
{[testenv:api-guide]commands}
{[testenv:api-ref]commands}
{[testenv:releasenotes]commands}
[testenv:api-guide]
description = Called from CI scripts to test and publish the API Guide
commands =
rm -rf api-guide/build
{[testenv:checkjson]commands}
sphinx-build -W -b html -d api-guide/build/doctrees api-guide/source api-guide/build/html
[testenv:api-ref]
description = Called from CI scripts to test and publish the API Ref
commands =
rm -rf api-ref/build
{[testenv:checkjson]commands}
sphinx-build -W -b html -d api-ref/build/doctrees api-ref/source api-ref/build/html
[testenv:releasenotes]
description = Called from CI script to test and publish the Release Notes
commands =
rm -rf releasenotes/build
sphinx-build -a -E -W -d releasenotes/build/doctrees -b html releasenotes/source releasenotes/build/html
[testenv:devdocs]
description = Builds developer documentation
commands =
rm -rf doc/build
{[testenv:checkjson]commands}
python setup.py build_sphinx
[testenv:checkniceness]
description = Validates (pep-like) documenation
commands =
doc8 --file-encoding utf-8 {toxinidir}/doc
doc8 --file-encoding utf-8 {toxinidir}/api-ref
doc8 --file-encoding utf-8 {toxinidir}/api-guide
doc8 --file-encoding utf-8 {toxinidir}/releasenotes
[testenv:checkjson]
description = Validates all json samples inside doc folder
deps =
whitelist_externals =
bash
python
commands =
bash -c "! find doc/ -type f -name *.json | xargs grep -U -n $'\r'"
bash -c '! find doc/ -type f -name *.json | xargs -t -n1 python -m json.tool 2>&1 > /dev/null | grep -B1 -v ^python'
[testenv:venv]
commands = {posargs}
[flake8]
exclude = .git,.tox,dist,doc,documentation,*.egg,build
exclude = .git,.tox,dist,doc,api-ref,api-guide,releasenotes,documentation,*.egg,build
show-source = True
enable-extensions = H203,H106