1.8.1.3 Как отправлять отчеты об ошибках или проблемах

Чтобы написать хороший отчет об ошибке, потребуется немало терпения. Однако лучше сделать все правильно с первой попытки - это сбережет и ваше, и наше время. Грамотно составленный отчет об ошибке, содержащий ее подробное описание, позволит нам исправить эту ошибку уже в следующей версии программы. Включенные в данный раздел рекомендации помогут вам правильно написать свой отчет, не тратя времени на описание того, что мало чем сможет нам помочь или не потребуется вовсе.

Мы рекомендуем для создания отчетов об ошибках (или отчетов о любых проблемах), всегда, если это возможно, использовать сценарий mysqlbug. mysqlbug можно найти в каталоге `scripts' раздела распространения исходных текстов, или в разделе распространения исполняемых программ, в каталоге `bin' инсталляционного каталога MySQL. Если же не удается воспользоваться mysqlbug, то все равно необходимо указать в своем отчете все данные, перечисленные ниже в этом разделе.

Сценарий mysqlbug помогает сгенерировать отчет путем автоматического определения большей части приведенной ниже информации, но если окажется, что в сгенерированном отчете отсутствует что-либо важное, обязательно включите это в свое сообщение! Внимательно прочитайте данный раздел и убедитесь, что в отчет вошли все описанные здесь сведения.

Обычно отчеты об ошибках и проблемах направляются в mysql@lists.mysql.com. Если же вы можете создать подробное описание, четко определяющее ошибку, его можно направить в список рассылки bugs@lists.mysql.com. Обратите внимание: в этот список рассылки можно посылать только полный отчет о повторяющейся ошибке, составленный при помощи сценария mysqlbug. Если вы работаете в Windows, необходимо включить описание операционной системы и версии MySQL. Прежде чем направлять отчет, желательно проверить, проявляется ли данная проблема при использовании последней окончательной или находящейся в стадии разработки версии MySQL! Чтобы любой желающий мог воспроизвести эту ошибку, желательно также включить в отчет контрольный тестовый пример, который можно было бы запустить при помощи ``mysql test < script'', либо Perl-сценарий или сценарий оболочки, которые можно запустить непосредственно. Все ошибки, сообщения о которых будут направлены в список рассылки, будут либо исправлены, либо включены в список ошибок в следующей версии MySQL! Если необходимо только небольшое изменение кода, мы также отправим исправляющий эту ошибку патч для программы.

Если вы нашли ошибку в системе безопасности MySQL, необходимо отправить сообщение по адресу security@mysql.com.

Не забывайте о том, что можно ответить на сообщение, в котором содержится слишком много информации, но нельзя ответить на сообщение, в котором информации недостаточно. Часто те, кто нам пишет, опускают некоторые факты: они считают, что им известна причина возникшей проблемы и поэтому, по их мнению, некоторые детали не имеют значения. Необходимо придерживаться следующего принципа: если возникают сомнения в отношении того, следует или нет приводить в отчете те или иные сведения, - включите их в отчет обязательно! Намного быстрее и проще написать несколько дополнительных строк в отчете, чем получать уточняющие вопросы и снова ждать ответа только потому, что в первый раз были указаны не все данные.

Чаще всего наши корреспонденты не указывают используемую версию MySQL или платформу, на которой установлен сервер MySQL (включая версию платформы). Это довольно существенная информация, и в 99 случаях из 100 отчет об ошибке без нее будет совершенно бесполезным! Очень часто бывает и так: мы получаем вопрос типа: ''Почему это у меня не работает?'', а потом оказывается, что указанная функция в данной версии MySQL отсутствует или что ошибка, описанная в отчете, уже была исправлена в более новой версии MySQL. Иногда ошибка зависит от используемой платформы. В таких случаях практически невозможно ничего исправить, не имея информации об операционной системе и о версии платформы.

Не забывайте указывать информацию о своем компиляторе - в тех случаях, когда это имеет отношение к возникшей проблеме. Ведь бывает и так: пользователь полагает, что проблема связана с MySQL, а на самом деле он нашел ошибку в компиляторе. Большинство компиляторов постоянно находятся в состоянии разработки и становятся лучше от версии к версии. Чтобы определить, зависит ли ваша проблема от компилятора, мы должны знать, какой именно используется компилятор. Обратите внимание на то, что все проблемы с компиляторами должны рассматриваться как ошибки и по ним должен составляться соответствующий отчет.

Вы окажете нам значительную помощь, включив в отчет об ошибке подробное описание проблемы. В качестве хорошего примера подобной информации можно привести описание всех действий, которые привели к возникновению проблемы и описание самой проблемы. Лучшие отчеты содержат подробные примеры, в которых показано, как можно воспроизвести ошибку или проблему. section E.1.6 Создание контрольного примера при повреждении таблиц.

Если программа выдает сообщение об ошибке, очень важно точно воспроизвести это сообщение в своем отчете! Возможно, нам придется производить поиск в архивах - лучше, чтобы указанное в отчете сообщение об ошибке точно совпадало с тем, которое выдает программа. Не следует пытаться запомнить сообщение об ошибке, имеет смысл просто скопировать его полностью и вставить в отчет!

Если возникли проблемы с MyODBC, необходимо попытаться создать файл трассировки MyODBC. See section 8.3.7 Составление отчетов о проблемах с MyODBC.

Не забывайте, что у большинства людей, которые будут читать ваш отчет, экраны дисплеев имеют ширину в 80 символов. При создании отчетов или примеров при помощи средств командной строки mysql необходимо использовать параметр --vertical (или терминатор оператора \G) для выходных данных, которые будут превышать ширину для таких дисплеев (пример для оператора EXPLAIN SELECT приведен ниже в данном разделе).

В свой отчет вам необходимо включить следующую информацию:

• Версию используемого дистрибутива MySQL (например MySQL Version 3.22.22). Чтобы узнать, какая версия запущена, следует выполнить команду mysqladmin version. Программу mysqladmin можно найти в каталоге `bin' инсталляционного каталога MySQL.
• Производителя и модель компьютера, на котором вы работаете.
• Название и версию операционной системы. Для большинства операционных систем эту информацию можно получить, выполнив команду Unix uname -a.
• Иногда важную роль играет количество памяти (реальной и виртуальной). Если у вас есть основания считать, что такая информация может оказаться полезной, включите в отчет эти значения.
• Если используется дистрибутив в виде исходных текстов программного обеспечения MySQL, необходимо указать версию используемого компилятора. Если используется бинарный дистрибутив, необходимо указать имя дистрибутива.
• Если проблема возникает во время компиляции, включите в отчет точное сообщение об ошибке (или ошибках), а также несколько строк до и после вызывающего ошибку кода в файле, вызвавшем проблему.
• Если произошло аварийное завершение работы mysqld, необходимо сообщить о запросе, который привел к такому завершению. Это можно выяснить, запустив mysqld с включенной функцией ведения журнала. See section E.1.5 Использование журналов для определения причин ошибок в mysqld.
• Если с программой связана какая-либо таблица базы данных, включите в отчет выходную информацию команды mysqldump --no-data db_name tbl_name1 tbl_name2 .... Выполняется это очень легко. Таким способом можно получить подробную информацию о таблице в базе данных, что поможет нам создать ситуацию, соответствующую той, в которой оказались вы.
• Для ошибок, связанных со скоростью выполнения или проблемами с операторами SELECT, всегда необходимо включать в отчет выходную информацию команды EXPLAIN SELECT ... и, по крайней мере, количество строк, которые выдает оператор SELECT. Вы также должны включить вывода SHOW CREATE TABLE ... для каждой таблицы, задействованной в запросе. Чем больше информации будет предоставлено о сложившейся ситуации, тем больше шансов, что будет оказана надлежащая помощь! Например, ниже приведен образец очень хорошего отчета об ошибке (он, конечно, должен быть отправлен при помощи сценария mysqlbug): Пример запускается при помощи командной строки mysql (обратите внимание на применение терминатора операторов \G, который используется для операторов, если ширина выводимой ими информации превышает ширину строки 80-символьного дисплея):

  mysql> SHOW VARIABLES;
  mysql> SHOW COLUMNS FROM ...\G
         <вывод SHOW COLUMNS>
  mysql> EXPLAIN SELECT ...\G
         <вывод EXPLAIN>
  mysql> FLUSH STATUS;
  mysql> SELECT ...;
         <Корокая версия вывода SELECT, включая время,
          затраченное на обработку запроса>
  mysql> SHOW STATUS;
         <вывод SHOW STATUS>
  

• Если ошибка или проблема возникли во время работы mysqld, постарайтесь предоставить сценарий, который воспроизведет аномальное поведение программы. Сценарий должен включать все необходимые файлы данных. Чем точнее сценарий может воспроизвести сложившуюся ситуацию, тем лучше. Если вы можете создать воспроизводимый контрольный пример, его необходимо отправить на bugs@lists.mysql.com для немедленного рассмотрения! Если сценарий обеспечить нельзя, необходимо, по крайней мере, включить в свое сообщение выходную информацию команды mysqladmin variables extended-status processlist, чтобы предоставить данные о работе системы!
• Если не удается создать контрольный пример в несколько строк, или если таблица тестирования слишком велика для отправления в список рассылки (более 10 строк), необходимо вывести содержимое таблиц при помощи команды mysqldump и создать файл `README' с описанием вашей проблемы. Запакуйте файлы при помощи tar и gzip или zip, и по ftp загрузите архив на ftp://support.mysql.com/pub/mysql/secret/. Затем отправьте краткое описание проблемы на bugs@lists.mysql.com.
• Если MySQL на ваш запрос выдает странный, на ваш взгляд, результат, приведите в отчете не только сам результат, но также и ваше мнение о том, каким должен быть результат, и расчеты, подтверждающие это мнение.
• Когда вы приводите пример ситуации, при которой возникает проблема, лучше сохранить действительные имена переменных, таблиц и т.п., вместо того, чтобы давать им новые имена. Иногда проблема может быть вызвана именем переменной или таблицы! Это довольно редкие случаи, но лучше, чтобы не терять времени, такую информацию отправить нам сразу. В конце концов, вам будет даже легче использовать данные, соответствующие реальной ситуации, и это во всех отношениях лучше для нас. Те же, кто не хотел бы показывать свои данные другим пользователям, могут загрузить файл по ftp на ftp://support.mysql.com/pub/mysql/secret/. Если данные действительно представляют собой секретную информацию, которую нельзя показывать даже нам, тогда можно привести пример, используя другие имена, но этот вариант следует оставить на крайний случай.
• Включите в отчет все параметры, указанные для важных программ, если это возможно. Например, приведите параметры, которые вы используете как для запуска сервера mysqld, так и для запуска клиентских программ MySQL. Параметры таких программ как mysqld и mysql, а также сценарий configure часто содержат ответы на многие вопросы и очень важны! Включить их в отчет не помешает в любом случае! Если используются какие-либо модули, такие как Perl или PHP, также укажите их версии.
• Если ваш вопрос относится к системе привилегий, укажите выходные данные команды mysqlaccess, выходные данные команды mysqladmin reload и все сообщения об ошибках, которые выдаются при попытке соединения! Во время проверки своих привилегий сначала необходимо выполнить команду mysqlaccess. После этого запустите mysqladmin reload version и попытайтесь соединиться с программой, которая вызывала проблемы. Программу mysqlaccess можно найти в каталоге `bin' установочного каталога MySQL.
• Если у вас есть патч, который исправляет ошибку, - это хорошо. Но не думайте, что одного лишь патча для нас будет достаточно, или что мы будем ее использовать, если вы не предоставите необходимую информацию, такую как описание ошибки, которую исправляет ваш патч. Ведь мы можем найти проблемы в самом патче или попросту в нем не разобраться, что не даст нам возможности его применять. Если нам не удастся проверить, для чего именно служит этот патч, мы не станем его использовать. В таких случаях нам помогут контрольные примеры. Продемонстрируйте, что патч исправляет все проблемы, которые могут возникнуть в связи с этой ошибкой. Если мы найдем хотя бы один вариант, в котором патч не работает, то он может оказаться бесполезным.
• Попытки угадать, что представляет собой ошибка, почему она возникает или от чего зависит, обычно не дают положительного результата. Даже члены команды MySQL не могут определить реальную причину ошибки без программы отладки.
• Укажите в своем почтовом сообщении, что вы просмотрели справочное руководство и почтовый архив - тогда будет видно, как вы пытались решить эту проблему самостоятельно.
• Если возникла синтаксическая ошибка, внимательно просмотрите свою программу! Если не удается найти никаких ошибок, может оказаться, что ваша версия MySQL не поддерживает используемый запрос. Если используется текущая версия в руководстве на http://www.mysql.com/doc/ не описан синтаксис, который вы используете, MySQL не поддерживает ваш запрос. В этом случае вы можете либо самостоятельно реализовать такой синтаксис, либо направить сообщение по адресу licensing@mysql.com и попросить либо предложить реализовать его! Если в руководстве описан используемый синтаксис, но у вас установлена более старая версия MySQL, необходимо проверить журнал изменений MySQL, чтобы узнать, когда был реализован данный синтаксис. В этом случае вы можете произвести обновление до более новой версии MySQL. See section D История изменений и обновлений MySQL.
• Если в результате ошибки ваши данные оказываются поврежденными, или возникают ошибки при обращении к какой-либо определенной таблице, сначала необходимо проверить, а потом попытаться восстановить таблицы при помощи команды myisamchk или CHECK TABLE и REPAIR TABLE. See section 4 Администрирование баз данных.
• Если повреждения ваших таблиц случаются часто, необходимо выяснить, когда и почему это происходит. В этом случае файл `mysql-data-directory/`hostname`.err' может содержать некоторую информацию о происходящем. See section 4.9.1 Журнал ошибок. Включите в отчет об ошибке всю важную информацию из этого файла. Обычно mysqld никогда не должна повреждать данные в таблицах, если не произошло никакого сбоя во время обновления! Если вам удалось найти причину ошибки в mysqld, нам будет гораздо проще оказать вам помощь в решении этой проблемы. See section A.1 Как определить, чем вызваны проблемы.
• Если это возможно, загрузите и установите последнюю версию MySQL Server и проверьте, не решена ли в ней ваша проблема. Все версии программного обеспечения MySQL проходят тщательное тестирование и должны работать без проблем. Мы делаем все возможное, чтобы сохранить обратную совместимость, поэтому при переходе с одной версии MySQL на другую никаких проблем не должно возникать. See section 2.2.6 Какую версию MySQL использовать.

Если вы пользователь, пользующийся официальной поддержкой, направьте отчет об ошибке на mysql-support@mysql.com, чтобы его рассмотрели в первую очередь, а также в соответствующий список рассылки, чтобы узнать, сталкивался ли кто-нибудь еще с этой проблемой (и, возможно, нашел решение).

Чтобы получить информацию по отчетам об ошибках в MyODBC, See section 8.3.4 Как сообщать о проблемах с MyODBC.

Решения для наиболее часто встречающихся проблем можно найти в разделе section A Проблемы и распространенные ошибки.

Если ответы направляются к вам индивидуально, не попадая в список рассылки, хорошим тоном считается составить отчет по полученным ответам и отправить его в список рассылки, чтобы другие пользователи смогли получить информацию, которая помогла решить вашу проблему!