29.12.2.3 The setup_instruments Table

The setup_instruments table lists classes of instrumented objects for which events can be collected:

mysql> SELECT * FROM performance_schema.setup_instruments\G
*************************** 1. row ***************************
         NAME: wait/synch/mutex/pfs/LOCK_pfs_share_list
      ENABLED: NO
        TIMED: NO
   PROPERTIES: singleton
        FLAGS: NULL
   VOLATILITY: 1
DOCUMENTATION: Components can provide their own performance_schema tables. 
This lock protects the list of such tables definitions.
...
*************************** 410. row ***************************
         NAME: stage/sql/executing
      ENABLED: NO
        TIMED: NO
   PROPERTIES:
        FLAGS: NULL
   VOLATILITY: 0
DOCUMENTATION: NULL
...
*************************** 733. row ***************************
         NAME: statement/abstract/Query
      ENABLED: YES
        TIMED: YES
   PROPERTIES: mutable
        FLAGS: NULL
   VOLATILITY: 0
DOCUMENTATION: SQL query just received from the network. 
At this point, the real statement type is unknown, the type 
will be refined after SQL parsing.
...
*************************** 737. row ***************************
         NAME: memory/performance_schema/mutex_instances
      ENABLED: YES
        TIMED: NULL
   PROPERTIES: global_statistics
        FLAGS:
   VOLATILITY: 1
DOCUMENTATION: Memory used for table performance_schema.mutex_instances
...
*************************** 823. row ***************************
         NAME: memory/sql/Prepared_statement::infrastructure
      ENABLED: YES
        TIMED: NULL
   PROPERTIES: controlled_by_default
        FLAGS: controlled
   VOLATILITY: 0
DOCUMENTATION: Map infrastructure for prepared statements per session.
...

Each instrument added to the source code provides a row for the setup_instruments table, even when the instrumented code is not executed. When an instrument is enabled and executed, instrumented instances are created, which are visible in the xxx_instances tables, such as file_instances or rwlock_instances.

Modifications to most setup_instruments rows affect monitoring immediately. For some instruments, modifications are effective only at server startup; changing them at runtime has no effect. This affects primarily mutexes, conditions, and rwlocks in the server, although there may be other instruments for which this is true.

For more information about the role of the setup_instruments table in event filtering, see Section 29.4.3, “Event Pre-Filtering”.

The setup_instruments table has these columns:

• NAME

  The instrument name. Instrument names may have multiple parts and form a hierarchy, as discussed in Section 29.6, “Performance Schema Instrument Naming Conventions”. Events produced from execution of an instrument have an EVENT_NAME value that is taken from the instrument NAME value. (Events do not really have a “name,” but this provides a way to associate events with instruments.)

• ENABLED

  Whether the instrument is enabled. The value is YES or NO. A disabled instrument produces no events. This column can be modified, although setting ENABLED has no effect for instruments that have already been created.

• TIMED

  Whether the instrument is timed. The value is YES, NO, or NULL. This column can be modified, although setting TIMED has no effect for instruments that have already been created.

  A TIMED value of NULL indicates that the instrument does not support timing. For example, memory operations are not timed, so their TIMED column is NULL.

  Setting TIMED to NULL for an instrument that supports timing has no effect, as does setting TIMED to non-NULL for an instrument that does not support timing.

  If an enabled instrument is not timed, the instrument code is enabled, but the timer is not. Events produced by the instrument have NULL for the TIMER_START, TIMER_END, and TIMER_WAIT timer values. This in turn causes those values to be ignored when calculating the sum, minimum, maximum, and average time values in summary tables.

• PROPERTIES

  The instrument properties. This column uses the SET data type, so multiple flags from the following list can be set per instrument:

  • controlled_by_default: memory is collected by default for this instrument.

  • global_statistics: The instrument produces only global summaries. Summaries for finer levels are unavailable, such as per thread, account, user, or host. For example, most memory instruments produce only global summaries.

  • mutable: The instrument can “mutate” into a more specific one. This property applies only to statement instruments.

  • progress: The instrument is capable of reporting progress data. This property applies only to stage instruments.

  • singleton: The instrument has a single instance. For example, most global mutex locks in the server are singletons, so the corresponding instruments are as well.

  • user: The instrument is directly related to user workload (as opposed to system workload). One such instrument is wait/io/socket/sql/client_connection.

• FLAGS

  Whether the instrument's memory is controlled.

  This flag is supported for non-global memory instruments, only, and can be set or unset. For example:

                SQL> UPDATE PERFORMANCE_SCHEMA.SETUP_INTRUMENTS SET FLAGS="controlled" WHERE NAME='memory/sql/NET::buff';

  Note

  Attempting to set FLAGS = controlled on non-memory instruments, or on global memory instruments, fails silently.

• VOLATILITY

  The instrument volatility. Volatility values range from low to high. The values correspond to the PSI_VOLATILITY_xxx constants defined in the mysql/psi/psi_base.h header file:

  #define PSI_VOLATILITY_UNKNOWN 0
  #define PSI_VOLATILITY_PERMANENT 1
  #define PSI_VOLATILITY_PROVISIONING 2
  #define PSI_VOLATILITY_DDL 3
  #define PSI_VOLATILITY_CACHE 4
  #define PSI_VOLATILITY_SESSION 5
  #define PSI_VOLATILITY_TRANSACTION 6
  #define PSI_VOLATILITY_QUERY 7
  #define PSI_VOLATILITY_INTRA_QUERY 8

  The VOLATILITY column is purely informational, to provide users (and the Performance Schema code) some hint about the instrument runtime behavior.

  Instruments with a low volatility index (PERMANENT = 1) are created once at server startup, and never destroyed or re-created during normal server operation. They are destroyed only during server shutdown.

  For example, the wait/synch/mutex/pfs/LOCK_pfs_share_list mutex is defined with a volatility of 1, which means it is created once. Possible overhead from the instrumentation itself (namely, mutex initialization) has no effect for this instrument then. Runtime overhead occurs only when locking or unlocking the mutex.

  Instruments with a higher volatility index (for example, SESSION = 5) are created and destroyed for every user session. For example, the wait/synch/mutex/sql/THD::LOCK_query_plan mutex is created each time a session connects, and destroyed when the session disconnects.

  This mutex is more sensitive to Performance Schema overhead, because overhead comes not only from the lock and unlock instrumentation, but also from mutex create and destroy instrumentation, which is executed more often.

  Another aspect of volatility concerns whether and when an update to the ENABLED column actually has some effect:

  • An update to ENABLED affects instrumented objects created subsequently, but has no effect on instruments already created.

  • Instruments that are more “volatile” use new settings from the setup_instruments table sooner.

  For example, this statement does not affect the LOCK_query_plan mutex for existing sessions, but does have an effect on new sessions created subsequent to the update:

  UPDATE performance_schema.setup_instruments
  SET ENABLED=value
  WHERE NAME = 'wait/synch/mutex/sql/THD::LOCK_query_plan';

  This statement actually has no effect at all:

  UPDATE performance_schema.setup_instruments
  SET ENABLED=value
  WHERE NAME = 'wait/synch/mutex/pfs/LOCK_pfs_share_list';

  This mutex is permanent, and was created already before the update is executed. The mutex is never created again, so the ENABLED value in setup_instruments is never used. To enable or disable this mutex, use the mutex_instances table instead.

• DOCUMENTATION

  A string describing the instrument purpose. The value is NULL if no description is available.

The setup_instruments table has these indexes:

• Primary key on (NAME)

TRUNCATE TABLE is not permitted for the setup_instruments table.

To assist monitoring and troubleshooting, the Performance Schema instrumentation is used to export names of instrumented threads to the operating system. This enables utilities that display thread names, such as debuggers and the Unix ps command, to display distinct mysqld thread names rather than “mysqld”. This feature is supported only on Linux, macOS, and Windows.

Suppose that mysqld is running on a system that has a version of ps that supports this invocation syntax:

ps -C mysqld H -o "pid tid cmd comm"

Without export of thread names to the operating system, the command displays output like this, where most COMMAND values are mysqld:

  PID   TID CMD                         COMMAND
 1377  1377 /usr/sbin/mysqld            mysqld
 1377  1528 /usr/sbin/mysqld            mysqld
 1377  1529 /usr/sbin/mysqld            mysqld
 1377  1530 /usr/sbin/mysqld            mysqld
 1377  1531 /usr/sbin/mysqld            mysqld
 1377  1534 /usr/sbin/mysqld            mysqld
 1377  1535 /usr/sbin/mysqld            mysqld
 1377  1588 /usr/sbin/mysqld            xpl_worker1
 1377  1589 /usr/sbin/mysqld            xpl_worker0
 1377  1590 /usr/sbin/mysqld            mysqld
 1377  1594 /usr/sbin/mysqld            mysqld
 1377  1595 /usr/sbin/mysqld            mysqld

With export of thread names to the operating system, the output looks like this, with threads having a name similar to their instrument name:

  PID   TID CMD                         COMMAND
27668 27668 /usr/sbin/mysqld            mysqld
27668 27671 /usr/sbin/mysqld            ib_io_ibuf
27668 27672 /usr/sbin/mysqld            ib_io_log
27668 27673 /usr/sbin/mysqld            ib_io_rd-1
27668 27674 /usr/sbin/mysqld            ib_io_rd-2
27668 27677 /usr/sbin/mysqld            ib_io_wr-1
27668 27678 /usr/sbin/mysqld            ib_io_wr-2
27668 27699 /usr/sbin/mysqld            xpl_worker-2
27668 27700 /usr/sbin/mysqld            xpl_accept-1
27668 27710 /usr/sbin/mysqld            evt_sched
27668 27711 /usr/sbin/mysqld            sig_handler
27668 27933 /usr/sbin/mysqld            connection

Different thread instances within the same class are numbered to provide distinct names where that is feasible. Due to constraints on name lengths with respect to potentially large numbers of connections, connections are named simply connection.