Taste of Tech Topics

Taste of Tech Topics

Acroquest Technology株式会社のエンジニアが書く技術ブログ

#Elasticsearch の cat APIs にまじめに入門する話

こんにちは、 @ です。

こちらはElastic stack Advent Calendarの9日目の記事となります。
qiita.com

Elasticsearchを構築・運用する際に頻繁に使うことになる cat APIsについて、その使い方をちゃんと知ってほしいとプロジェクトのメンバに思うことが増えてきましたので、アドベントカレンダーというイベントの力を借りてまとめておこう思います。

ことの起こり(スタート地点)

メンバに「cat indices でインデックス情報とって後でみせて」とお願いしたところ、次のような情報をもらいました。

yellow open  .monitoring-es-6-2017.12.09         EjmyMwfUR9GC7NpGE9J-Ew 1 1   339106 5678  226.7mb  226.7mb
green  open  report_attachment-2017.11.21        Z8Cptg_URveTYojN-PUeDg 1 0       66    0    1.1mb    1.1mb
yellow open  .watcher-history-3-2017.11.08       4yE6p3yrQ4WbRDr8Z6CHKw 1 1      660    0  617.2kb  617.2kb
green  open  report_attachment-2017.11.17        _t0M6p3HSj2SHX3TAraDtg 1 0      141    0    2.6mb    2.6mb
       close report_data-2017.11.13              6KO-h7faTU2_e472PEjwSQ                                    
green  open  report_attachment-2017.12           iE_4F5LLRISLuNIoXENCtg 1 0      154    0    2.4mb    2.4mb
yellow open  .watcher-history-3-2017.12.06       bnamUII8RHW0yqMtWS8xFg 1 1     7200    0    6.1mb    6.1mb
yellow open  .watcher-history-3-2017.12.05       GVDLk_p9T_6Mo2UNPw96PQ 1 1     7199    0    6.2mb    6.2mb
green  open  report_attachment-2017.11.14        WY8F_XBbRzKUqKUIh_fXrw 1 0       56    0      1mb      1mb
yellow open  .watcher-history-3-2017.10.26       bSAcokr1RsezlYVJTyzQQg 1 1     7200    0    5.8mb    5.8mb
yellow open  .watcher-history-3-2017.12.04       PkU3LewJR46a68dA8WUm1w 1 1     7200    0    6.1mb    6.1mb
yellow open  .watcher-history-3-2017.12.03       df6rtiv2SGKTWoP_G9S-8A 1 1     7200    0    6.1mb    6.1mb
yellow open  .watcher-history-3-2017.11.29       6HmPCZt8QUuMPeeKrZSa5w 1 1     7076    0    6.2mb    6.2mb
(略)

確かにお願いした通りの情報です。確かに。しかし・・・

  • 右から3番目のカラムって何の値だっけ?最後の2つのカラムの違いはなんだっけ?
  • データサイズがgb、mb、kbとなっているのは目視ではよいけど、計算したいときはどうしてくれる?
  • 最初からソートしてくれれば見やすいのに

などなど、実際にこの情報からあれこれ判断しようとすると情報が足りなかったり、データの取り回しが面倒だったりとで、困ってしまいました。

そこで、かく言う私自身も cat APIs をラフに使っていただけで、何ができるのか分かった上で頼んでいなかったことを反省し、一度ちゃんと何ができるのか調べることにしました。

ちゃんと cat indices の公式ドキュメントを読んでみる

そこでまずは、次の cat indices のドキュメントを読んでみましょう。

www.elastic.co

最初に出てくるのは次の例です。

GET /_cat/indices/twi*?v&s=index

こちら参考にして、次のように実行してみました。

GET _cat/indices?v&s=index
health status index                               uuid                   pri rep docs.count docs.deleted store.size pri.store.size
yellow open   .kibana                             pKQqx9GIQc-18XXQfZ9izQ   1   1         76            2    192.9kb        192.9kb
yellow open   .monitoring-alerts-6                ctx5fAJvRPyyrvQ5_2r90g   1   1          1            0     12.5kb         12.5kb
yellow open   .monitoring-es-6-2017.12.07         -T2tZg7mQASYINKzSglq-w   1   1    1036171         6130    620.7mb        620.7mb
yellow open   .monitoring-es-6-2017.12.08         350uCr70RqqxVQdAaa6dSA   1   1    1014396         6098      600mb          600mb
yellow open   .monitoring-es-6-2017.12.09         EjmyMwfUR9GC7NpGE9J-Ew   1   1     362824         6482    254.3mb        254.3mb
yellow open   .monitoring-kibana-6-2017.12.07     8vCosLHYRHmTplPwk5I34w   1   1       8633            0      3.5mb          3.5mb
yellow open   .monitoring-kibana-6-2017.12.08     1Ksw2PkOSsmh9beMxFg08g   1   1       8635            0      3.3mb          3.3mb
yellow open   .monitoring-kibana-6-2017.12.09     YxxKy594RAujnUBH-kwyqw   1   1       3043            0      1.3mb          1.3mb
yellow open   .triggered_watches                  txzhs8dCTnOvduA51onZFQ   1   1          0            0      3.2mb          3.2mb
yellow open   .watcher-history-3-2017.10.25       DF1MLpV2RxGRu-ASeb0e1g   1   1       4510            0      3.7mb          3.7mb
yellow open   .watcher-history-3-2017.10.26       bSAcokr1RsezlYVJTyzQQg   1   1       7200            0      5.8mb          5.8mb

出力にカラム名が表示されて、index名でソートされて表示されるようになりました。そうですよね。それくらいありますよね。

そのまま読み進めていくとソートオーダーを変更したり、表示項目を指定したりできるようです。ですよね。ですよね。

しかし、このドキュメントの中で紹介されている表示項目のところで手が止まってしまいました。

GET /_cat/indices/twitter?pri&v&h=health,index,pri,rep,docs.count,mt

「mt ? 」

GET /_cat/indices?v&h=i,tm&s=tm:desc

「tm ?」

それぞれ、merge操作の数やindex毎のメモリ量が分かるようなのですが、そもそもどんなカラムが存在するのかその先を読み進めても書いていません。
そもそも「v」とか「s」とかも、カラムヘッダの表示、ソートだとは内容からは分かるのですが、その説明自体は書いてありません。
これはつまり、もう一段階上のレベルのドキュメントがあるということだと思い、次のドキュメントを見ることにしました。

cat APIs の公式ドキュメントを読んでみる

Elasticsearchには cat indices を始めたとした、たくさんのcat APIがあります。その全体の最初にある cat APIs のドキュメントを読んでみましょう。

www.elastic.co

そうすると、「私が悪かったです」と反省したい気持ちになりますが、ちゃんと

  • Verbose(v)
  • Headers(h)
  • Sort(s)
  • Help
  • Numeric formats
  • Response as text, json, smile, yaml or cbor

について書かれており、help を使うことで各APIにおいてどのようなカラムが存在するかを確認でき、データ量の表現形式も bytes を使って統一できることが分かりました。

cat indices の使い方のまとめ

というわけで 、ここまで調べてきたことを踏まえて、次のように使ったらよいよ、というのをまとめます。

事前準備

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
docs.count                       | dc,docsCount                   | available docs
docs.deleted                     | dd,docsDeleted                 | deleted docs
(略)
merges.total                     | mt,mergesTotal                 | number of completed merge ops
pri.merges.total                 |                                | number of completed merge ops
(略)
segments.count                   | sc,segmentsCount               | number of segments
pri.segments.count               |                                | number of segments
segments.memory                  | sm,segmentsMemory              | memory used by segments
pri.segments.memory              |                                | memory used by segments
(略)
memory.total                     | tm,memoryTotal                 | total used memory
pri.memory.total                 |                                | total user memory

基本的な使い方

カラムヘッダの表示(v) 、表示したいカラムの指定(h) 、ソートオーダーの指定(s)を使いましょう。

GET _cat/indices?v&h=health,status,index,p,r,docs.count,docs.deleted,store.size,memory.total&s=docs.deleted:desc
health status index                               p r docs.count docs.deleted store.size memory.total
yellow open   .monitoring-es-6-2017.12.09         1 1     406248         6482    279.5mb        1.2mb
yellow open   .monitoring-es-6-2017.12.07         1 1    1036171         6130    620.7mb        2.6mb
yellow open   .monitoring-es-6-2017.12.08         1 1    1014396         6098      600mb        1.6mb
yellow open   .kibana                             1 1         76            2    192.9kb       23.8kb
green  open   report_data-2017.11                 1 0        144            1      1.6mb       27.2kb
green  open   report_data-2017.10.31              1 0          2            1     20.7kb       13.3kb
green  open   report_attachment-2017.11.21        1 0         66            0      1.1mb        6.6kb
yellow open   .watcher-history-3-2017.11.08       1 1        660            0    617.2kb       44.5kb
green  open   report_attachment-2017.11.17        1 0        141            0      2.6mb       18.8kb
green  open   report_attachment-2017.12           1 0        154            0      2.4mb        3.6kb
yellow open   .watcher-history-3-2017.12.06       1 1       7200            0      6.1mb       58.7kb
yellow open   .watcher-history-3-2017.12.05       1 1       7199            0      6.2mb      113.6kb
green  open   report_attachment-2017.11.14        1 0         56            0        1mb        4.5kb

これは削除フラグのついたドキュメント(docs.deleted)数を多い順に並べてみた例です。ソートの降順、昇順は desc 、 asc を付けることで制御できます。ソートに利用するカラムを複数指定することもできます。

数値のフォーマット指定

データサイズの量をMBで統一したい、というような時には bytes を指定しましょう。

GET _cat/indices?v&h=index,docs.count,docs.deleted,store.size,memory.total&s=docs.deleted:desc&bytes=mb
index                               docs.count docs.deleted store.size memory.total
.monitoring-es-6-2017.12.09             437754         6410        298            1
.monitoring-es-6-2017.12.07            1036171         6130        620            2
.monitoring-es-6-2017.12.08            1014396         6098        600            1
.kibana                                     76            2          0            0
report_data-2017.11                        144            1          1            0
report_data-2017.10.31                       2            1          0            0
report_attachment-2017.11.21                66            0          1            0
.watcher-history-3-2017.11.08              660            0          0            0
report_attachment-2017.11.17               141            0          2            0
report_attachment-2017.12                  154            0          2            0
.watcher-history-3-2017.12.06             7200            0          6            0
.watcher-history-3-2017.12.05             7199            0          6            0
report_attachment-2017.11.14                56            0          1            0

bytes の値には b, mb, gb などのように単位を指定できます。これまでとは異なりデータサイズの部分が数値のみになりました。これでExcelに貼ったときはそのまま計算できますね。

プライマリのみのデータサイズを表示する

priフラグを指定することで、プライマリのみのデータサイズを確認することができます。
priフラグを指定しない場合(デフォルト)ではレプリカも含んだ全体のデータサイズになっています。

GET _cat/indices?v&h=index,docs.count,docs.deleted,store.size,memory.total&s=docs.deleted:desc&pri
index                               docs.count docs.deleted store.size pri.store.size memory.total pri.memory.total
.monitoring-es-6-2017.12.09             439760         6482    299.8mb        299.8mb        1.1mb            1.1mb
.monitoring-es-6-2017.12.07            1036171         6130    620.7mb        620.7mb        2.6mb            2.6mb
.monitoring-es-6-2017.12.08            1014396         6098      600mb          600mb        1.6mb            1.6mb
.kibana                                     76            2    192.9kb        192.9kb       23.8kb           23.8kb
report_data-2017.11                        144            1      1.6mb          1.6mb       27.2kb           27.2kb
report_data-2017.10.31                       2            1     20.7kb         20.7kb       13.3kb           13.3kb
report_attachment-2017.11.21                66            0      1.1mb          1.1mb        6.6kb            6.6kb
.watcher-history-3-2017.11.08              660            0    617.2kb        617.2kb       44.5kb           44.5kb
report_attachment-2017.11.17               141            0      2.6mb          2.6mb       18.8kb           18.8kb
report_attachment-2017.12                  154            0      2.4mb          2.4mb        3.6kb            3.6kb
.watcher-history-3-2017.12.06             7200            0      6.1mb          6.1mb       58.7kb           58.7kb
.watcher-history-3-2017.12.05             7199            0      6.2mb          6.2mb      113.6kb          113.6kb
report_attachment-2017.11.14                56            0        1mb            1mb        4.5kb            4.5kb

試した環境(シングルノード)では差が出ませんが、「pri」が頭に付いた方がプライマリのみのデータサイズとなります。

indexを絞り込む

日単位のindexを作っていて、ある日だけのindexの情報がみたいというような時にindexを絞り込みたくなります。って、これは何も特別なことは不要で、単にindexパターンの指定をするだけです。

GET _cat/indices/*-2017.12.02?v&pri&h=health,status,index,p,r,docs.count,docs.deleted,store.size,memory.total&s=docs.deleted:desc
health status index                           p r docs.count docs.deleted store.size pri.store.size memory.total pri.memory.total
yellow open   .monitoring-es-6-2017.12.02     1 1      26905          112     17.9mb         17.9mb       88.8kb           88.8kb
yellow open   .monitoring-kibana-6-2017.12.02 1 1       1552            0      668kb          668kb         26kb             26kb
yellow open   .watcher-history-6-2017.12.02   1 1       1310            0        1mb            1mb       56.4kb           56.4kb

indexのhealthの状態で絞り込みたいときは、healthを使って絞り込みたい状態を指定します。

GET _cat/indices?v&health=yellow
health status index                               uuid                   pri rep docs.count docs.deleted store.size pri.store.size
yellow open   .monitoring-es-6-2017.12.09         EjmyMwfUR9GC7NpGE9J-Ew   1   1     444952         7688    303.3mb        303.3mb
yellow open   .watcher-history-3-2017.11.08       4yE6p3yrQ4WbRDr8Z6CHKw   1   1        660            0    617.2kb        617.2kb
yellow open   .watcher-history-3-2017.12.06       bnamUII8RHW0yqMtWS8xFg   1   1       7200            0      6.1mb          6.1mb
yellow open   .watcher-history-3-2017.12.05       GVDLk_p9T_6Mo2UNPw96PQ   1   1       7199            0      6.2mb          6.2mb
yellow open   .watcher-history-3-2017.10.26       bSAcokr1RsezlYVJTyzQQg   1   1       7200            0      5.8mb          5.8mb
yellow open   .watcher-history-3-2017.12.04       PkU3LewJR46a68dA8WUm1w   1   1       7200            0      6.1mb          6.1mb
yellow open   .watcher-history-3-2017.12.03       df6rtiv2SGKTWoP_G9S-8A   1   1       7200            0      6.1mb          6.1mb
yellow open   .watcher-history-3-2017.11.29       6HmPCZt8QUuMPeeKrZSa5w   1   1       7076            0      6.2mb          6.2mb
yellow open   .watcher-history-3-2017.11.28       leUNGN2uRyi76_fy_5zAOg   1   1       7200            0      6.2mb          6.2mb

こちらはindexの状態がyellowのものだけを表示しています。

終わりに

というわけで、 cat indices を例にして、cat APIs の使い方を見てきました。基本的には help でどのようなカラムが取得できるのか確認して、あとは表示項目絞ったり、ソートに使ったりしてください。

最後に重要なことを書いておきます。「公式のドキュメントをちゃんと読みましょう」と。

それでは!

Acroquest Technologyでは、キャリア採用を行っています。


  • ビッグデータHadoop/Spark、NoSQL)、データ分析(Elasticsearch、Python関連)、Web開発(SpringCloud/SpringBoot、AngularJS)といった最新のOSSを利用する開発プロジェクトに関わりたい。
  • マイクロサービスDevOpsなどの技術を使ったり、データ分析機械学習などのスキルを活かしたい。
  • 社会貢献性の高いプロジェクトや、顧客の価値を創造するようなプロジェクトで、提案からリリースまで携わりたい。
  • 書籍・雑誌等の執筆や、対外的な勉強会の開催・参加を通した技術の発信、社内勉強会での技術情報共有により、エンジニアとして成長したい。

 
少しでも上記に興味を持たれた方は、是非以下のページをご覧ください。
Elasticsearchを仕事で使いこみたいデータ分析エンジニア募集中! - Acroquest Technology株式会社のエンジニア中途・インターンシップ・契約・委託の求人 - Wantedlywww.wantedly.com