KibanaのスクリプトフィールドでPainlessを使用する

KibanaはElasticsearchに保存されたデータを検索して可視化するための強力な機能を備えています。Kibanaでは、可視化するために、Elasticsearchマッピングで定義されたフィールドを検索し、グラフを作成しているユーザーにそのフィールドをオプションとして表示します。スキーマで重要な値を別のフィールドとして定義することを忘れた場合はどうなるでしょうか？あるいは、2つのフィールドを結合し、そのフィールドを1つのフィールドとして処理したい場合はどうすればよいでしょうか？そこで、Kibanaのスクリプトフィールドの出番です。

実際には、スクリプトフィールドはKibana 4という早い段階から導入されてきました。スクリプトフィールドが導入されたときには、フィールドを定義する方法は、数値の処理しか行わない、Elasticsearchのスクリプト言語であるLucene Expressionsを使用するしかありませんでした。このため、スクリプトフィールドの能力は、一部のユースケースに限られていました。Elasticsearchは、5.0でPainlessを導入しました。これは安全かつ強力なスクリプト言語であり、さまざまなデータ型に対応します。このため、Kibana 5.0のスクリプトフィールドの能力が大幅に向上しました。

このブログでは、ここから、一般的なユースケースでスクリプトフィールドを作成する方法について説明します。そのために、Kibana基本操作チュートリアルのデータセットを利用し、Elastic Cloudで実行されているElasticsearchとKibanaのインスタンスを使用します。Elastic Cloudは無料で導入できます。

次の動画では、Elastic Cloudで個人用のElasticsearchとKibanaのインスタンスを設定し、サンプルデータセットをそのインスタンスに読み込む方法について説明します。

スクリプトフィールドの仕組み

Elasticsearchでは、すべてのリクエストでスクリプトフィールドを指定できます。Kibanaはこの点について改善を進め、［管理］セクションで1度スクリプトフィールドを定義すると、その後はUIの複数の場所でそのフィールドを使用できるようになりました。Kibanaでは、スクリプトフィールドは、.kibanaインデックスの他の構成と一緒に保存されます。この構成はKibana固有の構成であり、KibanaのスクリプトフィールドはElasticsearchのAPIユーザーには公開されません。

Kibanaでスクリプトフィールドを定義するときには、スクリプト言語を選択できます。動的スクリプトが有効なElasticsearchノードにインストールされているすべての言語の中から選ぶことができます。5.0のデフォルト言語は「expression」と「painless」です。2.xでは「expression」だけでした。他のスクリプト言語をインストールし、動的スクリプトを有効化できますが、十分にサンドボックスでテストができず、廃止予定になっているため、この方法は推奨されません。

スクリプトフィールドは一度に1つのElasticsearchドキュメントでしか動作しませんが、そのドキュメントの複数のフィールドを参照する場合があります。このため、スクリプトフィールドを使用して、1つのドキュメント内でフィールド結合または変換するか、複数のドキュメントに基づいた計算（例：時系列演算）を実行しないことをお勧めします。PainlessとLuceneの両方で、式はdoc_valuesに格納されたフィールドで動作します。このため、文字列データでは、データ型キーワードに格納される文字列が必要です。Painlessに基づくスクリプトフィールドは、直接on _sourceでも動作しません。

スクリプトフィールドが［管理］で定義されると、ユーザーはKibanaのその他のフィールドと同じ方法でスクリプトフィールドを操作できます。スクリプトフィールドは自動的にDiscoverのフィールドリストに表示され、Visualizeで可視化を作成するために使用できます。Kibanaは、クエリ実行時に、評価対象のスクリプトフィールド定義をElasticsearchに渡すだけです。結果のデータセットはElasticsearchから戻された他の結果と結合され、表またはグラフでユーザーに表示されます。

このブログの執筆時点では、スクリプトフィールドの操作時にいくつかの制限があることが確認されています。Kibanaビジュアルビルダーで使用できるほとんどのElasticsearch集約をスクリプトフィールドに適用できます。ただし、最も顕著な例外として、重要な用語の集約は除きます。また、Discover、Visualize、ダッシュボードのフィルターバーを使用して、スクリプトフィールドでフィルターを適応できますが、次のように、適切に定義された値を返す正しいスクリプトを作成するように注意する必要があります。さらに、次の「ベストプラクティス」セクションを参考に、スクリプトフィールドを作成するときに環境を不安定化させないことを確認することが重要です。

次の動画では、Kibanaを使用してスクリプトフィールドを作成する方法について説明します。

スクリプトフィールドの例

このセクションでは、一般的なシナリオで、Kibanaで使用されるLucene式とPainlessスクリプトフィールドの例をいくつか取り上げます。前述のように、これらの例は、Kibana基本操作チュートリアルのデータセットを基に作成されました。そして、前のバージョンでは、特定のタイプのスクリプトフィールドでフィルターと並べ替えに関連する問題がいくつか確認されているため、ElasticsearchとKibana 5.1.1を使用していることが前提となっています。

Elasticsearch 5.0ではLucene式とPainlessがデフォルトで有効化されているため、ほとんどの場合、スクリプトフィールドはそのままで動作します。ただし、唯一の例外として、フィールドを正規表現に基づいて解析する必要があるスクリプトがあります。このようなスクリプトでは、elasticsearch.ymlに「script.painless.regex.enabled: true」という設定を加え、Painlessで正規表現一致をオンにする必要があります。

単一のフィールドで計算を実行する

• 例：バイトからキロバイトを計算する
• 言語：式
• 戻り値の型：数値

 doc['bytes'].value / 1024

注：Kibanaのスクリプトフィールドは一度に1つのドキュメントでしか機能しないため、スクリプトフィールドで時系列演算を実行する方法はありません。

日付演算で数値を返す

• 例：日付を1日の時間に解析する
• 言語：式
• 戻り値の型：数値

Lucene式では、さまざまな日付操作関数をそのまま使用できます。ただし、Lucene式では数値のみが返されるため、文字列の曜日を返すには、Painlessを使用する必要があります（以下を参照）。

 doc['@timestamp'].date.hourOfDay

注：上記のスクリプトは1-24を返します

doc['@timestamp'].date.dayOfWeek

注：上記のスクリプトは1-7を返します

2つの文字列値を結合する

• 例：ソースとターゲット、または名と姓を結合する
• 言語：Painless
• 戻り値の型：文字列

 doc['geo.dest.keyword'].value + ':' + doc['geo.src.keyword'].value

注：スクリプトフィールドはdoc_valuesのフィールドで動作する必要があるため、上記の文字列の.keywordバージョンを使用しています。

ロジックの導入

• 例：10000バイトを超えるすべてのドキュメントで「big download」というラベルを返す
• 言語：Painless
• 戻り値の型：文字列

 if (doc['bytes'].value > 10000) { 
    return "big download";
}
return "";

 def path = doc['url.keyword'].value;
if (path != null) {
    int lastSlashIndex = path.lastIndexOf('/');
    if (lastSlashIndex > 0) {
    return path.substring(lastSlashIndex+1);
    }
}
return "";

if (doc['referer.keyword'].value =~ /jp/error/) { 
return "error"
} else {
return "no error"
}

def m = /^.*\.([a-z]+)$/.matcher(doc['host.keyword'].value);
if ( m.matches() ) {
   return m.group(1)
} else {
   return "no match"
}

 def m = /^([0-9]+)\..*$/.matcher(doc['clientip.keyword'].value);
if ( m.matches() ) {
   return Integer.parseInt(m.group(1))
} else {
   return 0
}

LocalDateTime.ofInstant(Instant.ofEpochMilli(doc['@timestamp'].value), ZoneId.of('Z')).getDayOfWeek().getDisplayName(TextStyle.FULL, Locale.getDefault())