Merge "Add test_get_vim_by_id_success"
[multicloud/framework.git] / docs / specs / parallelism_improvement.rst
1 ..
2  This work is licensed under a Creative Commons Attribution 4.0
3  International License.
4
5 ===============================================
6 Parallelism improvement of Multi Cloud Services
7 ===============================================
8
9
10 Problem Description
11 ===================
12
13 Multi-Cloud runs Django by using Django's built-in webserver currently.
14 According to Django Document[Django_Document]_, this mode should not be used
15 in production. This mode has not gone through security audits or performance
16 tests, and should only be used in development. From test on local computer,
17 this mode can only handle ONE API request at one time. This can not meet the
18 performance requirement.
19
20 .. [Django_Document] https://docs.djangoproject.com/en/dev/ref/django-admin/#runserver
21
22 Although security and scalability might be improved as the side effect of
23 resolving the performance issue, this spec will only focus on how to improve
24 the parallelism(performance) of current MultiCloud API framework.
25
26 Possible Solutions
27 ==================
28
29 Solution 1
30 ----------
31
32 Django is a mature framework. And it has its own way to improve parallelism.
33 Instead of running Django's build-in webserver, Django APP can be deployed in
34 some dedicated web server. Django’s primary deployment platform is WSGI[django_deploy]_,
35 the Python standard for web servers and applications.
36
37 .. [django_deploy] https://docs.djangoproject.com/en/2.0/howto/deployment/wsgi/
38
39
40 But on the other side, Danjgo is very huge. And Django is a black box if one
41 doesn't have good knowledge of it. Adding feature based on Django may be
42 time-consuming. For example, the unit test[unit_test]_ of Multi-Cloud can't use
43 regular python test library because of Django. The unit test has to base on
44 Django's test framework. When we want to improve the parallelism of Multi-Cloud
45 services, we need to find out how Django can implement it, instead of using some
46 common method.
47
48 .. [unit_test] https://gerrit.onap.org/r/#/c/8909/
49
50 Besides, Django's code pattern is too much like web code. And, most famous use
51 cases of Django are web UI. Current code of Multi-Cloud puts many logic in
52 files named `views.py`, but actually there is no view to expose. It is confusing.
53
54 The benefit of this solution is that most current code needs no change.
55
56 Solution 2
57 ----------
58
59 Given the fact that Django has shortcomings to move on, this solution propose
60 to use a alternative framework. Eventlet[Eventlet]_ with Pecan[Pecan]_ will be the
61 idea web framework in this case, because it is lightweight, lean and widely
62 used.
63
64 .. [Eventlet] http://eventlet.net/doc/modules/wsgi.html
65
66 .. [Pecan] https://pecan.readthedocs.io/en/latest/
67
68 For example, most OpenStack projects use such framework. This framework is so
69 thin that it can provide flexibility for future architecture design.
70
71 However, it needs to change existing code of API exposing.
72
73
74 Performance Test Comparison
75 ===========================
76
77 Test Environment
78 ----------------
79
80 Apache Benchmark is used as test tool. It is shipped with Ubuntu, if you
81 don’t find it, just run “sudo apt install -y apache2-utils”
82
83 2 Virtual Machine with Ubuntu1604. Virtual Machines are hosted in a multi-core
84 hardware server. One VM is for Apache Benchmark. This VM is 1 CPU core, 8G mem.
85 The other VM is for Multicloud. The VM is 4 CPU core, 6G mem.
86
87 Test Command
88 ~~~~~~~~~~~~
89
90 `ab  -n <num of total requests> -c <concurrency level> http://<IP:port>/api/multicloud/v0/vim_types`
91
92 Test result
93 -----------
94
95 It should be noted that data may vary in different test run, but overall result is
96 similar as below.
97
98 100 requests, concurrency level 1
99 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
100
101 Command:  `ab  -n 100 -c 1 http://<IP:port>/api/multicloud/v0/vim_types`
102 Result:
103   Django runserver: total takes 0.512 seconds, all requests success
104   Django+uwsgi: totally takes 0.671 seconds, all requests success.
105   Pecan+eventlet:  totally takes 0.149 seconds, all requests success.
106
107 10000 requests, concurrency level 100
108 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
109
110 Command:  `ab  -n 10000 -c 100 http://<IP:port>/api/multicloud/v0/vim_types`
111 Result:
112   Django runserver: total takes 85.326 seconds, all requests success
113   Django+uwsgi: totally takes 3.808 seconds, all requests success.
114   Pecan+eventlet:  totally takes 3.181 seconds, all requests success.
115
116 100000 requests, concurrency level 1000
117 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
118
119 Command:  `ab  -n 100000 -c 1000 http://<IP:port>/api/multicloud/v0/vim_types`
120 Result:
121   Django runserver: Apache Benchmark quit because it reports timeout after
122   running a random portion of all requests.
123   Django+uwsgi: totally takes 37.316 seconds, about 32% requests fail. I see
124   some error says that tcp socket open too many.
125   Pecan+eventlet:  totally takes 35.315 seconds, all requests success.
126
127 Proposed Change
128 ===============
129
130 Given the test result above, this spec proposes to use solution 2. Based on
131 the consideration of Elastic API exposure[jira_workitem]_, Multi-Cloud will
132 provide a new way to expose its API. That is to say, existing code of API
133 exposing needs rewrite in [jira_workitem]_. So the disadvantage of solution
134 2 doesn't exist.
135
136 .. [jira_workitem] https://jira.onap.org/browse/MULTICLOUD-152
137
138 To define a clear scope of this spec, VoLTE is the use case that will be used
139 to perform test to this spec. All functionality that VoLTE needed should be
140 implemented in this spec and [jira_workitem]_.
141
142 Backward compatibility
143 ----------------------
144
145 This spec will NOT change current API. This spec will NOT replace the current
146 API framework in R2, nor will switch to new API framework in R2. Instead,
147 this spec will provide a configuration option, named `web_framework`,  to make
148 sure use case and functionalities not be broken. Default value of the
149 configuration will BE `django`, which will still run current Django API
150 framework. An alternative value is `pecan`, which will run the API framework
151 proposed in this spec. So users don't care about the change won't be
152 affected.
153
154 WSGI Server
155 -----------
156
157 No matter what API framework will be used, a WSGI Server needs to be provided.
158 This spec will use Eventlet WSGI server. API framework will be run as an
159 application in WSGI server.
160
161 Multi processes framework
162 -------------------------
163
164 This spec proposes to run Multi-Cloud API server in multiple processes mode.
165 Multi-process can provide parallel API handlers. So, when multiple API
166 requests come to Multi-Cloud, they can be handled simultaneously. On the other
167 hand, different processes can effectively isolate different API request. So
168 that, one API request will not affect another.
169
170 Managing multiple processes could be overwhelming difficult and sometimes
171 dangerous. Some mature library could be used to reduce related work here, for
172 example oslo.service[oslo_service]_. Since oslo is used by all OpenStack
173 projects for many releases, and oslo project is actively updated, it can be
174 seen as a stable library.
175
176 .. [oslo_service] https://github.com/openstack/oslo.service
177
178 Number of processes
179 ~~~~~~~~~~~~~~~~~~~
180
181 To best utilize multi-core CPU, the number of processes will be set to the
182 number of CPU cores by default.
183
184 Shared socket file
185 ~~~~~~~~~~~~~~~~~~
186
187 To make multiple processes work together and provide a unified port number,
188 multiple processes need to share a socket file. To achieve this, a bootstrap
189 process will be started and will initialize the socket file. Other processes
190 can be forked from this bootstrap process.
191
192 Work Items
193 ==========
194
195 #. Add WSGI server.
196 #. Run Pecan application in WSGI server.
197 #. Add multiple processes support.
198 #. Update deploy script to support new API framework.
199