props.conf 解説【Splunk】

この記事は約10分で読めます。
sponsored link

props.conf とは

props.conf とは「データの処理 (e.g., inputs, indexing, searching) に関する構成ファイル」のことで、host, source, sourcetype 毎にイベント処理を細かくカスタマイズできます。(HF, Indexerが対象)

ただ、多くの機能を有効化しすぎたり、サーチ対象の文字数を0/-1(無制限)で指定したりすると、パフォーマンス低下の原因となるので注意が必要です。

props.conf の利用用途

  • イベントの定義
  • 複数行イベントの改行設定
  • 文字エンコーディング設定
  • バイナリファイルの許可設定
  • フィールドエイリアスの定義
  • SEDCMD を用いた機密データのマスキング設定
  • 識別するタイムスタンプの位置やフォーマットの設定
  • 外部ソースのフィールドを利用するための lookup tables の設定
  • 自動で付与された host, sourcetype を特定のルールに基づいて上書きする設定
  • (複数 Indexes の環境下で) 個別のイベントを特定の Index にルーティングする設定
  • インデックス時に抽出されるフィールドの定義 (e.g., header-based)
  • サーチ時に抽出されるフィールドの定義 (ただし、正規表現を複数のsources/sourcetypes/hostsに適用、複数の正規表現の利用、区切り文字抽出、1つのフィールドから複数の値を抽出、数値や_で始まるフィールドを抽出する場合は、transforms.conf が必要です)

代表的なスタンザ/コマンド

host : : <host_name>

『CHARSET = <encoding>』:文字のエンコードを指定。Windowsではデフォルトで「AUTO」それ以外では「UTF-8」

『TZ = <timezone>』:タイムゾーンを指定。デフォルトでは空。

『TIME_FORMAT = <time_format>』:指定したフォーマットに一致するものをタイムスタンプとして採用。イベント内に複数のタイムスタンプがある場合や、特殊なフォーマットの場合などに有効。デフォルトでは空。

『TIME_PREFIX = <regex>』:正規表現/文字にマッチしたテキスト以降からタイムスタンプを抽出。ライムスタンプがログの先頭にない場合に有効。デフォルトでは空。

『MAX_TIMESTAMP_LOOKAHEAD = n』:Splunkがタイムスタンプを探す文字数を指定。TIME_PREFIX で指定した位置からカウント。セットする数値が小さいほどパフォーマンスが向上し、0/-1(無制限)にするとパフォーマンスが低下する。デフォルトでは「128」

[host::my_splunk_server]        # スタンザでhostを指定 ([default]=グローバルな設定)
CHARSET = AUTO                  # default (Windowsマシン)
TZ = Asia/Tokyo                 # TZ:東京
TIME_FORMAT = %Y-%m-%d          # (e.g.) 2023-01-01
TIME_PREFIX = syslog_date:      # "syslog_date:"の後に続くテキストからタイムスタンプを抽出
MAX_TIMESTAMP_LOOKAHEAD = 128   # default (先頭128文字目までがタイムスタンプのサーチの対象)

source : : <source_name>

『sourcetype = <sourcetype_name>』:sourcetype を指定。inputs.confで既に指定している場合はprops.confで上書きできない。

[source::/.../web_access.log]   # スタンザでsourceを指定
sourcetype = web_access         # inputs.confで既に指定している場合、props.confで上書きすることはできない
CHARSET = UTF-8                 # default (Windows以外のマシン)

<sourcetype>

『SHOULD_LINEMERGE = <boolean>』:複数行を単一イベントとしてマージするかどうか。デフォルトでは「true

『LINE_BLEAKER = <regex>』:イベントの分割方法を定義。SHOULD_LINEMEGE の前に実行。デフォルトでは ([\r\n]+) = データは行毎に分割され、carriage return/newline characterで区切られる。

『BREAK_ONLY_BEFORE_DATE = <boolean>』:日付データがスキャンされれば改行。デフォルトでは「true」

『BREAK_ONLY_BEFORE = <regex>』:正規表現/文字にマッチすれば改行。イベントの境界はUFでも定義可能。デフォルトでは空。

[access_error]                  # host,sourceとは書き方が違うので注意 (ワイルドカードは利用不可)
SHOULD_LINEMERGE = true         # default (複数行のデータを単一イベントとしてマージ)
LINE_BLEAKER = ([\r\n]+)        # default (改行マークでイベントを区切る)
BREAK_ONLY_BEFORE_DATE = true   # default (日付データがスキャンされれば改行)
BREAK_ONLY_BEFORE = error       # errorの文字でイベントを区切る

タイムスタンプ/タイムゾーンの優先度

timestamp 優先度

  1. props.conf の『TIME_FORMAT』で指定されたタイムスタンプ
  2. Splunkがイベント内の time/date を自動で識別
  3. year がない場合、最終加工日や現在時刻などをもとに year を決定 (詳細)
  4. date がない場合、source/ファイル名 をもとに date を探す
  5. それでも見つからない場合は、最終編集日を date として採用
  6. インデックス化時点のタイムスタンプを採用

timezone (TZ) 優先度

  1. 生データ内の明示的な TZ (e.g., JST, UTC+9)
  2. props.conf で指定された TZ
  3. Forwarder により付与された TZ
  4. Indexes のホストの TZ

機密データのマスキング (SEDCMD)

SEDCMDでできること

HFのprops.confでSEDCMD* を用いることで_raw』に保存される前のデータを、シンプルかつ(regexより)高速にマスキングすることができます。(Win/*NIXの両方で使用可)
※ *NIXの編集/置換コマンド sed (system editor) を模したSplunkのコマンド。

構文は SEDCMD-<class> = s/<regex>/<replacement>/<number_of_strings> または SEDCMD-<class> = y/<old_words>/<new_words> を利用します。前者(s/)では置換する文字数(1桁)を指定できるのに対し、後者(y/)では条件に一致する文字がすべて置換されます。
<class> は処理の順番を決めるラベルであり、任意の文字列を設定可能です。

SEDCMDの使い方

『SEDMED-<class> = <sed_script>』:収集したデータをインデックス前にマスキング。<class> は任意のラベルを設定でき、先頭に数字をつけることで処理の優先度を指定できる。

『SEDMED-<class> = s/<regex>/<replacement>/<flags>』<regex> に一致した文字を <replacement> で置換。<flags> で置換する文字数(1桁)を指定。<flags>=g にすると一致するものを全て置換。

『SEDMED-<class> = y/<old_text>/<new_text>/』<old_text> に一致した文字を <new_text> で置換。

[source::.../abc.log]                                           # マスキング対象となるsourceを指定
SEDCMD-1Anon = s/cardNumber=\d{5}{\d{4})/cardNumber=xxxxx\1/g   # カード番号(9桁)の先頭5桁をxで置換
SEDCMD-2abc = y/abc/ABC/                                        # 小文字のabcをそれぞれABCに変換

Inline / Transform extraction

Inline extraction

インライン抽出とは「1つの正規表現を使って単一/複数フィールドを抽出する手法」のことで、transforms.conf を使用するトランスフォーム抽出と区別して使われます。

『EXTRACT-<class> = <regex>』(サーチ抽出):正規表現にマッチするイベントからフィールドを抽出。

『KV_MODE = none | auto (default) | auto_escaped | multi | json | xml』(サーチ抽出):KV(key/value) の抽出方法を指定。none =「KVを抽出しない (フィールドを上書きしたくない場合に有効)」auto =「”=”をキーとしてKVを識別」auto_escaped =「”=”をキーとしてKVを識別し “/””, “//” をエスケープシーケンスとして識別」json, xml =「JSON, XMLデータから自動で抽出」

[my_sourcetype]
EXTRACT-extract_ip = (?<ip>\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})   # _rawのイベントからIPアドレスを抽出
KV_MODE = auto   # default 

Transform extraction

トランスフォーム抽出とは「インライン抽出よりも高度な抽出方法*」のことで、props.conf/transform.conf を合わせて利用します。なお GUI の正規表現抽出では props.conf が使われ、区切り文字表現では props.conf, transform.conf が手動で作成されます。
(e.g.) 同じ正規表現を複数のsources/sourcetypes/hostsに適用、複数の正規表現の利用、区切り文字抽出、1つのフィールドから複数の値を抽出、数値や_で始まるフィールドを抽出

# props.conf
[source::map_logs]
REPORT-1color = red, yellow, green, blue

# transforms.conf
[red]
filtername = red_filter
filter = 480<color_id AND color_id<500

References

props.conf – Splunk Documentation

Configure timestamp recognition – Splunk Documentation

How timestamp assignment works – Splunk Documentation

Specify time zones for timestamps – Splunk Documentation

Anonymize data – Splunk Documentation

Configure custom fields at search time – Splunk Documentation

Configure inline extractions – Splunk Documentation

Configure advanced extractions with field transforms – Splunk Documentation