← Back to branch summary

~ubuntu-branches/ubuntu/trusty/mysql-5.6/trusty

« back to all changes in this revision

Viewing changes to storage/ndb/test/crund/INSTALL.txt

  • Committer: Package Import Robot
  • Author(s): James Page
  • Date: 2014-02-12 11:54:27 UTC
  • Revision ID: package-import@ubuntu.com-20140212115427-oq6tfsqxl1wuwehi
Tags: upstream-5.6.15
Import upstream version 5.6.15

Show diffs side-by-side

added added

removed removed

Lines of Context:
storage/ndb/test/crund/INSTALL.txt
 
1
 
 
2
How to Install, Configure, and Run the CRUND Benchmark
 
3
======================================================
 
4
 
 
5
The benchmark consists of a generic Driver and multiple "*Load" classes,
 
6
which implement the benchmark's operations against different persistence
 
7
APIs and database.
 
8
 
 
9
Depending upon which database APIs are to be benchmarked with CRUND, some
 
10
external software may need to be downloaded, installed, and configured.
 
11
 
 
12
 
 
13
0) Software Dependencies
 
14
 
 
15
    These 3rd party software dependencies need to be satisfied for the
 
16
    respective CRUND targets [in brackets, versions known to work]:
 
17
 
 
18
 Action         Target                  Dependencies
 
19
-------------------------------------------------------------------------------
 
20
 build          Java Driver,            JDK [1.5 and 1.6]
 
21
                 *Load.java             ANT [1.7]
 
22
-------------------------------------------------------------------------------
 
23
 build          C++ Driver,             GNU gcc [4.0.1, 4.2.4, 4.4.0]
 
24
                NdbApiLoad              gmake [3.81]
 
25
                                        "Martin's Little Helpers" Utilities
 
26
                                        [shipped with CRUND, see below]
 
27
-------------------------------------------------------------------------------
 
28
 build, run     NdbJTieLoad             NDB [7.1] (jar files + shared libraries)
 
29
-------------------------------------------------------------------------------
 
30
 build, run     ClusterjLoad            NDB [7.1] (jar files)
 
31
-------------------------------------------------------------------------------
 
32
 build          JdbcLoad                JDK [1.5]
 
33
-------------------------------------------------------------------------------
 
34
 run            JdbcLoad on MySQL       MySQL Connector/J [5.1.7]
 
35
-------------------------------------------------------------------------------
 
36
 build          JpaLoad                 JPA [1.0 == EJB 3.0] (jar files)
 
37
-------------------------------------------------------------------------------
 
38
 run            JpaLoad on OpenJPA      OpenJPA [1.2.2] has dependencies upon:
 
39
                                          JTA [1.1] API classes
 
40
                                          Apache Commons Lang [2.1]
 
41
                                          Apache Commons Collections [3.2]
 
42
                                          [Apache Commons Pool [1.3]]
 
43
                                          Sourceforge Serp Bytecode lib [1.13]
 
44
                on MySQL                [see JdbcLoad on MySQL]
 
45
                on Derby                [see JdbcLoad on Derby]
 
46
-------------------------------------------------------------------------------
 
47
 run            JdbcLoad on Derby       Apache Derby [10.4.2.0 and 10.5.1.1]
 
48
-------------------------------------------------------------------------------
 
49
 build, run     NdbjLoad                ndb-bindings [0.7.3]
 
50
                                        NDB [6.3.20]
 
51
-------------------------------------------------------------------------------
 
52
 
 
53
 
 
54
    For example, put dependencies into a local lib/ directory:
 
55
      commons-collections-3.2.jar
 
56
      commons-lang-2.1.jar
 
57
      commons-pool-1.3.jar
 
58
      derby-10.5.1.1.jar
 
59
      derbytools-10.5.1.1.jar
 
60
      geronimo-jpa_3.0_spec-1.0.jar
 
61
      geronimo-jta_1.1_spec-1.1.jar
 
62
      mysql-connector-java-5.1.11-bin.jar
 
63
      openjpa-1.2.2.jar
 
64
      serp-1.13.1.jar
 
65
 
 
66
 
 
67
1) Configure CRUND
 
68
 
 
69
    Copy the sample configuration files (*.properties, *.cnf, and *.ini)
 
70
        $ cp -v config_samples/* .
 
71
        config_samples/config.ini -> ./config.ini
 
72
        config_samples/crundClusterj.properties -> ./crundClusterj.properties
 
73
        config_samples/crundMysql.properties -> ./crundMysql.properties
 
74
        config_samples/crundNdbapi.properties -> ./crundNdbapi.properties
 
75
        config_samples/crundNdbjtie.properties -> ./crundNdbjtie.properties
 
76
        config_samples/crundOpenjpaClusterj.properties -> ./crundOpenjpaClusterj.properties
 
77
        config_samples/crundOpenjpaMysql.properties -> ./crundOpenjpaMysql.properties
 
78
        config_samples/crundRun.properties -> ./crundRun.properties
 
79
        config_samples/env.properties -> ./env.properties
 
80
        config_samples/my.cnf -> ./my.cnf
 
81
 
 
82
    Edit the file
 
83
        ./env.properties
 
84
    for all the paths to CRUND's external software dependencies.
 
85
 
 
86
    Edit the other *.properties, *.cnf, and *.ini files for cluster setup
 
87
    and benchmark run parameters.
 
88
 
 
89
 
 
90
2) Build "Martin's Little Helpers" Utilities
 
91
 
 
92
    (Only needed if building/running NdbApiLoad or using 'make', see below)
 
93
 
 
94
    See file README.txt in the subdirectory and run
 
95
        $ cd martins_little_helpers/
 
96
        $ make dep
 
97
        $ make opt
 
98
 
 
99
 
 
100
3) Build CRUND
 
101
 
 
102
3.1) Build the Java classes using Ant (for better diagnostics)
 
103
 
 
104
    Ant is used to build the Java Driver and *Load classes.
 
105
 
 
106
    For an overview of the supported targets:
 
107
        $ ant help
 
108
 
 
109
    Specific build targets:
 
110
        $ ant compile.ndbapi
 
111
        $ ant compile.ndbjtie
 
112
        $ ant compile.clusterj
 
113
        $ ant compile.jdbc
 
114
        $ ant compile.jpa
 
115
        $ ant compile             // builds all of above
 
116
 
 
117
    Additional compile.*.opt targets build optimized versions of the
 
118
    classes (but typically, the performance difference can be neglected).
 
119
 
 
120
    Other standard Ant targets:
 
121
        $ ant javadoc
 
122
        $ ant clean
 
123
        $ ant clobber
 
124
        $ ant distclean
 
125
 
 
126
3.2) Build all C++ binaries and Java classes using Make
 
127
 
 
128
    For an overview of the supported targets:
 
129
        $ make help
 
130
 
 
131
    Run once
 
132
        $ make dep
 
133
    to build the .depend files.
 
134
 
 
135
    Then run either of
 
136
        $ make dbg
 
137
        $ make opt
 
138
    to build debug or optimized binaries and classes.
 
139
 
 
140
    To build only the C++ classes run these make targets from subdirectory
 
141
        $ cd src/crundndb/
 
142
 
 
143
    To delete all temporary, +logging, +database files run
 
144
        $ make clean
 
145
        $ make clobber
 
146
        $ make distclean
 
147
 
 
148
 
 
149
4) Start the Database and Load the Schema
 
150
 
 
151
4.1) MySQL
 
152
 
 
153
    CRUND's and TWS's schema file:
 
154
        ./src/tables_mysql.sql
 
155
        ./tws_benchmark/schema.sql
 
156
 
 
157
    Edit these configuration files if using the convenience scripts below:
 
158
        ./config.ini
 
159
        ./my.cnf
 
160
 
 
161
    Convenience scripts to start/stop the cluster or to load the schema:
 
162
        $ cd ./scripts
 
163
        $ ./start_cluster.sh
 
164
        $ ./restart_cluster.sh 
 
165
        $ ./load_shema.sh 
 
166
        $ ./stop_cluster.sh 
 
167
 
 
168
    By default, log and data files are written to:
 
169
        ./scripts/ndblog/mysqld.log.err
 
170
        ./scripts/ndblog/
 
171
 
 
172
4.2) Apache Derby (Optional)
 
173
 
 
174
    CRUND's database schema file:
 
175
        ./src/tables_derby.sql
 
176
 
 
177
    This Ant target loads the schema:
 
178
        $ ant load.schema.derby
 
179
 
 
180
    (Derby can be used in embedded or network server mode.)
 
181
 
 
182
 
 
183
5) Run CRUND
 
184
 
 
185
5.1) Configure a benchmark run
 
186
 
 
187
    Configure the benchmark's dataset size and number of iterations in
 
188
        ./crundRun.properties
 
189
 
 
190
    Edit any load-specific connection and run settings:
 
191
        ./crundNdbapi.properties
 
192
        ./crundNdbjtie.properties
 
193
        ./crundClusterj.properties
 
194
        ./crundMysql.properties
 
195
        ./crundOpenjpaMysql.properties
 
196
        ./crundNdbj.properties
 
197
        ./crundOpenjpaDerby.properties
 
198
        ./crundDerby.properties
 
199
 
 
200
5.2) Run the benchmark
 
201
 
 
202
    Run the benchmark's Java driver on the respective *Load classes:
 
203
        $ ant run.ndbapi
 
204
        $ ant run.ndbjtie
 
205
        $ ant run.clusterj
 
206
        $ ant run.mysql
 
207
        $ ant run.openjpa.mysql
 
208
        $ ant run.openjpa.clusterj
 
209
        $ ant run.ndbj
 
210
        $ ant run.derby
 
211
        $ ant run.openjpa.derby
 
212
 
 
213
    Or start the Load classes directly with run properties as arguments
 
214
    to the main() method:
 
215
        $ java -classpath=... com.mysql.cluster.crund.JdbcLoad \
 
216
                -p crundRun.properties \
 
217
                -p crundMysql.properties
 
218
 
 
219
    (Check for correct classpath/libpath printed by the run.* targets.)
 
220
 
 
221
5.3) Inspect the result files
 
222
 
 
223
    CRUND writes all measured time/memory values into a local log file:
 
224
        ./log_<dtate>_<time>.txt
 
225
 
 
226
    The data format is a tab-separated list, which can be easily imported
 
227
    into a spreadsheet application for further processing or charting.
 
228
 
 
229
5.4) Automate Benchmark runs
 
230
 
 
231
     Run the Java/C++ driver on a *Load class and save the log files:
 
232
        $ cd ./scripts
 
233
        $ ./mytest.sh
 
234
        $ ./mytestcxx.sh
 
235
 
 
236
     Runs the Java driver on multiple *Load classes:
 
237
        $ ./mytests.sh
 
238
 
 
239
 
 
240
Hints for troubleshooting:
 
241
 
 
242
- check the cluster's status
 
243
        $ ndb_mgm -e show
 
244
 
 
245
- create the database from the MySQL client tool
 
246
        $ mysql
 
247
        mysql> create database crunddb;
 
248
        mysql> show databases;
 
249
 
 
250
- if create fails fue to lack of privileges, login as root and grant
 
251
 
 
252
        $ mysql -u root
 
253
        mysql> grant all on *.* to <user name>@localhost;
 
254
        mysql> grant all on *.* to ''@localhost;
 
255
 
 
256
- load the schema script
 
257
 
 
258
        mysql> \. ./src/tables_mysql.sql
 
259
 
 
260
- check the database schema
 
261
 
 
262
        mysql> use database crunddb;
 
263
        mysql> show tables;
 
264
        mysql> explain B0;
 
265
        ...