DOC: added information on performance schema

doc/devel/Benchmarking.md

@@ -7,6 +7,20 @@ Java code, how much time is spent inside the SQL backend, are the same costly me
 than once?  This documentation tries to answer some questions connected with these benchmarking
 aspects and give you the tools to answer your own questions.
 
+
+## Before you start ##
+In order to obtain meaningful results, you should disable caching.
+
+### MariaDB
+Set the corresponding variable to 0: `SET GLOBAL query_cache_type = 0;`
+
+### Java Server
+In the config:
+```conf
+CACHE_DISABLE=true
+```
+
+
 ## Tools for the benchmarking ##
 
 For averaging over many runs of comparable requests and for putting the database into a
@@ -45,25 +59,8 @@ enabled on start up.
 This script expects the MariaDB server to be accessible on 127.0.0.1 with the default caosdb user
 and password (caosdb;random1234).
 
-#### Preparing docker setup for this:
-Change the docker-compose file to include the following for the mariadb service:
-```
-    networks:
-      # available on port 3306, host name 'sqldb'
-      - caosnet
-    ports:
-      - 3306:3306
-```
-Check it with `mysql -ucaosdb -prandom1234 -h127.0.0.1 caosdb`
-Set the schema to `ON` in `profiles/empty/custom/mariadb.conf.d/mariadb.cnf` or in the profile that you use.
-The `performance_schema` setting in the MariaDB server must be enabled, for example by setting
-this in the config files:
-```
-[mysqld]
 
-performance_schema=ON
-```
-Start the server.
+The performance schema must be enabled (see below).
 
 ### MariaDB General Query Log ###
 
@@ -89,6 +86,67 @@ See [slow query log docs](https://mariadb.com/kb/en/slow-query-log-overview/)
 ### MariaDB Performance Schema ###
 The most detailed information on execution times can be acquired using the performance schema.
 
+To use it, the `performance_schema` setting in the MariaDB server must be enabled([docs](https://mariadb.com/kb/en/performance-schema-overview/#enabling-the-performance-schema), for example by setting
+this in the config files:
+```
+[mysqld]
+
+performance_schema=ON
+```
+
+The performance schema provides many different tables in the `performance_schema`. You can instruct MariaDB to create
+those tables by setting the appropriate `instrument` and `consumer` variables. E.g. 
+```SQL
+update performance_schema.setup_instruments set enabled='YES', timed='YES' WHERE NAME LIKE '%statement%';
+update performance_schema.setup_consumers set enabled='YES' WHERE NAME LIKE '%statement%';
+```
+This can also be done via the configuration. 
+```
+[mysqld]
+
+performance_schema=ON
+performance-schema-instrument='statement/%=ON'
+performance-schema-consumer-events-statements-history=ON                        
+performance-schema-consumer-events-statements-history-long=ON
+```
+You may want to look at the result of the following commands:
+```sql
+
+select * from performance_schema.setup_consumers;
+select * from performance_schema.setup_instruments;
+```
+
+Note, that the `base_settings.sql` enables appropriate instruments and consumers.
+
+Before you start a measurement, you will want to empty the tables. E.g.:
+```sql
+truncate table  performance_schema.events_statements_history_long ;
+```
+The procedure `reset_stats` in `base_settings.sql` clears the typically used ones.
+
+The tables contain many columns. An example to get an informative view is
+```sql
+select left(sql_text,50), left(digest_text,50), ms(timer_wait) from performance_schema.events_statements_history_long order by ms(timer_wait);
+```
+where the function `ms` is defined in `base_settings.sql`.
+Or a very useful one:
+```sql
+select  left(digest_text,100) as digest,ms(sum_timer_wait) as time_ms, count_star from performance_schema.events_statements_summary_by_digest order by time_ms;
+```
+
+### Useful SQL configuration with docker
+In order to allow easy testing and debugging the following is useful when using docker.
+Change the docker-compose file to include the following for the mariadb service:
+```
+    networks:
+      # available on port 3306, host name 'sqldb'
+      - caosnet
+    ports:
+      - 3306:3306
+```
+Check it with `mysql -ucaosdb -prandom1234 -h127.0.0.1 caosdb`
+Add the appropriate changes (e.g. `performance_schema=ON`) to `profiles/empty/custom/mariadb.conf.d/mariadb.cnf` (or in the profile folder that you use).
+
 ### Manual Java-side benchmarking #
 
 Benchmarking can be done using the `TransactionBenchmark` class (in package