报告BUG

很不幸,Sphinx还没有达到100%无bug(尽管我们正向这个目标努力),因此您可能偶尔遇到些问题。

对于每个问题的报告越详细越好,这很重要——因为要想修复bug,我们必须重现bug并调试它,或者根据您提供的信息来推断出产生bug的原因。因此在此提供一些如何报告bug的指导。

编译时的问题

如果Sphinx构建失败,请您按照以下步骤进行:

  1. 确认您的DBMS(数据库)的头文件和库文件都正确安装了(例如,检查mysql-devel包已经安装)

  2. 报告Sphinx的版本和配置文件(别忘了删除数据库连接密码),MySQL(或PostgreSQL)配置文件信息,gcc版本,操作系统版本和CPU类型(例如x86、x86-64、PowerPC等):

    mysql_config
    gcc --version
    uname -a
  3. 报告configure脚本或者gcc给出的错误信息(只需错误信息本身,不必附上整个构建日志)

运行时的问题

如果Sphinx已经成功构建并能运行,但运行过程中出现了问题,请您按照以下步骤进行:

  1. 描述您遇到的bug(即,您预期的行为和实际发生的行为),以及重现您遇到的问题需要的步骤;

  2. 附带Sphinx的版本和配置文件(别忘了删除密码),MySQL(或PostgreSQL)配置文件信息,gcc版本,操作系统版本和CPU类型(例如x86、x86-64、PowerPC等):

    mysql --version
    gcc --version
    uname -a
  3. 构建、安装和运行调试版本的全部Sphinx程序(这会启用很多内部校验,或称断言(assertions)):

    make distclean
    ./configure --with-debug
    make install
    killall -TERM searchd
  4. 重新索引,检查是否有断言(assertions)被触发(如果是,那很可能是索引损坏了并造成了问题);

  5. 如果bug在调试版本中没有重现,请回到非调试版本并在报告中说明这个情况;

  6. 如果bug可以在您的数据库的很小的子集(1-100条记录)上重现,请提供一个该子集的gzip压缩包;

  7. 如果问题与searchd有关,请在bug报告中提供searchd.logquery.log中的相关条目;

  8. 如果问题与searchd有关,请尝试在console模式下运行它并检查它是否因断言失败而退出。

    ./searchd --console
  9. 如果任何一个程序因断言失败而退出,请提供断言(assertions)信息。

调试断言,崩溃和挂断

如果任何一个程序因断言(assertions)失败而退出,崩溃或停止响应,您可以额外生成一个内存转储文件并检查它。

  1. 启用内存转储。在大多数Linux系统上,可以用ulimit命令启用它:

    ulimit -c 32768
  2. 运行程序,尝试重现bug;

  3. 如果程序崩溃(可能有断言失败的情况也可能没有),在当前目录下找到内存转储文件(一般会打印“Segmentation fault (core dumped)”消息);

  4. 如果程序停止响应,在另一个控制台上用kill -SEGV强制退出并获得内存转储:

    kill -SEGV HANGED-PROCESS-ID
  5. 使用gdb检查转储文件,查看backtrace:

    gdb ./CRASHED-PROGRAM-FILE-NAME CORE-DUMP-FILE-NAME
    (gdb) bt
    (gdb) quit

提示: HANGED-PROCESS-ID(停止响应的进程ID), CRASHED-PROGRAM-FILE-NAME(崩溃程序的文件名) and CORE-DUMP-FILE-NAME(核心转储文件的文件名)应该被换成具体的数字和文件名。例如,一次对停止响应的searchd的调试会话看起来 应该像下面这样:

# kill -SEGV 12345
# ls *core*
core.12345
# gdb ./searchd core.12345
(gdb) bt
...
(gdb) quit

注意ulimit并不是整个服务器范围的,而是仅影响当前的shell会话。因此您不必还原任何服务器范围的限制——但是一旦重新登陆,您就需要再次设置ulimit

核心内存转储文件会存放在当前工作目录下(Sphinx的各个程序不会改变工作目录),因此它们就在那。

不要立刻删除转储文件,从它里面可能获得更多有用的信息。您不需要把这个文件发送给我们(因为调试信息与您的系统本身紧密相关),但我们可能会向您询问一些与之相关的问题。