ElasticSearchのDemo環境で、cat APIについて学んでみた

DA事業本部の横山です。

ElasticSearchでは、公式でDemo環境が提供されています。 KibanaのDevToolsを使えるので、ElasticSearchのcat APIの使い方について学んでみます。

Demo環境

今回の記事で利用しているDemo環境のDevToolsのConsoleは以下です。

画面の左側の領域にクエリ文字列を入力して実行することで、Kibanaが連携しているElasticSearchに対してクエリを発行して結果を返してくれます。

また、該当APIのドキュメントを参照する、リクエスト履歴を確認すること等もできます。

cat APIとは

REST APIなどで返却されるJSONは、コンピュータにとても整理されていて扱いやすいですがデータを俯瞰しようとすると難しい場合があります。そのため、人間の目で確認しやすいようなテキストを返してくれるのがcat APIです。 クラスタの状況やインデックス、ドキュメント数など様々なことが確認できます。

cat APIs are only intended for human consumption using the Kibana console or command line. They are not intended for use by applications. For application consumption, we recommend using a corresponding JSON API.

cat APIは、Kibanaコンソールまたはコマンドラインを使用して人間が利用することのみを目的としています。これらは、アプリケーションによる使用を意図していません。アプリケーションで利用する場合は、対応するJSON APIを使用することをお勧めします。

上記のように、ドキュメントに記載があるためあくまでDevTools上でElasticSearchの状態を確認するために利用し、cat APIをアプリケーションに組み込むことは避けましょう。

基本的な構文は以下のようなものです。

GET _cat/<target>?<get_paramters>

実際にたたいてみる

今回は、cat indices APIを例にして確認してみたいと思います。

まずはそのまま叩いてみます。

GET _cat/indices

green open .ds-filebeat-8.6.1-2023.03.23-000083                               1yxHw2m8Tm2ajG2Mv2S_sA 1 1
green open .ds-metrics-elastic_agent.metricbeat-default-2023.02.07-000001     uvS5l31YSoKK6dllmHrapQ 1 1
green open .ds-metrics-kubernetes.system-default-2023.02.07-000001            0r8ERKAgS1qJzCFPTKlqrg 1 1
...以下省略

ElasticSearchに登録されているindexの一覧が取得できたようです。しかし、greenやopen,1yxHw2m8Tm2ajG2Mv2S_sAといった値が何を示しているのかよくわかりません。

Verboseパラメータを渡せばheaderも含めて表示してくれるので足してみます。

GET _cat/indices?v=true

health status index                                                              uuid                   pri rep docs.count docs.deleted store.size pri.store.size
green  open   .ds-metrics-system.cpu-default-2023.03.09-000002                   MX0Am-qnSdqWbvABVlmIRg   1   1
green  open   .ds-logs-enterprise_search.api-default-2023.03.21-000011           3NnpLZD4QpOj544AITxDXg   1   1
green  open   .ds-metrics-system.load-default-2023.02.07-000001                  Coh6ixQwR6-dmsQBFtfYIw   1   1
...以下省略

先ほどのレスポンスにheaderが追加されたことがわかります。greenやopen,1yxHw2m8Tm2ajG2Mv2S_sAはそれぞれ、indexのhealth,status,uuidを表していたことがわかりました。

cat indices APIでは、デフォルトでhealth,status,index,uuid,pri,rep,docs.count,docs.deleted,store.size,pri.store.sizeの情報を返すようですが、そのほかにもいろいろな情報をカラムとして表示させることができます。どういった値があるのか知りたい場合は、helpパラメータを使います。

GET _cat/indices?help

health                           | h                              | current health status
status                           | s                              | open/close status
index                            | i,idx                          | index name
uuid                             | id,uuid                        | index uuid
pri                              | p,shards.primary,shardsPrimary | number of primary shards
rep                              | r,shards.replica,shardsReplica | number of replica shards
...以下省略

利用可能なカラムに関する、パラメータ名と略称や別名, 概要が返却されました。デフォルトで返却されているカラム以外にも、要した時間やメモリ等の様々な情報を追加できることがわかりますね。

出力されるheader情報の指定してみます。

GET _cat/indices?h=index,docs.count&&v=true

index                                                              docs.count
.ds-traces-apm.rum-default-2023.02.23-000002                         16829719
.ds-metrics-kubernetes.proxy-default-2023.02.07-000001
.ds-metrics-system.socket_summary-default-2023.03.09-000002
...以下省略

index名とドキュメント数だけの情報を取得することができました。

次にソート条件を追加してみます。

indexに含まれるドキュメント数の降順、index名の昇順で取得してみます。

GET _cat/indices?s=docs.count:desc,index:asc&v=true

health status index                                                              uuid                   pri rep docs.count docs.deleted store.size pri.store.size
green  open   .ds-traces-apm-default-2023.02.23-000002                           fV6U4E3rTuu3acJ5vP9JlA   1   1  165938057            0    100.1gb           50gb
green  open   .ds-metrics-apm.internal-default-2023.02.23-000002                 BUW59fP6RFWldPTCna8trw   1   1   30321021            0     13.2gb          6.6gb
green  open   .ds-traces-apm-default-2023.03.21-000004                           ULeJ2NguSmeOYeacqsanXQ   1   1   19451299            0     11.9gb            6gb
...以下省略

指定したソートのレスポンスが取得できました。

store.size, pri.store.sizeの値がgbやmbで統一されていないため、出力する値の単位を指定してみます。どんな値が指定できるかはドキュメントに記載があります。

各数値のカラムに関して、Byte, 時間, 単位がない数量のデータに対して出力する単位を指定できるようです。今回はMB単位で出力するようにします。

GET _cat/indices?bytes=mb&s=docs.count:desc,index:asc&v=true

health status index                                                              uuid                   pri rep docs.count docs.deleted store.size pri.store.size
green  open   .ds-traces-apm-default-2023.02.23-000002                           fV6U4E3rTuu3acJ5vP9JlA   1   1  165938057            0     102535          51216
green  open   .ds-metrics-apm.internal-default-2023.02.23-000002                 BUW59fP6RFWldPTCna8trw   1   1   30325299            0      13599           6797
green  open   .ds-traces-apm-default-2023.03.21-000004                           ULeJ2NguSmeOYeacqsanXQ   1   1   19473958            0      12249           6197
...以下省略

gbやmbの単位表示は省略されてしまいましたが、すべての値をMB単位で統一して取得することができました。

ここまで、cat APIの目的である人が見やすいtext形式でレスポンスを取得してきましたが、cat APIでは以下の出力形式に対応しています。

• text
• json
• yaml
• smile
• cbor

cat APIで確認できるデータを手軽にプログラムから扱えるデータとして利用したい場合もあるとおもうので、今回はjson形式で返却してもらいましょう。 私はなじみがありませんでしたが、smile,とcborはバナリ形式となるようです。

GET _cat/indices?format=json

[
  {
    "health": "green",
    "status": "open",
    "index": ".ds-filebeat-8.6.1-2023.03.23-000083",
    "uuid": "1yxHw2m8Tm2ajG2Mv2S_sA",
    "pri": "1",
    "rep": "1",
    "docs.count": null,
    "docs.deleted": null,
    "store.size": null,
    "pri.store.size": null
  },
...以下省略

返却される情報がJSONフォーマットとなりました。「cat APIとは」の章で触れましたが、実際のアプリケーションで利用する場合は対応するJSON APIを使用することを検討しましょう。

cat APIを利用する上で、以下のような操作が可能であることが確認できました。

• ヘッダ情報の表示
  • v=true
• 表示可能なカラムの一覧取得
  • helpパラメータ
• 出力カラムの指定
  • h=
• ソート
  • s=:
• 表示単位の統一
  • =
• 出力形式の変更
  • format=

おわりに

ElasticSearchのDemo環境のKibana DevTools Consoleでcat APIについて学んでみました。 cat APIには、20種類程度のエンドポイントが用意されているので、上記のパラメータを用いて様々な情報の確認がしやすくなっていることがわかりました。 今後、ElasticSearchを利用する際に活用していきたいと思います。

以上になります。この記事がどなたかの助けになれば幸いです。