ルックアップ

このページの内容

1. ルックアップとは何か

ルックアップ(lookup)とは、外部のテーブル(対応表)を使って、イベントに情報を付け加える仕組みです。ログには含まれていない「意味」や「名前」を、別に用意した表から引っぱってきて補うイメージです。

たとえばWebアクセスログにはstatus=404という数字はあっても、「それが何を意味するのか(Not Found)」までは書かれていません。そこで「ステータスコードと説明文の対応表」を用意しておき、サーチのたびに説明文を付け足すのがルックアップの典型的な使い方です。

最も手軽なルックアップは、CSVファイルを対応表として使う「CSVルックアップ」です。上の表をそのままhttp_status.csvのようなCSVとしてSplunkに登録します。

http_status.csvの中身

status,status_description
        200,OK
        404,Not Found
        500,Internal Server Error

CSVをアップロードし、ルックアップ定義として名前を付けると、サーチからその名前で呼び出せるようになります。対応表の1列目(ここではstatus)が突き合わせの「キー」になり、残りの列(status_description)が付け加えられる情報になります。

ルックアップは「Settings > Lookups」から、(1) ルックアップテーブルファイル(CSV)と (2) ルックアップ定義を登録して使います。

登録したルックアップは、lookupコマンドで呼び出します。「どのルックアップを、どのフィールドをキーにして使うか」を指定します。

SPL ― lookupで説明文を付加する

index=web
        | lookup http_status status OUTPUT status_description
        | table _time, status, status_description, clientip

この例では、各イベントのstatusの値をキーにしてhttp_statusテーブルを引き、一致した行のstatus_descriptionをイベントに新しいフィールドとして追加しています。その結果、404のイベントには「Not Found」という説明が付き、読みやすくなります。

lookupは「今サーチしているイベントに情報を足す」コマンドです。キーが対応表に無いイベントは、付加フィールドが空欄のまま残ります(イベント自体は消えません)。

よく似た名前のinputlookupは、役割がまったく異なります。 lookupが「イベントに情報を足す」のに対し、 inputlookupはルックアップテーブルそのものをイベントとして読み込むコマンドです。

SPL ― inputlookupで表の中身を確認する

| inputlookup http_status

先頭にパイプを置いて| inputlookup http_statusと実行すると、インデックスのログではなくCSVの中身そのものが結果として表示されます。「対応表が正しく登録できているか確認したい」ときなどに便利です。

コマンド	役割	使いどころ
`lookup`	サーチ中のイベントに、表の情報を付け加える	コードに説明を付けるなど
`inputlookup`	表の中身をそのままイベントとして読み込む	表の内容確認、表を起点にした集計