-
Notifications
You must be signed in to change notification settings - Fork 1.7k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add customer documentation for read/write/batch API operation performance enhancing separation #2644
Add customer documentation for read/write/batch API operation performance enhancing separation #2644
Changes from 1 commit
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,115 @@ | ||
= Introducing Performance Enhancing Read/Write/Batch API Operation Separation | ||
|
||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Also, this new file is never referenced in the index file so it doesn't appear anywhere. |
||
Fineract is introducing performance enhancing read/write/batch API operation | ||
separation. | ||
|
||
Now, Fineract has three different instance types: | ||
|
||
* Read instance | ||
* Write instance | ||
* Batch instance | ||
|
||
In cases where Fineract has to deal with high load, it can cause a performance | ||
problem for a single Fineract instance. To overcome this problem, Fineract | ||
instances can be started in different instance types for better scalability and | ||
performance in a multi-instance environment: | ||
|
||
Detailed documentation on instance types can be found in this document: | ||
https://github.com/apache/fineract/blob/develop/fineract-doc/src/docs/en/chapters/deployment/instance-type.adoc | ||
|
||
The linked document also explains deployment steps and specifications. | ||
|
||
= Background | ||
|
||
Instances, where we're planning to deploy Fineract to a highly-available setup | ||
with the highest-throughput because we can scale individual parts of it. | ||
|
||
Reading data happens much more often than actually writing data so the ability | ||
to do this type of deployment will greatly improve what we can achieve in terms | ||
of performance. | ||
|
||
Also, with the separation in place, we could utilize read-replica databases as | ||
well where write and batch instances connect to a master DB and the read | ||
instances connect to read-replicas therefore reducing the load on the database | ||
as well. | ||
|
||
All three instances come with different types of restrictions in terms of what | ||
they are capable of. For example a read instance is going to be only capable of | ||
serving read (GET) APIs. Write APIs will be able to serve both read and write | ||
APIs. Batch instance is only able to serve batch job related APIs and run the | ||
batch jobs themselves. | ||
|
||
= Context | ||
|
||
== Instance types | ||
|
||
**Read instance** only accepts `GET` request. Optionally, there are | ||
database connection details for this mode. | ||
|
||
**Write instance** accepts `GET/POST/PUT/DELETE` requests. It uses the | ||
original database connection details. | ||
|
||
**BATCH instance** accepts `POST` request related to run jobs. It will start the | ||
Quartz scheduler at startup time and run the batch jobs. | ||
|
||
== Modes | ||
|
||
* Full mode (default) | ||
* Read mode | ||
* Write mode | ||
* Batch mode | ||
|
||
= Setup | ||
|
||
== Environment Variables | ||
|
||
Using environment variables, the three instance types performance enhancing | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Please no manual line breaks... see also other parts of the doc |
||
operation separation can be performed: | ||
|
||
* FINERACT_READ_MODE_ENABLED | ||
* FINERACT_WRITE_MODE_ENABLED | ||
* FINERACT_BATCH_MODE_ENABLED | ||
|
||
These three are the boolean variables to enable or disable the instance modes. | ||
|
||
== Database Settings | ||
|
||
Optional database connection details for reading mode are: | ||
|
||
.Database connection settings | ||
|=== | ||
^| Key ^| Type ^| Value | ||
|
||
| schema_server | character varying (100) | 127.0.0.1 | ||
| schema_name | character varying (100) | fineract_default | ||
| schema_server_port | character varying (10) | 5432 | ||
| schema_username | character varying (100) | mifosadmin | ||
| schema_password | character varying (100) | password | ||
| readonly_schema_server | character varying(100) | [null] | ||
| readonly_schema_name | character varying(100) | [null] | ||
| readonly_schema_server_port | character varying(10) | [null] | ||
| readonly_schema_usernname | character varying (100) | [null] | ||
| readonly_schema_password | character varying (100) | [null] | ||
| readonly_schema_connection_parameters | text | [null] | ||
|=== | ||
|
||
= Use Case Scenarios | ||
|
||
== APIs | ||
|
||
* Read APIs are allowed only for read and write instances | ||
* Write APIs are allowed only for write instances | ||
* Batch job APIs are allowed only for batch instances | ||
|
||
== Batch jobs | ||
|
||
* Batch job scheduling is allowed only for batch instances | ||
|
||
== Read-only instance type restrictions | ||
|
||
* Events are disabled for read-only instances | ||
* Read-only tenant connection support | ||
|
||
== Batch-only instance type restrictions | ||
|
||
* Receiving events is disabled for batch-only instances |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm not really sure why we created a new adoc file and calling it api-performance. Either it should be in the architecture doc or a brand new file which is specific to read/write/batch separation.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
good point, naming the file is still open for discussion; do you think a file name as api-performance-enhancement or improvement can have customer documentation on the best practices to work with api to get best performance? cc @edcable.