Отчёт о ходе выполнения

MariaDB поддерживает отчёт о ходе выполнения для некоторых длительных команд.

Что такое отчёт о ходе выполнения?

Отчёт о ходе выполнения означает, что:

• В столбце Progress запроса SHOW PROCESSLIST отображается общий прогресс (0-100%)
• INFORMATION_SCHEMA.PROCESSLIST содержит три столбца, которые позволяют увидеть, на какой стадии процесса мы находимся и сколько этой стадии завершено:
  • STAGE
  • MAX_STAGE
  • PROGRESS (в рамках текущей стадии).
• Клиент получает сообщения о ходе выполнения, которые он может отобразить пользователю, чтобы указать, сколько времени займёт выполнение команды.

У нас отдельный отчёт о ходе выполнения для каждой стадии, так как разные стадии занимают разное время.

Поддерживаемые команды

В настоящее время следующие команды могут отправлять сообщения о ходе выполнения клиенту:

• ALTER TABLE
• CREATE INDEX
• DROP INDEX
• LOAD DATA INFILE (не LOAD DATA LOCAL INFILE, так как в этом случае мы не знаем размер файла).

Некоторые операции движка хранения Aria также поддерживают сообщения о ходе выполнения:

• CHECK TABLE
• REPAIR TABLE
• ANALYZE TABLE
• OPTIMIZE TABLE

Ограничения

Хотя вышеперечисленные команды поддерживают отчёт о ходе выполнения, существуют некоторые ограничения на то, какой прогресс сообщается. А именно, при выполнении одной из этих команд над таблицей InnoDB с ALGORITHM=INPLACE (что является значением по умолчанию в MariaDB 10.0+), прогресс сообщается только во время фазы сортировки слиянием при восстановлении индексов.

Включение и отключение отчёта о ходе выполнения

mysqld (сервер MariaDB) автоматически отправляет сообщения о ходе выполнения клиентам, которые поддерживают новый протокол, используя значение переменной progress_report_time. Они отправляются каждые max(global.progress_report_time , progress_report_time) секунды (по умолчанию 5). Вы можете отключить отправку сообщений о ходе выполнения клиенту, установив либо локальную переменную (влияет только на текущее подключение), либо глобальную переменную (влияет на все подключения) в значение 0.

Если дополнительный столбец в SHOW PROCESSLIST вызывает проблемы совместимости, вы можете отключить его, запустив mysqld со флагом --old.

Клиенты, которые поддерживают отчёт о ходе выполнения

• Клиентская программа командной строки mariadb
• Входящий в состав MariaDB mytop имеет столбец '%' для отображения прогресса.

Отчёт о ходе выполнения в клиенте командной строки mysql

Отчёт о ходе выполнения по умолчанию включён в клиенте mariadb. Вы можете отключить его с помощью --disable-progress-reports. Он автоматически отключается в пакетном режиме.

При включении для каждой поддерживаемой команды вы получаете отчёт о ходе выполнения, например:

ALTER TABLE my_mail ENGINE=aria;
Stage: 1 of 2 'copy to tmp table'  5.37% of stage done

Он обновляется каждые progress_report_time секунд (по умолчанию 5). Если глобальная переменная progress_report_time выше, то будет использоваться это значение. Также вы можете отключить отчёт об ошибках, установив переменную в 0.

Как добавить поддержку отчёта о ходе выполнения в клиент

Вам нужна клиентская библиотека MariaDB 5.3 или более поздней версии. Вы можете проверить, поддерживает ли библиотека отчёт о ходе выполнения, выполнив:

#ifdef CLIENT_PROGRESS

Для включения отчёта о ходе выполнения в клиенте вам нужно добавить CLIENT_PROGRESS в connect_flag в mysql_real_connect():

mysql_real_connect(mysql, host, user, password,
                   database, opt_mysql_port, opt_mysql_unix_port,
                   connect_flag | CLIENT_PROGRESS);

Затем вам необходимо предоставить функцию обратного вызова для сообщений о ходе выполнения:

static void report_progress(const MYSQL *mysql, uint stage, uint max_stage,
                            double progress, const char *proc_info,
                            uint proc_info_length);

mysql_options(&mysql, MYSQL_PROGRESS_CALLBACK, (void*) report_progress);

Функция report_progress выше будет вызываться для каждого сообщения о ходе выполнения.

Вот реализация, используемая в mysql.cc:

uint last_progress_report_length;

static void report_progress(const MYSQL *mysql, uint stage, uint max_stage,
                            double progress, const char *proc_info,
                            uint proc_info_length)
{
  uint length= printf("Stage: %d of %d '%.*s' %6.3g%% of stage done",
                      stage, max_stage, proc_info_length, proc_info, 
                      progress);
  if (length < last_progress_report_length)
    printf("%*s", last_progress_report_length - length, "");
  putc('\r', stdout);
  fflush(stdout);
  last_progress_report_length= length;
}

Если вам нужно только одно число для общего прогресса, вы можете вычислить его следующим образом:

double total_progress=
 ((stage -1) / (double) max_stage * 100.00 + progress / max_stage);

Как добавить поддержку отчёта о ходе выполнения в движок хранения

Функции для использования в отчёте о ходе выполнения:

void thd_progress_init(MYSQL_THD thd, unsigned int max_stage);

Инициализация отчёта о ходе выполнения со стадиями. Это в основном используется для команд, которые полностью выполняются внутри движка, например, CHECK TABLE. Не используйте это для операций, которые могут вызываться, например, ALTER TABLE, поскольку эта функция уже была вызвана.

max_stage — количество стадий, которые будет иметь ваш движок хранения.

void thd_progress_report(MYSQL_THD thd, unsigned long long progress,
                         unsigned long long max_progress);

Вышеупомянутое используется для отчёта о ходе выполнения.

• progress — сколько из файлов/строк/ключей вы уже обработавли.
• max_progress — максимальное количество строк, которые вы будете обрабатывать.

Вы можете вызывать эту функцию с различными значениями, но, как правило, отношение progress/max_progress должно увеличиваться.

Эту функцию можно вызывать даже если вы не используете стадии, например, при включении ключей в рамках ALTER TABLE или ADD INDEX.

void thd_progress_next_stage(MYSQL_THD thd);

Переход к следующей стадии в многоэтапном процессе, инициированном thd_progress_init():

void thd_progress_end(MYSQL_THD thd);

Завершение отчёта о ходе выполнения; устанавливает 'Progress' обратно в 0 в SHOW PROCESSLIST.

const char *thd_proc_info(thd, 'stage name');

Это устанавливает имя текущего статуса/стадии, которое отображается в SHOW PROCESSLIST и в клиенте. Рекомендуется вызывать эту функцию между стадиями, а также перед thd_progress_report() и thd_progress_next_stage().

Эта функция возвращает последнюю использованную proc_info. Рекомендуется восстановить proc_info до исходного значения по завершении обработки.

Примеры, которые можно посмотреть в исходном коде MariaDB:

• client/mysql.cc для примера использования отчёта.
• libmysql/client.c:cli_safe_read() для того, как обрабатываются пакеты прогресса в клиенте
• sql/protocol.cc::net_send_progress_packet() для обработки пакетов прогресса на сервере.

Формат пакетов отчёта о ходе выполнения

Пакет прогресса отправляется как пакет ошибки с номером ошибки 65535.

Он содержит следующие данные (в дополнение к заголовку ошибки):

См. также

• Что такое MariaDB 5.3