3.1.4. grntest

3.1.4.1. 名前

grntest - groongaテストプログラム

3.1.4.2. 書式

grntest  [options...] [script] [db]

3.1.4.3. 説明

grntestは、groonga汎用テストツールです。

groongaを単独のプロセスとして利用する場合はもちろん、サーバプログラムとして利用する場合の動作確認や実行速度測定が可能です。

grntest を利用するために必要なデータファイルは、ftp.groonga.orgから必要に応じダウンロードしますので、groonga及びgrntestが動作し、インターネットに接続できる環境であればgroongaコマンドの知識がなくてもgroongaの動作を確認できます。

現在は、linux 及びWindows上で動作します。make installしてもインストールは行われません。

3.1.4.4. オプション

-i, --host <ip/hostname>
接続するgroongaサーバを、ipアドレスまたはホスト名で指定します。指定先にgroongaサーバが立ち上がっていない場合、接続不能となることに注意してください。このオプションを指定しない場合、grntestは自動的にlocalhostのgroongaサーバを起動して接続します。
-p, --port <port number>
自動的に起動するgroongaサーバ、または明示的に指定した接続先のgroonga サーバが利用するポート番号を指定します。接続先のgroongaサーバが利用しているポートと、このオプションでしていしたポート番号が異なる場合、接続不能となることに注意してください。
--dir
ftp.groonga.org に用意されているスクリプトファイルを表示します。
--noftp
通常grntestはftp.groonga.orgとftp通信を行い、scriptファイルの同期やログファイルの送信を行います。–noftp オプションを指定するとftp 通信を一切行わないようになります。存在しないスクリプトファイルを指定した場合、エラーとなることに注意してください。

3.1.4.5. 引数

script
grntestの動作方法(以下、grntest命令と呼びます)を記述したテキストファイルです。拡張子は.scrです。
db
grntestが利用するgroonga データベースです。指定されたデータベースが存在しない場合、grntestが新規に作成します。またgroonga サーバを自動的に起動する場合もこの引数で指定したデータベースが利用されます。接続するgroonga サーバを明示的に指定した場合に利用するデータベースは、接続先サーバが使用中のデータベースになることに注意してください。

3.1.4.6. 使い方

まず、シェル上(Windowsならコマンドプロンプト上)で

grntest test.scr 任意のDB名

とタイプしてください。もしgrntestが正常に動作すれば、

test-ユーザ名-数字.log

というファイルが作成されるはずです。そうでない場合は、このドキュメントの「トラブルシューティング」の章を参照してください。

3.1.4.7. スクリプトファイル

スクリプトファイルは、grntest命令を記述したテキストファイルです。 “;”セミコロンを利用して、一行に複数のgrntest命令を記述することができます。一行に複数のgrntest命令がある場合、各命令は並列に実行されます。 “#”で始まる行はコメントとして扱われます。

3.1.4.7.1. grntest命令

現在サポートされているgrntest命令は以下の4つです。

do_local コマンドファイル [スレッド数] [繰り返し数]

コマンドファイルをgroonga 単体で実行します。スレッド数が指定されている場合、複数のスレッドで同じコマンドファイルを同時に実行します。繰り返し数が指定されてい場合、コマンドファイルの内容を繰り返し実行します。スレッド数、繰り返し数とも省略時は1です。1スレッドで複数回動作させたい場合は、do_local コマンドファイル 1 [繰り返し数]と明示的に指定してください。

do_gqpt コマンドファイル [スレッド数] [繰り返し数]

コマンドファイルをgroonga サーバで実行します。スレッド数や繰り返し数の意味はdo_localの場合と同じです。

rep_local コマンドファイル [スレッド数] [繰り返し数]

コマンドファイルをgroonga 単体で実行し、より詳細な報告を行います。

rep_gqpt コマンドファイル [スレッド数] [繰り返し数]

コマンドファイルをgroonga サーバ実行し、より詳細な報告を行います。 スレッド数や繰り返し数の意味はdo_localと 同じです。

3.1.4.7.2. コマンドファイル

コマンドファイルは、groonga組み込みコマンドを1行に1つずつ記述したテキストファイルです。拡張子に制限はありません。groonga組み込みコマンドに関しては./commands.htmlを参照してください。

3.1.4.7.3. サンプル

スクリプトファイルのサンプルです。:

# sample script
rep_local test.ddl
do_local test.load;
do_gqtp test.select 10 10; do_local test.status 10

上記の意味は以下のとおりです。:

1行目:コメント行。
2行目:test.dll というコマンドファイルをgroonga単体で実行し、詳細に報告する。
3行目:test.load というコマンドファイルをgroonga単体で実行する。(最後の";"セミコロンは複数のgrntest命令を記述する場合に必要ですが、この例のように1つのgrntest命令を実行する場合に付与しても問題ありません。)
4行目:test.select というコマンドファイルをgroongaサーバで10個のスレッドで同時に実行する。各スレッドはtest.selectの中身を10回繰り返す。また同時に、groonga単体でtest.statusというコマンドファイルを10個のスレッドで実行する。

3.1.4.7.4. 特殊命令

スクリプトファイルのコメント行には特殊コマンドを埋め込むことが可能です。現在サポートされている特殊命令は以下の二つです。

#SET_HOST <ip/hostname> -i, –hostオプションと同等の機能です。コマンドラインオプションに指定したIPアドレス/ホスト名と、SET_HOSTで指定したIPアドレス/ホスト名が異なる場合、またコマンドラインオプションを指定しなかった場合にもSET_HOSTが優先されます。SET_HOSTを利用した場合、サーバが自動的には起動されないのもコマンドラインオプションで指定した場合と同様です。

#SET_PORT <port number>

-p, –port オプションと同等の機能です。コマンドラインオプションに指定したポート番号とSET_PORTで指定したポート番号が異なる場合、またコマンドラインオプションを指定しなかった場合にもSET_PORTが優先されます。

特殊命令はスクリプトファイルの任意の場所に書き込むことができます。同一ファイル内に複数回特殊命令を記述した場合、「最後の」特殊命令が有効となります。

例えば、

$ ./grntest --port 20010 test.scr testdb

とコマンド上でポートを指定した場合でも、もしtest.scrの中身が

::
#SET_PORT 10900 rep_local test.ddl do_local test.load; rep_gqtp test.select 10 10; rep_local test.status 10 #SET_PORT 10400

であれば、自動的に起動されるgroongaサーバはポート番号10400を利用します。

3.1.4.8. grntest実行結果

grntestが正常に終了すると、(拡張子を除いた)スクリプト名-ユーザ名-実行開始時刻.logという形式のログファイルがカレントディレクトリに作られます。ログファイルは自動的にftp.groonga.org に送信されます。ログファイルは以下のようなjson形式のテキストです。

[{"script": "test.scr",
  "user": "homepage",
  "date": "2010-02-10 06:17:08",
  "CPU": Intel(R) Pentium(R) 4 CPU 2.80GHz",
  "BIT": 32,
  "CORE": 1,
  "RAM": "975MBytes",
  "HDD": "257662232KBytes",
  "OS": "Linux 2.4.20-24.7-i686",
  "HOST": "localhost",
  "PORT": "10400",
  "VERSION": "0.1.5"
},
{"jobs": "rep_local test.ddl",
"detail": [
[0, "table_create res_table --key_type ShortText", 1275, 2692, [0]],
[0, "column_create res_table res_column --type Text", 2742, 5248, [0]],
[0, "column_create res_table user_column --type Text", 5306, 7901, [0]],
[0, "column_create res_table mail_column --type Text", 7963, 10656, [0]],
[0, "column_create res_table time_column --type Time", 10715, 11624, [0]],
[0, "status", 11641, 11663, [0]],
[0, "table_create thread_table --key_type ShortText", 11674, 12690, [0]],
[0, "column_create thread_table thread_title_column --type ShortText", 12716, 15281, [0]],
[0, "status", 15344, 15367, [0]],
[0, "table_create lexicon_table --flags 129 --key_type ShortText --default_tokenizer TokenBigram", 15376, 16552, [0]],
[0, "column_create lexicon_table inv_res_column 514 res_table res_column ", 16577, 30426, [0]],
[0, "column_create lexicon_table inv_thread_column 514 thread_table thread_title_column ", 30533, 44591, [0]],
[0, "status", 44696, 44721, [0]]],
"summary" :[{"job": "rep_local test.ddl", "latency": 44777, "self": 43979, "qps": 295.595625, "min": 22, "max": 14058}]},
{"jobs": "do_local test.load; ",
"summary" :[{"job": "do_local test.load", "latency": 63715, "self": 18606, "qps": 1074.922068, "min": 166, "max": 5015}]},
{"jobs": "do_gqtp test.select 10 10; do_local test.status 10",
"summary" :[{"job": " do_local test.status 10", "latency": 493483, "self": 429467, "qps": 93.138704, "min": 5, "max": 177},{"job": "do_gqtp test.select 10 10", "latency": 802498, "self": 738482, "qps": 2031.193719, "min": 305, "max": 114292}]},
{"total": 849332, "qps": 1852.043724}]

3.1.4.9. 制限事項

  • スクリプトファイルの一行には複数のgrntest命令を記述できますが、すべてのスレッド数の合計は最大64です。
  • コマンドファイル中のgroongaコマンドの長さは最長10000byteです。

3.1.4.10. トラブルシューティング

もし、grntestが正常に動作しない場合、まず以下を確認してください。

  • インターネットに接続しているか? –noftp モードを指定しない限り、grntestは動作のたびにftp.groonga.orgと通信します。ftp.groonga.orgと通信可能でない場合、grntestは正常に動作しません。
  • groonga サーバが動作していないか? grntestは、-i, –host オプションで明示的にサーバを指定しないかぎり、自動的にlocalhostのgroongaサーバを立ち上げます。すでにgroongaサーバが動作している場合、grntestは正常に動作しない可能性があります。
  • 指定したDBが適切か? grntestは、引数で指定したDBの中身はチェックしません。もし指定されたDBが存在しなければ自動的にDBを作成しますが、もしファイルとして存在する場合は中身に関わらず動作を続けてしまい、結果が異常になる可能性があります。

以上の原因でなければ、問題はgrntestかgroongaにあります。ご報告をお願いします。