Java on @johtaniの日記 3rd

Elasticsearchの新しいJavaクライアント（2024年3月版）

Thu, 21 Mar 2024 06:55:57 +0000

以前、Elasticsearchの新しいJavaクライアントについてブログを書きました。

あれから、ほぼ2年経ちましたが、差分を調べたのでブログに残しておきます。

前回の問題点

前回のブログを書いている時点では、2点ほど気になることがありました。それぞれ解決しているので、まずはその紹介をしようと思います。

どんなリクエストを投げているかが不明

Elasticsearchの公式ドキュメントでは、各エンドポイントやクエリの書き方の紹介では、JSONのサンプルが紹介されています。自分で書いたリクエストが想定した形になっているか？、プログラムで書いたクエリがJSONだとどんな形になっているか？というのを確認したくなります。前回記事を書いた時点では、JSON文字列にするためにJsonGeneratorを利用していくつか処理を書く必要がありました。こんな感じに。

    private void printRequestBodyJsonForDebug(RequestBase request) {
        //for debug
        Logger.log("** Debug print start **");
        StringWriter writer = new StringWriter();
        SimpleJsonpMapper mapper = new SimpleJsonpMapper();
        JsonGenerator generator = mapper.jsonProvider().createGenerator(writer);
        mapper.serialize(request, generator);
        generator.close();
        Logger.log(writer.toString());
        Logger.log("** Debug print finish **");
    }

v8.3から、各種RequestクラスにtoString()メソッドが実装され、簡単にJSON文字列が取り出せるようになっています。

    private void printRequestBodyJsonForDebug(RequestBase request) {
        //for debug
        Logger.log("** Debug print start **");
        Logger.log(request.toString());
        Logger.log("** Debug print finish **");
    }

実際の出力内容は次のようになります。

PutIndexTemplateRequest: PUT /_index_template/wikipedia-index-template {"index_patterns":["wikipedia-*"],"template":{"mappings":{"properties":{"images":{"type":"nested","properties":{"target_type":{"type":"keyword"},"link_target":{"type":"keyword"},"taget":{"type":"keyword"},"text":{"type":"text","fields":{"keyword":{"type":"keyword","ignore_above":256}},"analyzer":"kuromoji"}}},"contents":{"type":"text","fields":{"keyword":{"type":"keyword","ignore_above":256}},"analyzer":"kuromoji"},"headings":{"type":"text","fields":{"keyword":{"type":"keyword","ignore_above":256}},"analyzer":"kuromoji"},"links":{"type":"nested","properties":{"link_target":{"type":"keyword"},"text":{"type":"text","fields":{"keyword":{"type":"keyword","ignore_above":256}},"analyzer":"kuromoji"}}},"id":{"type":"keyword"},"categories":{"type":"keyword"},"title":{"type":"text","fields":{"keyword":{"type":"keyword","ignore_above":256}},"analyzer":"kuromoji"},"revision_id":{"type":"keyword"},"timestamp":{"type":"date"}}},"settings":{"number_of_shards":"3","number_of_replicas":"0","refresh_interval":"0"}}}

最初にクラス名: があり、移行がKibanaのDev Toolですぐ使える形式になっています（リクエストボディのJSONの前で改行するだけ）。デバッグや確認などが簡単にできそうですね。

変更された時のPull Requestは次のものになります。

Add toString() implementations by swallez · Pull Request #269 · elastic/elasticsearch-java

プラグインなどで提供されるクエリが書けない

Elasticsearchはプラグインを使って拡張することができ、LtRプラグインなどでは、クエリの拡張が行われています。

以前調査したタイミングではelasticsearch-specificationで定義されたリクエストしか受け取れない実装になっていました。 v8.5（実際には8.4.xにバックポートされている）からは、プラグインなどが追加しているクエリなどのカスタムな記述ができるようになっています。

_custom()というメソッドが各所に追加されており、これを利用することで定義にないJSONの属性などが追加できるようになっています。公式ドキュメントにも利用方法が追加されています。

Variant types | Elasticsearch Java API Client ［8.12］ | Elastic

レスポンスでも同様に_custom()が追加されており、プラグイン独自のレスポンス形式などにも対応できます。

変更された時のPull Requestは次のものになります。

Add support for plugin-defined custom components in union types by swallez · Pull Request #370 · elastic/elasticsearch-java

それ以外に変更されたポイント

各バージョンで導入された変更点がリリースハイライトとしてドキュメントにまとめてあります。いくつかピックアップして簡単に紹介します。

BulkIngesterヘルパーの追加（8.7）

Bulk APIをより楽に利用することができるヘルパークラスです。Pythonのクライアントにあったstreaming_bulkなどに似ています。どのくらいの数・サイズの操作をまとめて送るか、定期的にrefreshするのか？などを設定してインスタンスを作った後は、インスタンスにadd()していくと、指定されたタイミングで定期的にBulkのリクエストを送信してくれます。自分でループを回しながら定期的にAPIをたたくよりも便利です。詳細についてはドキュメントがあるので参考にしてください。

Bulk： indexing multiple documents | Elasticsearch Java API Client ［8.12］ | Elastic

OpenTelemetry対応（8.10）

OpenTelemetryを利用してトレースすることができるようになっています。JavaクライアントからEsへのHTTPのリクエストの処理時間やリクエスト本体をスパンに含めてくれるようになっています。自分たちのプロジェクトがOpenTelemetryを利用していれば、Esのリクエストに関連する部分が追加でとれるようになっています。詳細は公式ドキュメントに利用方法が記載されています。

Using OpenTelemetry | Elasticsearch Java API Client ［8.12］ | Elastic

まとめ

約2年ぶり触ってみると、さらに便利になっていました。前回はカスタムパラメータが利用できないなど、切り替えできない可能性もありましたが、だいぶ問題点は減っていそうです。

とはいえ、利用しようとしている機能が使えない、バグなどがあるかもしれないので、何か気になる点があった場合は、Issueのリストをチェックするのがいいでしょう。

Issues · elastic/elasticsearch-java

とくに、新しくElasticsearchでリリースされたけど、Javaクライアントにはまだ利用できないパラメータなどが時々あります。ということで、簡単ですが補足情報でした。

参考

Elasticsearchの新しいJavaクライアント

Mon, 13 Jun 2022 20:24:06 +0900

7.16で正式リリースされましたが、Elasticsearchの新しいJavaのクライアントが出ています。使ってみたので、ちょっとだけ紹介でもしてみようかな。

このクライアントが出るまでは、ElasticsearchのJavaクライアント（REST版）はElasticsearch本体の一部として実装・管理されていました（Elasticsearchのリポジトリにあるclientディレクトリ）。

HTTP経由でElasticsearchにアクセスするクライアントだったのですが、Elasticsearch本体のリポジトリで管理されていることもあり、Elasticsearch本体で利用されているクラスを使用していました。このため、クライアントライブラリなのですが、Elasticsearch本体のJarが必要になりサイズが大きくなっていました。また、JavaのObjectへの詰め替えなどの機能も備えておらず、すこし古臭い感じでもあります。この辺りを刷新する目的もあり新しいクライアントが公開されたようです。 3月くらいに触った時はまだ、ドキュメントが揃ってなかったのですが利用方法などが増えているので移行も楽になってきているようです。根本的に作り直されたため、これまでのREST Clientとは使い方が違います。ですので、jarだけの差し替えでこれまで動いていたプログラムを移行ができるわけではないので注意が必要です。

どの辺が便利？

順次移行が可能

これまでのRESTクライアントとはパッケージ名もjarも別モノになっています。ですので、少しずつ新しいJava Clientに切り替えていくことが可能になっています。根本的に使い方が変わっているので、大きなシステムのクライアントを全部切り替えるのは結構大変かと思います。ですので、Indexをしている部分だけとか、検索部分だけなどといった部分的な置き換えをしつつ新しいクライアントに慣れていくことができます。

ラムダっぽく書ける

検索のクエリのサンプルを見るとわかりますが、こんな感じでクエリが書けます(公式ドキュメントより抜粋)。

SearchResponse<Product> response = esClient.search(s -> s
    .index("products") 
    .query(q -> q      
        .match(t -> t   
            .field("name")  
            .query(searchText)
        )
    ),
    Product.class      
);

また、最後で渡しているProduct.classは、検索結果をどのクラスのインスタンスにして返すかの指定です。 Elasticsearchのレスポンス（JSON）から値をコピーして返してくれるようになっています。ですので、値を入れ替える処理を書く必要がなくなっています。

JSON文字列をそのまま使える

触り始めてからリリース（7.17.2より後なら使える）された、JSON文字列からリクエストを作る機能もあります。

これまでのREST Clientだと、Elasticsearchへのリクエストを必ずJavaのメソッドで構築する必要がありました。今回のこの機能を利用すると、JSON文字列（やファイル）からリクエストオブジェクトを作るためのメソッド.withJson()が提供されています。例えば、スキーマや設定変更用のリクエストのJSONなどは、Kibanaやcurlから試験的に投げたリクエスト（JSON）と同じものを使いたいことが多いです。また、ElasticsearchのAPIは数が多く、ドキュメントを見ながら利用方法を調べてJSONでまず試行錯誤することが多いです。このwithJsonメソッドを利用することで、動作確認などをしたJSONがそのままソースにも利用できるので、リクエスト変更時の確認なども容易になると思います。

使ってみて困ったのは？

便利な面も多いのですが、使っていて少し困ったこともあったのでそれもメモを残しておきます。

どんなリクエストを投げているかが不明

先ほども書きましたが、Elasticsearchのリクエストを試行錯誤するときは公式ドキュメントを見ながら、Kibanaなどを利用して試すことが多いです。ですので、自分がやりたいことのJSONは手元にあることが多いです。ただ、プログラムでクエリを組み立てる必要も出てきます。この時、実際にRESTリクエストとしてどんなJSONを投げているのかを知りたいことがあります（実際、検索クエリ作っててメソッドの使い方がうまくいかなくて四苦八苦してました）。 4月時点では簡単にリクエストで投げているJSONを文字列としてログに出すメソッドなどは用意されていないようでした。デバッグ用に次のようなメソッドを書いてみました。 Elasticsearchへ投げるRequestのクラス（例：CreateTemplateRequestとか）を引数に渡すことで、JSON文字列に変換できるようになっています（StringWriterに書き出されてる）。ここのLoggerはサンプルです。writer.toString()で取り出せる文字列がJSON文字列になっているので、ログに出してみるなり、ファイルに落とすなりしてデバッグのお供にしてください。


import java.io.StringWriter;
import co.elastic.clients.elasticsearch._types.RequestBase;
import co.elastic.clients.json.SimpleJsonpMapper;
import jakarta.json.stream.JsonGenerator;


...
    private void printRequestBodyJsonForDebug(RequestBase request) {

        //for debug
        Logger.log("** Debug print start **");
        StringWriter writer = new StringWriter();
        SimpleJsonpMapper mapper = new SimpleJsonpMapper();
        JsonGenerator generator = mapper.jsonProvider().createGenerator(writer);
        mapper.serialize(request, generator);
        generator.close();
        Logger.log(writer.toString());
        Logger.log("** Debug print finish **");
    }

プラグインなどで提供されるクエリが書けない

LtRプラグインなどは、Elasticsearchの検索クエリを拡張しています。残念ながら、現時点（2022/06/13）ではカスタムクエリを新しいJavaクライアントで利用しようとした場合、エラーが発生してしまいます（知らないJSONだと判断されてしまいます）。

GitHubのIssueとして「［roadmap］ Add support for plugin-defined custom components · Issue #252 · elastic/elasticsearch-java」があります。これに対応されたら、拡張されたクエリも利用できるようになるでしょう。プラグインなどで拡張されているものを使いたい場合は、残念ながら既存のRESTクライアントを当面は使うことになりそうです。

まとめ

新しいElasticsearchのJavaクライアントを簡単ですが触ってみて、気になった点を記事にしました。 JavaのObjectに詰め替えてくれる機能など便利になっているので使ってみてください。ドキュメントもちょっとずつ増えているようで、使い方も分かりやすくなっていました（触った時はレスポンスの扱い方などがJavaDocしか用意されてなかったんです）。説明が欲しいなぁと思うことがあれば、GitHubにIssueを上げてみるといいかもです。

参考

JVM Operation Casual Talksに参加しました #jvmcasual

Mon, 07 Apr 2014 19:24:00 +0900

JVM Operation Casual Talksに参加しました。あんまり、運用とかやってないので、ついていけるか不安ですが、楽しそうだったので。懇親会は予定されてないらしい。

@stanaka 15分でわかるJVMのメモリ管理

スライド：https://speakerdeck.com/stanaka/understanding-memory-management-of-javavm-in-15-minutes

JVMの基礎知識
某研究所で。。。
Elasticsearch、Solrの名前が！
JVM困りどころ。ネットの情報が古いのが多いとか。
使いこなすにはきちんと知識が必要。

Memory Model

困ったらJava8に。。。
Heapのチューニングが重要
Heapの構成やGC処理の説明
CMSでもすべて並列ではない
- OlgGenがフラグメントして確保が遅くなっていく
G1GCの概念図。YoungやOld、Survivorの区別がない？
- リージョン？
リファレンスリストすばらしい。

@oranie Cassandra運用で実施しているJVM監視について

スライド：http://www.slideshare.net/oranie/jvm-operation-casual-talks-33218856

Cassandra(1.1)で運用中。
35TBとか
エンジニアブログ読め。
Cassandraの監視って何すればいいの？
GC頻度とかグラフで見れる
VisualVM便利って教えてもらった。
- VisualVMでどんな値があるか見ながら調べて、取りたい値を考える。
SNMPで頑張るの辛い＝JMXかな？＝Javaで叩くの？＝Jolokia
どんなことやってる？
- Nagios+Jenkins＋。。。あとでスライド
yohoushi+GrowthForecastも便利。

@waysaku Spray(Akka)運用でJVMをCPUスケールさせるために行った事

スライド：http://www.slideshare.net/waysaku/jvm-operation-casual-talks

Spray
Akkaアプリケーションの運用を任されちゃった人
カットオーバー直前の負荷試験でびっくりするくらいスループットでない。。。
- いろんなActorが特定のActorに処理を投げた状態で待ってるという状況。。。
- スレッドダンプ追っかけてる様子を追体験してる。
- ログ出力がBLOCKしてた
- I/Oを伴う処理は非常にセンシティブ