12.9.2 collectHighLoadDiagnostics Utility

About the Utility

util.debug.collectHighLoadDiagnostics() runs multiple iterations of diagnostic reporting on your MySQL server, enabling you to analyze multiple aspects of your server while under load.

The High Load diagnostic report is generated as a zip file to either the local directory or a specified path.

The utility generates files in both TSV and YAML format.

Requirements and Restrictions

The following requirements apply to exports using the diagnostics collection utility:

MySQL 5.7 or later is required.
The utility must be run as root.

Running the Utility

The diagnostics utility has the following signature:

  
  util.debug.collectHighLoadDiagnostics(path, {options})

The following example writes the zip file to the user's temp directory, performs 5 iterations of collection, and enables all Performance Schema instruments and consumers:

      
      util.debug.collectHighLoadDiagnostics("/home/userName/temp/highLoad.zip", {iterations: 5, pfsInstrumentation: "full"})

Note

The data returned by this utility also includes data collected by util.debug.collectDiagnostics().

Options for Collecting High Load Diagnostics

iterations: number

Default is 2. Number of iterations of high load diagnostic data collection.

delay: number

Default is 300 seconds. Number of seconds between iterations of high load diagnostic data collection.

innodbMutex: [true | false]

Default is false. If set to true, the output of SHOW ENGINE INNODB MUTEX is collected.

Note

This parameter can affect performance.

pfsInstrumentation: [current | medium | full]

Default is current. Defines which Performance Schema instruments and consumers are used. Possible values are:

current: The currently enabled Performance Schema instruments and consumers. No changes are made to your server's configuration.
medium: Enables all consumers except %history and %history_long, and all instruments except wait/synch/%.
full: Enables all consumers and all instruments.

customSql: array

One or more SQL statements to run. You can control when the statements are run with the following prefixes:

PRE: Default. The statement is run once, before the metrics collection iterations begin.
POST: The statement is run once, after the metrics collection iterations complete.
ITER: The statement is run once for each iteration of the metrics collection.

For example:

            {"customSql": ["statement1", "statement2", "statement3"]}

customShell array

One or more Shell commands to run. You can control when the commands are run with the following prefixes:

BEFORE: Default. The statement is run once, before the metrics collection iterations begin.
DURING: The statement is run once for each iteration of the metrics collection.
AFTER: The statement is run once, after the metrics collection iterations complete.

For example:

            {"customShell": ["command1", "command2", "command3"]}

Important

These commands run with the privileges of the user running MySQL Shell and should be used with caution.