Browse Source

Add documentation bits

Ilya Shakhat 3 years ago
parent
commit
754d1a4f8f

+ 30
- 14
README.rst View File

@@ -1,19 +1,35 @@
1
-===============================
2
-performa
3
-===============================
1
+========
2
+Performa
3
+========
4 4
 
5
-Performance testing toolkit
5
+What Performa is?
6
+-----------------
6 7
 
7
-Please feel here a long description which must be at least 3 lines wrapped on
8
-80 cols, so that distribution package maintainers can use it in their packages.
9
-Note that this is a hard requirement.
8
+Performa is distributed scenario runner, results processor and report generator.
9
+It is the strong mixture of powerful technologies:
10
+ * Ansible_ for easy running modularized code in distributed manner
11
+ * MongoDB_ for storing and transforming data
12
+ * Pygal_ for creating light-weight charts
13
+ * Jinja2_ for templating the world
10 14
 
11
-* Free software: Apache license
12
-* Documentation: http://docs.openstack.org/developer/performa
13
-* Source: http://git.openstack.org/cgit/openstack/performa
14
-* Bugs: http://bugs.launchpad.net/performa
15 15
 
16
-Features
17
---------
16
+Example
17
+-------
18 18
 
19
-* TODO
19
+::
20
+
21
+    performa --mongo-url 127.0.0.1 --mongo-db performa --scenario db/sysbench \
22
+        --hosts "{target: [192.168.20.20]}" --remote-user developer --debug \
23
+        --book doc/source/test_results/db/sysbench
24
+
25
+This example runs Performa tool with scenario 'sb/sysbench'. It uses MongoDB
26
+located at localhost and database named 'performa'. The scenario is executed
27
+against remote host 192.168.20.20 which can be accessed with user 'developer'.
28
+The report is stored into 'doc/source/test_results/db/sysbench' folder.
29
+
30
+.. references:
31
+
32
+.. _Ansible: http://docs.ansible.com/
33
+.. _MongoDB: https://docs.mongodb.org/manual/
34
+.. _Pygal: http://www.pygal.org/
35
+.. _Jinja2: http://jinja.pocoo.org/

+ 5
- 0
config-generator.conf View File

@@ -0,0 +1,5 @@
1
+[DEFAULT]
2
+output_file = etc/performa.conf
3
+wrap_width = 79
4
+namespace = performa.engine.config
5
+namespace = oslo_log

+ 18
- 12
doc/source/index.rst View File

@@ -1,25 +1,31 @@
1
-.. performa documentation master file, created by
2
-   sphinx-quickstart on Tue Jul  9 22:26:36 2013.
3
-   You can adapt this file completely to your liking, but it should at least
4
-   contain the root `toctree` directive.
1
+Performa
2
+========
3
+
4
+What Performa is?
5
+-----------------
6
+
7
+Performa is distributed scenario runner, results processor and report generator.
8
+It is the strong mixture of powerful technologies:
9
+ * Ansible_ for easy running modularized code in distributed manner
10
+ * MongoDB_ for storing and transforming data
11
+ * Pygal_ for creating light-weight charts
12
+ * Jinja2_ for templating the world
5 13
 
6
-Welcome to performa's documentation!
7
-====================================
8 14
 
9 15
 Contents:
10 16
 
11 17
 .. toctree::
12 18
    :maxdepth: 2
13 19
 
14
-   readme
15 20
    installation
16 21
    usage
22
+   tools
17 23
    contributing
18 24
 
19
-Indices and tables
20
-==================
21 25
 
22
-* :ref:`genindex`
23
-* :ref:`modindex`
24
-* :ref:`search`
26
+.. references:
25 27
 
28
+.. _Ansible: http://docs.ansible.com/
29
+.. _MongoDB: https://docs.mongodb.org/manual/
30
+.. _Pygal: http://www.pygal.org/
31
+.. _Jinja2: http://jinja.pocoo.org/

+ 1
- 0
doc/source/installation.rst View File

@@ -10,3 +10,4 @@ Or, if you have virtualenvwrapper installed::
10 10
 
11 11
     $ mkvirtualenv performa
12 12
     $ pip install performa
13
+

+ 18
- 0
doc/source/tools.rst View File

@@ -0,0 +1,18 @@
1
+===================
2
+CLI Tools Reference
3
+===================
4
+
5
+performa
6
+--------
7
+
8
+Runs specified scenario, stores data and generates report.
9
+
10
+.. literalinclude:: tools/performa.txt
11
+
12
+
13
+performa-report
14
+---------------
15
+
16
+Generates report based on previously collected data.
17
+
18
+.. literalinclude:: tools/shaker-report.txt

+ 80
- 0
doc/source/tools/performa-report.txt View File

@@ -0,0 +1,80 @@
1
+usage: performa-report [-h] [--book BOOK] [--config-dir DIR]
2
+                       [--config-file PATH] [--debug] [--hosts HOSTS]
3
+                       [--log-config-append PATH]
4
+                       [--log-date-format DATE_FORMAT] [--log-dir LOG_DIR]
5
+                       [--log-file PATH] [--mongo-db MONGO_DB]
6
+                       [--mongo-url MONGO_URL] [--nodebug] [--nouse-syslog]
7
+                       [--noverbose] [--nowatch-log-file]
8
+                       [--remote-user REMOTE_USER] [--scenario SCENARIO]
9
+                       [--syslog-log-facility SYSLOG_LOG_FACILITY] [--tag TAG]
10
+                       [--use-syslog] [--verbose] [--version]
11
+                       [--watch-log-file]
12
+
13
+optional arguments:
14
+  -h, --help            show this help message and exit
15
+  --book BOOK           Generate report in ReST format and store it into the
16
+                        specified folder, defaults to env[PERFORMA_BOOK].
17
+  --config-dir DIR      Path to a config directory to pull *.conf files from.
18
+                        This file set is sorted, so as to provide a
19
+                        predictable parse order if individual options are
20
+                        over-ridden. The set is parsed after the file(s)
21
+                        specified via previous --config-file, arguments hence
22
+                        over-ridden options in the directory take precedence.
23
+  --config-file PATH    Path to a config file to use. Multiple config files
24
+                        can be specified, with values in later files taking
25
+                        precedence. Defaults to None.
26
+  --debug, -d           If set to true, the logging level will be set to DEBUG
27
+                        instead of the default INFO level.
28
+  --hosts HOSTS         Hosts inventory definition in YAML format, Can be
29
+                        specified via env[PERFORMA_HOSTS].
30
+  --log-config-append PATH, --log_config PATH
31
+                        The name of a logging configuration file. This file is
32
+                        appended to any existing logging configuration files.
33
+                        For details about logging configuration files, see the
34
+                        Python logging module documentation. Note that when
35
+                        logging configuration files are used then all logging
36
+                        configuration is set in the configuration file and
37
+                        other logging configuration options are ignored (for
38
+                        example, logging_context_format_string).
39
+  --log-date-format DATE_FORMAT
40
+                        Defines the format string for %(asctime)s in log
41
+                        records. Default: None . This option is ignored if
42
+                        log_config_append is set.
43
+  --log-dir LOG_DIR, --logdir LOG_DIR
44
+                        (Optional) The base directory used for relative
45
+                        log_file paths. This option is ignored if
46
+                        log_config_append is set.
47
+  --log-file PATH, --logfile PATH
48
+                        (Optional) Name of log file to send logging output to.
49
+                        If no default is set, logging will go to stderr as
50
+                        defined by use_stderr. This option is ignored if
51
+                        log_config_append is set.
52
+  --mongo-db MONGO_DB   Mongo DB, defaults to env[PERFORMA_MONGO_DB].
53
+  --mongo-url MONGO_URL
54
+                        Mongo URL, defaults to env[PERFORMA_MONGO_URL].
55
+  --nodebug             The inverse of --debug
56
+  --nouse-syslog        The inverse of --use-syslog
57
+  --noverbose           The inverse of --verbose
58
+  --nowatch-log-file    The inverse of --watch-log-file
59
+  --remote-user REMOTE_USER
60
+                        User for connecting to remote systems, defaults to
61
+                        env[PERFORMA_REMOTE_USER].
62
+  --scenario SCENARIO   Scenario to play. Can be a file name or one of
63
+                        aliases: "db/sysbench", "mq/omsimulator". Defaults to
64
+                        env[PERFORMA_SCENARIO].
65
+  --syslog-log-facility SYSLOG_LOG_FACILITY
66
+                        Syslog facility to receive log lines. This option is
67
+                        ignored if log_config_append is set.
68
+  --tag TAG             Tag the execution, defaults to env[PERFORMA_TAG].
69
+  --use-syslog          Use syslog for logging. Existing syslog format is
70
+                        DEPRECATED and will be changed later to honor RFC5424.
71
+                        This option is ignored if log_config_append is set.
72
+  --verbose, -v         If set to false, the logging level will be set to
73
+                        WARNING instead of the default INFO level.
74
+  --version             show program's version number and exit
75
+  --watch-log-file      Uses logging handler designed to watch file system.
76
+                        When log file is moved or removed this handler will
77
+                        open a new log file with specified path
78
+                        instantaneously. It makes sense only if log_file
79
+                        option is specified and Linux platform is used. This
80
+                        option is ignored if log_config_append is set.

+ 78
- 0
doc/source/tools/performa.txt View File

@@ -0,0 +1,78 @@
1
+usage: performa [-h] [--book BOOK] [--config-dir DIR] [--config-file PATH]
2
+                [--debug] [--hosts HOSTS] [--log-config-append PATH]
3
+                [--log-date-format DATE_FORMAT] [--log-dir LOG_DIR]
4
+                [--log-file PATH] [--mongo-db MONGO_DB]
5
+                [--mongo-url MONGO_URL] [--nodebug] [--nouse-syslog]
6
+                [--noverbose] [--nowatch-log-file] [--remote-user REMOTE_USER]
7
+                [--scenario SCENARIO]
8
+                [--syslog-log-facility SYSLOG_LOG_FACILITY] [--tag TAG]
9
+                [--use-syslog] [--verbose] [--version] [--watch-log-file]
10
+
11
+optional arguments:
12
+  -h, --help            show this help message and exit
13
+  --book BOOK           Generate report in ReST format and store it into the
14
+                        specified folder, defaults to env[PERFORMA_BOOK].
15
+  --config-dir DIR      Path to a config directory to pull *.conf files from.
16
+                        This file set is sorted, so as to provide a
17
+                        predictable parse order if individual options are
18
+                        over-ridden. The set is parsed after the file(s)
19
+                        specified via previous --config-file, arguments hence
20
+                        over-ridden options in the directory take precedence.
21
+  --config-file PATH    Path to a config file to use. Multiple config files
22
+                        can be specified, with values in later files taking
23
+                        precedence. Defaults to None.
24
+  --debug, -d           If set to true, the logging level will be set to DEBUG
25
+                        instead of the default INFO level.
26
+  --hosts HOSTS         Hosts inventory definition in YAML format, Can be
27
+                        specified via env[PERFORMA_HOSTS].
28
+  --log-config-append PATH, --log_config PATH
29
+                        The name of a logging configuration file. This file is
30
+                        appended to any existing logging configuration files.
31
+                        For details about logging configuration files, see the
32
+                        Python logging module documentation. Note that when
33
+                        logging configuration files are used then all logging
34
+                        configuration is set in the configuration file and
35
+                        other logging configuration options are ignored (for
36
+                        example, logging_context_format_string).
37
+  --log-date-format DATE_FORMAT
38
+                        Defines the format string for %(asctime)s in log
39
+                        records. Default: None . This option is ignored if
40
+                        log_config_append is set.
41
+  --log-dir LOG_DIR, --logdir LOG_DIR
42
+                        (Optional) The base directory used for relative
43
+                        log_file paths. This option is ignored if
44
+                        log_config_append is set.
45
+  --log-file PATH, --logfile PATH
46
+                        (Optional) Name of log file to send logging output to.
47
+                        If no default is set, logging will go to stderr as
48
+                        defined by use_stderr. This option is ignored if
49
+                        log_config_append is set.
50
+  --mongo-db MONGO_DB   Mongo DB, defaults to env[PERFORMA_MONGO_DB].
51
+  --mongo-url MONGO_URL
52
+                        Mongo URL, defaults to env[PERFORMA_MONGO_URL].
53
+  --nodebug             The inverse of --debug
54
+  --nouse-syslog        The inverse of --use-syslog
55
+  --noverbose           The inverse of --verbose
56
+  --nowatch-log-file    The inverse of --watch-log-file
57
+  --remote-user REMOTE_USER
58
+                        User for connecting to remote systems, defaults to
59
+                        env[PERFORMA_REMOTE_USER].
60
+  --scenario SCENARIO   Scenario to play. Can be a file name or one of
61
+                        aliases: "db/sysbench", "mq/omsimulator". Defaults to
62
+                        env[PERFORMA_SCENARIO].
63
+  --syslog-log-facility SYSLOG_LOG_FACILITY
64
+                        Syslog facility to receive log lines. This option is
65
+                        ignored if log_config_append is set.
66
+  --tag TAG             Tag the execution, defaults to env[PERFORMA_TAG].
67
+  --use-syslog          Use syslog for logging. Existing syslog format is
68
+                        DEPRECATED and will be changed later to honor RFC5424.
69
+                        This option is ignored if log_config_append is set.
70
+  --verbose, -v         If set to false, the logging level will be set to
71
+                        WARNING instead of the default INFO level.
72
+  --version             show program's version number and exit
73
+  --watch-log-file      Uses logging handler designed to watch file system.
74
+                        When log file is moved or removed this handler will
75
+                        open a new log file with specified path
76
+                        instantaneously. It makes sense only if log_file
77
+                        option is specified and Linux platform is used. This
78
+                        option is ignored if log_config_append is set.

+ 11
- 4
doc/source/usage.rst View File

@@ -1,7 +1,14 @@
1
-========
1
+=====
2 2
 Usage
3
-========
3
+=====
4 4
 
5
-To use performa in a project::
5
+**Example**::
6 6
 
7
-    import performa
7
+    performa --mongo-url 127.0.0.1 --mongo-db performa --scenario db/sysbench \
8
+        --hosts "{target: [192.168.20.20]}" --remote-user developer --debug \
9
+        --book doc/source/test_results/db/sysbench
10
+
11
+This example runs Performa tool with scenario 'sb/sysbench'. It uses MongoDB
12
+located at localhost and database named 'performa'. The scenario is executed
13
+against remote host 192.168.20.20 which can be accessed with user 'developer'.
14
+The report is stored into 'doc/source/test_results/db/sysbench' folder.

+ 125
- 0
etc/performa.conf View File

@@ -0,0 +1,125 @@
1
+[DEFAULT]
2
+
3
+#
4
+# From oslo_log
5
+#
6
+
7
+# If set to true, the logging level will be set to DEBUG instead of the default
8
+# INFO level. (boolean value)
9
+#debug = false
10
+
11
+# If set to false, the logging level will be set to WARNING instead of the
12
+# default INFO level. (boolean value)
13
+# This option is deprecated for removal.
14
+# Its value may be silently ignored in the future.
15
+#verbose = true
16
+
17
+# The name of a logging configuration file. This file is appended to any
18
+# existing logging configuration files. For details about logging configuration
19
+# files, see the Python logging module documentation. Note that when logging
20
+# configuration files are used then all logging configuration is set in the
21
+# configuration file and other logging configuration options are ignored (for
22
+# example, logging_context_format_string). (string value)
23
+# Deprecated group/name - [DEFAULT]/log_config
24
+#log_config_append = <None>
25
+
26
+# Defines the format string for %%(asctime)s in log records. Default:
27
+# %(default)s . This option is ignored if log_config_append is set. (string
28
+# value)
29
+#log_date_format = %Y-%m-%d %H:%M:%S
30
+
31
+# (Optional) Name of log file to send logging output to. If no default is set,
32
+# logging will go to stderr as defined by use_stderr. This option is ignored if
33
+# log_config_append is set. (string value)
34
+# Deprecated group/name - [DEFAULT]/logfile
35
+#log_file = <None>
36
+
37
+# (Optional) The base directory used for relative log_file  paths. This option
38
+# is ignored if log_config_append is set. (string value)
39
+# Deprecated group/name - [DEFAULT]/logdir
40
+#log_dir = <None>
41
+
42
+# Uses logging handler designed to watch file system. When log file is moved or
43
+# removed this handler will open a new log file with specified path
44
+# instantaneously. It makes sense only if log_file option is specified and
45
+# Linux platform is used. This option is ignored if log_config_append is set.
46
+# (boolean value)
47
+#watch_log_file = false
48
+
49
+# Use syslog for logging. Existing syslog format is DEPRECATED and will be
50
+# changed later to honor RFC5424. This option is ignored if log_config_append
51
+# is set. (boolean value)
52
+#use_syslog = false
53
+
54
+# Syslog facility to receive log lines. This option is ignored if
55
+# log_config_append is set. (string value)
56
+#syslog_log_facility = LOG_USER
57
+
58
+# Log output to standard error. This option is ignored if log_config_append is
59
+# set. (boolean value)
60
+#use_stderr = true
61
+
62
+# Format string to use for log messages with context. (string value)
63
+#logging_context_format_string = %(asctime)s.%(msecs)03d %(process)d %(levelname)s %(name)s [%(request_id)s %(user_identity)s] %(instance)s%(message)s
64
+
65
+# Format string to use for log messages when context is undefined. (string
66
+# value)
67
+#logging_default_format_string = %(asctime)s.%(msecs)03d %(process)d %(levelname)s %(name)s [-] %(instance)s%(message)s
68
+
69
+# Additional data to append to log message when logging level for the message
70
+# is DEBUG. (string value)
71
+#logging_debug_format_suffix = %(funcName)s %(pathname)s:%(lineno)d
72
+
73
+# Prefix each line of exception output with this format. (string value)
74
+#logging_exception_prefix = %(asctime)s.%(msecs)03d %(process)d ERROR %(name)s %(instance)s
75
+
76
+# Defines the format string for %(user_identity)s that is used in
77
+# logging_context_format_string. (string value)
78
+#logging_user_identity_format = %(user)s %(tenant)s %(domain)s %(user_domain)s %(project_domain)s
79
+
80
+# List of package logging levels in logger=LEVEL pairs. This option is ignored
81
+# if log_config_append is set. (list value)
82
+#default_log_levels = amqp=WARN,amqplib=WARN,boto=WARN,qpid=WARN,sqlalchemy=WARN,suds=INFO,oslo.messaging=INFO,iso8601=WARN,requests.packages.urllib3.connectionpool=WARN,urllib3.connectionpool=WARN,websocket=WARN,requests.packages.urllib3.util.retry=WARN,urllib3.util.retry=WARN,keystonemiddleware=WARN,routes.middleware=WARN,stevedore=WARN,taskflow=WARN,keystoneauth=WARN,oslo.cache=INFO,dogpile.core.dogpile=INFO
83
+
84
+# Enables or disables publication of error events. (boolean value)
85
+#publish_errors = false
86
+
87
+# The format for an instance that is passed with the log message. (string
88
+# value)
89
+#instance_format = "[instance: %(uuid)s] "
90
+
91
+# The format for an instance UUID that is passed with the log message. (string
92
+# value)
93
+#instance_uuid_format = "[instance: %(uuid)s] "
94
+
95
+# Enables or disables fatal status of deprecations. (boolean value)
96
+#fatal_deprecations = false
97
+
98
+#
99
+# From performa.engine.config
100
+#
101
+
102
+# Scenario to play. Can be a file name or one of aliases: "db/sysbench",
103
+# "mq/omsimulator". Defaults to env[PERFORMA_SCENARIO]. (string value)
104
+#scenario = <None>
105
+
106
+# Mongo URL, defaults to env[PERFORMA_MONGO_URL]. (string value)
107
+#mongo_url = <None>
108
+
109
+# Mongo DB, defaults to env[PERFORMA_MONGO_DB]. (string value)
110
+#mongo_db = <None>
111
+
112
+# User for connecting to remote systems, defaults to env[PERFORMA_REMOTE_USER].
113
+# (string value)
114
+#remote_user = <None>
115
+
116
+# Hosts inventory definition in YAML format, Can be specified via
117
+# env[PERFORMA_HOSTS]. (string value)
118
+#hosts = <None>
119
+
120
+# Generate report in ReST format and store it into the specified folder,
121
+# defaults to env[PERFORMA_BOOK].  (string value)
122
+#book = <None>
123
+
124
+# Tag the execution, defaults to env[PERFORMA_TAG]. (string value)
125
+#tag = <None>

+ 62
- 0
tools/cli_auto_doc.py View File

@@ -0,0 +1,62 @@
1
+# Copyright (c) 2015 Mirantis Inc.
2
+#
3
+# Licensed under the Apache License, Version 2.0 (the "License");
4
+# you may not use this file except in compliance with the License.
5
+# You may obtain a copy of the License at
6
+#
7
+#   http://www.apache.org/licenses/LICENSE-2.0
8
+#
9
+# Unless required by applicable law or agreed to in writing, software
10
+# distributed under the License is distributed on an "AS IS" BASIS,
11
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
12
+# implied.
13
+# See the License for the specific language governing permissions and
14
+# limitations under the License.
15
+
16
+import os
17
+import sys
18
+
19
+try:
20
+    import ConfigParser as configparser
21
+except ImportError:
22
+    import configparser
23
+
24
+
25
+def split_multiline(value):
26
+    value = [element for element in
27
+             (line.strip() for line in value.split('\n'))
28
+             if element]
29
+    return value
30
+
31
+
32
+def get_entry_points(config):
33
+    if 'entry_points' not in config:
34
+        return {}
35
+    return dict((option, split_multiline(value))
36
+                for option, value in config['entry_points'].items())
37
+
38
+
39
+def make(cfg, dest):
40
+    parser = configparser.RawConfigParser()
41
+    parser.read(cfg)
42
+    config = {}
43
+    for section in parser.sections():
44
+        config[section] = dict(parser.items(section))
45
+    entry_points = get_entry_points(config)
46
+
47
+    console_scripts = entry_points.get('console_scripts')
48
+    if console_scripts:
49
+        for item in console_scripts:
50
+            tool = item.split('=')[0].strip()
51
+            print('Running %s' % tool)
52
+            os.system('%(tool)s --help > %(dest)s/%(tool)s.txt' %
53
+                      dict(tool=tool, dest=dest))
54
+
55
+
56
+if len(sys.argv) < 2:
57
+    print('Usage: cli_auto_doc <dest folder>')
58
+    sys.exit(1)
59
+
60
+
61
+print('Generating docs from help to console tools')
62
+make(cfg='setup.cfg', dest=sys.argv[1])

+ 3
- 0
tools/svg2png.sh View File

@@ -0,0 +1,3 @@
1
+#!/bin/bash -xe
2
+
3
+find doc/source/ -name *svg | sed "s/\.svg$//" | xargs -I% cairosvg "%.svg" -o "%.png"

+ 14
- 0
tox.ini View File

@@ -19,6 +19,20 @@ commands = {posargs}
19 19
 [testenv:pep8]
20 20
 commands = flake8
21 21
 
22
+[testenv:genconfig]
23
+commands =
24
+    oslo-config-generator --config-file=config-generator.conf
25
+    python tools/cli_auto_doc.py doc/source/tools
26
+
27
+[testenv:svg2png]
28
+deps =
29
+    cairosvg
30
+    lxml
31
+    tinycss
32
+    cssselect
33
+whitelist_externals = bash
34
+commands = bash tools/svg2png.sh
35
+
22 36
 [testenv:docs]
23 37
 commands = python setup.py build_sphinx
24 38
 

Loading…
Cancel
Save