This is the very first post in the series of Performance Schema Implementation Internals. This series is for MySQL Developers to understand implementation of Performance Schema. For user point of view of performance Schema, please refer to mysql documentation link : http://dev.mysql.com/doc/refman/5.7/en/performance-schema-quick-start.html

This post talks about the mechanism to register instruments in Performance Schema (referred as P_S from hereon) so that their statistics could be collected at runtime.

To understand this, lets first understand different instrument classes in P_S.

Instrument Classes in P_S:

An enum PFS_class_type is there to keep track of all possible classes of instruments.

enum PFS_class_type
{
PFS_CLASS_NONE= 0,
PFS_CLASS_MUTEX= 1,
PFS_CLASS_RWLOCK= 2,
PFS_CLASS_COND= 3,
PFS_CLASS_FILE= 4,
PFS_CLASS_TABLE= 5,
PFS_CLASS_STAGE= 6,
PFS_CLASS_STATEMENT= 7,
…
};

For eg. here PFS_CLASS_STATEMENT is type of a class which is used for all statement related instruments (eg. statement/sql/select, statement/sql/insert etc.).

Now there is a base class PFS_instr_class from which all other instrument classes are derived. Following figure shows the relationship.

Each instrument in P_S is instantiated with one of the above class.

For every set of instruments (Stages, Waits, Statements etc.) we maintain arrays which we name as class array. An array of this kind keeps records of all the instruments in that particular class and their configurations (i.e. name, enabled, timed etc.).

For example:
PFS_mutex_class *mutex_class_array : to hold information of all mutex instruments.
PFS_statement_class *statement_class_array : to hold information of all statement instruments.

During initialization of P_S, memory is allocated to these arrays based on their sizing values eg. mutex_class_max, statement_class_max. Default values of these sizing are set internally, but user can also specify them while starting MySQL server. If user specify a sizing value less then the number of instruments available in that specific class, few instruments of that class won’t be registered to be tracked. These lost instrument information can be seen in “show status command as follow”.

mysql> show status like “%performance%”;
+——————————————————-+——-+
| Variable_name | Value |
+——————————————————-+——-+
| Performance_schema_cond_classes_lost | 0 |
| Performance_schema_file_classes_lost      | 0 |
…

Instrument Class Array

Now, lets see how does an array of an instrument class look like and what does each element represent in that array.

Above figure shows statement_class_array. Each element of this array represent an instrument (statement/sql/select in this case) and contains information about that instrument. In this case, select instrument is enabled and it is to be timed as well. This m_enabled/m_timed could also be seen for instruments (statement/sql/select in this case) on the fly when MySQL server is running with P_S.

Similarly there are arrays for other class types as well and each element of those arrays represents an instrument of its respective class.

Registering Instruments:

As it might have been obvious by now that this is the array which P_S use during execution to find out information of instruments. So it is necessary for each instrument (which we intend to instrument) should be in one of these array i.e. should be registered.

Lets see how do we register instruments (i.e. keep their information in the class array). Here I took example of statement instruments.

Hold on!!
Before that lets understand one more structure. I call it info structure.

struct PSI_statement_info_v1
{
/** The registered statement key. */
PSI_statement_key m_key;
/** The name of the statement instrument to register. */
const char *m_name;
/** The flags of the statement instrument to register. */
int m_flags;
};

This is a structure which keeps “where to look” information (m_key) of an instrument which would be used at run time to get other information about that instrument.
m_name : keeps the name of the instrument to be registered ( say select)
m_key : is an index in the statement_class_array where the information of this
instrument is stored.
m_flags: flag for that instrument.

Similar to PSI_statement_info_v1, there are info structure for other classes as well like PSI_stage_info_v1, PSI_mutex_info_v1 etc.

An array, sql_statement_info, is made of this structure and each element of array represent a statement instrument of SQL Statement. Information (m_name) in this array is filled up by function init_sql_statement_info() which does nothing but populate m_name from all possible sql statements in MySQL and reset flags to ‘0’.

Still with me?

Now we have sql_statement_info populated but its still not linked to statement_class_array. To do that, a call to mysql_statement_register() is made with this sql_statement_info array.

This function, mysql_statement_register() which finally maps to pfs_statement_register_v1() (pfs.cc) does following:

1. for all elements in sql_statement_info
   1. make a formatted string to be stored for instrument name (eg. statement/sql/select)
   2. call register_statement_class(), which would stores information of this instrument in statement_class_array and return its index.
   3. store this index into m_key.

Now lets see what function register_statement_class() does.

1. call REGISTER_CLASS_BODY_PART to see if this instrument already registered. If yes, then return that index.
2. search for first empty index in statement_class_array and populate information by calling init_instr_class().
3. populate event_name_index with index.
4. call configure_instr_class(), to set the user specified values (if any).
5. return index+1 to be stored in m_key.

Thats it !!! Its done.

Now for a particular instrument in sql_statement_info, this m_key is populated with the index in statement_class_array where information about this instrument is stored. During execution, P_S use this m_key to see the information of that instrument in statement_class_array.
This entire flow could be depicted from following figure:

Similarly registration mechanism exists for all the instruments available in P_S. Once registered, instruments become ready to be collected statistics for, in P_S.

Performance Schema Implementation Internals : To be continued …