こんばんは。torippy1024です。
Splunkにはlookupという機能があるのですが、何かどう役に立つのか、説明を読んでも初心者には理解しづらいです。
またしても公式チュートリアルまんまで恐縮なのですが、実機で作業することによって理解できるようになるため、その手順を書いてみました。
(厳密には、lookupにもいくつかの種類がありますが、今回はCSV lookupのみを対象とします。詳しい説明は以下のリンクも参照してください https://docs.splunk.com/Documentation/SplunkCloud/9.1.2308/Knowledge/Aboutlookupsandfieldactions)
CSV Lookup機能とは
CSV Lookupとは、Lookup TableというテーブルをあらかじめSplunk内部に定義(設定)しておき、呼び出すことで、ある値(例えばproduct_name=Dream Crusher)を表示する際、Lookup Table内に存在するFieldと値(例えばprice=39.99)を参照(Lookup)させることができるという機能です。
Lookup Tableファイルをアップロードすることでこの機能が実現できます。
・・・・・・と言っても文字だけではよくわからないので、以下のように図示してみました。
一言で言えば、Excelのlookup関数と同じことができる機能というわけです。Lookup Tableは、lookupによって参照するテーブルのことを指しています。
厳密には、サーチ結果にキーであるproductIdが含まれている必要はなく、インデックス内部のイベントにproductIdが含まれていればlookupを利用することは可能です。
そして用語として難しい点があり、Splunkでは、CSV等でルックアップテーブルが記述されたデータファイルをLookup Tableファイルと呼びます。これに対し、Lookup TableファイルをSplunkにインポートし、Splunkが利用できる形式に変換した定義を、Splunkではルックアップ定義と呼んで区別しています。
つまり、Lookup TableファイルをSplunkに単にインポートしただけでははただのファイルアップロードと変わらず、その後、Lookup Tableファイルをルックアップ定義に変換することで初めてルックアップ定義が利用可能となるのです。
Lookup機能を使うための手順
Lookup機能を使うための手順はちょっと面倒です。
具体的には、以下の流れで作業をする必要があります。
- Lookup Tableファイル(CSV)を用意する。
- ルックアップファイルをSplunkにアップロードする。
- Splunk上でアップロードしたファイルを共有する。
- Splunk上でルックアップ定義を作成する。
- Splunk上でルックアップ定義を共有する。
- ルックアップ定義を⾃動化する。(任意なので必須ではない)
1,2は容易に理解できると思われますが、3からが初心者には難解です。
3は、アップロードしたLookup Tableファイルのファイル読み取り権限は、デフォルトではアップロードしたユーザーおよびアップロード時に指定したSplunkアプリのみとなっています。この場合、ルックアップテーブルを参照できるユーザーやSplunkアプリが極めて限定された状態であるので、これを他のユーザーやSplunkアプリからも参照できるように、権限をグローバルレベルに変更する作業を指します。
4は、Lookup Tableファイルは、アップロードしただけではただのファイルでしかありません。これをSplunkがLookup機能として使えるための定義としてSplunkに認識させる作業を示しています。
5は、3と同じく、デフォルトでは作成したルックアップ定義は、定義を作成したユーザーおよび定義作成時に指定したSplunkアプリのみとなっているため、この権限をグローバルレベルに変更する作業を指します。
6は、ルックアップ定義を頻繁に使う場合、いちいちSPLでlookupコマンドを指定するのは面倒なので、lookupコマンドを省略して常にlookupが実行されている状態にするための作業です。こちらにも共有(グローバルレベルへの権限変更)作業が含まれます。
Lookup機能を使ってみる
まずデモ環境を構築します。以下の記事を参考にして、tutorialdata.zipのアップロードまでを実行してください。といっても、やるべきことはSplunk Cloudのトライアル環境を構築して、tutorialdata.zipをアップロードするだけです。
【Splunkデモ】Splunkことはじめ〜初心者が作るデモ環境構築〜
https://qiita.com/torippy1024/items/bb59154918b0d2aabe29
それから1~6の作業を行います。が、本作業はチュートリアルまんまなので、困ったらチュートリアルを参照してください。
https://docs.splunk.com/Documentation/SplunkCloud/9.1.2308/SearchTutorial/Usefieldlookups
1. Lookup Tableファイル(CSV)を用意する
tutorialdata.zipと一緒にダウンロードしたPrice.csv.zipを解凍します。
すると、price.csvという名前のLookup Tableファイルを取得できます。このLookup Tableファイルを使ってルックアップ機能を試します。
(https://docs.splunk.com/Documentation/SplunkCloud/latest/SearchTutorial/Systemrequirements#Download_the_tutorial_data_files)
Price.csv.zipを回答するとCSVファイルが得られます。中身は以下のようになっています。
| productId | product_name | price | sale_price | Code |
|---|---|---|---|---|
| DB-SG-G01 | Mediocre Kingdoms | 24.99 | 19.99 | A |
| DC-SG-G02 | Dream Crusher | 39.99 | 24.99 | B |
| FS-SG-G03 | Final Sequel | 24.99 | 16.99 | C |
| WC-SH-G04 | World of Cheese | 24.99 | 19.99 | D |
| : | : | : | : | : |
ここでポイントとなるのが、productIdはtutorialdata.zip内のログに含まれているFieldであるが、product_name、priceは、ログから自動抽出されていないFieldであるということです。
product_Id=DB-SG-G01であるログが含まれている際に、このLookup Tableで定義したproduct_name、priceをLookupして参照することができるというのがLookup機能です。
2. ルックアップファイルをSplunkにアップロードする
Splunk Cloudのログイン画面上のメニューバーより、「Settings」 > 「Lookups」を選択した後「Lookup table files」の右にある「Add new」を選択します。
次に、Add new画面にて、以下の通り指定します。
| 項目 | 入力する項目 | 意味 |
|---|---|---|
| Upload the lookup files | prices.csv | アップロードするLookup TableファイルのローカルPC上の名前 |
| Destination filename | prices.csv | アップロードしたLookup TableファイルのSplunk上の名前 |
入力画面は以下のようになります。
(画像引用元：https://docs.splunk.com/Documentation/SplunkCloud/latest/SearchTutorial/Searchwithfieldlookups)
無事に成功すると、Lookup table files一覧画面にて、今アップロードしたprices.csvが登録されていることが確認できるようになります。
3. Splunk上でアップロードしたファイルを共有する
Splunk Cloudのログイン画面上のメニューバーより、「Settings」 > 「Lookups」を選択した後「Lookup table files」を選択します。または、アップロードした直後であればLookup table files画面がそのまま表示されています。
先ほどアップロードしたprices.csvのSharing列の値を見ると、他ファイルがGlobalとなっているのに対し、このファイルはPrivateとなっていることがわかります。これを編集します。「Permission」をクリックし、「Object should appear in」で「All Apps(System)」を選択してSaveすれば完了です。
以下の画像のように、Sharing列が「Global」となります。
(画像引用元：https://docs.splunk.com/Documentation/SplunkCloud/latest/SearchTutorial/Searchwithfieldlookups)
4. Splunk上でルックアップ定義を作成する
Splunk Cloudのログイン画面上のメニューバーより、「Settings」 > 「Lookups」を選択した後「Lookup definitions」の右にある「Add new」を選択します。
次に、Add new画面にて、以下の通り指定します。
| 項目 | 入力する項目 | 意味 |
|---|---|---|
| Name | prices_lookup | ルックアップ定義の名前 |
| Lookup file | prices.csv | アップロードしたLookup Tableファイル |
入力画面は以下のようになります。
(画像引用元：https://docs.splunk.com/Documentation/SplunkCloud/latest/SearchTutorial/Searchwithfieldlookups)
無事に成功すると、Lookup definitions一覧画面にて、今作成したprices_lookupが登録されていることが確認できるようになります。
5. Splunk上でルックアップ定義を共有する
なんかもう同じような作業ばっかりやっていますが、Splunk Cloudのログイン画面上のメニューバーより、「Settings」 > 「Lookups」を選択した後「Lookup definitions」を選択します。または、ルックアップ定義を作成した直後であればLookup definitions画面がそのまま表示されています。
数が多いので、ページを次のページに移動させないと見えない可能性があります。
Lookup Tableファイルの時と同じく、Sharing列がPrivateとなっているため、これを編集します。「Permission」をクリックし、同じく「Object should appear in」で「All Apps(System)」を選択してSaveすれば完了です。
(画像は省略します)
6. ルックアップ定義を⾃動化する。(任意なので必須ではない)
最後にルックアップの自動化です。本来、Lookupを使うときはコマンドを指定して実行するのですが、いちいちこれを指定するのは面倒なので、自動でSplunkがルックアップを実行してくれるようにします。
Splunk Cloudのログイン画面上のメニューバーより、「Settings」 > 「Lookups」を選択した後「Automatic lookups」の右にある「Add new」を選択します。
次に、Add new画面にて、以下の通り指定します。
| 項目 | 入力する項目 | 意味 |
|---|---|---|
| Name | autolookup_prices | 自動ルックアップの名前 |
| Lookup Table | prices_lookup | ルックアップ定義名の指定 |
| Apply to | sourcetype, access_combined_wcookie | 対象の指定。今回はsourcetype=access_combined_wcookieを指定 |
| Lookup input fields | productId, productId | Lookupを実行する際に指定するフィールド。今回はproductIdをキーとしてLookup Table内部を検索する |
| Lookup output fields | product_name, productName | Lookupによって取得するフィールド。これは、Lookup Table内部のproduct_nameを、productNameとして利用することを意味する |
| Lookup output fields | price, price | Lookupによって取得するフィールド。これは、Lookup Table内部のpriceを、同じくpriceとして利用することを意味する |
入力画面は以下のようになります。
(画像引用元：https://docs.splunk.com/Documentation/SplunkCloud/latest/SearchTutorial/Searchwithfieldlookups)
無事に成功すると、Automatic lookups一覧画面にて、今作成した自動ルックアップ定義が登録されていることが確認できるようになります。
これまでと同様に、権限設定の変更も必要です。Automatic lookups一覧画面から、作成した定義「access_combined_wcookie : LOOKUP-autolookup_prices」のSharing列にある「Permission」をクリックし、「Object should appear in」で「All Apps(System)」を選択してSaveします。
Lookup機能の実行
以上の操作によって、自動ルックアップが実行されるようになりました。
まず、実際に自動ルックアップが動作しているか確認してみます。以下のSPLを実行して、sourcetypeがaccess_で始まり、productIdというフィールドが含まれるイベントを表示します。
sourcetype=access_* productId="*"
(余談ですが、productId="*"を省略した場合、productIdというフィールドが含まれないイベントも表示されることになります。productId="*"を指定することで、productIdというフィールドを含むイベントのみを表示させることができます)
(本画像のみ、引用でなく自分で取得したスクリーンショットです)
出力結果のInteresting Field(日本語だと"関連するフィールド")を見ると、priceとproductNameというフィールドが表示されていることがわかります。これは、自動ルックアップを作成する前は表示されないフィールドです。このフィールドが表示されているようになっていれば、問題なく自動ルックアップの設定ができていることになります。
次に、以下コマンドを実行してみます。これによって、製品名と価格が一覧で表示されます。
sourcetype=access_* |stats values(price) AS Price BY productName |rename productName AS "Product Name"
(画像引用元：https://docs.splunk.com/Documentation/SplunkCloud/latest/SearchTutorial/Searchwithfieldlookups)
ちなみに、|rename AS "Product Name"は、出力されたproductNameというフィールドをProduct Nameにリネームしているだけなので、あまり気にしなくていいです。またAS Priceというオプションも、values(price)という出力フィールドをPriceにリネームしているだけなので気にしないほうが良いと思います。
単純に自動ルックアップ機能が動作していることを確認するだけであれば、以下のコマンドだけ実行するほうがわかりやすいかもしれません。
sourcetype=access_* |stats values(price) BY productName
ちなみに、上記が実現できるのは、裏で自動ルックアップ機能が動作しており、productIdを含むイベントに対し、自動でルックアップが行われ、product_nameとpriceが取得されているためとなります。
自動ルックアップを指定しないでコマンドを実行する方法もあります。その場合のコマンドは以下です。
(実際に、自動ルックアップを削除するなりして試してみてください)
sourcetype=access_* | lookup prices_lookup productId | stats values(price) BY productName
パイプで渡した先のlookupコマンドで指定するオプションは、ルックアップ定義名でもいいですし、ルックアップテーブル名でもいいです。以下でも結果は同じになります。
sourcetype=access_* | lookup prices.csv productId | stats values(price) BY productName
Lookup機能のユースケース
Lookupは、Splunkに取り込んだログに含まれない情報を追加して、Splunk上のサーチ結果に表示させるための機能の一つです。
例えばログに含まれない機器のロケーションや拠点名、製品の標準価格などがそれに該当します。
一つ注意しなければならないのは、「CSV lookup機能によって参照するテーブルは、基本的に更新頻度が低く小規模なデータにするのがよい」ということです。
製品の標準価格などはあまり更新されない情報ですが、セールス価格などは時期によって変動する可能性があります。こういった更新処理が発生する場合、Lookup Tableファイルを書き換える必要があるのですが、この場合、SplunkにアップロードしたCSVファイルを直接書き換えることはできません。ローカル上でCSVファイルを書き替え、Lookup Tableファイルを一括更新する必要があるためやや手間がかかります。
またCSV lookupは、大規模なデータを取り扱う場合、処理負荷が高くなります。
頻繁に更新する情報があったり、大規模なデータを使う場合、KV Store lookup機能を使うほうがよい可能性が高いです。
https://docs.splunk.com/Documentation/Splunk/9.2.2/Knowledge/DefineaKVStorelookupinSplunkWeb
以上です。