Per pagespace I/O statistics and new trace API interfaces to allow extendable statistics (#8808)

* Add support of grouping page-level I/O counters per pagespace

* Add support for per-pagespace I/O statistics. Deprecate non-extendable PerformanceInfo struct in favor of the new PerformanceCounters/PerformanceStats interfaces. Adjust the trace implementation to the new API.

* Better names for interface methods. Add the basic docs. Get rid of the separate global counters. Misc renaming.

* Add the docs weirdly escaped from the last commit

* Follow Dimitry Sibiryakov's suggestion to unify get*Counters methods.

* Rename the method

Author: dyemanov

doc/Using_OO_API.md

@@ -2101,3 +2101,44 @@ struct FbVarChar
 
 This document is currently missing 2 types of plugins – ExternalEngine and Trace. Information about them will be made
 available in next release of it.
+
+# Trace plugin
+
+_TODO_
+
+# Trace objects
+
+_TODO_
+
+# Trace performance statistics
+
+Trace plugin may retrieve various performance statistics available using the `getPerfStats()` method of the trace object, which returns a pointer to the `IPerformanceStats` interface.
+
+```cpp
+IPerformanceStats* stats = statement->getPerfStats();
+```
+
+The returned pointer may be `nullptr` if the corresponding trace object is not in the terminate state yet (i.e. still active / being executed).
+
+<a name="PerformanceStats"></a> PerformanceStats interface:
+
+- ISC_UINT64 getElapsedTime() - returns the elapsed time, in milliseconds
+- ISC_UINT64 getFetchedRecords() - returns number of records fetched during execution
+- IPerformanceCounters* getCounters(unsigned group) - returns the requested performance counters group
+
+The following groups of performance counters are currently supported:
+
+- COUNTER_GROUP_PAGES - per-pagespace counters
+- COUNTER_GROUP_TABLES - per-table counters
+
+If `getCounters()` is called with a counter group not supported by the implementation, `nullptr` is returned.
+
+<a name="PerformanceCounters"></a> PerformanceCounters interface:
+
+- unsigned getObjectCount() - returns number of objects (e.g. tables) containing non-zero performance counters
+- unsigned getMaxCounterIndex() - returns maximum index number of the performance counters supported by the implementation (it's the same for all objects of the same group)
+- unsigned getObjectId(unsigned index) - returns ID of the specified object
+- const char* getObjectName(unsigned index) - returns name of the specified object
+- const ISC_INT64* getObjectCounters(unsigned index) - returns pointer to the vector of performance counters (containing getMaxCounterIndex() + 1 elements) of the specified object
+
+The returned pointer to the vector (as well as the whole instance of `PerformanceStats`) is valid until the object used to obtain the statistics (using the `getPerfStats()` method) is destroyed.

src/include/firebird/FirebirdInterface.idl

@@ -1364,6 +1364,9 @@ interface TraceTransaction : Versioned
 version: // 3.0.4 -> 3.0.5
 	int64 getInitialID();
 	int64 getPreviousID();
+
+version: // 5.0 -> 6.0
+	PerformanceStats getPerfStats();
 }
 
 interface TraceParams : Versioned
@@ -1379,6 +1382,9 @@ interface TraceStatement : Versioned
 {
 	int64 getStmtID();
 	PerformanceInfo* getPerf();
+
+version: // 5.0 -> 6.0
+	PerformanceStats getPerfStats();
 }
 
 interface TraceSQLStatement : TraceStatement
@@ -1421,6 +1427,9 @@ version: // 4.0 -> 5.0
 	int64 getStmtID();
 	const string getPlan();
 	const string getExplainedPlan();
+
+version: // 5.0 -> 6.0
+	PerformanceStats getPerfStats();
 }
 
 interface TraceFunction : Versioned
@@ -1434,6 +1443,9 @@ version: // 4.0 -> 5.0
 	int64 getStmtID();
 	const string getPlan();
 	const string getExplainedPlan();
+
+version: // 5.0 -> 6.0
+	PerformanceStats getPerfStats();
 }
 
 interface TraceTrigger : Versioned
@@ -1456,6 +1468,9 @@ version: // 4.0 -> 5.0
 	int64 getStmtID();
 	const string getPlan();
 	const string getExplainedPlan();
+
+version: // 5.0 -> 6.0
+	PerformanceStats getPerfStats();
 }
 
 interface TraceServiceConnection : TraceConnection
@@ -1480,6 +1495,9 @@ interface TraceSweepInfo : Versioned
 	int64 getOAT();
 	int64 getNext();
 	PerformanceInfo* getPerf();
+
+version: // 5.0 -> 6.0
+	PerformanceStats getPerfStats();
 }
 
 interface TraceLogWriter : ReferenceCounted
@@ -1876,3 +1894,50 @@ interface ProfilerStats : Versioned
 {
 	uint64 getElapsedTicks();
 }
+
+// Extendable replacement for struct PerformanceInfo
+
+interface PerformanceCounters : Versioned
+{
+	// Page-level performance counters (grouped per tablespace)
+	const uint PAGE_FETCHES = 0;
+	const uint PAGE_READS = 1;
+	const uint PAGE_MARKS = 2;
+	const uint PAGE_WRITES = 3;
+
+	// Record-level performance counters (grouped per table)
+	const uint RECORD_SEQ_READS = 0;
+	const uint RECORD_IDX_READS = 1;
+	const uint RECORD_UPDATES = 2;
+	const uint RECORD_INSERTS = 3;
+	const uint RECORD_DELETES = 4;
+	const uint RECORD_BACKOUTS = 5;
+	const uint RECORD_PURGES = 6;
+	const uint RECORD_EXPUNGES = 7;
+	const uint RECORD_LOCKS = 8;
+	const uint RECORD_WAITS = 9;
+	const uint RECORD_CONFLICTS = 10;
+	const uint RECORD_BACK_READS = 11;
+	const uint RECORD_FRAGMENT_READS = 12;
+	const uint RECORD_RPT_READS = 13;
+	const uint RECORD_IMGC = 14;
+
+	uint getObjectCount();
+	uint getMaxCounterIndex();
+
+	uint getObjectId(uint index);
+	const string getObjectName(uint index);
+	const int64* getObjectCounters(uint index);
+}
+
+interface PerformanceStats : Versioned
+{
+	const uint COUNTER_GROUP_PAGES = 0;
+	const uint COUNTER_GROUP_TABLES = 1;
+
+	uint64 getElapsedTime();	// in milliseconds
+	uint64 getFetchedRecords();
+
+	PerformanceCounters getCounters(uint group);
+}
+