4-6 ルックアップ

本章では、ルックアップ機能において最も基本的なCSVテーブルルックアップについて、概要と設定手順を説明します。 ルックアップは、Splunk初心者が最初につまづく可能性がある機能です。 文章を読んだだけではわからないことがありますが、その場合は実際に実機で操作すると理解できるようになるかもしれません。

1. ルックアップとは

ルックアップとは、ルックアップテーブルというテーブルからフィールドを取得することで、サーチ結果に含まれるイベントにそのフィールドを追加して表示することができる機能です。 Excelにもlookupと呼ばれる関数があります。あるフィールド値をキーとしてその値が含まれる表から別のフィールドを取得できる関数です。原理としては同じ機能となります。

例えば、HTTPステータスコードが出力されたログがあるとします。 このログのHTTPステータスコードに対応するステータスメッセージが含まれるルックアップテーブルをSplunkに登録し、ルックアップ機能を使うと、HTTPステータスコードに対応したステータスメッセージを生ログに追加してサーチ結果に出力することができます。

ルックアップ機能を使うことで、ログに含まれない外部データをサーチ結果に含めて結果を充実(Enrich)することができます。

flowchart TD
    subgraph proc[" "]
        direction RL
        raw["<span style='white-space:nowrap'>生ログ</span><br/><span style='white-space:nowrap'>_time=2024-01-15 10:23:45 <span style='color:red'>status=200</span> src_ip=10.0.0.1</span><br/><span style='white-space:nowrap'>_time=2024-01-15 10:23:46 <span style='color:red'>status=404</span> src_ip=10.0.0.2</span><br/><span style='white-space:nowrap'>_time=2024-01-15 10:23:47 <span style='color:red'>status=500</span> src_ip=10.0.0.3</span>"]
        csv["<span style='white-space:nowrap'>ルックアップテーブル（http_status）</span><br/><span style='white-space:nowrap'><span style='color:red'>status</span>, <span style='color:blue'>description</span></span><br/><span style='white-space:nowrap'>──────────────────</span><br/><span style='white-space:nowrap'><span style='color:red'>200</span>, <span style='color:blue'>OK</span></span><br/><span style='white-space:nowrap'><span style='color:red'>404</span>, <span style='color:blue'>Not Found</span></span><br/><span style='white-space:nowrap'><span style='color:red'>500</span>, <span style='color:blue'>Internal Server Error</span></span>"]
        csv -->|"lookup http_status <span style='color:red'>status</span> OUTPUT <span style='color:blue'>description</span>"| raw
    end
    result["<span style='white-space:nowrap'>サーチ結果</span><br/><span style='white-space:nowrap'>_time, <span style='color:red'>status</span>, src_ip, <span style='color:blue'>description</span></span><br/><span style='white-space:nowrap'>──────────────────────────────────</span><br/><span style='white-space:nowrap'>2024-01-15 10:23:45, <span style='color:red'>200</span>, 10.0.0.1, <span style='color:blue'>OK</span></span><br/><span style='white-space:nowrap'>2024-01-15 10:23:46, <span style='color:red'>404</span>, 10.0.0.2, <span style='color:blue'>Not Found</span></span><br/><span style='white-space:nowrap'>2024-01-15 10:23:47, <span style='color:red'>500</span>, 10.0.0.3, <span style='color:blue'>Internal Server Error</span></span>"]

    proc -->|"table _time, status, src_ip, description"| result

    style proc fill:#F7F7F7
    style raw fill:#ffffff
    style csv fill:#ffffff
    style result fill:#ECECEC

Splunkには、いくつかのルックアップ機能があります。 ここでは、最も基本的なCSVテーブルルックアップについて、設定手順を紹介します。

2. CSVルックアップテーブルファイル

ルックアップ機能を使用するための代表的な方法がCSVルックアップテーブルファイルを作成し、Splunkにアップロードして利用する方法です。 以下がCSVルックアップテーブルファイルのサンプルです。

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

形式は一般的なCSVです。一行目にヘッダーを入力し、二行目以降に値を入力します。文字コードはUTF-8にしてください。 このCSVルックアップテーブルファイルをSplunkにアップロードしておくことにより、例えばstatus=200というフィールドを持つイベントをサーチした際に、description=OKという値をCSVルックアップテーブルからルックアップしてサーチ結果に一緒に表示する、といったことが可能になります。

3. ルックアップテーブルファイルとルックアップ定義の設定手順

ルックアップ機能を使用するためには、以下の手順が必要となります。

(1)ルックアップテーブルファイルのアップロード/権限設定

ルックアップテーブルファイル(CSV)を作成し、これをSplunkにアップロードします。

(2)ルックアップテーブル定義の作成/権限設定

アップロードしたルックアップテーブルファイルから、ルックアップテーブル定義を作成します。

(3)自動ルックアップの設定/権限設定(オプション)

必要に応じて、自動ルックアップの設定を行います。自動ルックアップをすることで、lookupコマンドを使わなくても自動でlookupコマンドがバックグラウンドで実行されるようになります。

4. ルックアップコマンドと自動ルックアップ

ルックアップ定義を作成した後は、lookupコマンドでルックアップ機能を使用することができます。

index=main sourcetype=access_combined_wcookie status=*
| lookup http_status status AS status OUTPUT description AS description

上記のコマンドは、http_statusルックアップテーブルから、イベントに含まれているstatusをキーとして、ルックアップテーブルからdescriptionを取得し、サーチ結果に追加して表示するためのコマンドです。

しかし、上記のコマンドをルックアップのたびに実行するのは手間であるため、ルックアップを自動化することも可能です。

ルックアップの自動化を設定すれば、常に上記のようなコマンドが実行されている状態となり、statusを持つイベントを取得した時に、同時にルックアップテーブルから取得したdescriptionも取得することができるようになります。 (ただ本章では自動ルックアップ手の手順については省略します)

5. ルックアップ機能を使用したサーチの例

ルックアップ機能を使用したサーチの例は以下です。

index=main sourcetype=access_combined_wcookie
| stats count BY status
| lookup http_status status OUTPUT description

上記のコマンドは、webアクセスログをstatusフィールドごとに集計し、その集計結果のstatusをキーとしてhttp_statusルックアップテーブルからdescriptionを取得して表示しています。

6. ルックアップファイルの検証のためのコマンド

ルックアップテーブルファイルをアップロードした後、想定通りファイルがアップロードされているか、また想定通りルックアップ定義が作成されているかを確認するためのコマンドとして、inputlookupというコマンドがあります。 このコマンドは| inputlookup <ルックアップテーブルファイル名またはルックアップ定義>の書式で実行します。 先頭にパイプ(|)を付与して実行することに注意してください。

| inputlookup http_status.csv

| inputlookup http_status

実行すると、ルックアップテーブルの内容がサーチ結果に表示されます。

7. まとめ

• CSVテーブルルックアップを使うと、IPアドレスに対応する拠点名のように、ログに含まれない外部データをサーチ結果に追加できる
• 利用にはCSVルックアップテーブルファイルのアップロードとルックアップ定義の作成が必要で、自動ルックアップを設定すればlookupコマンドを省略できる
• ルックアップはlookupコマンドで実行し、アップロードしたテーブルや定義の内容はinputlookupコマンドで確認できる