実施環境： Splunk Free 8.2.2
0. 概要
Splunk には、マクロ(サーチマクロ)という機能があります。
この機能は、 SPL 文でよく使用するパーツを簡単に使いまわせるようにするものです。
今回はそのマクロ機能について紹介していきます。
1. 設定方法
まず、「設定」から「詳細サーチ」を選択します。
「詳細サーチ」画面で、「サーチマクロ」を選択します。
作成済みのサーチマクロの一覧が表示されます。
今回は新規作成となるので、右上の「新しいサーチマクロ」を押します。
マクロの作成画面が表示されます。
各項目の説明は次の通りです。
- 宛先 App (必須) : マクロを使用できる App 名
- 名前(必須) : マクロの名前、引数を使用する場合は特殊な規則あり
- 定義(必須) : マクロが対応する SPL パーツ
- eval ベースの定義を使用しますか?(チェックボックス) : 定義が eval ベースの場合はチェックを入れる
- 引数(任意) : マクロで使用する引数の名前
- 検証式(任意) : 引数が適切かどうかを検証する eval ベースの判定式
- 検証エラーメッセージ(任意) : 引数が不適切な場合に返すメッセージ
細かいルールについては後で述べます。
とりあえず今回は、次のように入力し、「保存」を押しましょう。
| 項目名 | 設定値 |
|---|---|
| 宛先 App | search |
| 名前 | test_count |
| 定義 | stats count |
| eval ベースの定義を使用しますか? | チェックを外す |
| 引数 | (設定値なし) |
| 検証式 | (設定値なし) |
| 検証エラーメッセージ | (設定値なし) |
これでマクロが作成できました。
一覧に表示されない場合は左上の App を変更して探してみてください。
2. 使用方法
さて、では作成したマクロを実際に使用してみましょう。
次の SPL を実行してみてください。
index="_internal"
| `test_count`
ログの件数がカウントできました。
これは、マクロの部分がstats countと置き換わったものと同じ動きです。
以下のように、マクロはバッククォート(`)でマクロ名を囲うことで使用できます。
`マクロ名`
上記ではマクロは1つのコマンドを置き換えましたが、マクロが置き換えられる表現の範囲は結構広く、必ずしも1つのコマンドである必要はありません。
例えば以下のように、パイプを含む複数のコマンドを置き換えることも可能です。
| 項目名 | 設定値 |
|---|---|
| 宛先 App | search |
| 名前 | test_command |
| 定義 | | timechart span=1h count | sort - count | table _time |
| eval ベースの定義を使用しますか? | チェックを外す |
| 引数 | (設定値なし) |
| 検証式 | (設定値なし) |
| 検証エラーメッセージ | (設定値なし) |
index="_internal"
`test_command `
| eval _time = strftime(_time, "%Y/%m/%d %H:%M:%S")
| rename _time AS "日時"
逆に、コマンドの一部のみを置き換えることも可能です。
| 項目名 | 設定値 |
|---|---|
| 宛先 App | search |
| 名前 | test_limit |
| 定義 | limit=5 |
| eval ベースの定義を使用しますか? | チェックを外す |
| 引数 | (設定値なし) |
| 検証式 | (設定値なし) |
| 検証エラーメッセージ | (設定値なし) |
index="_internal"
| sort `test_limit` _time
ただし、唯一気を付けるべき場合として、 search や inputlookup などの生成コマンド( generating commands )を定義に使用する場合は「定義の先頭にパイプ(|)を付けない」「マクロ使用箇所の直前にパイプを付ける」の2点を守る必要があります。
| 項目名 | 設定値 |
|---|---|
| 宛先 App | search |
| 名前 | test_lookup |
| 定義 | inputlookup "geo_attr_countries.csv" |
| eval ベースの定義を使用しますか? | チェックを外す |
| 引数 | (設定値なし) |
| 検証式 | (設定値なし) |
| 検証エラーメッセージ | (設定値なし) |
| `test_lookup`
| 項目名 | 設定値 |
|---|---|
| 宛先 App | search |
| 名前 | test_lookup_pipe |
| 定義 | | inputlookup "geo_attr_countries.csv" |
| eval ベースの定義を使用しますか? | チェックを外す |
| 引数 | (設定値なし) |
| 検証式 | (設定値なし) |
| 検証エラーメッセージ | (設定値なし) |
`test_lookup_pipe`
3. 引数
サーチマクロでは、引数を指定して使用することができます。
引数を使用する方法は以下の通りです。
-
「名前」の末尾に以下の形で引数の個数を指定します。
マクロの名前(引数の個数) -
「引数」に引数の名前をカンマ(,)区切りで指定します。
引数で使用できる文字は半角の英数字とアンダースコア(_)、ダッシュ(-)のみです。 -
「定義」中の引数で置き換えたい箇所を以下のように指定します。
\$引数の名前\$
試しに以下のマクロを作成し、実行してみましょう。
| 項目名 | 設定値 |
|---|---|
| 宛先 App | search |
| 名前 | test_percent(2) |
| 定義 | eval per = $part$ / $all$ * 100 |
| eval ベースの定義を使用しますか? | チェックを外す |
| 引数 | part,all |
| 検証式 | (設定値なし) |
| 検証エラーメッセージ | (設定値なし) |
| makeresults count=1
| eval num1 = 10, num2 = 20
| `test_percent( num1, num2)`
なお、引数を使用する際に気を付けるべき点として、「引数にフィールド名を指定した場合も、マクロの展開時点では単なる文字列として扱われる」点が挙げられます。
例えば、以下のようなマクロを作ります。
| 項目名 | 設定値 |
|---|---|
| 宛先 App | search |
| 名前 | test_merge(2) |
| 定義 | eval merge = "$str1$" . "$str2$" |
| eval ベースの定義を使用しますか? | チェックを外す |
| 引数 | str1,str2 |
| 検証式 | (設定値なし) |
| 検証エラーメッセージ | (設定値なし) |
そして、次の SPL 文を実行します。
| makeresults count=1
| eval str_a = "aaa", str_b = "bbb"
| `test_merge( str_a, str_b)`
単純に考えると、上記の結果 merge の値には「 aaabbb 」が入るように思えます。
そして、実際に動かしてみた結果が以下です。
merge の値には「 str_astr_b 」が入っています。
これは一見奇妙に思えます。
ですが、先ほど述べた通り「マクロの展開時点では引数は単なる文字列である」ことを考えると、以下のように引数の箇所がフィールド名ではなく「文字列」となるため、展開されないことがわかります。
なので実は、以下のように引数に与える値をダブルクォーテーションでくくっても同じ結果になります。
| makeresults count=1
| eval num1 = 10, num2 = 20
| `test_percent( "num1", "num2")`
| makeresults count=1
| eval str_a = "aaa", str_b = "bbb"
| `test_merge( "str_a", "str_b")`
先の test_percent も、一見フィールドの値がマクロに与えられているように見えますが、実際の動きとしては「マクロの展開」→「フィールドの展開」という順番で動作しています。
この「マクロ展開時にフィールドが展開されない」というのは、後述の検証式でも同様です。
意外と引っ掛かりがちなので、気を付けましょう。
4. 引数の検証
サーチマクロで引数を指定する場合、「検証式」「検証エラーメッセージ」を指定することで引数が想定した形式かどうかを検証することができます。
検証の結果引数の形式が不適切である場合、そのマクロを使用している SPL はエラーとなります。
検証式は、 eval コマンド内で使用できる形で作成します。
検証式の結果は基本的に、 Boolean 形式になるように指定します。
true なら成功、 false なら失敗です。
検証式を実際に使用してみます。
| 項目名 | 設定値 |
|---|---|
| 宛先 App | search |
| 名前 | test_percent_bool(2) |
| 定義 | eval per = $part$ / $all$ * 100 |
| eval ベースの定義を使用しますか? | チェックを外す |
| 引数 | part,all |
| 検証式 | $all$ != 0 |
| 検証エラーメッセージ | Test Macro - Bad Args! |
| makeresults count=1
| `test_percent_bool( 10, 20)`
| makeresults count=1
| `test_percent_bool( 10, 0)`
5. eval ベース
「 eval ベースの定義を使用しますか?」にチェックを入れると、 eval 関数や演算子を用いた表現でマクロの結果を返せます。
「eval ベース」とは言っても eval コマンドでしか使用できないわけではなく、どのようなコマンドでも使用可能です。
定義内の関数や演算子の処理はマクロの展開時に行われ、その結果がここまで見てきたマクロの「定義」と同等、すなわち SPL 文にあてはめられた後で再度 SPL のルールに沿って解釈されます。
この形式を用いた場合、マクロの返す結果は必ず「単一の文字列」となる必要があり、「数値」などの場合はエラーとなります。
と、説明してきましたが、この形式は結構ややこしいので、以下の例をもとに実際の挙動を1歩ずつ確認してみましょう。
| 項目名 | 設定値 |
|---|---|
| 宛先 App | search |
| 名前 | test_count_by(1) |
| 定義 | "stats count BY " . substr("$name$", 1, 9) |
| eval ベースの定義を使用しますか? | チェックを入れる |
| 引数 | name |
| 検証式 | (設定値なし) |
| 検証エラーメッセージ | (設定値なし) |
index="_internal"
| `test_count_by("log_level_test")`
まず、 eval ベースの定義を展開します。
"stats count BY " . substr("$name$", 1, 9)
引数に与えた値は文字列「 log_level_test 」なので、
"stats count BY " . substr("log_level_test", 1, 9)
評価関数 substr は「引数1の文字列について、引数2で指定した文字数の箇所から引数3で指定した文字数分を切り出す関数」なので、文字列「 log_level_test 」の1文字目から9文字分を切り出し、
"stats count BY " . "log_level"
演算子ドット(.)は「文字列を結合する演算子」なので、
"stats count BY log_level"
よって、文字列「 stats count BY log_level 」がマクロの返す結果です。
この文字列をそのまま SPL に入れると
index="_internal"
| stats count BY log_level
となり、これが先の SPL で実行された処理となります。
正直かなりわかりにくい形式ですし、そもそもこれを使わなくとも大抵のマクロは作成できるので、見かける機会はあまり多くないと思います。
6. マクロのエスケープ
使う機会はほぼないと思いますが、マクロ部分を単なる文字列として扱う場合は、ダブルクォーテーション(")で囲むことでエスケープします。
| makeresults count=1
| eval test = "`test_limit`"
