Conf files (概要 / 処理の優先度 / btool )【Splunk】

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

Conf files

Conf files とは「Splunkの構成ファイル (e.g., inputs.conf, props.conf, outputs.conf)」で、システム設定、認証情報、knowledge objects (e.g., tags, alerts, reports) などが含まれます。

デフォルトでは $SPLUNK_HOME*/etc/system/default に [stanza] <key>=<value> で記述されています。
※ $SPLUNK_HOMEとは「Splunkがインストールされたディレクトリ」のことで、[Settings] > [Server settings] > [General settings] > [Installation path] から確認できます。

[stanza1_header]
<attribute1> = <val1>
# comment 
<attribute2> = <val2>
...

[stanza2_header]
<attribute1> = <val1>
<attribute2> = <val2>
...

Conf filesのドキュメントは $SPLUNK_HOME/etc/system/README に『.conf.spec』『.conf.example』というファイル名で存在します。

何かカスタマイズを行う際は /etc/system/default/ ではなく「/etc/system/local/」を編集してください。(/default の編集はアップデート時のトラブルに繋がります)
※ /default のスタンザは /loacal で空の値を設定することで無効化できます。

代表例 (inputs, props, outputs.conf)

ここでは conf file の代表例として『inputs.conf』『props.conf』『output.conf』を紹介します。それぞれ Forwarder, Indexer, Search Head (SH) に対して以下の内容を定義します。

コンポーネント input.conf props.conf output.conf
Forwarder 各種システムから収集するデータ 文字エンコーディング、
メタデータ、イベント間隔など
収集したデータの転送先
(e.g., Indexer, Forwarder)
Indexer Forwarderから収集するデータ メタデータの上書き、
フィールド抽出定義/加工など
なし
SH Splunk logとして収集するデータ サーチ抽出、Lookupsなど 内部ログの転送先
(e.g., IndexerA, IndexerB)

ディレクトリ

Webでシステム構成を変更した場合、その変更がconf filesのコピーとして上書き (or 新規で作成) されます。

【例】新しく Index を追加する場合のSplunkの挙動

  1. $SPLUNK_HOME/etc/system/local/ に indexes.conf があるかを確認
  2. ①で存在しなければ、新たに作成
  3. /local/indexes.conf に変更を上書き
  4. デフォルトファイル(/default/indexes.conf) を削除

処理の優先度

Global vs. User/Apps

Conf filesは『Global』『User/Apps』の2つに分けられます。

  • Global:アプリやユーザーから独立したファイル (e.g., server, inputs, outputs)
  • User/Apps (サーチ用途):アプリやユーザーに関連したファイル (e.g., app, fields, macros)

Global における優先度

  1. /system/local
  2. /apps/local
  3. /apps/default
  4. /system/default

Globalにおいて同じ優先度のファイルは A→Z (アルファベット順) に処理されます。

User/Apps における優先度

  1. /users/username
  2. /apps/<running_app> (local→default)
  3. /apps/<other_apps> (local→default)
  4. /system (local→default)

User/Appsにおいて同じ優先度のファイルは Z→A (アルファベットの逆順) に処理されます。

②, ③は例えば、ユーザーが利用しているマクロが /search にある場合「/search /unix よりも高い優先度になる」ということを意味します。

Global vs. User/Apps

まとめ

  • local は default よりも優先度が高い
  • User/Apps における優先度は user > running app > app > system の順
  • Grobalで同じ優先度のファイルは A→Z の順に処理されるが、User/Appsでは Z→A (逆順) になる

btool コマンド

btool は、Splunkがタスクを実行する際に利用する「マージされた conf file の場所/中身を表示するコマンド」です。(ディスク内の構成を確認する際はbtool ですが、インメモリではshow を使います)

『monitor://<file_path>』:特定のファイルに絞る。
『–debug』:マージされた conf file の値のソース(パス)を表示。
『–user = <user>』:ユーザーを指定。
『–app = <app>』:アプリを指定。
『 | grep <stanza>』:スタンザを指定。*NIXでは「grep」Windowsでは「findstr」
『 > /tmp/<file_name>』:/tmp に名前を指定してファイルを配置
『check』:”typo in stanza”(エラー) の原因調査

# Forwarder上の収集構成 (e.g., host, index, python_version)
$SPLUNK_HOME/bin/splunk btool inputs list   # btool <conf_file> list

# Forwarder上のsearch app内で「収集構成」「値の参照元」を確認
# ./splunk btool <conf_file> list --app=<app> --debug
$SPLUNK_HOME/bin/splunk btool inputs list --app=search --debug

# Forwar上の[splunktcp]スタンザ内で「収集構成」「値の参照元」を確認
# ./splunk btool <conf_file> list --debug | grep (or findstr) <stanza>
$SPLUNK_HOME/bin/splunk btool inputs list --debug | grep splunktcp

# Forwar上の[splunktcp]スタンザ内で「収集構成」「値の参照元」を確認し、inputs_splunktcpというファイルを/tmpに配置
# ./splunk btool <conf_file> list --debug | grep (or findstr) <stanza> > /tmp/<filename>
$SPLUNK_HOME/bin/splunk btool inputs list --debug | grep splunktcp > /tmp/inputs_splunktcp

# Splunk起動時に"typo in stanza"というエラー文が出た場合のエラーの探し方
$SPLUNK_HOME/bin/splunk btool check

Conf files の更新

Web, CLI による設定の変更では (ほとんどの場合) インスタンスの再起動は求められませんが、conf filesを手動で変更した場合は以下の方法で再起動を行う必要があります。
※ Splunkの再起動は「Standalone configuration」「SH」でのみ有効です。

  • 主要な conf files のみを更新“http://<server_name>:<web_port>/debug/refresh” による強制リロード
  • 全ての conf files を更新[Settings] > [Server controls] > [Restart Splunk] または “$SPLUNK_HOME/bin/splunk restart” の実行

References

configuration files – Splunk Documentation

About configuration files – Splunk Documentation

Configuration file directories – Splunk Documentation

Configuration file structure – Splunk Documentation

Configuration file precedence – Splunk Documentation

How to edit a configuration file – Splunk Documentation

Update common peer configurations and apps – Splunk Documentation

Command line tools for the use with Support – Splunk Documentation

Use btool to troubleshoot configurations – Splunk Documentation

Understand file precedence in apps for Splunk Cloud Platform or Splunk Enterprise – Splunk Dev

List the entities that can be refreshed in splunkweb by hitting the /debug/refresh endpoint – Splunk Community