diff --git a/ChangeLog b/ChangeLog index 9dfc8d2..ef5828b 100644 --- a/ChangeLog +++ b/ChangeLog @@ -4,6 +4,7 @@ vX.Y.Z (YYYY-MM-DD) - Update `run` script to use PID files to stop processes instead of killall with program names - Refactor `run` script output +- Reorganize documentation v0.60.0 (2024-02-29) diff --git a/doc/architecture.rst b/doc/architecture.rst index 2322ecc..546e987 100644 --- a/doc/architecture.rst +++ b/doc/architecture.rst @@ -2,20 +2,11 @@ Architecture ------------ -Introduction -============ - -The OSDL Database Test 2 (DBT-2) workload test kit provides an on-line -transaction processing (OLTP) workload using an open source database and a -set of defined transactions. This document gives an overview of the -DBT-2 test kit. - -The DBT-2 test kit is a derivative of a benchmark specification released -by the Transaction Processing Performance Council (TPC). The TPC Benchmark C -(TPC-C) is briefly described before the DBT-2 test kit is discussed. +This section briefly recaps the TPC-C, and then describes how DBT-2 implements +the TPC-C specification. TPC-C ------ +===== The TPC-C represents the database activities of any industry that manages, sells, and distributes a product or service, such as car rental agencies, @@ -61,7 +52,7 @@ Further information on the TPC-C can be found on the web at: http://www.tpc.org/tpcc/. DBT-2 ------ +===== DBT-2 is a derivative of the TPC-C designed to produce a real-world on-line OLTP workload, similar to the TPC-C, to stress the Linux operation @@ -77,13 +68,13 @@ do not constitute a TPC-C result, and are incomparable with any TPC-C benchmark. The primary metric reported by the DBT-2 workload is the number of New-Order -transactions executed per second and is expressed as NOTPM (New Order +transactions executed per minute and is expressed as NOTPM (New Order Transactions per Minute). However, NOTPM's do not and should not be compared to tpmC measurements in any way since the DBT-2 workload does not constitute a compliant TPC-C benchmark. Improper Comparisons --------------------- +==================== If you discover any usage of DBT-2 in drawing conclusions about TPC-C performance, this inappropriate usage should be reported to both the TPC and @@ -107,17 +98,17 @@ single database. Each component is described in the following sub-sections. Database -------- -The database consists of nine tables with stored procedures, currently only -for SAP DB, to support five transactions. While this test kit was developed -using SAP DB, it can be adapted to any other database. The data represents a -company that is a wholesale supplier with a number of distributed sales -districts and associated warehouses covering a wide geographic range. The -database can be scaled to any number of warehouses to simulate businesses of -varying sizes. By default, a warehouse covers 10 districts, each district -serving 3,000 customers, with each warehouse maintaining stock for a complete -inventory of 100,000 items. DBT-2 allows the rest of the database to be -scaled as defined by the user. The five transactions supported are: -New-Order, Payment, Order-Status, Delivery, and Stock-Level. +The database consists of nine tables with supportint five transactions. While +this test kit is currently primarily maintained for PostgreSQL, it can be +adapted to any other database. The data represents a company that is a +wholesale supplier with a number of distributed sales districts and associated +warehouses covering a wide geographic range. The database can be scaled to any +number of warehouses to simulate businesses of varying sizes. By default, a +warehouse covers 10 districts, each district serving 3,000 customers, with each +warehouse maintaining stock for a complete inventory of 100,000 items. DBT-2 +allows the rest of the database to be scaled as defined by the user. The five +transactions supported are: New-Order, Payment, Order-Status, Delivery, and +Stock-Level. New-Order Transaction ~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/dbt2.rst b/doc/dbt2.rst index 1038347..fc29efa 100644 --- a/doc/dbt2.rst +++ b/doc/dbt2.rst @@ -23,6 +23,19 @@ others. .. contents:: Table of Contents +------------ +Introduction +------------ + +The OSDL Database Test 2 (DBT-2) workload test kit provides an on-line +transaction processing (OLTP) workload using an open source database and a set +of defined transactions. This document gives an overview of the DBT-2 test +kit. + +The DBT-2 test kit is a derivative of a benchmark specification released by the +Transaction Processing Performance Council (TPC). The TPC Benchmark(TM) C +(TPC-C) is briefly described before the DBT-2 test kit is discussed. + .. include:: tpc.rst .. include:: architecture.rst .. include:: quick-start.rst diff --git a/doc/quick-start.rst b/doc/quick-start.rst index 49f009d..2ecb232 100644 --- a/doc/quick-start.rst +++ b/doc/quick-start.rst @@ -9,8 +9,9 @@ https://github.com/osdldbt/dbt2/releases Rename the AppImage file to **dbt2** and make sure it is in your `PATH` and is executable. -The rest of this section describes the easiest way to use this test kit. See -the rest of the documentation for more advanced uses. +The rest of this section describes the easiest way to use this test kit per +database management system. See the rest of the documentation for more +advanced uses. PostgreSQL ========== diff --git a/doc/user-guide.rst b/doc/user-guide.rst index 97524df..781c6a8 100644 --- a/doc/user-guide.rst +++ b/doc/user-guide.rst @@ -2,9 +2,6 @@ User Guide ---------- -Introduction -============ - This document provides instructions on how to set up and use the Open Source Development Lab's Database Test 2 (DBT-2) test kit. Database management systems can be installed from source or packages, or a DBaaS option can @@ -99,7 +96,7 @@ include the extracted environment. DBT-2 Test Kit Source --------------------- -The latest stable version of the kit can be found on GitHub at: +The primary source repository of the kit can be found on GitHub at: https://github.com/osdldbt/dbt2 Environment Configuration @@ -173,7 +170,8 @@ errors if a warehouse referenced does not exist. If DBT-2 is used with standard transaction mix ratios, keying, and thinking times, etc. then the maximum throughput is limited to `12.86 x the number of warehouses`. Thus if you want more throughput, the database size also needs to -be increased. +be increased. See Clause 4.1 in the TPC-C specification for a complete +explanation. If non-standard ratios, times, etc. are used, the database should be resized to match the measured throughput. This could take multiple revisions if database