1Author : Hakan Mattsson <hakan@cslab.ericsson.se> 2Created : 21 Jun 2001 by Hakan Mattsson <hakan@cslab.ericsson.se> 3 4This is an implementation of a real-time database benchmark 5(LMC/UU-01:025), defined by Richard Trembley (LMC) and Miroslaw 6Zakrzewski (LMC) . The implementation runs the benchmark on the Mnesia 7DBMS which is a part of Erlang/OTP (www.erlang.org). 8 9The implementation is organized in the following parts: 10 11 bench.erl - main API, startup and configuration 12 bench.hrl - record definitions 13 bench_populate.erl - create database and populate it with records 14 bench_trans.erl - the actual transactions to be benchmarked 15 bench_generate.erl - request generator, statistics computation 16 17Compile the files with: 18 19 make all 20 21and run the benchmarks with: 22 23 make test 24 25================================================================ 26 27The benchmark runs on a set of Erlang nodes which should reside on 28one processor each. 29 30There are many options when running the benchmark. Benchmark 31configuration parameters may either be stated in a configuration file 32or as command line arguments in the Erlang shell. Erlang nodes may 33either be started manually or automatically by the benchmark program. 34 35In its the most automated usage you only need to provide one or more 36configuration files and run the 37 38 bench.sh <ConfigFiles> 39 40script to start all Erlang nodes, populate the database and run the 41actual benchmark for each one of the configuration files. The 42benchmark results will be displayed at stdout. 43 44In order to be able to automatically start remote Erlang nodes, 45you need to: 46 47 - put the $ERL_TOP/bin directory in your path on all nodes 48 - bind IP adresses to hostnames (e.g via DNS or /etc/hosts) 49 - enable usage of rsh so it does not prompt for password 50 51If you cannot achieve this, it is possible to run the benchmark 52anyway, but it requires more manual work to be done for each 53execution of the benchmark. 54 55================================================================ 56 57For each configuration file given to the bench.sh script: 58 59 - a brand new Erlang node is started 60 - the bench:run(['YourConfigFile']) function is invoked 61 - the Erlang node(s) are halted. 62 63Without arguments, the bench.sh simply starts an Erlang shell. 64In that shell you have the ability to invoke Erlang functions, 65such as bench:run/1. 66 67The bench:start_all/1 function analyzes the configuration, starts 68all Erlang nodes necessary to perform the benchmark and starts 69Mnesia on all these nodes. 70 71The bench:populate/1 function populates the database according 72to the configuration and assumes that Mnesia is up and running 73on all nodes. 74 75The bench:generate/1 function starts the actual benchmark 76according to the configuration and assumes that Mnesia is 77up and running and that the database is fully populated. 78Given some arguments such as 79 80 Args = ['YourConfigFile', {statistics_detail, debug}]. 81 82the invokation of 83 84 bench:run(Args). 85 86is equivivalent with: 87 88 SlaveNodes = bench:start_all(Args). 89 bench:populate(Args). 90 bench:generate(Args). 91 bench:stop_slave_nodes(SlaveNodes). 92 93In case you cannot get the automatic start of remote Erlang nodes to 94work (implied by bench:start_all/1) , you may need to manually start 95an Erlang node on each host (e.g. with bench.sh without arguments) and 96then invoke bench:run/1 or its equivivalents on one of them. 97 98================================================================ 99 100The following configuration parameters are valid: 101 102generator_profile 103 104 Selects the transaction profile of the benchmark. Must be one 105 of the following atoms: t1, t2, t3, t4, t5, ping, random. 106 Defaults to random which means that the t1 .. t5 transaction 107 types are randomly selected according to the benchmark spec. 108 The other choices means disables the random choice and selects 109 one particular transaction type to be run over and over again. 110 111generator_warmup 112 113 Defines how long the request generators should "warm up" the 114 DBMS before the actual measurements are performed. The unit 115 is milliseconds and defaults to 2000 (2 seconds). 116 117generator_duration 118 119 Defines the duration of the actual benchmark measurement activity. 120 The unit is milliseconds and defaults to 15000 (15 seconds). 121 122generator_cooldown 123 124 Defines how long the request generators should "cool down" the 125 DBMS after the actual measurements has been performed. The unit 126 is milliseconds and defaults to 2000 (2 seconds). 127 128generator_nodes 129 130 Defines which Erlang nodes that should host request generators. 131 The default is all connected nodes. 132 133n_generators_per_node 134 135 Defines how many generator processes that should be running on 136 each generator node. The default is 2. 137 138statistics_detail 139 140 Regulates the detail level of statistics. It must be one of the 141 following atoms: normal, debug and debug2. debug enables a 142 finer grain of statistics to be reported, but since it requires 143 more counters, to be updated by the generator processes it may 144 cause slightly worse benchmark performace figures than the brief 145 default case, that is normal. debug2 prints out the debug info 146 and formats it according to LMC's benchmark program. 147 148storage_type 149 150 Defines whether the database should be kept solely in primary 151 memory (ram_copies), solely on disc (disc_only_copies) or 152 in both (disc_copies). The default is ram_copies. Currently 153 the other choices requires a little bit of manual preparation. 154 155table_nodes 156 157 Defines which Erlang nodes that should host the tables. 158 159n_fragments 160 161 Defines how many fragments each table should be divided in. 162 Default is 100. The fragments are evenly distributed over 163 all table nodes. The group table not devided in fragments. 164 165n_replicas 166 167 Defines how many replicas that should be kept of each fragment. 168 The group table is replicated to all table nodes. 169 170n_subscribers 171 172 Defines the number of subscriber records. Default 25000. 173 174n_subscribers 175 176 Defines the number of subscriber records. Default 25000. 177 178n_groups 179 180 Defines the number of group records. Default 5. 181 182n_servers 183 184 Defines the number of server records. Default 1. 185 186write_lock_type 187 188 Defines whether the transactions should use ordinary 189 write locks or if they utilize sticky write locks. 190 Must be one of the following atoms: write, sticky_write. 191 Default is write. 192 193use_binary_subscriber_key 194 195 Defines whether the subscriber key should be represented 196 as a string (binary) or as an integer. Default is false. 197 198always_try_nearest_node 199 200 The benchmark was initially written to test scalability 201 when more nodes were added to the database and when the 202 (fragmented) tables were distributed over all nodes. In 203 such a system the transactions should be evenly distributed 204 over all nodes. When this option is set to true it is possible 205 to make fair measurements of master/slave configurations, when 206 all transactions are performed on on one node. Default is false. 207 208cookie 209 210 Defines which cookie the Erlang node should use in its 211 distribution protocol. Must be an atom, default is 'bench'. 212