7.1.5. groonga-httpd

警告

Groonga 13.0.3からgroonga-httpdは groonga-nginx に切り出されました。

7.1.5.1. 概要

groonga-httpdはGroongaサーバーとHTTPプロトコルで通信するプログラムです。 機能的には、 Groonga HTTPサーバー と同じです。 Groonga HTTPサーバー はHTTPサーバーとしては最小限の機能しか持ちませんが、groonga-httpdは nginx を組み込むことでnginxが準拠しているHTTPの仕様と機能をすべて利用できます。

groonga-httpdにはHTML + JavaScriptで実装された管理ツールが標準で付属しています。ウェブブラウザでhttp://hostname:port/にアクセスすると、管理ツールを利用できます。

7.1.5.2. 構文

groonga-httpd [nginx options]

7.1.5.3. 使い方

7.1.5.3.1. 設定をする

まずは、データベースを指定するためにgroonga-httpdの設定ファイルを編集する必要があります。次のように/etc/groonga/httpd/groonga-httpd.confを編集して groonga_database ディレクティブを有効にしてます。

# Match this to the file owner of groonga database files if groonga-httpd is
# run as root.
#user groonga;
...
http {
  ...
  # Don't change the location; currently only /d/ is supported.
  location /d/ {
    groonga on; # <= This means to turn on groonga-httpd.

    # Specify an actual database and enable this.
    groonga_database /var/lib/groonga/db/db;
  }
  ...
}

次に、groonga-httpdを実行してください。すぐにターミナルに制御が戻ってきます。これはgroonga-httpdはデフォルトでデーモンプロセスになるからです。

% groonga-httpd

7.1.5.3.2. クエリーを実行する

動作を確認するため、簡単なクエリー（ status ）をリクエストしてみます。

実行例:

$ curl http://localhost:10041/d/status
[
  [
    0,
    1337566253.89858,
    0.000355720520019531
  ],
  {
    "alloc_count": 29,
    "starttime": 1696558618,
    "start_time": 1696558618,
    "uptime": 0,
    "version": "2.9.1",
    "n_queries": 0,
    "cache_hit_rate": 0.0,
    "command_version": 1,
    "default_command_version": 1,
    "max_command_version": 3,
    "n_jobs": 0,
    "features": {
      "nfkc": true,
      "mecab": true,
      "message_pack": true,
      "mruby": true,
      "onigmo": true,
      "zlib": true,
      "lz4": true,
      "zstandard": true,
      "kqueue": false,
      "epoll": true,
      "poll": false,
      "rapidjson": false,
      "apache_arrow": true,
      "xxhash": true,
      "blosc": true,
      "bfloat16": true,
      "h3": true,
      "simdjson": true,
      "llama.cpp": true,
      "back_trace": true,
      "reference_count": false
    },
    "apache_arrow": {
      "version_major": 2,
      "version_minor": 9,
      "version_patch": 1,
      "version": "2.9.1"
    },
    "memory_map_size": 2929,
    "n_workers": 0,
    "default_n_workers": 0,
    "os": "Linux",
    "cpu": "x86_64"
  }
]

7.1.5.3.3. POSTでのデータロード

JSONデータをPOSTするとデータをロードできます。

Users テーブルに alice と bob ユーザーをロードする curl のコマンドライン例は次の通りです:

% curl --data-binary '[{"_key": "alice"}, {"_key": "bob"}]' -H "Content-Type: application/json" "http://localhost:10041/d/load?table=Users"

JSONファイルからユーザーをロードする場合は、次のようなJSONファイルを準備します:

[
{"_key": "alice"},
{"_key": "bob"}
]

それから curl のコマンドラインでJSONファイルを指定します:

% curl -X POST 'http://localhost:10041/d/load?table=Users' -H 'Content-Type: application/json' -d @users.json

7.1.5.3.4. 管理ツールを使う

補足ですが、 http://localhost:10041/ にアクセスすると管理ツールを利用できます。

7.1.5.3.5. 終了する

最後に、次のコマンドで動作中のgroonga-httpdデーモンを終了できます。

% groonga-httpd -s stop

7.1.5.4. 設定ディレクティブ

このセクションでは重要なディレクティブのみ説明します。重要なディレクティブとはgroonga-http特有のディレクティブと性能に関するディレクティブです。

以下のディレクティブはgroonga-httpdの設定ファイル中で使用することができます。デフォルトでは、設定ファイルは/etc/groonga/httpd/groonga-httpd.confに置かれています。

7.1.5.4.1. groonga-httpd特有のディレクティブ

以下のディレクティブはnginxが提供しているものではなく、groonga-httpd関連の設定をするためにgroonga-httpdが提供しているディレクティブです。

7.1.5.4.1.1. groonga

構文:

groonga on | off;

デフォルト

groonga off;

コンテキスト

location

この location ブロックでGroongaを使うかどうかを指定します。デフォルトは off です。Groongaを使うためには on を指定してください。

例:

location /d/ {
  groonga on;  # Enables groonga under /d/... path
}

location /d/ {
  groonga off; # Disables groonga under /d/... path
}

7.1.5.4.1.2. groonga_database

構文:

groonga_database /path/to/groonga/database;

デフォルト

groonga_database /usr/local/var/lib/groonga/db/db;

コンテキスト

http, server, location

Groongaデータベースのパスを指定します。このディレクティブは必須です。

7.1.5.4.1.3. groonga_database_auto_create

構文:

groonga_database_auto_create on | off;

デフォルト

groonga_database_auto_create on;

コンテキスト

http, server, location

Groongaのデータベースを自動で作成するかどうかを指定します。もし、この値が on で groonga_database に指定したGroongaのデータベースが存在しない場合は自動でGroongaのデータベースを作成します。Groongaのデータベースが存在している場合は何もしません。

もし、親ディレクトリが存在しな場合は再帰的に親ディレクトリも作成します。

デフォルト値は on です。通常、この値を変更する必要はありません。

7.1.5.4.1.4. groonga_base_path

構文:

groonga_base_path /d/;

デフォルト

location の名前と同じ値。

コンテキスト

location

URIのベースパスを指定します。Groongaは command を実行するために /d/command?parameter1=value1&... というパスを使います。groonga-httpdでもこのパスの形式を使いますが、groonga-httpdは /other-prefix/command?parameter1=value1&... というように /d/ ではなく別のプレフィックスを使った形式もサポートしています。この別の形式もサポートするために、groonga-httpdはリクエストURIの先頭からベースパスを削除し、先頭に /d/ を追加します。このパスの変換をすることにより、ユーザーはプレフィックスをカスタムできるようになりますが、Groongaは常に /d/command?parameter1=value1&... という形式で処理できます。

通常、このディレクティブを使う必要はありません。このディレクティブはコマンド毎に設定をしたい場合に使います。

以下は shutdown コマンドに認証をかける設定例です。:

groonga_database /var/lib/groonga/db/db;

location /d/shutdown {
  groonga on;
  # groonga_base_path is needed.
  # Because /d/shutdown is handled as the base path.
  # Without this configuration, /d/shutdown/shutdown path is required
  # to run shutdown command.
  groonga_base_path /d/;
  auth_basic           "manager is required!";
  auth_basic_user_file "/etc/managers.htpasswd";
}

location /d/ {
  groonga on;
  # groonga_base_path doesn't needed.
  # Because location name is the base path.
}

7.1.5.4.1.5. groonga_log_path

構文:

groonga_log_path path | off;

デフォルト

/var/log/groonga/httpd/groonga.log

コンテキスト

http, server, location

Groongaのログ保存先を http 、server もしくは location ブロックで指定します。デフォルトは /var/log/groonga/httpd/groonga.log です。ログを無効にするには off を指定します。

例:

location /d/ {
  groonga on;
  # You can disable log for groonga.
  groonga_log_path off;
}

7.1.5.4.1.6. groonga_log_level

構文:

groonga_log_level none | emergency | alert | ciritical | error | warning | notice | info | debug | dump;

デフォルト

notice

コンテキスト

http, server, location

Groongaのログレベルを http 、 server もしくは location ブロックで指定します。デフォルトは notice です。 none を指定することでログを無効にできます。

例:

location /d/ {
  groonga on;
  # You can customize log level for groonga.
  groonga_log_level notice;
}

7.1.5.4.1.7. groonga_query_log_path

構文:

groonga_query_log_path path | off;

デフォルト

/var/log/groonga/httpd/groonga-query.log

コンテキスト

http, server, location

Groongaのクエリーログの保存先を http 、server もしくは location ブロックで指定します。デフォルトは /var/log/groonga/httpd/groonga-query.log です。ログを無効にするには off を指定します。

例:

location /d/ {
  groonga on;
  # You can disable query log for groonga.
  groonga_query_log_path off;
}

クエリーログは以下のようなケースで有用です:

• スロークエリーを見つける。

• デバッグ。

groonga-query-log パッケージ でクエリーログを解析できます。このパッケージは有用なツールを提供しています。

例えば、クエリーログを解析するツールがあります。これを使えば、スロークエリーを見つけることができます。クエリーログ内のすべてのクエリーを再生するツールもあります。これを使えば、新しいGroongaをプロダクション環境にデプロイする前に網羅的にテストすることができます。

7.1.5.4.2. 性能関連のディレクティブ

以下のディレクティブはgronoga-httpdの性能に関連しているディレクティブです。

7.1.5.4.2.1. worker_processes

最適なパフォーマンスを得るためには、CPU数あるいはコア数と同じ数になるようにこのディレクティブを設定してください。大抵の場合、GroongaのクエリーはCPU負荷が高いものとなり、複数のCPU/コアを使い切るためには、このディレクティブを設定する必要があります。

このディレクティブはgroonga-httpdのディレクティブではなく、nginxのディレクティブです。詳細は、 http://wiki.nginx.org/CoreModule#worker_processes を参照してください。

デフォルトで、このディレクティブには1が設定されています。

7.1.5.4.2.2. groonga_cache_limit

構文:

groonga_cache_limit limit;

デフォルト

groonga_cache_limit 100;

コンテキスト

http, server, location

Groongaのクエリキャッシュの制限を http 、 server もしくは location ブロックで指定します。デフォルトは 100 です。 0 を指定することで groonga_cache_limit を明示的に無効にできます。

例:

location /d/ {
  groonga on;
  # You can customize query cache limit for groonga.
  groonga_cache_limit 100;
}

7.1.5.4.2.3. groonga_cache_base_path

構文:

groonga_cache_base_path path | off;

デフォルト

groonga_cache_base_path off;

コンテキスト

http, server, location

クエリーキャッシュの保存先のベースになるパスを http 、 server もしくは location ブロックで指定します。

マルチワーカーの設定をしている場合はこの設定をすることをオススメします。

ベースのパスを指定すると、メモリーキャッシュではなく永続キャッシュを使えます。永続キャッシュを使うと、ワーカー間でクエリーキャッシュを共有できます。複数のワーカー間で同じレスポンスを1回だけキャッシュするので複数ワーカー設定のときに効率的です。

永続キャッシュにはもう1つメリットがあります。groonga-httpdを再起動した後にキャッシュをウォームアップ必要がありません。groonga-httpdが停止しても永続キャッシュは消えません。そのため、既存の永続キャッシュを再利用することができます。

デフォルト値は off です。これは永続キャッシュは無効ということです。メモリーキャッシュが使われます。メモリーキャッシュはワーカー毎に独立しています。複数のワーカーがそれぞれで同じレスポンスをキャッシュする可能性があるため、複数ワーカー設定のときはメモリーキャッシュは効率的ではありません。

永続キャッシュはメモリーキャッシュよりも少し遅いです。通常、この差によるパフォーマンスの影響は軽微です。

このベースとなるパスはメモリーファイルシステム上のパスを指定するべきです。ディスク上にベースとなるパスを指定するとキャッシュが遅くなります。これでは意味がありません。

例:

location /d/ {
  groonga on;
  # You can customize query cache limit for groonga.
  groonga_cache_base_path /dev/shm/groonga-httpd-cache;
}

7.1.5.4.2.4. proxy_cache

まとめると、Groonga組み込みのクエリーキャッシュ機能の代わりにnginxのリバースプロキシとキャッシュの仕組みを使うこともできます。

7.1.5.4.2.4.1. クエリーキャッシュ

groongaは select コマンド用にクエリーキャッシュ機能を提供しています。この機能は多くのケースで性能向上を実現します。

クエリーキャッシュ機能は cache_limit コマンドを使っていないあるいはワーカー数が1だけの場合はgroonga-httpd上でもきちんと動作します。通常、 cache_limit コマンドは使わないので、多くの場合は問題がありません。

2ワーカー以上で cache_limit コマンドを使ったときの問題点を説明します。

groongaのクエリーキャッシュは同じプロセス内で有効です。これは、同じキャッシュを複数のワーカー間で共有できないということです。キャッシュサイズを変更しないならこれは大きな問題ではありません。もし、 cache_limit コマンドでキャッシュサイズを変更したいなら問題になります。

すべてのワーカーのキャッシュサイズを変更する汎用的な方法がないのです。

例えば、3ワーカーいるとします:

                                   +-- worker 1
client -- groonga-httpd (master) --+-- worker 2
                                   +-- worker 3

クライアントが cache_limit コマンドをリクエストし、worker 1が受け取りました:

                                   +-> worker 1 (changed!)
client -> groonga-httpd (master) --+-- worker 2
                                   +-- worker 3

クライアントがもう一度 cache_limit コマンドをリクエストし、またworker 1が受け取りました:

                                   +-> worker 1 (changed again!!!)
client -> groonga-httpd (master) --+-- worker 2
                                   +-- worker 3

この場合、worker 2とworker 3は1つもリクエストを受けとっていません。そのため、これらのワーカーのキャッシュサイズは変更されていません。

クライアントはワーカーを選ぶことができないので、 cache_limit コマンドですべてのワーカのキャッシュサイズを変更することができないのです。

7.1.5.4.2.4.2. リバースプロキシとキャッシュ

nginxのリバースプロキシ機能とキャッシュ機能を使ってクエリーキャッシュを実現できます:

                                                            +-- worker 1
client -- groonga-httpd (master) -- reverse proxy + cache --+-- worker 2
                                                            +-- worker 3

この方法ではすべてのワーカーで同じキャッシュの設定を利用できますが、HTTPで動的にキャッシュの設定を変更することはできません。

以下はサンプルの設定です:

...
http {
  proxy_cache_path /var/cache/groonga-httpd levels=1:2 keys_zone=groonga:10m;
  proxy_cache_valid 10m;
  ...
  # Reverse proxy and cache
  server {
    listen 10041;
    ...
    # Only select command
    location /d/select {
      # Pass through groonga with cache
      proxy_cache groonga;
      proxy_pass http://localhost:20041;
    }

    location / {
      # Pass through groonga
      proxy_pass http://localhost:20041;
    }
  }

  # groonga
  server {
    location 20041;
    location /d/ {
      groonga on;
      groonga_database /var/lib/groonga/db/db;
    }
  }
  ...
}

パラメーターの詳細は以下のnginxのドキュメントを見てください:

• http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_path

• http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_valid

• http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache

• http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_pass

Groongaに新しいデータをロードしたときは自分でnginxが作ったキャッシュファイルを削除しなければいけないことに注意してください。前述のサンプル設定では、以下のコマンドでキャッシュを消せます:

% groonga DB_PATH < load.grn
% rm -rf /var/cache/groonga-httpd/*

Groongaのクエリーキャッシュ機能を使うと、手動でキャッシュを失効する必要はありません。自動で失効します。

7.1.5.4.3. nginxログ関連のディレクティブ

7.1.5.4.3.1. access_log

nginxのログを access_log ディレクティブを使うことで出力できます。以下の例は、デフォルトのnginxのログ設定です。:

http {
  log_format  combined  '$remote_addr - $remote_user [$time_local] "$request" '
                    '$status $body_bytes_sent "$http_referer" '
                    '"$http_user_agent" "$http_x_forwarded_for"';

  access_log  access.log  combined;
}

log_format ディレクティブを使って、ログのフォーマットを指定できます。利用できるログの項目の詳細は、 Module ngx_http_log_module を参照してください。

nginxのアクセスログは、処理終了時に出力されます。リクエスト処理時間を出力したい場合は、以下のように設定する必要があります。:

http {
  log_format  combined  '$remote_addr - $remote_user [$time_local] "$request" '
                    '$status $body_bytes_sent "$http_referer" '
                    '"$http_user_agent" "$http_x_forwarded_for" '
                    '"$request_time"';

  access_log  access.log  combined;
}

7.1.5.5. 利用可能なnginxモジュール

全てのHTTPの標準モジュールが利用可能です。PCRE（Perl Compatible Regular Expressions）がない場合はHttpRewriteModuleは無効になります。標準モジュールの一覧は、 nginx documentation を参照してください。