diff --git a/api-guide/source/conf.py b/api-guide/source/conf.py new file mode 100644 index 00000000..17bfda0b --- /dev/null +++ b/api-guide/source/conf.py @@ -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 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') +] diff --git a/api-guide/source/general_info.rst b/api-guide/source/general_info.rst new file mode 100644 index 00000000..ae6cad6a --- /dev/null +++ b/api-guide/source/general_info.rst @@ -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 diff --git a/api-guide/source/index.rst b/api-guide/source/index.rst new file mode 100644 index 00000000..1de38b1a --- /dev/null +++ b/api-guide/source/index.rst @@ -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 `__. + +We welcome feedback, comments, and bug reports at +`storyboard/monasca `__. + +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 + diff --git a/api-guide/source/logs.rst b/api-guide/source/logs.rst new file mode 100644 index 00000000..db0306f7 --- /dev/null +++ b/api-guide/source/logs.rst @@ -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 +==== diff --git a/api-ref/source/conf.py b/api-ref/source/conf.py new file mode 100644 index 00000000..43a19986 --- /dev/null +++ b/api-ref/source/conf.py @@ -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 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/'] diff --git a/api-ref/source/healthcheck.inc b/api-ref/source/healthcheck.inc new file mode 100644 index 00000000..b1bfdb36 --- /dev/null +++ b/api-ref/source/healthcheck.inc @@ -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 diff --git a/api-ref/source/http_codes.yaml b/api-ref/source/http_codes.yaml new file mode 100644 index 00000000..756e95b8 --- /dev/null +++ b/api-ref/source/http_codes.yaml @@ -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 diff --git a/api-ref/source/index.rst b/api-ref/source/index.rst new file mode 100644 index 00000000..807149a7 --- /dev/null +++ b/api-ref/source/index.rst @@ -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 diff --git a/api-ref/source/locale/.gitkeep b/api-ref/source/locale/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/api-ref/source/log.inc b/api-ref/source/log.inc new file mode 100644 index 00000000..881ffab5 --- /dev/null +++ b/api-ref/source/log.inc @@ -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 diff --git a/api-ref/source/logs.inc b/api-ref/source/logs.inc new file mode 100644 index 00000000..5b47d07d --- /dev/null +++ b/api-ref/source/logs.inc @@ -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 diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml new file mode 100644 index 00000000..dc9038ca --- /dev/null +++ b/api-ref/source/parameters.yaml @@ -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 diff --git a/api-ref/source/version.inc b/api-ref/source/version.inc new file mode 100644 index 00000000..6bce887e --- /dev/null +++ b/api-ref/source/version.inc @@ -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 +======= diff --git a/doc/api_samples/v2/req_json.json b/doc/api_samples/v2/req_json.json new file mode 100644 index 00000000..d70e2db3 --- /dev/null +++ b/doc/api_samples/v2/req_json.json @@ -0,0 +1,4 @@ +{ + "message":"Hello World!" +} + diff --git a/doc/api_samples/v2/req_text.txt b/doc/api_samples/v2/req_text.txt new file mode 100644 index 00000000..557db03d --- /dev/null +++ b/doc/api_samples/v2/req_text.txt @@ -0,0 +1 @@ +Hello World diff --git a/doc/api_samples/v3/req_global_dims.json b/doc/api_samples/v3/req_global_dims.json new file mode 100644 index 00000000..b6735b68 --- /dev/null +++ b/doc/api_samples/v3/req_global_dims.json @@ -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" + } + } + ] +} diff --git a/doc/api_samples/v3/req_multiple_logs.json b/doc/api_samples/v3/req_multiple_logs.json new file mode 100644 index 00000000..4da99a16 --- /dev/null +++ b/doc/api_samples/v3/req_multiple_logs.json @@ -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" + } + } + ] +} diff --git a/doc/api_samples/v3/req_single_log.json b/doc/api_samples/v3/req_single_log.json new file mode 100644 index 00000000..201ca18a --- /dev/null +++ b/doc/api_samples/v3/req_single_log.json @@ -0,0 +1,12 @@ +{ + "dimensions":{}, + "logs":[ + { + "message":"msg1", + "dimensions":{ + "component":"mysql", + "path":"/var/log/mysql.log" + } + } + ] +} diff --git a/doc/source/admin/index.rst b/doc/source/admin/index.rst new file mode 100644 index 00000000..36a9908c --- /dev/null +++ b/doc/source/admin/index.rst @@ -0,0 +1,6 @@ +====================== + Administration guide +====================== + +.. toctree:: + :maxdepth: 2 diff --git a/doc/source/cli/index.rst b/doc/source/cli/index.rst new file mode 100644 index 00000000..29a84d16 --- /dev/null +++ b/doc/source/cli/index.rst @@ -0,0 +1,7 @@ +======================== + Command Line Interface +======================== + +.. toctree:: + :glob: + :maxdepth: 1 diff --git a/doc/source/conf.py b/doc/source/conf.py index f548a487..76f19d5f 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -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 # " v 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 diff --git a/doc/source/configuration/configuring.rst b/doc/source/configuration/configuring.rst new file mode 100644 index 00000000..3992ff59 --- /dev/null +++ b/doc/source/configuration/configuring.rst @@ -0,0 +1,4 @@ +.. _basic-configuration: + +Basic Configuration +=================== diff --git a/doc/source/configuration/index.rst b/doc/source/configuration/index.rst new file mode 100644 index 00000000..6910c2bd --- /dev/null +++ b/doc/source/configuration/index.rst @@ -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 + + * diff --git a/doc/source/contributor/history.rst b/doc/source/contributor/history.rst new file mode 100644 index 00000000..f69be70b --- /dev/null +++ b/doc/source/contributor/history.rst @@ -0,0 +1 @@ +.. include:: ../../../ChangeLog diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst new file mode 100644 index 00000000..45bbb9b0 --- /dev/null +++ b/doc/source/contributor/index.rst @@ -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 `_. + +Developer reference +------------------- + +.. toctree:: + :maxdepth: 1 + + tox + +Changelog +--------- + +.. toctree:: + :maxdepth: 1 + + history diff --git a/doc/source/contributor/tox.rst b/doc/source/contributor/tox.rst new file mode 100644 index 00000000..3a47c7ab --- /dev/null +++ b/doc/source/contributor/tox.rst @@ -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. diff --git a/doc/source/deprecation_note.inc b/doc/source/deprecation_note.inc new file mode 100644 index 00000000..191950fe --- /dev/null +++ b/doc/source/deprecation_note.inc @@ -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 + `_ instead of version 2 + of the API. The Log API v1 will ultimately be removed, following the + `OpenStack standard deprecation policy + `_. diff --git a/doc/source/glossary.rst b/doc/source/glossary.rst new file mode 100644 index 00000000..fa106d19 --- /dev/null +++ b/doc/source/glossary.rst @@ -0,0 +1,3 @@ +======== +Glossary +======== diff --git a/doc/source/index.rst b/doc/source/index.rst index de383f7f..ffd2972b 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -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 diff --git a/doc/source/install/index.rst b/doc/source/install/index.rst new file mode 100644 index 00000000..e6bc440e --- /dev/null +++ b/doc/source/install/index.rst @@ -0,0 +1,6 @@ +============== + Installation +============== + +.. toctree:: + :maxdepth: 2 diff --git a/doc/source/monasca_log_api.api.rst b/doc/source/monasca_log_api.api.rst deleted file mode 100644 index ebb20447..00000000 --- a/doc/source/monasca_log_api.api.rst +++ /dev/null @@ -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: diff --git a/doc/source/monasca_log_api.healthcheck.rst b/doc/source/monasca_log_api.healthcheck.rst deleted file mode 100644 index 38b3031c..00000000 --- a/doc/source/monasca_log_api.healthcheck.rst +++ /dev/null @@ -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: diff --git a/doc/source/monasca_log_api.middleware.rst b/doc/source/monasca_log_api.middleware.rst deleted file mode 100644 index e474c9e2..00000000 --- a/doc/source/monasca_log_api.middleware.rst +++ /dev/null @@ -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: diff --git a/doc/source/monasca_log_api.monitoring.rst b/doc/source/monasca_log_api.monitoring.rst deleted file mode 100644 index 0b4c458e..00000000 --- a/doc/source/monasca_log_api.monitoring.rst +++ /dev/null @@ -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: diff --git a/doc/source/monasca_log_api.reference.common.rst b/doc/source/monasca_log_api.reference.common.rst deleted file mode 100644 index 8264b089..00000000 --- a/doc/source/monasca_log_api.reference.common.rst +++ /dev/null @@ -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: diff --git a/doc/source/monasca_log_api.reference.v2.rst b/doc/source/monasca_log_api.reference.v2.rst deleted file mode 100644 index 9c71b41b..00000000 --- a/doc/source/monasca_log_api.reference.v2.rst +++ /dev/null @@ -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: diff --git a/doc/source/monasca_log_api.reference.v3.rst b/doc/source/monasca_log_api.reference.v3.rst deleted file mode 100644 index 014c3cb0..00000000 --- a/doc/source/monasca_log_api.reference.v3.rst +++ /dev/null @@ -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: - diff --git a/doc/source/monasca_log_api.rst b/doc/source/monasca_log_api.rst deleted file mode 100644 index f0329aeb..00000000 --- a/doc/source/monasca_log_api.rst +++ /dev/null @@ -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: diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst new file mode 100644 index 00000000..475c57c9 --- /dev/null +++ b/doc/source/user/index.rst @@ -0,0 +1,6 @@ +============ + User guide +============ + +.. toctree:: + :maxdepth: 2 diff --git a/monasca_log_api/middleware/role_middleware.py b/monasca_log_api/middleware/role_middleware.py index 74b178c9..7fd2070b 100644 --- a/monasca_log_api/middleware/role_middleware.py +++ b/monasca_log_api/middleware/role_middleware.py @@ -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', diff --git a/releasenotes/notes/os-docs-bf79803595ac884b.yaml b/releasenotes/notes/os-docs-bf79803595ac884b.yaml new file mode 100644 index 00000000..1ec3efc7 --- /dev/null +++ b/releasenotes/notes/os-docs-bf79803595ac884b.yaml @@ -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 diff --git a/releasenotes/source/conf.py b/releasenotes/source/conf.py new file mode 100644 index 00000000..21664016 --- /dev/null +++ b/releasenotes/source/conf.py @@ -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 +# " v 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 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/'] diff --git a/releasenotes/source/index.rst b/releasenotes/source/index.rst new file mode 100644 index 00000000..74e9ae03 --- /dev/null +++ b/releasenotes/source/index.rst @@ -0,0 +1,10 @@ +=========================== +MonascaLogApi Release Notes +=========================== + +Contents: + +.. toctree:: + :maxdepth: 1 + + unreleased diff --git a/releasenotes/source/locale/.gitkeep b/releasenotes/source/locale/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/releasenotes/source/unreleased.rst b/releasenotes/source/unreleased.rst new file mode 100644 index 00000000..cd22aabc --- /dev/null +++ b/releasenotes/source/unreleased.rst @@ -0,0 +1,5 @@ +============================== + Current Series Release Notes +============================== + +.. release-notes:: diff --git a/setup.cfg b/setup.cfg index fe051c4b..a91af0cf 100644 --- a/setup.cfg +++ b/setup.cfg @@ -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 diff --git a/test-requirements.txt b/test-requirements.txt index 1dd25d54..bff60a62 100644 --- a/test-requirements.txt +++ b/test-requirements.txt @@ -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 diff --git a/tox.ini b/tox.ini index de074828..c9e2502a 100644 --- a/tox.ini +++ b/tox.ini @@ -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