Splunk 5.0 - Splunk Docs

Splunk 5.0
サーチマニュアル
作成：2012 年 10 月 31 日 午後 2 時 37 分
Copyright © 2012 Splunk, Inc. All Rights Reserved
Copyright (c) 2013 Splunk, Inc. All Rights Reserved
Table of Contents
はじめに
サーチマニュアルにようこそ
4
4
サーチの概要
サーチについて
サーチパイプラインについて
サーチ言語について
サーチ言語の構文について
サーチアシスタントについて
サーチジョブ調査によるサーチプロパティの表示
サーチに合わせたサーチモードの設定
実行中のサーチへのアクション
より良いサーチの作成
4
4
5
5
6
7
8
11
13
13
イベントの取得
イベントの取得について
サーチコマンドの使用
フィールドを使ったイベントの取得
インデックスおよび分散サーチピアからのイベントの取得
類似イベントの分類とグループ化
タイムラインを使ったイベントパターンの調査
15
15
16
17
17
18
20
時間範囲の指定
サーチにおける時間範囲について
サーチに適用する時間範囲の選択
サーチへの時間修飾子の指定
サーチへのリアルタイム時間範囲ウィンドウの指定
22
22
22
23
25
サーチ結果のレポート
レポートコマンドについて
時間ベースのグラフの作成
時間ベースではないグラフの作成
多い/少ないフィールド値のビジュアル化
サマリー統計情報を表示するレポートの作成
サーチでの関連、統計的相関、および差異の調査
複数のデータシリーズを持つグラフの作成
複数日の時間ごとの合計の比較
26
26
26
26
27
28
28
28
29
リアルタイムのサーチとレポート
リアルタイムサーチとレポートについて
Splunk Web でのリアルタイムサーチとレポート
CLI でのリアルタイムサーチとレポート
リアルタイムサーチとレポートの、予想されるパフォーマンスと既
知の制限事項
リアルタイムサーチの利用の制限方法
30
30
31
31
32
統計の算出
34
32
統計の算出について
stats コマンドおよび関数の使用
stats と eval 式および関数の使用
サーチ結果へのスパークラインの追加
34
34
34
34
フィールドの評価と操作
フィールドの評価と操作について
eval コマンドおよび関数の使用
ルックアップを使ったルックアップテーブルからのフィールドの追
加
サーチコマンドによるフィールドの抽出
複数値フィールドの操作と評価
36
37
37
37
イベントの相関
イベントの相関について
時間を使ったイベント間の関係の識別
サブサーチについて
サブサーチを使ったイベントの相関
サブサーチ結果のフォーマットの変更
トランザクションについて
イベントの識別とトランザクションへのグループ化
39
39
39
40
41
41
42
42
将来のイベントの予測
Splunk による予測分析について
44
44
その他のサーチ方法
サーチマクロの作成と編集
44
44
カスタムサーチコマンドの作成
この章について
サーチコマンドスタイルガイド
サーチコマンドの作成
Splunk へのカスタムコマンドの追加
カスタムコマンドへのアクセス制御
カスタムサーチコマンドの例
外部化されたサーチエラー文字列
外部化されたサーチエラー
45
45
46
47
48
49
50
50
50
37
38
はじめに
サーチマニュアルにようこそ
システム内のすべてのデータを取り込んだら、それをどのように取り扱いますか？まず、Splunk の強力なサーチ
機能を使用して、定義されている一部のフィールドだけではなく、いろいろな情報を探してみましょう。時間サー
チと単語サーチを組み合わせられます。IT インフラ内のあらゆるレイヤのエラーを検索して設定の変更を追跡
し、システム障害の発生を防止してください。
このマニュアルでは、サーチ言語の概要および Splunk でのサーチの作成方法について説明していきます。
サーチに関する情報をご覧になる前に、以下の事項を確認してください。
ローカルマシンまたはリモートサーバー上のデータにアクセスできる。Splunk へのデータの取り込みの詳細
は、『Getting Data In Manual』を参照してください。
Splunk でのインデックスの働きを理解している。詳細は、『Managing Indexers Manual』を参照してくださ
い。
フィールドとソースタイプやイベントタイプなどのナレッジオブジェクトを理解している。ナレッジオブ
ジェクトの詳細は、『Knowledge Manager Manual』を参照してください。
サーチ App およびサーチ/レポートダッシュボードの使用法を理解している。Splunk が初めての方は、ぜひ
『Splunk チュートリアル』をご覧ください。データの追加、データのサーチ、簡単なレポートやダッシュ
ボードの作成方法などが詳細に説明されています。
Splunk のサーチコマンドや利用できる引数の一覧については、『Search Reference Manual』を参照してくださ
い。
PDF を作成
このマニュアルの PDF 版が欲しい場合は、このページの目次の左下にある赤い [Download the Search Manual
as PDF] リンクをクリックしてください。PDF 版のマニュアルがその場で作成されます。作成された PDF は後で
利用するために保存、印刷することができます。
サーチの概要
サーチについて
この章ではサーチの概要、Splunk サーチの構造、サーチ言語とその構文、サーチの作成とトラブルシューティン
グに役立つツール、およびより良いサーチの作成に関するヒントなどを説明していきます。
サーチの種類
サーチ言語とその構文の詳細を学習する前に、まず自分の目的が何なのかを確認しておきましょう。一般的には、
Splunk にデータを取り込んだら、以下のような作業を行います。
インデックスを作成したデータを調査して詳細を把握する、または問題の主原因を特定する。
サーチ結果を表形式またはその他の視覚的な形式のレポートで表示する。
このために、raw イベントサーチとレポート生成サーチの 2 種類のサーチが存在しています。
raw イベントサーチ
raw イベントサーチは、インデックスから単にイベントを取得するサーチで、一般的には問題の分析を行う場合に
実行されます。このようなサーチの例として、エラーコードのチェック、イベントの相関付け、セキュリティ上の
問題の調査、障害の分析などが挙げられます。一般的にこのようなサーチには (サーチ自体を除く) サーチコマン
ドは含まれず、サーチ結果は raw イベントの一覧になります。
raw イベントサーチの詳細は、本マニュアルの「イベントの取得」の章にある「イベントの取得について」
を参照してください。
レポート生成サーチ
レポート生成サーチは、一連の結果に対してある種の統計的な計算を実行するサーチです。これらは、まずイン
デックスからイベントを取得して、それを 1 つまたは複数のサーチコマンドに渡すタイプのサーチです。これらの
サーチは常にフィールドと最低 1 つの統計コマンドのセットを必要としています。この例としては、毎日のエラー
イベント数の取得、特定ユーザーのログイン回数のカウント、フィールド値の 95 番目のパーセンタイルの算出な
どが挙げられます。
サーチ構造の詳細は、「サーチパイプラインについて」を参照してください。
サーチコマンドでできる操作の詳細は、「サーチ言語について」を参照してください。
4
このマニュアルの「検索結果のレポート」にあるレポート生成の詳細は、「レポートコマンドについて」を
参照してください。
サーチとナレッジ
サーチを実行するにつれて、そのパターンを理解したり、サーチ可フィールドとして役立つその他の情報が分かっ
てくることでしょう。新たなデータのインデックスを作成するにつれて、これらの新規フィールドを認識するよう
に Splunk を設定したり、サーチに応じて新たなフィールドを作成することができます。どのような場合でも、イ
ベントデータのフィールド、イベント、およびトランザクションに関するこのナレッジを使用、追加、編集できま
す。このナレッジの収集は、効率的なサーチの作成や詳細なレポートの構築に役立ちます。
Splunk Web、CLI、または REST API による検索
これらの違いは何で、どのような理由でそれを選ぶのでしょうか？
サーチパイプラインについて
Splunk サーチを説明するための用語「サーチパイプライン」をすでにご存じかもしれません。サーチパイプライ
ンは、Splunk サーチの構造を表しています。これは、パイプ文字「|」を使って複数のコマンドを連続的に結合し
ます。パイプ文字は、あるコマンド (パイプの左側) の出力または結果を、次のコマンド (パイプの右側) の入力と
して使用することを表しています。これにより、目的の結果が得られるまでパイプラインの各ステップでデータを
調節または追加することができます。
Splunk サーチは、パイプラインの先頭にあるサーチ単語から開始されます。これらのサーチ単語は、インデック
スから取得するイベントを示す、キーワード、フレーズ、論理演算式、キー/値のペアなどです。
詳細は、「イベントの取得について」を参照してください。
次に取得されたイベントは、パイプ文字を使って次のサーチコマンドに入力として渡されます。サーチコマンド
は、インデックスから取得したイベントに対する処理を Splunk に指示します。たとえば、コマンドを使って不要
な情報のフィルタリング、追加情報の抽出、新しいフィールドの評価、統計情報の算出、結果の並べ替え、グラフ
の作成などを行います。一部のコマンドには、それに関連した関数や引数が用意されています。これらの関数と引
数により、結果の処理方法や処理対象フィールドなどを指定できます。たとえば、グラフの作成方法、算出する統
計情報、評価対象フィールドなどを指定できます。また、句を使ってサーチ結果をグループ化できるコマンドも用
意されています。
サーチコマンドでできる操作の詳細は、「サーチ言語について」を参照してください。
すべてのサーチコマンドの一覧については、『Search Reference』マニュアルを参照してください。このマ
ニュアルには、各サーチコマンドおよびその構文と使用法が記載されています。
サーチ言語について
サーチ言語のコンポーネント
Splunk サーチ言語は、あらゆるサーチコマンド、関数、引数、句を網羅しています。サーチコマンドは、イン
デックスから取得したイベントに対する処理を Splunk に指示します。たとえば、コマンドを使って不要な情報の
フィルタリング、追加情報の抽出、新しいフィールドの評価、統計情報の算出、結果の並べ替え、グラフの作成な
どを行います。
一部のサーチコマンドには、それに関連した関数や引数が用意されています。これらの関数や引数を使って、結果
の処理方法や処理対象フィールドを指定します。たとえば、関数を使ってグラフ内のデータのフォーマット、算出
する統計情報の指定、評価対象フィールドの指定などを行えます。また、句を使ってサーチ結果をグループ化でき
るコマンドも用意されています。
サーチの詳細
サーチコマンドがデータをどのように処理するかを理解するための例として、コマンドはインデックス作成された
すべてのデータをビジュアル化するために役立ちます。各サーチコマンドは、表の形状を定義します。
たとえば、以下のサーチコマンドについて見てみましょう。
sourcetype=syslog ERROR | top user | fields - percent
ディスクはインデックス作成されたすべてのデータを、列を持つ一定サイズのテーブルの列はフィールドを、行は
5
ディスクはインデックス作成されたすべてのデータを、列を持つ一定サイズのテーブルの列はフィールドを、行は
イベントを表しています。最初の中間結果テーブルでは、行数が少なくなっています。これは、サーチ単語
「sourcetype=syslog ERROR」に一致したインデックスから取得された、イベントのサブセットを表していま
す。2 番目の中間結果テーブルでは、列が減少しています。これは、イベントを上位 10 人のユーザーに限定し、
ユーザー、カウント、および割合を表示する「top user」コマンドの結果を表しています。次に、「fields percent」で、割合を表示する列が削除され、目的の情報のみを含む最終結果テーブルが表示されます。
先頭または他の場所からのサーチ
サーチコマンドパイプライン内の任意の場所でサーチを実行できます。サーチ結果は小さなテーブルで、同数の列
からサーチ条件に一致しないイベント行を差し引いたデータが含まれています。サーチでセルの値が変更されるこ
とはありません。
サーチコマンド： crawl、savedsearch、search。
不要な情報のフィルタリング
フィルタリングコマンドもサーチと同様に小さなテーブルを生成します。ただし、サーチコマンドによっては、小
さなテーブルの行数や列数がより少なくなります。フィルタリングコマンドでもセルの値は変更されません。
フィルタリングコマンド：dedup、fields、head、localize、regex、search、set、tail、where。
データの評価
評価コマンドを使って、特定の列名またはセルの値を変更することができます。評価コマンドによっては、列が追
加されることも、追加されないこともあります。
評価コマンド：abstract、addtotals、bucket、cluster、collect、convert、correlate、diff、eval、eventstats、
format、fillnull、format、kmeans、makemv、mvcombine、mvexpand、nomv、outlier、overlap、replace、
strcat、transaction、typelearner、xmlunescape。
結果の並べ替え
並べ替えコマンドは、指定された列名の値に基づいてテーブル全体の行をソートします。これらのコマンドは、列
を追加、削除したり、セル値を変更したりすることはありません。
並べ替えコマンド：reverse、sort。
他の情報の抽出
抽出コマンドは、_raw 列の各行から見つかった情報で、新たな行または列を作成します。
抽出コマンド：addinfo、extract/kv、iplocation、multikv、rex、top、typer、xmlkv。
例：extract/kv で、イベント内のキーと値のペアから新しい列を作成します。
例：multikv で、複数行または表形式イベント内で見つかった情報から新しい行を作成します。
統計情報を算出して結果を変換
統計コマンドは、新たなデータテーブルを作成します。これらのコマンドは、各イベントの特定のセル値を数値に
変更します。それらの情報は、統計目的で使用できます。
変換コマンド： chart、contingency、highlight、rare、stats、timechart、top。
サーチ言語の構文について
サーチは、パイプ (|) 文字で区切られた一連のコマンドから成り立っています。各パイプ文字の直後の、空白文字
で区切られた最初の文字列がコマンドになります。各コマンドの残りの文字列は、そのコマンドに応じた方法で処
理されます。
引用符とエスケープ文字
一般的に、空白文字、カンマ、パイプ、引用符、角括弧を含むフレーズやフィールド値は、引用符で囲む必要があ
ります。引用符の数は偶数でなければなりません。文字列の最初に引用符を指定したら、その文字列の終了を表す
引用符も指定する必要があります。例：
のようなサーチは、文字列「error」を含むイベント数を検索します。
のようなサーチは、error、1 つのパイプ、stats、および count がその順番
で含まれている raw イベントを返します。
error | stats count
... | search "error | stats count"
また、論理演算子やフィールド/値のペアなどが、サーチ時に元の意味で解釈されないように、そのようなキー
ワードやフレーズを引用符で囲むことも可能です。例：
キーワード AND を論理演算子として解釈せずにサーチする場合： error
6
"AND"
フィールド/値のペアをフレーズとしてサーチする場合： error
"startswith=foo"
円記号 (\) は、引用符、パイプ、および円記号自身をエスケープ処理する場合に使用します。円記号によるエス
ケープシーケンスは、引用符内でも展開されます。例：
サーチ内に「\|」と指定すると、このパイプ文字は 2 つのコマンドの区切り文字ではなく、処理対象のパイ
プ文字としてコマンドに渡されます。
「\"」と指定すると引用符がそのまま文字としてコマンドに渡されます。たとえば、文字通りの引用符を検
索したり、rex を使ってフィールド内に引用符を挿入する場合に使用します。
「\\」と指定すると、文字通りの円記号がコマンドに渡されます。
認識されない円記号のシーケンスは変更されません。
たとえば、サーチ文字列内に「\s」とある場合、これは既知のエスケーブシーケンスではないため「\s」とし
てコマンドに渡されます。
しかし、「\\s」と指定した場合、「\\」は既知のエスケープシーケンスで「\」に変換されるため、「\s」とし
てコマンドに渡されます。
例
例 1： 値が 6 の myfield が作成されます。
... | eval myfield="6"
例 2： 値が " の myfield が作成されます。
... | eval myfield="\""
例 3： 値が \ の myfield が作成されます。
... | eval myfield="\\"
例 4：引用符の数が偶数でないため、エラーが発生します。
... | eval myfield="\"
フィールド
Splunk のサーチパイプライン内を通過するイベントと結果は、フィールドの集合体として存在しています。基本
的にフィールドは、_time はイベントの時刻、source はファイル名、などのように Splunk のインデックスに由来
しています。また、イベントタイプ、タグ、rex コマンドを使った正規表現による抽出、stats コマンドの合計値な
ど、サーチ時にさまざまなソースから取得することも可能です。
特定のイベントに対して、特定のフィールド名が存在することも、存在しないこともあります。存在する場合、単
一値または複数の値が含まれている可能性があります。各値はテキスト文字列です。値は正の長さを持つ (文字列
またはテキスト) か、または長さ 0 (空文字列または "") になります。
たとえば、数字はその数字を表す単なる文字列です。たとえば、数字 10 の値を持つフィールドは、文字 1 と文字
0 を含む文字列「10」になります。数値を取得するコマンドは、計算のために内部で自動的に文字を数値に変換し
ます。
Splunk マニュアルおよびメッセージでは、以下の用語を使用しています。
ヌルフィールド
ヌルフィールドは、特定の結果やイベントに存在しないフィールドです。サーチ内のその他のイベントまた
は結果に、このようなフィールド値が存在していることがあります。たとえば、サーチコマンド fillnull は、
サーチ内の他のイベントや結果に存在しているフィールドが見つからないイベントや結果に、フィールドと
デフォルト値を追加するために用いられます。
空のフィールド
空のフィールドは、単一の空文字列を値に持つフィールドです。
空の値
空文字列 ""、または長さ 0 の文字列です。
複数値フィールド
複数の値を持つフィールドです。ヌルフィールド以外のフィールドは、文字列のリストを保有しています。
一般的には、1 つの値を持つリストになります。リストに複数のエントリが存在している場合に、それを複
数値フィールドと呼んでいます。詳細は、『サーチマニュアル』の「複数値を持つフィールドの操作と評
価」を参照してください。
サーチアシスタントについて
Splunk のサーチ言語は多彩で、さまざまなサーチコマンド、引数、および関数が用意されています。すべてのコ
マンドを理解している訳ではなく、またデータからどのような情報が抽出されているのか分からないために、サー
チの作成に多少時間がかかるかもしれません。
サーチアシスタントを使用してサーチ作成時にデータを表示
7
サーチの作成時に、使用するサーチコマンドや引数を知っておく必要はありません。サーチアシスタントがそれを
提案してくれます。
サーチバーに文字を入力すると、サーチアシスタントがそれに合わせた先行入力テキストまたは文脈上適切なテキ
ストを表示します。このような文脈上のテキストは、データの内容に基づいて表示されます。入力を続ける
と、[一致する単語] に表示される項目がそれに応じて変化します。
サーチアシスタントには、サーチ用語に一致する項目数も表示されます。この値は、Splunk から返されるサーチ
結果数の目安になります。データ内に当該の用語またはフレーズが存在していない場合、サーチアシスタントには
表示されません。
サーチアシスタントの設定の変更
サーチアシスタントはサーチバーから呼び出される Python エンドポイントで、サーチバーの下側にスライドされ
るパネルに表示される HTML を返します。サーチアシスタントは searchbnf.conf からその説明と構文情報を取得し
ます。このファイルには、すべての Splunk サーチコマンドとその構文が定義されています。また、提案する
フィールドの表示に fields.conf を使用したり、ユーザーに既存の保存済みサーチと似ていることを知らせるため
に savedsearches.conf を使用したりもしています。
サーチアシスタントの動作は、SearchBar モジュールの UI 設定で変更することができます。これらの設定は、デ
フォルトでサーチアシスタントを表示するかどうか (autoOpenAssistant)、先行入力を使用するかどうか
(useTypeahead)、コマンドのヘルプを表示するかどうか (showCommandHelp)、サーチ履歴を表示するかどうか
(showCommandHistory)、およびフィールド情報を表示するかどうか (showFieldInfo) を定義します。これらのモジュー
ルの詳細は、『Module Reference』を参照してください。
サーチジョブ調査によるサーチプロパティの表示
サーチジョブ調査は、サーチの処理状況や Splunk が時間をもっとも費やしている所を確認するためのツールで
す。ここでは、サーチジョブ調査を使ったサーチパフォーマンスのトラブルシューティング、およびイベントタイ
プ、タグ、ルックアップなどのナレッジオブジェクトの働きについて説明していきます。
サーチジョブ調査の使用
過去のサーチ結果が存在している限り (期限切れでない限り)、サーチジョブ調査でサーチジョブを調査することが
できます。サーチが動作している必要はありません。
サーチを調査するには：
1. サーチを実行します。
2. [アクション] ドロップダウンメニューから、[サーチジョブの検査] を選択します。
新しいブラウザウィンドウにサーチジョブ調査が表示されます。
過去のサーチ結果のプロパティを表示するには：
サーチ ID (SID) がある場合、URL を使って過去のサーチ結果を調査できます。サーチの SID は、ジョブ管理で確
認できます (右上の [ジョブ] リンクをクリック)。または、Splunk のディスパッチディレクトリ
$SPLUNK_HOME/var/run/splunk/dispatch にも記載されています。ジョブ管理の詳細は、『Knowledge Manager
Manual』の「Supervise your search jobs with the Job Manager」を参照してください。
サーチジョブ調査ウィンドウで URI パスに注目すると、文字列の最後に以下のような文字列が付いているのが分
かります。
.../inspector?sid=1299600721.22&namespace=search
および namespace は SID 番号およびそれが属する App 名を表しています。ここでは、SID は 1299600721.22 に
なります。
sid
過去のサーチ結果の SID を URI パスの sid= の後に入力して、Return キーを押してください。サーチを表示するた
めに十分な権限を持っている限り、それを調査することができます。
さて、何を調査しますか？
ジョブ調査で分かること
サーチの実行中、ジョブ調査には 2 種類のパネルが表示されます。[実行コスト] には、サーチのコンポーネントに
関する情報、およびサーチの総合的なパフォーマンスにおいて各コンポーネントが与える影響が表示されま
す。[サーチジョブのプロパティ] には、ジョブのその他の特徴が表示されます。サーチ完了時にジョブ調査は、見
つかった結果数およびサーチ完了までにかかった時間を通知します。サーチ完了後、ジョブ調査の画面上部にはエ
ラーメッセージも表示されます。大部分の情報は簡単に理解できますが、このセクションではパネルをもう少し詳
細に説明していきます。
実行コスト
8
[実行コスト] パネルでは、サーチ-時間イベント処理アクションに関連する特定のコンポーネントのパフォーマン
ス上の影響に注目することで、サーチ効率のトラブルシューティングを行えます。このパネルには、コンポーネン
トのテーブル、それぞれの期間 (秒)、サーチ実行時の各コンポーネントの起動回数、各コンポーネントの入出力イ
ベント数が表示されます。コンポーネントはアルファベット順に表示され、実行したサーチによってその数は異な
ります。以下の表は、個別のサーチコマンドおよび分散サーチコンポーネントの意義について説明しています。
(これらは、単にキーワードサーチを実行した場合に表示されるコンポーネントです。)
サーチコマンドコンポーネント
名
説明
Splunk は、サーチに一致するインデックスフィールドを含むイベントを識別すると、イベント
自体を調査してその他の基準に一致するかどうかを判断します。これらは同時に処理されます。
順次処理されるのではありません。
command.search.index - raw データ内の読み取り場所を判断するため
に、TSIDX ファイルの調査にかかった時間を示します。
command.search.rawdata - raw データファイルから実際のイベントを読
み取るまでにかかった時間を示します。
command.search.typer - イベントタイプの識別にかかった時間を示しま
す。
command.search.kv - イベントへのフィールド抽出の適用にかかった時
間を示します。
command.search.fieldalias - props.conf に基づいた、フィールド名の変更
にかかった時間を示します。
command.search.lookups - 既存のフィールドに基づいて、新しいフィー
ルドを作成するためにかかった時間を示します (フィールドルックアッ
プを実行)。
command.search.filter - 一致しないイベントのフィルタリングにかかっ
た時間を示します (たとえば、フィールドとフレーズ)。
command.search.typer - イベントへのイベントタイプの割り当てにか
かった時間を示します。
command.search.tags - イベントへのタグの割り当てにかかった時間を
示します。
command.search
使用するコマンドのタイプと、呼び出し、入力数/出力数に表示される項目数には関係があります。イベントを生
成するサーチの場合、入力数は 0 で、出力数はある程度のイベント数 X になると予測できます。サーチがサーチ
の生成とフィルタリングの両方を行う場合、フィルタリングには入力 (生成サーチの出力 X と等しい) および出力
= X となります。合計数は、入力 = X、出力 = 2*X になり、呼び出し回数は倍になります。
分散サーチコンポーネント名
説明
dispatch.createProviderQueue
すべてのサーチピアに接続する時間。
引数のパーシングとサブサーチ評価に消費された時間。これは、使用される各サーチコマンドに
よりさらに詳細に分けられます。
dispatch.evaluate
dispatch.evaluate.search - search コマンドが実行されたことを示しま
す。
dispatch.fetch
サーチピアからのイベントの待機または取得に費やされた時間。
dispatch.preview
プレビュー結果の生成に費やされた時間。
dispatch.process_remote_timeline
サーチピアが生成したタイムラインのデコードに費やされた時間。
dispatch.stream.local
サーチのストリーミング部でサーチヘッドが費やした時間。
dispatch.timeline
タイムラインとフィールドピッカー情報の生成に費やされた時間。
サーチジョブのプロパティ
[サーチジョブのプロパティ] フィールドはアルファベット順に表示されます。
パラメータ名
説明
cursorTime
以降にイベントがスキャンされていない、もっとも早い時間。進捗状況を示すために使用できま
す。doneProgress の説明を参照してください。
delegate
保存済みサーチに対して、ユーザーが開始したジョブを指定します。デフォルトはスケジュー
ラーになります。
diskUsage
使用されている合計ディスクスペース量 (バイト)。
dispatchState
サーチの状態。QUEUED、PARSING、RUNNING、PAUSED、FINALIZING、FAILED、または
DONE になります。
9
サーチのおおよその進捗状況を示す、0～1.0 の数字。
doneProgress
doneProgress = (latestTime ? cursorTime) / (latestTime ? earliestTime)
dropCount
リアルタイムサーチのみ。rt_queue_size のために破棄された、見込みイベント数 (デフォルト
は 100000)。
earliestTime
サーチジョブの開始が設定されたもっとも早い時間。進捗状況を示すために使用できます。
doneProgress の説明を参照してください。
eai:acl
App およびユーザーレベルの権限を記述します。たとえば、App がグローバルに共有されてい
るかどうか、サーチを実行または表示できるユーザーなどを記述します。
eventAvailableCount
エクスポートに利用できるイベント数。
eventCount
サーチが返したイベント数。
eventFieldCount
サーチ結果で見つかったフィールド数。
eventIsStreaming
このサーチのイベントをストリーム配信するかどうかを示します。
eventIsTruncated
サーチのイベントが保管されていないため、サーチのイベントエンドポイントから利用できない
かどうかを示します。
eventSearch
任意の変換コマンド前のサーチ全体のサブセット。タイムラインおよびイベントエンドポイント
は、サーチのこの部分の結果を表しています。
eventSorting
このサーチのイベントがソートされているかどうか、およびソート順序を示します (asc = 昇
順、desc = 降順、none = 未ソート)。
isDone
サーチが完了したかどうかを示します。
isFailed
サーチ実行時に致命的なエラーがあったかどうかを示します。たとえば、サーチ文字列に無効な
構文があった場合にそれを示します。
isFinalized
サーチが完了 (実際の終了前に停止) されたかどうかを示します。
isPaused
サーチが一時停止されたかどうかを示します。
isPreviewEnabled
プレビューが有効になっているかどうかを示します。
isRealTimeSearch
サーチがリアルタイムサーチかどうかを示します。
isRemoteTimeline
リモートタイムライン機能が有効になっているかどうかを示します。
isSaved
サーチが永久保存されたかどうかを示します。
isSavedSearch
スケジューラーを使って実行する保存済みサーチかどうかを示します。
isZombie
サーチを実行しているプロセスは dead になったけれども、サーチが完了されていないかどうか
を示します。
keywords
このサーチが使用するすべての肯定キーワード。肯定キーワードとは、NOT 句内にはないキー
ワードです。
label
このサーチが作成したカスタム名。
latestTime
サーチジョブの開始が設定されたもっとも遅い時間。進捗状況を示すために使用できます。
doneProgress の説明を参照してください。
numPreviews
このサーチジョブで現在までに生成されたプレビュー数。
messages
エラーとデバッグメッセージ。
performance
実行コストの他の表記法です。
remoteSearch
各サーチピアに送信されるサーチ文字列。
reportSearch
レポートコマンドが使用された場合のレポート対象サーチ。
request
サーチが splunkdに送信する GET
resultCount
サーチが返す結果数合計。別の言い方をすれば、スキャンしたイベント数 (scanCount で表され
る) の中で、実際にサーチ単語に一致したサブセット。
resultIsStreaming
サーチの最終結果をストリーミングを使って利用できるかどうかを示します (たとえば、変換操
作なし)。
resultPreviewCount
最新のプレビュー結果の結果行数。
runDuration
サーチ完了までにかかった時間 (秒)。
scanCount
スキャンされたまたはディスクから読み込まれたイベント数。
search
サーチ文字列。
searchProviders
通信したすべてのサーチピアのリスト。
10
引数。
sid
サーチ ID 番号。
statusBuckets
最大タイムラインバケツ数。
ttl
有効期間、またはサーチジョブの完了後、それが失効するまでの時間。
サーチに関するその他の情報へのリンクを示します。これらのリンクは利用できない場合もあり
ます。
その他の情報
タイムライン
フィールドサマリー
search.log
注意：サーチパフォーマンスのトラブルシューティングを行う場合、scanCount と resultCount のコストの違いを
正しく理解しておくことが重要です。デンスサーチの場合、scanCount と resultCount は類似します(scanCount =
resultCount)。スパースサーチの場合、scanCount は resultCount よりも大幅に大きな値になります (scanCount >>
resultCount)。サーチパフォーマンスを測定する際には、resultCount/時間の比ではさほど正確には表せません。
scanCount/時間の比を使用してください。一般的に、scanCount/秒のイベントレートが 10,000～20,000 イベント/
秒の場合に、パフォーマンスは良好とみなされます。
デバッグメッセージ
サーチにエラーがある場合、これらのメッセージはサーチジョブ調査ウィンドウの上部に、DEBUG メッセージと
して表示されます (以前のバージョンでは、ダッシュボードのバナーとして表示されていた)。たとえば、結果に一
部のフィールドが存在しない場合、デバッグメッセージがその旨を通知します。
注意：サーチ完了までは、これらのメッセージは表示されません。
サーチジョブ調査の出力例
全時間実行した dedup サーチの実行コスト例を以下の示します。
* | dedup punct
[実行コスト] パネルのサーチコマンドコンポーネントは、以下のような感じで表示されます。
command.search コンポーネントおよびその下にある項目は、サーチの search コマンド部のパフォーマンス上の影
響を表しています (パイプ文字の前のすべて)。
command.prededup は、dedup コマンドに渡す前の search コマンドの結果処理のパフォーマンス上の影響を表して
います。command.prededup の入力カウントは、command.search の出力カウントと一致し、command.dedup の
入力カウントは command.prededup の出力カウントと一致しています。この場合、command.dedup の出力カウン
トは、サーチ完了時に返されるイベント数と一致していなければなりません ([サーチジョブのプロパティ] の下の
resultCount の値)。
回答
何か質問がありますか？「Splunk Answers」から、Splunk コミュニティに寄せられた、サーチジョブ調査の使用
方法に関する質問と回答をご覧ください。
サーチに合わせたサーチモードの設定
11
サーチモードセレクタを使って、ご自分のニーズに合わせたサーチを利用することができます。設定内容に応じ
て、サーチで利用できるすべてのデータを表示したり (サーチ時間が長くなる)、さまざまな方法でサーチを高速
化/能率化したりすることができます。
サーチモードセレクタは、サーチバーの右上角にあります。[スマート] (デフォルト)、[高速]、および [詳細] モード
を利用できます。
高速および詳細モードは、サーチモードの両極を為しています。デフォルトのスマートモードは、実行するサーチ
の種類に応じてこれらのモードを切り替えます。保存済みサーチを初めて実行する場合は、スマートモードで実行
されます。
高速モードの選択
[高速] を選択した場合、パフォーマンスが優先され、重要ではないフィールドやイベントデータは無視されます。
この場合、サーチですべての候補データが返される訳ではありません。必要なデータのみが返されます。高速モー
ドを使用する場合の Splunk の動作を以下に示します。
フィールド検出を無効にします。フィールド検出は、Splunk がデフォルトフィールド以外
の、host、source、およびsourcetype などのフィールドの抽出に使用するプロセスです。これは、Splunk がデ
フォルトフィールドとサーチの要件を満たすために必要なフィールド (特定のフィールドをサーチする場
合、それらのフィールドが抽出される) の情報のみを返すことを表しています。
レポートサーチの実行時に、サーチ結果をレポート結果テーブルまたはビジュアル化でのみ表示します (レ
ポートコマンドを含むサーチ)。高速モードでは、レポートコマンドを含まないサーチについては、イベント
リストとイベントタイムラインのみが表示されます。
詳細モードの選択
詳細モードを選択した場合、サーチ完了に時間がかかる場合でも、サーチにレポートコマンドが含まれている場合
でも、Splunk は可能なすべてのフィールドとイベントデータを返します。詳細サーチモードを使用する場合の
Splunk の動作を以下に示します。
可能なすべてのフィールドを検出します。これには、デフォルトのフィールド、自動サーチ-時間フィールド
抽出、およびすべてのユーザー定義のインデックス-時間およびサーチ-時間フィールド抽出が含まれていま
す。検出されたフィールドは、左側のサイドバーに表示されます。
結果のイベントリストビューを返して、サーチタイムラインを生成する。サーチにレポートコマンドが含ま
れている場合は、レポートテーブルと視覚エフェクトも生成します。
レポートサーチを利用したいけれども、レポートに必要なフィールドが分からない場合、または正しいイベントを
要約しているかどうかを検証したい場合には、詳細モードを使用します。
注意：サーチを詳細モードで実行する場合、レポート高速化の恩恵は受けられません。サーチの保存時に [Turn
on acceleration] (高速化をオンにする) を選択したらサーチが高速化された場合に、そのサーチを詳細モードに切
り替えると、サーチ速度は遅くなり、高速化機能を利用しない場合と同じになります。
レポート高速化機能は、10 万件を超えるイベントに対してレポートコマンドを利用したサーチを実行するよう
な、完了までに時間がかかるサーチを前提に設計されています。詳細は、『Knowledge Manager Manual』の
「Save searches and share search results」を参照してください。
スマートモードの選択
スマートモードはデフォルトのサーチモードです。また、保存済みサーチを初めて実行する場合に使用されるモー
ドでもあります。実行するサーチに対して最良の結果を得ることを目的に設計されています。単にイベントをサー
チする場合、必要なすべてのイベントの情報が取得されます。レポートサーチを実行する場合、Splunk は完全性
よりも速度を重視して、レポート結果テーブルや視覚エフェクトを直接提供します。
レポートコマンドを含まないスマートモードサーチを実行する場合、Splunk は詳細モードのように動作します。
たとえば：
可能なすべてのフィールドを検出します。
フルイベントリストおよびイベントタイムラインを生成します。レポートコマンドが必要なため、イベント
テーブルや視覚エフェクトは表示されません。
12
レポートコマンドを含むスマートモードサーチを実行する場合、Splunk は高速モードのように動作します。たと
えば：
フィールド検出を無効にします。
イベントリストとイベントタイムラインの生成に時間を費やさず、レポート結果テーブルや視覚エフェクト
に直接移動します。
レポートコマンドやレポートサーチの詳細は、『サーチマニュアル』の「レポートコマンドについて」を参照して
ください。
実行中のサーチへのアクション
Splunk は、処理中のサーチを管理し、レポートやダッシュボードを作成するための一連のコントロールが用意さ
れています。サーチ実行中、これらのコントロールはサーチバーの下に青いボタンで表示されます。以下のような
コントロールがあります。
バックグラウンドに送信：フォアグラウンドで他の作業を行っている間、サーチを「バックグラウンド」に
移動します。バックグラウンドのサーチが完了したら、その旨が通知されます。バックグラウンドのサーチ
ジョブへのアクセスおよびその結果の確認は、[ジョブ] ページから行えます。
一時停止/再開：実行中のサーチを一時停止します。長い時間がかかるサーチを実行中に、一時的にそれを停
止するような場合に役立ちます。[再開] をクリックしてサーチを継続したり、[完了] をクリックしてサーチ
を完了 (以下を参照) したりすることができます。
完了：サーチが完全に終了する前に処理を停止します。その時点までに取得した結果が表示されます。完了
させた結果を使ってレポートを作成できます。
キャンセル：処理中のサーチをキャンセルして、結果をすべて削除します。[ジョブ] ページには、最近キャ
ンセルされたサーチの一覧が表示されます。ただし、結果は削除されているため、[表示] リンクは表示され
ません。
ジョブ調査：サーチジョブ調査を開きます。これは、サーチの内容や Splunk が時間をもっとも費やしてい
る所を確認するためのツールです。サーチの実行中またはサーチ完了後にこの操作を行えます。詳細は、
「サーチジョブ調査の使用」を参照してください。
印刷：サーチ完了後、現在のページの結果タイムラインとイベントリストを印刷することができます。
バックグラウンドに移動したサーチの追跡、キャンセル、アラートなどの [ジョブ] ページの使用方法については、
『Knowledge Manager Manual』の「Supervise Your Search Jobs with the Job Manager」を参照してください。
[作成] オプションを使って以下の項目を作成できます。
ダッシュボードパネル...：サーチに基づいてダッシュボードパネルを生成し、それを新たなまたは既存
のダッシュボードに追加する場合にクリックします。ダッシュボードの詳細は、『Splunk データのビジュア
ル化マニュアル』の「UI を使ったダッシュボードの作成と編集」を参照してください。
アラート...：サーチに基づくアラートを定義する場合にクリックします。アラートは保存済みサーチをバッ
クグラウンドで実行します (スケジュールまたはリアルタイムで)。サーチでアラートに設定した条件と一致
する結果が返されると、アラートが生成されます。詳細は、『アラートマニュアル』の「アラートについ
て」を参照してください。
レポート...：長い時間がかかるサーチを実行しており、サーチが実際に完了する前にそれに基づくレポー
トを定義したい場合は、これをクリックしてレポートビルダーを起動し、レポートの定義を開始することが
できます。レポートビルダーの起動後もサーチは続行されます。レポートには、返されたイベントデータが
すべて反映されます。詳細は、『Splunk データのビジュアル化マニュアル』の「レポートビルダーによるレ
ポートの定義」を参照してください。
イベントタイプ...：イベントタイプを使って、共通の特徴を持つイベントを分類することができます。パイ
プ演算子またはサブサーチが含まれていないサーチは、このオプションを使ってイベントタイプとして保存
できます。詳細は、『Knowledge Manager Manual』の「About event types」および「Define and maintain
event types in Splunk Web」を参照してください。
スケジュールサーチ...：サーチ実行時に毎回アクション (サーチ結果を特定の人々にメール送信するなど) を
実行するスケジュール済みサーチを作成する場合に選択します。詳細は、『Knowledge Manager Manual』
の「Define scheduled searches」を参照してください。
より良いサーチの作成
このトピックでは、効率的なサーチを作成するために役立つ簡単なルールを説明していきます。サーチ速度には多
くの要因が影響します。サーチ対象のデータ量、サーチの内容、同時にサーチを実行するユーザー数に対応できる
デプロイ環境かどうかなど、さまざまな要因が考えられます。サーチ速度を最適化するために大切なのは、
Splunk が必要な作業以外を行わないようにすることです。
13
サーチの種類
サーチ最適化の推奨事項は、実行するサーチの種類およびサーチ対象データの特徴によって異なります。一般的に
は、イベントの取得やレポートの生成など、何をするかに基づいてサーチを区別します。データセット内で目的の
イベントが頻繁に発生しているような場合、それを「デンスサーチ」と呼んでいます。データセット内で目的のイ
ベントが滅多に存在しない場合は、それを「スパースサーチ」と呼んでいます。
詳細は、「サーチについて」を参照してください。
raw イベントサーチ
raw イベントサーチは、取得したイベントを処理することなく、Splunk インデックスからそのままイベントを返
します。基本的にインデックスからイベントを取得する際には、目的のイベントのみを取得するように適切な指定
を行うことが大切です。そのためには、イベント固有のキーワードおよびフィールド/値のペアを使用します。大
量のデータにスパースサーチを実行する場合、同じデータセットにデンスサーチを行う場合と比べて時間がかかる
ことに注意してください。
最初からできる限りサーチを絞り込んで、ディスクから取得するデータ量を最低限に抑えるようにしてくだ
さい。たとえば、Web アクセスイベントのみに注目する場合は、当該データの特定のホスト、インデック
ス、またはソースタイプのみにサーチを制限します。
一度に複数のタイプのデータにまたがるサーチを行うことがほとんどない場合は、各データタイプを異なる
インデックスで分割し、サーチを特定のインデックスに限定します。たとえば、あるインデックスには Web
アクセスデータを、別のインデックスにはファイアウォールデータを保管します。複数のインデックスの設
定方法、および異なるインデックスのサーチ方法を参照してください。
サーチを特定の時間ウィンドウに限定します。たとえば、数分前に発生したエラーの原因を調査する場合
は、過去 1 週間 (-1w) ではなく過去 1 時間 (-1hr) のデータをサーチします。「サーチの時間範囲について」
を参照してください。
レポート生成サーチ
レポート生成サーチは、インデックスから取得したイベントに対して、さらなる処理を行います。結果セットに対
して 1 つまたは複数の統計関数を利用した、フィルタリング、変換、およびその他の操作を行えます。この処理は
メモリー内で行われるため、ディスクから取得するイベント数を限定するほど、サーチが高速に行われます。
レポートを作成する場合、タイムラインビューではなく詳細グラフビューからサーチを開始してくださ
い。タイムラインビューでは、タイムラインの計算と作成のために大量の処理が行われます。詳細グラフ
ビューでサーチを実行すると、プレビューは無効になるため、それに伴う処理上のオーバーヘッドを減らせ
ます。
レポートはフィールドに依存しており、フィールドのすべての最適化ルールが適用されます。
情報密度
raw イベントを取得するにせよレポートを作成するにせよ、サーチ対象の情報がスパースなのかまたはデンスなの
かを考慮する必要があります。
スパースサーチは、大量のデータセット内で滅多に発生しない単一のイベントを検索するサーチです。これ
は「干し草の山から 1 本の針を見つける」サーチと比喩されることもあります。たとえば、特定の IP アドレ
スやエラーコードを探すサーチなどが挙げられます。スパースサーチを実行する際には、サーチ (タイムラ
イン) ビューを使用してください。このビューは、イベントからできる限りの関連情報の抽出を試みるた
め、独自のイベントの検索に役立ちます。
デンスサーチは、多数のイベントをスキャン、レポートするサーチです。たとえば、発生したエラー数のカ
ウントや特定のホストからのすべてのイベントの検索などが挙げられます。大量のデータにまたがってイベ
ントをレポートするデンスサーチを実行する際には、詳細グラフビューを使用してください。このビュー
は、すべてのフィールド情報を処理するのではなく、サーチを完了するために必要な情報のみを処理するよ
うに最適化されています。
サーチでのフィールドの使用
サーチ時に抽出されるフィールドではなく、すでに抽出されているフィールド (インデックスが作成されたフィー
ルド) を使用すると、フィールドによるサーチを高速化できます。
データを効率的にサーチ、フィルタリングするために、できる限りインデックスが作成されたフィールドお
よびデフォルトのフィールドを活用してください。インデックス時に、Splunk は各イベントに共通の一連の
デフォルトフィールドを抽出します。これらのフィールドには、host、source、および sourcetype が含まれま
す。サーチではできる限りこれらのフィールドを使ってデータをフィルタリングしてください。そうするこ
とにより、必要最低限のデータのみを処理できます。たとえば、Web アクセスエラーに関するレポートを作
成する場合、レポートコマンドを実行する前に特定のエラーのみをサーチします。
sourcetype=access_* (status=4* OR status=5*) | stats count by status
サーチ時にフィールドを抽出すると、処理上のオーバーヘッドが生じます。サーチで追加のフィールドが不
要な場合は、サーチモードの設定でフィールド検出を無効にして、タイムラインビューでのパフォーマンス
を向上するか、または fields コマンドを使って結果に必要なフィールドのみを指定してください。
14
ただし、フィールド検出を無効にすると、サーチを実現するために必要なフィールド (サーチ対象の特定のフィー
ルドなど)、および _time、host、source、sourcetype などのデフォルトフィールド以外のフィールドの自動抽出は行
われません。イベントから可能性がある各フィールドを抽出する手間がなくなるため、サーチの実行は高速化され
ます。
デフォルトで [サーチモード] は、[スマート] に設定されています。レポートコマンドを使用するサーチ、データに
存在しているフィールドが分からないサーチ、サーチを絞り込むために追加フィールドが必要な場合などは、これ
を [詳細] に設定してください。
サーチモードの設定の詳細は、このマニュアルの「サーチを調整するためのサーチモードの設定」を参照してくだ
さい。
フィールドおよびフィールド抽出の詳細は『Knowledge Manager Manual』を、fields コマンドについては
『Search Reference Manual』を参照してください。
データの要約
大量のデータセットに対してサーチを行う場合、非常に時間がかかることがあります。大量のデータに対して定期
的にレポートを生成する場合は、サマリーインデックスを使って、レポートでもっとも頻繁に使用する値を事前に
算出してください。保存済みサーチをスケジュールして定期的に指標を収集し、raw データの代わりに要約した
データをレポートします。
レポート効率を向上するためのサマリーインデックスの使用方法に関する記事を参照してください。
サーチジョブ調査の使用
サーチジョブ調査は、サーチのパフォーマンスに関する問題のトラブルシューティング、およびイベントタイプ、
ルックアップ、その他のサーチ内コンポーネントなどのナレッジオブジェクトの実行コストの理解に利用できる
ツールです。このツールは、サーチの最適化方法をより良く判断できるように、サーチの動作を解析します。
詳細は、「サーチジョブ調査の使用方法」を参照してください。
イベントの取得
イベントの取得について
Splunk でサーチを実行する場合、サーチコマンドを使ってサーチ単語に一致するイベントデータを検索します。
これらのサーチ単語は、インデックスから取得するイベントを示す、キーワード、フレーズ、論理演算式、フィー
ルド名/値のペアなどです。
イベントの取得方法の詳細は、「サーチコマンドの使用」を参照してください。
イベントデータが異なるインデックスや複数の分散サーチピア間にパーティション分割されている場合もありま
す。
複数のインデックスやサーバーにまたがるサーチについては、「インデックスおよび分散サーチピアからの
イベントの取得」を参照してください。
時刻でフィルタリングを行うと、タイムラインを使ってイベントの集合にズームインする場合でも、サーチ自体に
時間範囲を適用する場合でも、イベントの取得が高速化されます。
詳細は、「タイムラインを使ったイベントパターンの調査」を参照してください。
詳細は、「サーチの時間範囲について」を参照してください。
イベント、イベントデータ、およびフィールド
一般的に「イベントデータ」とは、Splunk のインデックスに追加された後のデータを表しています。イベント自
体は、単一のアクティビティレコードまたはこのイベントデータのインスタンスです。たとえば、ログファイル内
の単一のログエントリが 1 つのイベントになります。Splunk は個別のイベントを、その時間情報により分割しま
す。あるイベントと他のイベントはタイムスタンプで区別されます。
15
イベントの例を以下に示します。
172.26.34.223 - - [01/Jul/2005:12:05:27 -0700] "GET /trade/app?action=logout HTTP/1.1" 200 2953
イベントには、情報のペア、またはフィールドが含まれています。データを追加してインデックスを作成すると、
Splunk は自動的にいくつかのフィールド (イベントのホストやデータソースの種類など) を抽出します。
サーチコマンドの使用
Splunk サーチを実行するには search コマンドを使用する必要があります。サーチパイプラインの先頭にこのコマ
ンドは暗示されています。実際にコマンドを起動する必要はありませんが、それを使用していることになります。
search コマンドにより、キーワード、フレーズ、フィールド、論理演算式、比較式を使って、Splunk インデック
スから取得するイベントを正確に指定することができます。
キーワード、フレーズ、ワイルドカード
キーワードとフレーズの例を以下に示します。
web
error
web error
"web error"
引用符で囲まれたフレーズ "web error" は、その前のサーチとは異なることに注意してください。
ワイルドカードのアスタリスク (*) を使ってキーワードやフレーズを照合することができます。* でサーチを実行
すると、それは「すべてにマッチ」を意味しており、上限値に至るまですべてのイベントが返されます。単語の一
部に * を使用すると、その単語に基づいて照合が行われます。たとえば、以下のサーチを実行すると fail、failed、
failures などにマッチするイベントが返されます。
fail*
目的のイベントに特有のサーチ単語を指定すれば、より良好な結果を得ることができます。たとえば、「denied」
(拒否) でサーチを実行するよりも、「access denied」 (アクセス拒否) の方が良い結果を得られます。イベントの
90% に「?error?」と言う単語が存在しているけれども、「?sshd?」は 5% にしか存在していない場合 (そして目
的のイベントに両方の単語が必要な場合)、サーチに「?sshd?」を入れるとより効率的に検索を行えます。
論理演算式
Splunk は論理演算子 AND、OR、および NOT をサポートしています。演算子は大文字でなければなりません。複数の
単語の間には、常に AND 演算子が存在するものとみなされます。つまり、web error は web AND error と同じです。
括弧を使って論理演算式をグループ化することができます。Splunk は論理演算式を次の順序で評価します。ま
ず、括弧内の式が評価されます。次に、OR 句が評価されます。最後に AND または NOT 句が評価されます。
web client error NOT (403 OR 404)
注意：一般的に包含条件の方が除外条件よりも良好な結果を得られます。"access denied" (アクセス拒否) の方が
NOT "access granted" (「アクセス許可」の否定) よりも素早く結果を得られます。
フィールド式
データの追加時に、Splunk は情報のペアを抽出して、それをフィールドとして保存します。一部のフィールドは
すべてのイベントに共通ですが、そうではないフィールドも存在しています。サーチ単語にフィールドを追加する
と、特定のイベントをより正確に探し出せます。
特定の HTTP ステータスエラーに関する Web アクセスログをサーチする場合、「web error 404」でサーチする代
わりに、以下のようにフィールドを使ってサーチを行えます。
status=404
詳細は、「フィールドを使ったイベントの取得」を参照してください。
ワイルドカードを使った複数フィールド値との照合
ワイルドカード文字のアスタリスクを使って、複数のフィールド値と照合することもできます。たとえば、以下の
サーチを実行すると、HTTP ステータス 400、401、402 などを持つイベントが返されます。
status=40*
比較演算子を使ったフィールド値の照合
比較演算子を使って、特定の値または一連のフィールド値を照合できます。
16
演算子
例
結果
「foo」と完全一致する複数値フィールドの値。
=
field=foo
!=
field!=foo 「foo」と完全一致しない複数値フィールドの値。
<
field<x
値が x 未満の数値フィールド値。
>
field>x
値が x を超える数値フィールド値。
<=
field<=x
値が x 以下の数値フィールド値。
>=
field>=x
値が x 以上の数値フィールド値。
たとえば、delay フィールドの値が 10 を超えるイベントを検索するには、以下のように指定します。
delay > 10
CASE() または TERM() ディレクティブを使ったフレーズの照合
イベント内のフレーズをサーチする場合、CASE() または TERM() ディレクティブを使用することもできます。
CASE を使用すると、大文字と小文字を区別して単語やフィールドとの完全一致が検索されます。
TERM を使用すると、一般的に改行や区切り文字として認識される文字 (アンダースコア、スペース、また
は IP アドレスのピリオドなど) が含まれている場合でも、括弧内のすべてがインデックス内の単一の単語と
して照合が行われます。
引用符で囲まれたフレーズ「"error_type"」をサーチする場合、「error」と「type」でサーチが行われ、後処理で
結果のフィルタリングが行われます。これには、他のキーワードやフレーズの一部として「error_type」を含むイ
ベントも含まれます (例：error_type.default、this_error_type)。TERM(error_type) を使用すれば、これらの余計な
キーワードは除外されます。
フィールドを使ったイベントの取得
フィールドは、イベントデータ内のサーチ可能な名前と値のペアです。データのインデックスを作成する際に、
Splunk は自動的にフィールドを抽出して、イベントデータに分かりやすいラベルを追加します。これらのフィー
ルドを使ってサーチを行ったり、フィールドを編集したり、他のナレッジを抽出してカスタムフィールドとして保
存したりすることができます。
インデックスおよび分散サーチピアからのイベントの取得
新しいインデックスの作成、サーチピアの追加、データの保管場所の管理はいつでも行えます。異なる複数のイン
デックスや分散サーチピアにまたがってデータを分割している場合、1 回に 1 つのインデックスやサーバーに対し
てサーチを実行する必要はありません。複数のインデックスやサーバーに対して一度にサーチを実行できます。
1 つまたは複数のインデックスサーチの指定
Splunk 管理者は、ユーザーがサーチするデフォルトのインデックスを設定することができます。ユーザーのロー
ルや権限に基づいて、1 つまたは複数のインデックスにアクセスさせることができます。たとえば、メインイン
デックスのサーチのみを行えるようにすることも、公開されているすべてのインデックスのサーチを行えるように
することも可能です。ユーザーはサーチを行う際に、これらのインデックスのサブセットを指定します (個別のイ
ンデックスまたは複数のインデックスに対して)。ユーザーとロールの設定方法の詳細は、『Securing Splunk』の
「About users and roles」を参照してください。
インデックスの管理と複数インデックスの設定については、『インデクサーとクラスタの管理マニュアル』の「イ
ンデックスの管理について」を参照してください。
Splunk Web を介したインデックスアクセスの制御
[管理] >> [アクセス制御] >> [ロール] に移動します。ユーザーに割り当てられているロールを選択します。次の画面
の下部に、インデックスコントロールが記載されています。特定のロールが利用できるインデックスやデフォルト
のサーチインデックスなどを設定することができます。
構文
フィールド名と値を指定する場合と同じ方法で、複数のサーチ対象インデックスを指定できます。この場合、
フィールド名は index、フィールド値は特定のインデックス名になります。
index=<indexname>
ワイルドカード * を使って複数のインデックスを指定できます。たとえば、「mail」と「main」の両方のインデッ
クスをサーチする場合は、次のように指定します：
index=mai*
また、括弧を使って各インデックスに対して異なるサーチを適用することもできます。詳細は例 3 を参照してくだ
さい。
17
注意：サーチバーに「index=」と入力する場合、ロールと権限に基づいて、先行入力にはサーチ可能なすべてのイ
ンデックスが表示されます。
例
例 1：すべての公開インデックスに対してサーチを実行します。
index=*
例 2：すべての公開インデックスおよび内部インデックスに対してサーチを実行します。
index=* OR index=_*
例 3：異なるサーチを異なるインデックスに分割します。この例では、3 つの異なるインデックス main、
_internal、および mail をサーチします。ここで、3 つのインデックスすべてに対して「error」とマッチするイベ
ントを探しますが、それに加えて main では「warn」、mail では「failed」とマッチするエラーを探します。
(index=main (error OR warn)) OR (index=_internal error) OR (index=mail (error OR failed))
例 4：異なる分散 Splunk サーバー上の複数のインデックスにまたがってサーチを実行します。
(splunk_server=local index=main 404 ip=10.0.0.0/16) OR (splunk_server=remote index=mail user=admin)
1 つまたは複数のサーチピアにまたがるサーチ
サーチヘッドから分散サーチを実行する場合、デフォルトではサーチを特定のサーチピア (インデクサーノード)
に制限することができます。これは、保存済みサーチやスケジュール済みサーチでも可能です。Splunk サーチピ
アの名前は、[splunk_server] フィールドの値として保存されます。分散サーチの詳細は、『Distributed
Deployment manual』の「About distributed search」を参照してください。
サーチピアを指定しない場合は、アクセス権があるすべてのサーチピアが利用されます。アクセスできるデフォル
トのピアは、自分のプロファイルに関連付けられているロールと権限によって決まります。この設定は、Splunk
管理者が行います。詳細は、『Securing Splunk』の「About users and roles」を参照してください。
特定のピアにサーチを制限する機能は、あるサーチピアの遅延時間が大きく、デフォルトではそれを対象にサーチ
したくないような場合などに役立ちます。1 つまたは複数のサーチピアを指定すると、それらのサーバーのみが
サーチに含められます。
その他のフィールド名と値を指定する場合と同じ方法で、複数のサーチピアを指定できます。この場合、フィール
ド名は「splunk_server」、フィールド値は特定の分散ピア名になります。
splunk_server=<peer_name>
注意：サーチ元の Splunk インスタンス (サーチヘッド自身) を表すために値「local」を使用することができます。
splunk_server=local
フィールド名では大文字と小文字が区別されることに注意してください。大文字小文字が違っていると、その
フィールド名は認識されません。
例
例 1：指定したサーチピアから結果を返します。
error (splunk_server=NYsplunk OR splunk_server=CAsplunk) NOT splunk_server=TXsplunk
例 2：分散サーチピア「foo」または「bar」で、異なるインデックスをサーチします。
(splunk_server=foo index=main 404 ip=10.0.0.0/16) OR (splunk_server=bar index=mail user=admin)
目的のイベントが見つかりませんか？
Splunk に入力を追加すると、その入力はその時点で利用している App に追加されます。一部の App は、入力デー
タを独自のインデックスに書き込みます (たとえば、UNIX 版および Linux 版 Splunk App は、「os」インデックス
を使用します)。
Splunk に取り込んだはずのデータが見つからない場合は、適切なインデックスを使用しているかどうかを確認し
てください。使用しているロールに対して、デフォルトインデックスのリストに App 固有のインデックスを追加
しなければならないこともあります。ロールの詳細は、『Securing Splunk』のロールに関するトピックを参照し
てください。
類似イベントの分類とグループ化
18
イベントはイベントタイプとは異なっています。イベントは、データの単一のインスタンスです。たとえば、1 つ
のログエントリがイベントになります。イベントタイプは、イベントにラベルを付けてグループ化するために用い
られる分類方法です。
イベントに対応するイベントタイプ名は、イベントの eventtype と呼ばれる複数値フィールドに設定されます。こ
れらのイベントグループ (例：SSH ログイン) は、任意のフィールド値と同じ方法でサーチできます。
ここでは、イベントの分類方法 (サーチをイベントタイプして保存) およびタグ付きフィールドのサーチ方法につ
いて説明していきます。イベントの詳細、Splunk のイベントの認識方法、インデックス作成時のイベントの処理
方法などについては、『Getting Data In Manual』の「Overview of event processing」を参照してください。
重要：サーチパイプラインをイベントタイプとして保存することはできません。つまり、サーチをイベントタイプ
として保存する場合、それにサーチコマンドを入れることはできません。
サーチの新規イベントタイプとしての保存
基本的に、イベントデータをサーチする場合、不要なイベントをすべて除去することになります。サーチ結果は類
似の特徴を持つイベントの集合になり、それらに総称名を指定することができます。
たとえば、異なるホストマシン上の失敗したログインを頻繁にサーチする場合、それらのイベントに対応するイベ
ントタイプを保存して、failed_login と言う名前を付けられます。
"failed login" OR "FAILED LOGIN" OR "Authentication failure" OR "Failed to authenticate user"
このサーチをイベントタイプとして保存するには：
1. [作成] をクリックして、[イベントタイプ...] を選択します。
2. [イベントタイプとして保存] で、サーチに名前を指定します。このサーチ例では、「failed_login」と名付けま
す。
必要に応じて、[サーチ文字列] フィールドを変更することができます。このフィールドには、先ほど実行したサー
チが自動的に入力されています。
また、必要に応じて [タグ] フィールドに、イベントタイプに適用するタグのリストを追加することもできます。
詳細は、後述のイベントタイプへのタグ設定に関する説明を参照してください。
3. [保存] をクリックするとイベントタイプ名が保存されます。
これで、任意のフィールドをサーチするのと同じ方法で、イベントタイプにマッチするすべてのイベントを手軽に
サーチできるようになります。
たとえば、特定のホストマシン上の失敗したログインを調査することができます。
host=target eventtype=failed_login
また、疑わしいユーザーのアクティビティを調査することもできます。
user=suspicious eventtype=failed_login
typelearner を使った新規イベントタイプの検出
任意のサーチを typelearner コマンドに渡すと、Splunk が提案するイベントタイプを確認できます。デフォルト
で、typelearner はサーチ結果となるイベントの句読点を比較し、類似の句読点や単語を持つイベントをグループ化
します。
19
イベントをグループ化するために、異なるフィールドを指定することができます。typelearner は任意のフィールド
と同じように機能します。結果は、このフィールドとフレーズを共通に保有する、一連のイベント (サーチ結果か
らの) になります。
詳細と例については、『Search Command Reference』の「typelearner」を参照してください。
タグを使った類似イベントのグループ化と検索
データ内で、関連するフィールド値でイベントをグループ化している場合があります。これらのフィールドのグ
ループを効率的にサーチするために、フィールド値にタグを割り当てることができます。抽出された任意のフィー
ルドに、1 つまたは複数のタグを割り当てられます (イベントタイプ、ホスト、ソース、またはソースタイプを含
む)。
イベントタイプには、それに関連する 1 つまたは複数のタグを割り当てられます。サーチをイベントタイプとして
保存する際に、またはイベントタイプ管理 ([管理] > [イベントタイプ])から、これらのタグを追加できます。この
ウィンドウのイベントタイプリストから、編集するイベントタイプを選択します。
イベントタイプにタグを追加したら、任意のタグのサーチと同じ方法でサーチを実施することができます。ファイ
アウォールイベントのサーチをイベントタイプ firewall_allowed として保存し、ログインイベントのサーチをイベ
ントタイプ login_successful として保存した場合を考えてみましょう。これらのイベントタイプにタグ「allow」を
設定しておけば、サーチを使って両方のイベントタイプのイベントを取得できます。
tag::eventtype="allow"
フィールド/値のペアにタグを設定することができます。また、フィールド名のエイリアスを設定することもでき
ます。タグの使用方法の詳細は、『Knowledge Manager Manual』の「Tag and alias field values in Splunk Web」
を参照してください。
タグ設定した値のサーチ
タグのサーチには 2 種類の方法があります。任意のフィールドの値に関連するタグをサーチする場合は、以下の構
文を使用できます。
tag=<tagname>
特定のフィールドの値に関連するタグをサーチする場合は、以下の構文を使用できます。
tag::<field>=<tagname>
ワイルドカードを使用したタグのサーチ
イベントタイプやタグを含め、キーワードやフィールド値をサーチする場合、ワイルドカード文字のアスタリスク
(*) を使用することができます。
たとえば、各種 IP アドレスに対して複数のイベントタイプタグがある場合 (IP-src や IP-dst など)、以下のように
指定してそれらのすべてをサーチすることができます。
tag::eventtype=IP-*
タグに「local」を含むすべてのホストを性する場合は、以下のようにタグをサーチします。
tag::host=*local*
タグのないイベントタイプを持つイベントをサーチする場合は、論理演算式を使用します。
NOT tag::eventtype=*
タイムラインを使ったイベントパターンの調査
タイムラインは、各時点で発生したイベント数を視覚的に表したものです。これは、時間の経過に伴うイベントの
分布を表しています。バー上にカーソルを移動すると、そのイベント数が表示されます。バーをクリックすると、
その時刻にドリルダウンできます。この方法でドリルダウンしても新たなサーチは実行されません。単に前のサー
チから結果をフィルタリングするだけです。タイムラインを使ってイベントのパターンまたはクラスタを強調表示
したり、イベントアクティビティのピーク (アクティビティのスパイク) を調査したりすることができます。
タイムラインオプションは、タイムラインの上にあります。ズームイン/アウトして、グラフのスケールを変更す
ることができます。タイムラインがさほど重要ではなく、イベントの表示領域を増やしたい場合は、タイムライン
を折りたたむことも可能です。必要に応じてそれをクリックして復元することができます。
20
タイムラインのスケールの変更
タイムラインは、線形または対数 (log) の 2 種類のスケールで表示できます。
以下の画像は、線形スケールでの第 2 四半期のすべてのイベントに対するサーチ結果を表しています。
以下の画像は、対数スケールでの第 2 四半期のすべてのイベントに対する同じサーチ結果を表しています。
イベントを調査するためのズームイン/アウト
ズームイン/アウトにより、注目する時間を変更することができます。たとえば、ズームインすることにより、タ
イムラインのバーが時間から分に変化します。バーをクリックすると、その時点のイベントにドリルダウンしま
す。ズームアウトすると、たとえば時間単位から分単位ではなく、日単位のイベントに変化します。
タイムライン内の一連のバーをマウスでクリックアンドドラッグします。
サーチ結果が更新され、選択した時間範囲内に発生したイベントのみが表示されます。
[ズームイン] をクリックすると、選択した期間のイベントのみを表示するように、タイムラインが更新され
ます。
タイムライン内の 1 つのバーをクリックします。
サーチ結果が更新され、選択したポイントの時点で発生したイベントのみが表示されます。
この場合も、[ズームイン] をクリックするとタイムラインが更新され、選択した時点のイベントのみが表示
されます。
タイムライン内のすべてのバーを選択する場合は (前の選択を取り消す)、[すべて選択] をクリックします。このオ
プションは、1 つまたは複数のバーを選択後、[ズームイン] または [ズームアウト] を選択する前にのみ利用できま
す。
21
時間範囲の指定
サーチにおける時間範囲について
何が問題なのかを特定する場合、時間が非常に重要になります。何か問題が起きた場合、正確に何が起きたのか分
からなくても、何らかの問題があると感じることもあるでしょう。同時刻に発生したイベントを調査することで、
結果間の相互関係を見つけ出し、主原因を特定する手がかりにできるかもしれません。あまりにも長期間のデータ
を調査することは、システムリソースを無駄にし、また結果が膨大で処理しきれなくなってしまいます。
この章では、サーチへの時間の追加方法を説明していきます。
時間範囲メニューからの選択
サーチへの時間修飾子の指定
リアルタイムサーチでのウィンドウの指定
サーチに適用する時間範囲の選択
サーチを実行する期間を指定するには、[時間範囲] メニューを使用します。
カスタム時間範囲の定義
カスタムの日付範囲を指定する場合は、ドロップダウンメニューから [カスタム時間...] を選択します。
次にポップアップウィンドウから [日付] を選択します。日付範囲を手動入力することも、カレンダーポップアップ
から選択することもできます。
たとえば、第二四半期 (4 月～6 月) に発生したイベントのみに注目する場合に、日付範囲を選択します。
時間範囲メニューは、選択した日付範囲を示します。タイムラインには、選択した時間範囲のみが表示されている
ことが分かります。
注意：サーバーとは別のタイムゾーンで作業を行っている場合、時間ベースのサーチでは、インデックスが作成さ
れたサーバーからのイベントのタイムスタンプが用いられます。
カスタム相対時間範囲の定義
1. タイムレンジピッカーで、[カスタム時間...] を選択します。
2. [範囲タイプ] オプションから [相対] を選択します。
3. [もっとも早い時刻] に値を入力します。
22
注意：またこのウィンドウを使って、もっとも早い時刻値のサーチ言語相当、および有効範囲を確認することもで
きます。
選択できる時間範囲のカスタマイズ
Splunk には、ビルトインの時間範囲が用意されています。Splunk 管理者は一連の時間範囲をカスタマイズして、
それをサーチ時にドロップダウンメニューから選択させることができます。時間範囲の設定方法については、『管
理マニュアル』の「times.conf リファレンス」を参照してください。
サーチへの時間修飾子の指定
サーチを実行または保存する場合、以下の属性を使って絶対/相対時間範囲を指定することができます。
earliest=<time_modifier>
latest=<time_modifier>
絶対時間範囲の指定
正確な時間範囲を指定する場合、time_modifier の構文は %m/%d/%Y:%H:%M:%S になります。. たとえば、2009 年 10 月
19 日午前 12 時～2009 年 10 月 27 日午前 12 時の時間範囲は、以下のように指定します。
earliest=10/19/2009:0:0:0 latest=10/27/2009:0:0:0
「earliest」属性のみを指定した場合、デフォルトで「latest」は現在の時刻 (now) になります。一般的に、
「earliest」を指定せずに「latest」を指定することはありません。
サーチまたは保存済みサーチに時間範囲を指定した場合、その値はドロップダウンメニューで選択した値に優先し
ます。ただし、サーチ文字列に直接指定した時間範囲は、サブサーチには適用されません (ドロップダウンで選択
した時間範囲が適用されます)。
相対時間範囲の指定
時間の量を示す文字列を使って相対時間を指定することができます (整数と単位)。また、必要に応じて「スナッ
プ」時間単位を使用することもできます。例：[+|-]<time_integer><time_unit>@<time_unit>。また、相対時間を指定
する際には、現在の時刻を表す now を使用できます。
1. 文字列は、時間量のオフセットを示すプラス (+) またはマイナス (-) 記号で開始します。
2. 時間量を数字と単位で定義します。1 つの時間量を指定する場合は、数字を省略できます。たとえば、「s」は
「1s」、「m」は「1m」と同じ扱いになります。サポートしている時間単位を以下に示します。
秒：s、sec、secs、second、seconds
分：m、min、minute、minutes
時間：h、hr、hrs、hour、hours
日：d、day、days
週：w、week、weeks
月：mon、month、months
四半期：q、qtr、qtrs、quarter、quarters
年：y、yr、yrs、year、years
3. スナップ (snap to) 時間単位を使用して、時間量を切り捨てた最寄りの時間またはもっとも遅い時間を指定する
ことができます。このためには、時間量とスナップ (snap to) 時間単位を、「@」文字で区切ります。
相対時間修飾子は、「スナップ」時間単位としてのみ定義できます。たとえば、特定の曜日にスナップするには、
日曜日の場合は @w0、月曜日の場合は @w1 などのように指定します。
23
スナップ時間単位を指定しない場合、Splunk は自動的に秒にスナップします。
特殊時間単位
これらの省略形は、時間単位の特殊な事例とスナップ時間オフセットのために予約されています。
時間単位
説明
earliest=0
(および latest!=0) の場合、サーチの開始時刻は UTC エポック 0 になります。
および latest=now または latest=<a
す。違いは：
earliest=0
0
latest=now
large number>
の場合、サーチは全時間実行されま
を指定した場合、将来のイベントは返されません (デフォルト)。
を指定すると、将来のイベントが返されます。
latest=<a big number>
注意：将来のイベントとは、現在の時刻 now よりも後のタイムスタンプを持つイベントを指して
います。
now
@q, @qtr, or
@quarter
現在の時刻：
もっとも間近な四半期の開始 (1 月 1 日、4 月 1 日、7 月 1 日、10 月 1 日) にスナップします。
rt
リアルタイムサーチの時間ウィンドウを指定します。
w0, w1, w2,
曜日にスナップすることを指定します。日曜日は w0、月曜日は w1 のように指定します。週に
スナップする場合 (@w または @week)、日曜日にスナップまたは @w0 と同じことになります。
w3, w4, w5,
and w6
時間にスナップの詳細
最寄りのまたは一番遅い時間にスナップする場合、Splunk は常に後方にスナップまたはもっとも遅い時間に切り
捨てた値 (指定時間以降ではない) にスナップします。たとえば、11:59:00 で時間に「スナップ」した場合、12 時
ではなく 11 時にスナップします。
スナップ量の前に時間オフセットを指定しない場合、Splunk は「現在の時刻を指定された時間量にスナップ」す
るものと解釈します。たとえば、現在時刻が金曜日の午後 11 時 59 分で、土曜日にスナップするために @w6 を使用
した場合、結果は前の土曜日の午前12時 01 分になります。
相対時間修飾子の例
これらの例では、現在の時刻が 2009 年 2 月 5 日水曜日の午後 1 時 37 分 5 秒であると仮定しています。また、サ
マータイム境界のために、24h が常に 1d と同じになる訳ではないことに注意してください。
時間修飾子
説明
結果となる時間
同等の修飾子
now
現在の時刻
Wednesday, 05 February 2009, 01:37:05 PM now
-60m
60 分前
Wednesday, 05 February 2009, 12:37:05 PM -60m@s
-1h@h
1 時間前、時間へ
Wednesday, 05 February 2009, 12:00:00 PM
-1d@d
昨日
Tuesday, 04 February 2009, 12:00:00 AM
-24h
24 時間前 (昨日)
Tuesday, 04 February 2009, 01:37:05 PM
-7d@d
7 日前、今日から 1 週間前 Wednesday, 28 January 2009, 12:00:00 AM
-7d@m
7 日前、分境界にスナップ
Wednesday, 28 January 2009, 01:37:00 PM
@w0
今週の開始日
Sunday, 02 February 2009, 12:00:00 AM
+1d@d
明日
Thursday, 06 February 2009, 12:00:00 AM
+24h
今から 24 時間後、明日
Thursday, 06 February 2009, 01:37:05 PM
-24h@s
+24h@s
相対時間オフセットのチェーン例
より詳細な相対時間定義を行うために、オフセットを「チェーン」することができます。
時間修飾子
@d-2h
説明
結果となる時間
今日の開始 (午前 0 時) にスナップし、そこから 2 時間差し引きます。 昨晩の午後 10 時
-mon@mon+7d 1 ヶ月前の月の初日の午前 0 時にスナップして、7 日間を加算
24
先月の 8 日 (午前 0 時)
相対時間修飾子を使ったサーチ例
例 1：週の初めから現在の時刻 (now) までのサーチの Web アクセスエラー。
eventtype=webaccess error earliest=@w0
このサーチは、今週日曜日の午前 0 時から現在の時刻までの、マッチするイベントを返します。もちろん、この
サーチを月曜日の正午に実行したら、36 時間分のデータに該当するイベントしか返されません。
例 2：今週の営業日 (月～金) の Web アクセスエラー。
eventtype=webaccess error earliest=@w1 latest=+7d@w6
このサーチは、今週月曜日の午前 0 時から今週金曜日午後 11 時 59 分までの、マッチするイベントを返します。
このサーチを月曜日の正午に実行したら、12 時間分のデータに該当するイベントしか返されません。一方、この
サーチを金曜日に実行すれば、月曜日から金曜日の現在の時刻までのイベントが返されます。ただし、タイムライ
ンには週の営業日全体が表示されます。
例 3：先週の営業日からの Web アクセスエラー。
eventtype=webaccess error earliest=-7d@w1 latest=@w6
このサーチは、先週月曜日午前 0 時から、先週金曜日午後 11 時 59 分までの、マッチするイベントを返します。
サーチへのリアルタイム時間範囲ウィンドウの指定
履歴サーチの時間境界は、サーチ実行時の時間に設定されます。リアルタイムサーチでは、時間境界は常時更新さ
れ、デフォルトで結果はサーチ開始時から累積されます。また、過去 30 秒などのように、時間範囲がスライドし
ていくウィンドウとなる時間範囲を指定することもできます。スライドウィンドウを指定した場合、Splunk はそ
の時間量を使ってデータを蓄積します。たとえば、スライドウィンドウが 5 分間の場合、最初の 5 分間が経過す
るまではデータを参照することができません。この動作に優先させて、通常のリアルタイムサーチを実行する前
に、初期ウィンドウに履歴データをバックフィルすることができます (後述の「リアルタイムバックフィル」を参
照)。
タイムレンジピッカーに記載されている事前設定オプションを使って、リアルタイムウィンドウを指定することが
できます。また、独自のリアルタイムウィンドウを定義することも可能です。
リアルタイムサーチの時間範囲の構文は履歴サーチと同じですが、相対時間指定子の前に「rt」を付ける必要があ
ります (rt<時間修飾子>)。
リアルタイムサーチの構文は、rt[+|-]<time_integer><time_unit>@<time_unit> になります。時間修飾子の構文は、
「サーチへの時間修飾子の指定」を参照してください。
これらの値は、サーチ言語内から使用するようには設計されていません。これは、[カスタム] > [リアルタイム] の
選択時に、タイムレンジピッカー内で指定できる設定値です。また、times.conf (タイムレンジピッカーにオプショ
ンを追加するため) 内、保存済みサーチダイアログ内、または直接 REST API を使って Splunk のバックエンド
サーチエンジンにアクセスする場合にも、これらの値を使用することができます。
リアルタイムサーチでタイムレンジウィンドウを使用する場合、直前に発生した一部のイベントが表示されない場
合があります。これは、イベントのタイムスタンプとイベント到着時刻の間の遅延時間が原因で、想定通りの動作
です。タイムレンジウィンドウはイベントの到着時刻ではなく、イベント内のタイムスタンプに対応しているた
め、時間ウィンドウ後に到着したイベントが表示されることはありません。
「全時間」リアルタイムサーチ
設定された時間ウィンドウ (30 秒、1 分、2 時間) 内で行われるリアルタイムサーチと「全時間」が設定されたリ
アルタイムサーチの間には、わずかな違いがあることに注意してください。
ウィンドウを使用するリアルタイムサーチでは、サーチ内のイベントはウィンドウから外れると消えてしま
います。また、サーチジョブ作成時刻よりも新しいイベントは、発生時にウィンドウに表示されます。
「全時間」リアルタイムサーチの場合、ウィンドウはイベント全体にまたがっています。そのため、ウィン
ドウに登場したイベントが消えることはありません。サーチジョブ作成時刻よりも新しいイベントは、発生
時に表示されます。
また、標準的なサーチでは、サーチで指定した時間範囲内のイベントが消えることはありません。また、最
新のイベントは常にジョブ作成時刻よりも前になります (将来の日付のタイムスタンプを持つイベントを含
むサーチを除く)。
リアルタイムバックフィル
リアルタイムウィンドウを使用するサーチの場合，初期ウィンドウに履歴データをバックフィルするように設定で
きます。これは、2 つの手順を利用した単一のサーチとして実行します。まず、イベントをバックフィルするため
のサーチを行い、その次に通常のリアルタイムサーチを実行します。リアルタイムバックフィルにより、リアルタ
イムダッシュボードには開始時点から、時間の経過に伴う正確な視覚エフェクトや統計的指標が表示されます。
25
リアルタイムバックフィルを有効にするには、limits.conf の [realtime] スタンザを使用します。
[realtime]
default_backfill = <bool>
* Specifies if windowed real-time searches should backfill events
* Defaults to true
サーチ結果のレポート
レポートコマンドについて
サーチ文字列に直接レポートコマンドを追加して、レポートを生成し、サーチ結果を要約することができます。
レポートコマンド入門
ここでは、レポートコマンドの主な分類と、サーチへの使用例を説明していきます。
主なレポートコマンド：
chart：描画する任意のデータのシリーズを表示できるグラフ。グラフの
X 軸に使用するフィールドを指定で
きます。
timechart：「傾向の推移」レポートを作成するために用いられます。常に _time が X 軸になります。
top：フィールドで一番多い値を表すグラフを表示します。
rare：フィールドで一番少ない値を表すグラフを表示します。
stats、eventstats、および streamstats：サマリー統計情報を表示するレポートを生成します。
associate、correlate、および diff：データのフィールド間の関連、相関、差異を表すレポートを作成しま
す。
注意：以下の例で示すように、レポートコマンドは常にサーチコマンドの後にパイプ文字 (|) を使って指定しま
す。
chart、timechart、stats、eventstats、および streamstats
す。統計関数には、以下のようなものがあります。
はすべて、統計関数と連携動作するように設計されていま
count、distinct count
mean、median、mode
min、max、range、percentiles
standard deviation、variance
sum
first occurrence、last occurrence
統計関数の詳細および使用例については、『Search Reference Manual』の「Functions for stats, chart, and
timechart」を参照してください。一部の統計関数は、timechart コマンドしか利用できません。
注意：レポートコマンドを使ったサーチはすべて、特定構造のデータを生成します。Splunk で利用できるグラフ
に応じて、これらのデータ構造を特定の方法で設定する必要があります。たとえば、横棒グラフ、縦棒グラフ、折
れ線グラフ、面グラフを生成できるサーチでも、円グラフは作成できないことがあります。詳細は、『データのビ
ジュアル化マニュアル』の「視覚エフェクトのデータ構造要件」を参照してください。
リアルタイムレポート
リアルタイムサーチを使って、サマリーインデックスを使わずに、大量のデータからリアルタイムに指標を算出す
ることができます。ただし、ライブで継続的にデータストリームをレポートしているため、イベントストリームの
入力に伴ってタイムラインが更新され、テーブルやグラフはプレビューモードでしか表示できません。また、リア
ルタイムでの使用に適したサーチコマンドが存在しています (例：streamstats および rtorder)。
時間ベースのグラフの作成
統計的な傾向の推移を表示するグラフを作成するには、timechart コマンドを使用します。このグラフでは、X 軸
に時間が使用されます。必要に応じて他のフィールドでデータを分割することができます。この場合、split by
フィールドの各一意の値が、グラフに別個のシリーズとして表示されます。一般的にこれらのレポートは、折れ線
グラフまたは面グラフとして表示されますが、縦棒グラフを使用することも可能です。
たとえば、このレポートは内部 Splunk ログデータを使って、Splunk プロセスによるインデックス作成の平均ス
ループット (インデックスの kbps) の推移を、プロセッサ別にビジュアル化します。
index=_internal "group=thruput" | timechart avg(instantaneous_eps) by processor
時間ベースではないグラフの作成
26
任意のデータシリーズを表示できるグラフを作成するには、chart コマンドを使用します。timechart コマンドと違
い、chart コマンドで作成するグラフは任意のフィールドを X 軸として使用できます。over キーワードを使って、
X 軸に使用するフィールドを指定します。
注意：over は、chart コマンド固有のキーワードです。たとえば、これを timechart コマンドに使用することはでき
ません。すでに _time が X 軸に使用するデフォルトフィールドとして決められています。
たとえば、以下のレポートは Web アクセスデータを使用して、各平日の一意のビジター数平均を表します。
index=sampledata sourcetype=access* | chart avg(clientip) over date_wday
必要に応じて他のフィールドでデータを分割することができます。この場合、split by フィールドの各一意の値
が、グラフに別個のシリーズとして表示されます。サーチに split by 句を指定する場合、over 句は split by 句の前
に配置してください。
以下のレポートは、指定期間内に各 clientip が処理したキロバイト数を host で分割したグラフを 生成します。生
成されたグラフでは、Y 軸に kb が、X 軸に clientip が使用されます。遅延値はホストにより区分されます。レ
ポートビルダーを使ってこのレポートを積み上げ横棒グラフとして表示することができます。
index=sampledata sourcetype=access* | chart sum(kb) over clientip by host
別の例：サーバーでヒットした HTTP および HTTPS リクエストを区分した積み上げ横棒グラフを作成する場合を
考えてみましょう。この場合、まず着信ポート番号または着信 URL リクエストを含むサーチ時フィールド抽出の
ssl_type を作成します (これらの情報がログに記録されていると仮定)。サーチは以下のようになります。
sourcetype=whatever | chart count over ssl_type
レポートビルダーを使ってこのレポートを積み上げ横棒グラフとして表示することができます。
多い/少ないフィールド値のビジュアル化
top および rare コマンドを使って、もっとも多い値およびもっとも少ない値を表すグラフを作成できます。
この一連のコマンドは、ファイアウォール情報を調査して、システムが使用した上位 100 件の宛先ポートを表示
します。
index=sampledata | top limit=100 dst_port
一方以下のコマンドは、同じファイアウォールデータセットを使用して、拒否数がもっとも少ないソースポートを
示すレポートを生成します。limit を指定しない場合、デフォルトで top または rare で表示される値数は 10 件で
す。
index=sampledata action=Deny | rare src_port
複雑な top コマンドの例
2 つのフィールドを持つ監視対象システムのアラートログから、インデックスを作成する場合を考えてみましょ
う。
msg
は CPU at 100% のようなメッセージです。
は、log01 のようなメッセージを生成するホストです。
mc_host
およびそれを送信した mc_host の値の上位値を表示するレポートを生成して、以下のようなテーブルを取得す
るにはどうしたら良いでしょうか？
msg
mc_host 別メッセージ
CPU at 100%
log01
log02
log03
ログファイルアラート
host02
host56
host11
このためには、mc_host 当たりの message のトップ値を探し (limit=1 を使って 1 件のみを返す)、次にメッセージ
count の降順に sort を実行します。
27
サマリー統計情報を表示するレポートの作成
フィールドに関連するサマリー統計を表示するレポートを生成するには、stats および eventstats レポートコマン
ドを使用します。
コマンドを有効活用するためには、split by 句を指定する必要があります。たとえば、以下のレポートコマン
ドでは十分な情報が得られません。
stats
sourcetype=access_combined | stats avg(kbps)
これはソースタイプが access_combined のすべてのイベントの平均 kbps を算出しますが、単一の値です。結果とな
るグラフには、1 つの列しか表示されません。
このような場合 split by フィールドを利用することで、当該フィールドの統計情報を記載したレポートを生成する
ことができます。以下のレポートは、access_combined ログを調査して、ホスト別の平均スループット (kbps) を取得
する縦棒グラフを生成します。
sourcetype=access_combined | stats avg(kbps) by host
コマンドのもう少し洗練された例を見ていきましょう。以下のレポートは、Splunk プロセスを CPU 使用率
の降順に表示します。
stats
index=_internal "group=pipeline" | stats sum(cpu_seconds) by processor | sort sum(cpu_seconds) desc
各イベントに関係するコマンドの集計結果のみが、各イベントにインラインに追加されることを除き、eventstats
コマンドは stats とまったく同じ働きをします。
eventstats
結果のフィールド名を指定するには、as 引数を追加します。これを利用すれば、前述の最初の例で
操作の結果を含む新規フィールド名を「avgkbps」にすることができます。
eventstats avg(kbps)
sourcetype=access_combined | eventstats avg(kbps) as avgkbps by host
この一連のコマンドを実行すると、kbps を含む各 sourcetype=access_combined イベントに、新しい avgkbps フィール
ドが追加されます。avgkbps の値は、当該イベントの平均 kbps になります。
また、Splunk はその一連のコマンドを使って、ソースタイプが access_combined の全イベントの平均 kbps をホスト
別に表示するグラフを生成します。
サーチでの関連、統計的相関、および差異の調査
サーチ結果の各フィールド値間の関連、類似性、差異を検索するには、associate、correlate、および diff コマンド
を使用します。
associate コマンドは、フィールド値のペアを使って相互に関連するイベントを判別します。たとえば、あるイベ
ントに「http://www.google.com/」の referer_domain があり、別のイベントに同じ URL 値の referer_domain がある
場合、それらは関連していると判断されます。
コマンドにより得られた結果は、supcnt、supfreq、および improv 引数でチューニングできます。これら
の引数の詳細は、『Search Reference Manual』の Associate コマンドに関連するページを参照してください。
associate
たとえば以下のレポートは、アクセスソースタイプをサーチして、最低 3 つのフィールド/フィールド-値のペアの
関連を持つイベントを判別します。
sourcetype=access* | associate supcnt=3
correlate コマンドは、フィールド間の統計的相関を算出します。このコマンドは cocur 操作を使って、同じ結果
セットに対して 2 つのフィールドが存在する割合 (パーセント) を算出します。
以下のレポートは、eventtype=goodaccess の全イベントをサーチして、それらの全フィールド間の共起相関を算出し
ます。
eventtype=goodaccess | correlate type=cocur
diff コマンドは、2 つのサーチ結果間の差異を比較する場合に使用します。デフォルトでこのコマンドは、attribute
引数で特定のフィールド属性を指定しない限り、選択したサーチ結果の raw テキストが比較されます。
たとえば、以下のレポートはサーチで返された 44 番目と 45 番目のイベントに注目し、その IP アドレス値を比較
します。
eventtype=goodaccess | diff pos1=44 pos2=45 attribute=ip
複数のデータシリーズを持つグラフの作成
Splunk のレポートコマンドには、グラフ (または時間グラフ) に複数のデータシリーズを定義する直接的な方法が
ありません。ただし、stats コマンドと xyseries コマンドを組み合わせれば、複数のデータシリーズを定義するこ
28
とが可能です。
コマンドと timechart コマンドは両方とも、グラフ作成用に表形式のデータを返します。X 軸はそれぞれ任意
のフィールドまたは _time になります。これらのコマンドと split-by フィールドを使用すると、各列が split-by
フィールドの一意の値を示す表が出力されます。
chart
一方 stats コマンドは、各行が group-by フィールドの、単一で一意の値の組み合わせを示す表を生成します。次
に xyseries コマンドを使って、グラフ化用のデータシリーズを再定義することができます。
たいていの場合は、「... | chart n by x,y」の結果を「... | stats n by x,y | xyseries x y n」を使ってシミュレーション
できます。(timechart と同等の結果は x = _time.)
シナリオ
アプリケーションサーバーのクラスタからのデータについてレポートを作成する場合を考えてみましょう。各サー
バーから収集されたイベントには、アクティブなセッション数や前回の更新後に処理されたリクエスト数などの情
報が含まれており、applications_servers インデックスに配置されています。セッションや負荷の分布を確認できる
ように、各サーバーインスタンスとインスタンス当たりのセッション数を同じ時間グラフに表示します。
理想的なのは、以下のような時間グラフレポートを実行、生成することです。
index=application_servers | timechart sum(handledRequests) avg(sessions) by source
しかし、時間グラフは複数のデータシリーズをサポートしていないため、代わりに以下のようなサーチを実行する
必要があります。
index=application_servers | stats sum(handledRequests) as hRs, avg(sessions) as ssns by _time,source | eval
s1="handledReqs sessions" | makemv s1 | mvexpand s1 | eval yval=case(s1=="handledReqs",hRs,s1=="sessions",ssns) |
eval series=source+":"+s1 | xyseries _time,series,yval
説明
... | stats sum(handledRequests) as hRs, avg(sessions) as ssns by _time,source
これは、stats コマンドを使って各ソース値の統計を算出しています。handledRequests 値の合計は hRs と名付
け、sessions の平均は ssns と名付けます。
... | eval s1="handledReqs sessions" | makemv s1 | mvexpand s1
また、eval コマンドを使って、stats コマンドからの各結果に単一値フィールド「s1」を追加します。次に、
makemv コマンドで sl を複数値フィールドに変換します。このフィールドで、最初の値は「handleReqs」、2 番
目の値は「sessions」になります。次に mvexpand で、s1 の各値に対して個別のシリーズを作成します。
... | eval yval=case(s1=="handledReqs",hRs,s1=="sessions",ssns)
これは、eval コマンドを使って新たなフィールド yval を定義し、マッチしたケースに基づいて値を割り当てま
す。s1 の値が「handledReqs」の場合、yval には「hRs」が割り当てられます。また、s1 の値が「sessions」の
場合、yval には「ssns」が割り当てられます。
... | eval series=source+":"+s1
これは eval コマンドを使って新たな series フィールドを定義します。このフィールドは、host および s1 フィー
ルドの値を連結します。
... | xyseries _time,series,yval
最後に xyseries コマンドを使って、X 軸が _time、Y 軸が yval で、シリーズで定義されたデータを利用したグラフ
を作成します。
複数日の時間ごとの合計の比較
は傾向の推移を表すグラフを作成するための優れた手段ですが、できることに厳密な境界制限が存在し
ています。状況によっては、柔軟性に優れる chart コマンドの方が適している場合もあります。
timechart
ここでは、複数の日数に渡って収集された値を比較するための、chart の使用例を取り上げます。このような処理
は、timechart では行えません。
シナリオ
ほぼ同一の 2 つのサーチがあります。どちらも 24 時間の期間における P フィールドの時間ごとの合計値を表示し
ます。ただし、片方のサーチは過去 10 日間の期間をカバーしており、もう一方は 過去 9 日間の期間をカバーして
いると言う違いがあります。
サーチ 1：
29
earliest=-10d latest=-9d | timechart span="1h" sum(P)
サーチ 2：
earliest=-9d latest=-8d | timechart span="1h" sum(P)
ここでは、これらの 2 つのサーチ結果を組み合わせた棒グラフを作成し、10 日前の午後 3 時の P の合計と 9 日前
の午後 3 時の P の合計を並べて表示します。
解決策
コマンドでは、この目的を実現することはできません。しかし、chart コマンドを使用すれば簡単にこの
目的を達成できます。両方の日をカバーするサーチを設定し、サーチイベント内で見つかった一意の date_hour お
よび date_day の各組み合わせに対して、［sum of P］ (P の合計) 列を作成します。
timechart
サーチは以下のようになります。
earliest=-10d latest=-8d | chart sum(P) by date_hour date_day
これは、24 スロットを持つ単一のグラフを作成します。各スロットが、その日の各時間を表しています。各ス
ロットにはレポートの時間範囲がカバーしている、2 日間の時間後との合計を比較するための 2 つの列が含まれて
います。
レポートサーチの詳細および作成方法については、『User Manual』の「Use reporting commands」を参照してく
ださい。
および timechart 関数の詳細については、『Search Reference Manual』の「Functions for stats, chart, and
timechart」を参照してください。
chart>
リアルタイムのサーチとレポート
リアルタイムサーチとレポートについて
リアルタイムサーチとレポートでは、イベントのインデックスが作成される前にイベントをサーチし、イベントの
入力に伴ってレポートをプレビューすることができます。
バックグラウンドで継続的に実行されるリアルタイムサーチに基づくアラートを作成できます。このようなリアル
タイムアラートにより、スケジュール済みサーチに基づくアラートよりもタイムリーに通知することができます。
詳細は、『アラートマニュアル』の「アラートについて」を参照してください。
また、ダッシュボードエディタ、パネルエディタ、シンプル XML を使って、カスタムダッシュボードにリアルタ
イムサーチ結果およびレポートを表示することもできます。ビジュアルダッシュボードエディタの詳細は、『デー
タのビジュアル化マニュアル』の「UI による簡単なダッシュボードの作成」を参照してください。
ビジュアルダッシュボードエディタよりも高度な機能を提供するリアルタイムダッシュボードの使用方法について
は、『Developer manual』の「Build a real-time dashboard」を参照してください。
注意：Splunk をそのままの設定で利用する場合、管理者ロールを持つユーザーのみがリアルタイムサーチを実
行、保存することができます。ロールの管理とユーザーへの割り当てについては、『Securing Splunk』の「Add
and edit roles」を参照してください。
リアルタイムサーチの仕組み
リアルタイムサーチでは、インデックス処理のために Splunk にイベントが入力されると、それに対してサーチが
行われます。リアルタイムサーチを開始すると、Splunk はサーチのマッチ候補であることを示す、インデックス時間フィールドを含む到着イベントをスキャンします。これらのイベントは、UI 内でスキャンしたイベントとし
て識別されます。この数は累積値で、サーチ起動時からスキャンしたすべてのイベントの合計を表しています。
リアルタイムサーチを実行すると、Splunk は定期的にスキャンしたイベントをサーチ基準に対して評価して、実
際のマッチを探します。これらのイベントは UI で、一致したイベントとして識別されます。この値は、サーチに
定義したスライドしていくタイムレンジウィンドウ内に、現在存在しているマッチイベント数を表しています。そ
のため、マッチするイベントの発見率が増加/減少するにつれて、時間の経過とともにこの値は増減します。
Splunk Web でサーチを実行している場合、サーチタイムラインには、選択した時間範囲内に返されたサーチに
マッチするイベントも表示されます。
1 分間のタイムレンジウィンドウを指定した、リアルタイムサーチの例を示します。この画面キャプチャの取得時
点では、サーチは実行後合計 3,105 件のイベントをスキャンしています。マッチしたイベント数 558 件は、サー
チ基準にマッチする過去 1 分間に識別されたイベント数を表しています。この値は次の 1 分間で 530～560 の範囲
で変動しています。これが急激に増加/減少した場合は、何か調査する必要がある注目すべき事態が発生した可能
性があります。
画面のように、タイムラインの右側には最新のイベントが表示されます。時間の経過に伴い、これが左側に移動し
30
ていき、タイムレンジウィンドウから完全に消えることになります。
リアルタイムサーチは、誰かがサーチを停止するかまたはサーチジョブを削除するまで継続的に動作します。何ら
かの理由でタイムアウトになることはありません。イベントが停止している場合は、パフォーマンス上の問題が発
生している可能性があります (下の「予想されるパフォーマンスと既知の制限事項」を参照)。
リアルタイムサーチは、ルックアップやトランザクションなどの高度な機能を含め、Splunk のすべてのサーチ機
能を活用することができます。また、streamstats や rtorder などの、特にリアルタイムサーチと連携動作すること
を前提に設計されたサーチコマンドも用意されています。
Splunk Web でのリアルタイムサーチとレポート
Splunk Web でのリアルタイムサーチ
リアルタイムサーチの実行とリアルタイムレポートの作成は、標準のサーチを実行する場合と同じ方法で行えま
す。ただし、ライブで継続的にデータストリームをサーチするため、イベントストリームの入力に伴ってタイムラ
インが更新され、またレポートはプレビューモードでしか表示できません。また、標準のサーチよりもリアルタイ
ムサーチに適したサーチコマンドが存在しています。たとえば、streamstats および rtorder は、リアルタイムサー
チでの使用を前提に設計されています。
Splunk Web でリアルタイムサーチを開始するには、[時間範囲] メニューから事前設定されているリアルタイム
のタイムレンジウィンドウを選択します (例：[30 秒] または [1 分] など)。また、リアルタイムサーチに適用す
る、スライドするタイムレンジウィンドウを指定することもできます。
このサーチを実行すると、到着したページビューイベントを参照することができます。
eventtype="pageview"
入力パイプラインから入力される raw イベントは、時間順に並んではいません。rtorder コマンドを使用すれば、
リアルタイムサーチからのイベントをバッファに格納し、それを時間の昇順に出力することができます。
以下の例では、過去 5 分間のページビューイベントをバッファに保管し、5 分以上経過したイベントを時間の昇順
に送信します。新たに受信したイベントが 5 分以上前の時刻を持つ場合、その時刻以降のイベントをすでに送信し
ているならば、当該イベントを破棄します。
eventtype="pageview" | rtorder discard=t buffer_span=5m
リアルタイムサーチは、イベントのストリームに依存しています。そのため、イベントを生成しない | metadata
や、単にファイルを読み取るだけの | inputcsv などのコマンドをリアルタイムサーチに利用することはできませ
ん。また、サーチ結果を | outputcsv に送信しても、リアルタイムサーチを完了させない限り、CSV ファイルに書
き込まれることはありません。
Splunk Web でのリアルタイムレポート
大部分の Web ページにアクセスする IP アドレスをプレビューするには、レポートを実行します。この場合、top
コマンドは、clientip (クライアント IP)、count (カウント)、および percent (パーセント) の 3 つの列を持つテーブ
ルを返します。データストリームが到着すると、テーブルが新たな値で更新されます。
eventtype="pageview" | top clientip
各ページビューイベントに対して、現在までに確認されたイベント数を表す count フィールドを追加します (ただ
し、現在のイベントはカウントに入れない)。
eventtype="pageview" | streamstats count current=false
リアルタイムレポートにドリルダウンすることもできます。ただし、リアルタイムにドリルダウンを行っても新た
なリアルタイムサーチが行われる訳ではありません。代わりに、すでに取得され、インデックスが作成されたイベ
ントの履歴サーチが実行されます。詳細は、『User Manual』の「Understand table and chart drilldown actions」
を参照してください。
CLI でのリアルタイムサーチとレポート
31
CLI でのリアルタイムサーチとレポート
CLI でリアルタイムサーチを実行するには、「search」の代わりに「rtsearch」を使用します。
./splunk rtsearch 'eventtype=pageview'
サーチ結果内の単語を強調するには、highlight コマンドを使用します。以下の例では、ページビューイベントの
「GET」を強調表示しています。
./splunk rtsearch 'eventtype=pageview | highlight GET'
デフォルトでは、サーチ結果の行の折り返しが有効になっています。行の折り返しを無効にするには、-wrap オプ
ションを使用します。
./splunk rtsearch 'eventtype=pageview' -wrap 0
CLI でのリアルタイムレポートもプレビューモードで表示され、データの到着に伴い更新されていきます。
./splunk rtsearch 'error | top clientip'
結果のプレビューを抑制するには、-preview オプションを使用します。
./splunk rtsearch 'error | top clientip' -preview false
プレビューをオフにしても、Splunk Web の [ジョブ] ページからサーチを管理することができます (保存、一時停
止、完了、または削除)。サーチを完了させると、レポートテーブルが表示されます。詳細は、このマニュアルの
「ジョブ管理を使ったサーチジョブの管理」を参照してください。
CLI ヘルプリファレンスで、すべての CLI コマンドの情報を参照することができます。詳細は、このマニュアルの
「CLI でのヘルプの使用」を参照してください。
リアルタイムサーチとレポートの、予想されるパフォーマンスと既知
の制限事項
Splunk のパフォーマンスは、インデクサーに膨大な負荷がかかっておらず、多数のリアルタイムサーチを同時に
実行しない限り、十分に許容できるものと想定されています。ただし、多数のリアルタイムサーチを同時に実行す
ると、大量のデータが存在する環境ではパフォーマンスやネットワークに大きな影響を与えます。
ハードウェアの能力が許す範囲内で、複数のリアルタイムサーチと履歴サーチを同時実行することができます。同
じユーザーまたは異なるユーザーによる、個別のサーチに関する制限はありません。
リアルタイムサーチをプランニングする場合、以下の両方のパフォーマンスに与える影響を考慮する必要がありま
す。
ライブイベントを転送するインデクサー
ライブイベントを処理するサーチャー
インデクサーでの作業が多くなれば、サーチャーで必要な作業は減少します。また、逆も同様です。インデクサー
は総合的なシステム機能にとって重要です。そのため、ライブイベントのフィルタリングであまり大きな負荷をか
けないようにしてください。しかし、インデクサーで何もフィルタリングを行わないと、サーチャーにすべてのラ
イブイベントを送信するために必要な帯域幅のコストが高くなる可能性があります (特に複数のリアルタイムサー
チを同時実行する場合)。
サーチャーがインデクサーに追随できない場合、インデックスプロセッサ上のキューはイベントを破棄します。た
だし、イベントにはシーケンス番号があり、これを使って破棄されたイベント数とその時期を確認することができ
ます。
リアルタイムサーチの利用の制限方法
リアルタイムサーチの過度の使用はパフォーマンスに悪影響を与えるため、必要に応じてその利用を制限しなけれ
ばならないこともあります。Splunk にはこのためのさまざまな方法が用意されています。以下の作業を行えま
す。
特定のインデックスの indexes.conf を編集して、インデクサーレベルでリアルタイムサーチを無効にする。
特定のロールおよびユーザーに対してリアルタイムサーチを無効にする。
limits.conf を編集して、同時に実行できるリアルタイムサーチ数を減らす。
limits.conf を編集して、リアルタイムサーチのインデクサーサポートを制限する。
indexes.conf でリアルタイムサーチを無効にする
32
リアルタイムサーチにより、インデクサーに非常に負担がかかることがあります。インデクサー上でリアルタイム
サーチを無効にする場合は、インデクサーの indexes.conf で [default] 設定を編集します。
[default]
enableRealtimeSearch = <bool>
注意：複数のインデクサーに接続するサーチヘッドは、リアルタイムサーチが有効になっているインデクサーから
引き続きリアルタイムサーチ結果を取得することができます。
ユーザーまたはロールに対してリアルタイムサーチを無効にする
リアルタイムサーチは、Splunk Web の [管理] > [アクセス制御] から、特定のユーザーやロールに割り当てられ
る権限です。デフォルトで、rtsearch 権限は、Admin (管理者) および Power (パワー) ロールに割り当てられてい
ます。User (ユーザー) ロールには割り当てられていません。rtsearch 権限のないロールは、サーチヘッドが接続し
ているインデクサーに関係なく、そのサーチヘッドでリアルタイムサーチを実行することはできません。
リアルタイムサーチの制限の設定
の [search] スタンザを使って、システム上で同時に実行できる最大リアルタイムサーチ数を変更するこ
とができます。
limits.conf
[search]
max_rt_search_multiplier = <decimal number>
realtime_buffer = <int>
max_rt_search_multiplier
履歴サーチの最大数に数字が乗算されて、最大同時リアルタイムサーチ数が決まります。デフォルトは 3 で
す。
注意：リアルタイムサーチの最大数は、以下のように算出されます。 max_rt_searches =
max_rt_search_multiplier x max_hist_searches
realtime_buffer
UI からのリアルタイムサーチ用に保持するアクセス可能イベントの最大数。1 以上でなければなりません。
デフォルトは 10000 です。
リアルタイムバッファがこの制限値に達すると、それは循環バッファとして動作します。
リアルタイムサーチのインデクサー制限の設定
の [realtime] スタンザを使用して、リアルタイムサーチのインデクサーサポートのデフォルト設定を変
更することができます。個別のサーチに REST API 引数を使って、これらのオプションに優先させることができ
ます。
limits.conf
[realtime]
queue_size = <int>
blocking = [0|1]
max_blocking_secs = <int>
indexfilter = [0|1]
queue_size = <int>
各リアルタイムサーチのキューサイズ。0 より大きな値でなければなりません。
デフォルトは 10000 です。
blocking =[0|1]
キューが満杯になった場合、インデクサーをブロックするかどうかを示します。
デフォルトは偽 (0) です。
max_blocking_secs = <int>
キューが満杯の場合に、ブロックする最大時間。blocking
ません。
0 を設定すると「無制限」になります。
デフォルトは 60 です。
= false
の場合、このオプションは何も意味を持ち
indexfilter = [0|1]
効率のために、インデクサーがイベントを事前フィルタリングするかどうかを示します。
デフォルトは真 (1) です。
33
統計の算出
統計の算出について
この章では、イベントのサマリー統計の算出方法について説明していきます。
サーチ言語には、さまざまな統計コマンドが用意されています。このマニュアルの「サーチ結果のレポー
ト」で、すでにいくつかの例を取り上げています。この章では、「stats コマンドおよび関数の使用」から始
めて、さらに詳細に内容を説明していきます。
また、「stats と eval 式および関数の使用」の説明に従って、統計情報を算出することもできます。
また、stats と chart を使って作業を行う場合、「サーチ結果へのスパークラインの追加」を行うことも可能
です。
stats コマンドおよび関数の使用
ここでは、chart、timechart、stats、eventstats、および streamstats コマンドおよび統計関数の使用方法について説
明していきます。統計関数には、以下のようなものがあります。
count、distinct count
mean、median、mode
min、max、range、percentiles
standard deviation、variance
sum
first occurrence、last occurrence
統計関数の詳細および使用例については、『Search Reference Manual』の「Functions for stats, chart, and
timechart」を参照してください。一部の統計関数は、timechart コマンドしか利用できません。
stats と eval 式および関数の使用
このトピックは作成途中です！
ここでは、stat 内での eval 式と関数の使用方法について説明していきます。
eval コマンドの詳細と構文については、『Search Reference Manual』の eval コマンドに関する説明を参照
してください。
eval 関数の詳細は、『Search Reference Manual』の「Functions for eval and where」を参照してくださ
い。
また、このマニュアルの次の章にある「フィールドの評価と操作」には、他の eval コマンドの使用方法が説
明されています。
例 1：一致したイベントとの一意の数
エラーが発生した IP アドレス数を数えたい場合を考えてみましょう。これは、イベントのサーチと似ています。
特定のコードでフィルタリングして、stats コマンドで IP アドレス数を数えます。
... | search error=404 | stats dc(ip)
これを実現するための eval 式は以下のようになります。
... | stats dc(eval(if(error==404),ip,NULL))) AS dc_ip
サーチ結果へのスパークラインの追加
および chart を使ったサーチを行う場合、結果テーブルにスパークラインを追加することで、その有用性を
高め、総合的な情報密度を向上することができます。スパークラインはテーブルのセル内に表示されるインライン
グラフで、各行のプライマリキーに関連する時間ベースの傾向を表示することを目的にしています。
stats
たとえば、過去 15 分のイベントに対して実行する以下のサーチを考えてみましょう。
index=_internal | chart count by sourcetype
このサーチは、過去 15 分に _internal にインデックス作成された、ソースタイプに対するイベント数を表す、2 つ
の列を持つ結果テーブルを返します。最初の列は、過去 1 時間の _internal インデックスイベントセット内で見つ
かった各 sourcetype を記載しています。これが、テーブルのプライマリキーです。2 番目の列 count には、記載さ
れている各ソースタイプのイベント数が表示されます。
34
サーチ自体に sparkline 関数を追加して、このサーチ結果にスパークラインを追加できます。
index=_internal | chart sparkline count by sourcetype
このテーブル内の結果は前の結果とほとんど同じです。ただし各行には、記載されている各ソースタイプのイベン
ト数の、過去 15 分間の傾向を表すスパークライングラフが表示されます。
これで、以前には分からなかったデータのパターンを手軽に確認することができます。15 分の期間の 3/4 当たり
で、サーチ活動が大半の index=_internal ソースタイプに対して変動を与えていることが明確に分かります。ま
た、splunkd はこの期間全体に渡って、ほぼ通常通りにハートビートを実行しているように見えます。
注意：テーブル内の各スパークラインには、当該スパークラインで表されているその他のイベントに関連する情報
が表示されます。ただし、他のスパークラインに関連する情報ではありません。あるスパークラインのピーク値が
他のスパークラインのピーク値と同じである必要はありません。
stats および chart コマンドでのスパークラインの使用
スパークライン機能は常に、chart および stats サーチと一緒に使用します。スパークラインは、これらの 2 つの
サーチコマンド用の関数です。それ自体はコマンドではありません。スパークラインの機能は、どちらのサーチコ
マンドでも同じです。
注意：スパークライン自体をダッシュボードグラフの視覚エフェクトとして使用することはできません。ただし、
ダッシュボードパネルにスパークラインを表示するテーブル視覚エフェクトを入れることは可能です。詳細は、
『データのビジュアル化マニュアル』の「ビジュアル化リファレンス」を参照してください。
および stats コマンドの詳細、sparkline 関数の構文などについては、『Search Reference Manual』の
「chart」および「stats」を参照してください。
chart
例：Stats、スパークライン、および地震データ
ここでは、スパークラインを使って地震データに関する追加情報を得るための、stats サーチの使用例を説明して
いきます。
これらの例は、USGS Earthquakes Web サイトからダウンロードされたデータ (2011 年 9 月 13～20 日の 7 日間の期間) を使用してい
ます。データは過去 7 日間に発生した地震について、ソースネットワーク (Src)、ID
(Eqid)、version、date、location、magnitude、深さ (km)、および報告ステーション数 (NST) を含むカンマ区切り形
式の ASCII テキストファイルです。
テキストファイル M 2.5+ earthquakes, past 7 days をダウンロードして CSV ファイルとして保存し、それを
Splunk にアップロードしてください。Splunk はフィールドを自動的に抽出します。ダウンロードデータはダ
ウンロード時から過去 7 日間のデータになるため、結果は下記の例とは異なることに注意してください。
ここでは、USGS Earthquakes データを使って過去 1 週間に地震発生頻度の高かった地域を表示します。また、各
地域における地震の平均マグニチュードを表す列も追加します。以下のサーチを使用することができます。
source=eqs7day-M2.5.csv | stats sparkline count, avg(Magnitude) by Region | sort count
35
このサーチは、以下のテーブルを返し、過去 1 週間の地震発生頻度が高い地域の地震発生数の推移を表すスパーク
ラインを表示します (この例では、Region がテーブルのプライマリキーになります)。
地震発生数上位 10 の地域間の地震の分布の違いが明確に分かります。Southern Alaska や Virgin Islands などの地
域は、比較的継続的に地震が発生していますが、Fox Islands や Vanuatu ではある時点に地震活動が集中していま
す。
スパークライン上にカーソルを移動すると、特定の地域の最低/最大カウントが分かります。この例では、
Southern Alaska で過去 1 週間に発生した地震で、各日に発生した地震数は一番少ない日で 1 回、一番多い日で 6
回であることが分かります。
スパークラインに地震発生回数だけでなく、各地域の地震の相対平均マグニチュードも表示させたい場合はどうし
たら良いでしょうか？別の言い方をすれば、スパークラインの折れ線グラフが、各「時間バケツ」 (セグメント)
の平均マグニチュードを表すようにするにはどうしたら良いでしょうか？
以下のサーチを試してください。
source=eqs7day-M2.5.csv | stats sparkline(avg(Magnitude),6h) as magnitude_trend, count, avg(Magnitude) by Region |
sort count
このサーチは、各地域において、スパークラインの各セグメント内で発生した地震の、平均マグニチュードを表す
スパークラインを生成します。
ただし、それだけではありません。スパークラインをより小さな時間単位に分割します>前のテーブル例では、ス
パークラインが日単位に分割されていました。スパークライン内の各データポイントは、24 時間の期間における
イベントカウントを表しています。これが、それらのスパークラインが短い理由です。
サーチ言語に 6h を追加すると、この設定がデフォルト値に優先され、スパークラインが 6 時間単位で表示されま
す。こうすることにより、指定期間内の各イベントの分布が、より把握しやすくなります。
また、このサーチではスパークラインの列名をより分かりやすい、「magnitude_trend」 (マグニチュードの傾向)
に変更します。
ここでは、Honshu, Japan で発生した地震のマグニチュードがほぼ同じなのに対して、Puerto Rico で発生した地
震はマグニチュードの強弱にかなりのばらつきがあることが分かります。また、Southern California では比較的弱
い地震が 7 日間の期間の最初と最後に発生していることが一目で理解できます。また、前回のサーチで考えたよう
に Virgin Islands で発生する地震が一定の頻度で発生している訳ではないことが、今回のサーチでは分かります。
また、Honshu の地震は前のテーブルと比べてより定期的に発生していることが分かります。
フィールドの評価と操作
36
フィールドの評価と操作について
この章では、新規フィールドの評価、既存のフィールドの操作、新規フィールドによるイベント情報の強化、およ
び複数値フィールドの解析などを行うためのサーチコマンドについて説明していきます。
新規フィールド評価の主役となるのが、eval コマンドとその関数です。
eval コマンドおよび関数の使用
ここでは、eval コマンドとその関数を使った、任意の式による新規フィールドの評価について説明していきま
す。
ルックアップを使ったルックアップテーブルからのフィールドの追加
イベント内のフィールドを、ルックアップテーブルなどの外部ソースのフィールドと照合し、マッチする情報を
使って他の情報をイベントに追加することができます。
ルックアップテーブルは、静的 CSV ファイルまたは Python スクリプトの出力になります。また、サーチ結果を
CSV ファイルに出力し、それをルックアップテーブルとして使用することもできます。フィールドルックアップ
の詳細は、『Knowledge Manager Manual』の「Configure field lookups」を参照してください。
フィールドルックアップの設定後は、サーチ App から lookup コマンドを使って起動できます。
例：名前が dnslookup のフィールドルックアップは、DNS ルックアップおよび逆引き DNS ルックアップを実行
し、ホスト名または IP アドレスを引数として受け取る Python スクリプトを参照します。lookup コマンドを使っ
て、イベント内のホスト名値とテーブル内のホスト名値を照合し、イベントに対応する IP アドレス値を追加する
ことができます。
... | lookup dnslookup host OUTPUT ip
Splunk スクリプト external_lookup.py の詳細な使用例については、Splunk ブログの「Reverse DNS Lookups for
Host Entries」を参照してください。
サーチコマンドによるフィールドの抽出
多彩なサーチコマンドを使って、フィールドをさまざまな方法で抽出することができます。
rex は Perl 正規表現名前付きグループを使って、フィールド抽出を行います。
extract (「キー/値」の場合は kv) は、デフォルトのパターンを使って明示的にフィールド/値を抽出します。
multikv は、複数行、表形式イベントのフィールド/値を抽出します。
spath は、XML および JSON 形式のイベントデータのフィールド/値を抽出します。
xmlkv および xpath は、XML 形式イベントデータのフィールド/値を抽出します。
kvform は、あらかじめ定義されたテンプレートに基づいてフィールド/値を抽出します。
rex、extract、multikv、xmlkv、および kvform コマンドの使用例も参照してください。
正規表現を使ったフィールドの抽出
rex サーチコマンドは、サーチ文字列に指定した Perl 正規表現名前付きグループを使ってフィールド抽出を実行し
ます。これは、raw イベントのセグメントを正規表現と照合し、これらの値をフィールドに保存します。
この例では、文字列「From:」および「To:」の後に存在する用語を照合し、それらの値をそれぞれ「from」および
「to」フィールドに保存します。
... | rex field=_raw "From: (?<from>.*) To: (?<to>.*)"
raw イベントに文字列「From: Susan To: Bob」がある場合、Splunk は「from=Susan」および「to=Bob」のよう
に、フィールドの名前/値のペアを抽出します。
正規表現の構文と使用法については、「Regular-Expressions.info」を参照してください。Splunk には、正規表現
の作成とテストに役立つサードパーティ製ツールの一覧も用意されています。
サーチ結果のフィールド値抽出の強制
設定ファイルに定義されているフィールド抽出の強制
extract (「キー/値」の場合は kv) サーチコマンドは、結果セットのフィールド/値の抽出を強制します。extract に引
数を指定しないで使用すると、props.conf に追加されている field extraction スタンザを使ってフィールド抽出が行
われます。この設定ファイルにフィールドを追加して、extract で任意のフィールドの抽出をテストすることがで
きます。
表形式のイベントからのフィールド抽出
37
複数行、表形式イベントのフィールド/値の抽出を強制するには、multikv を使用します。この場合、各テーブル行
に対して新しいイベントが作成され、テーブルのタイトルからフィールド名が取得されます。
XML 形式のイベントからのフィールド抽出
xmlkv コマンドを使って、Web ページからのトランザクションなどの、イベントデータ内の XML 形式タグの
フィールド/値の抽出を強制できます。
XML および JSON ドキュメントからのフィールドの抽出
spath コマンドは、構造化データフォーマットの XML および JSON から情報を抽出し、それをフィールドに保存
する手段を提供しています。
フォームテンプレートに基づいたイベントからのフィールドの抽出
kvform コマンドは、$SPLUNK_HOME/etc/system/local/ または $SPLUNK_HOME/etc/apps/ 内の独自のカスタムアプリケー
ションディレクトリに、事前定義、保管されているフォームテンプレートに基づいて、イベントからフィールド/
値のペアを抽出します。たとえば、form=sales_order の場合、Splunk は sales_order.form を探して、すべての処理
済みイベントをそのフォームと照合し、値の抽出を試みます。
複数値フィールドの操作と評価
Splunk はサーチ時に複数値フィールドを解析します。これにより、値をサーチパイプライン内で処理することが
できます。複数値フィールドを利用できるサーチコマンドには、makemv、mvcombine、mvexpand、および
nomv があります。eval および where コマンドは、複数値フィールドを利用できる mvcount(), mvfilter(),
mvindex(), and mvjoin() などの関数をサポートしています。これらの関数の詳細は、『Search Reference Manual』
の「Functions for eval」およびこのページの例を参照してください。
fields.conf に複数値フィールドを設定し、単一の抽出されたフィールド値内にある複数のフィールド値の認識方
法を Splunk に指示できます。fields.conf は $SPLUNK_HOME/etc/system/local/、または $SPLUNK_HOME/etc/apps/ 内の独自
のカスタムアプリケーションディレクトリ内で編集します。詳細は、『Knowledge Manager Manual』の
「Configure multivalue fields」を参照してください。
複数値フィールドの操作
nomv を使った複数値フィールドの単一値への変換
nomv コマンドを使って、指定した複数値フィールドの値を単一の値に変換することができます。nomv コマンド
は、fields.conf にある複数値フィールドの設定に優先します。
この sendmail イベントの例では、senders フィールドの値を単一値にまとめます。
eventtype="sendmail" | nomv senders
makemv を使った複数値フィールドの分割
makemv コマンドを使って、複数値フィールドを複数の単一値フィールドに分割することができます。この
sendmail サーチ結果の例では、senders フィールドの値を複数のフィールド値に分割します。
eventtype="sendmail" | makemv delim="," senders
フィールド値を分割したら、パイプ文字を使ってそれを他のコマンドの入力にすることができます。たとえば、上
位何人かの送信者を表示することができます。
eventtype="sendmail" | makemv delim="," senders | top senders
mvexpand を使った、複数値フィールドに基づく複数イベントの作成
mvexpand コマンドを使って、複数値フィールド内の各値を個別のイベントに展開することができます。この例で
は、複数値フィールド「foo」の各値に対して新しいイベントが作成されます。
... | mvexpand foo
mvcombine を使った類似イベントからの複数値フィールドの作成
「foo」の値を、区切り文字「:」で結合します。
... | mvcombine delim=":" foo
複数値フィールドの評価
複数値フィールドの一般的な例として、メールアドレスフィールドが挙げられます。一般的にこのフィールドは単
38
一の sendmail イベント内に 2～3 回登場します (送信者用、一連の受信者用、そして CC アドレスが指定されてい
る場合はそのリスト用)。
フィールド内の値数の算出
単一値または複数値フィールド内の値数を算出するには、mvcount() 関数を使用します。
この例で mvcount() は、To、From、および Cc フィールド内のメールアドレス数を返し、それを指定した _count
フィールドに保存します。
eventtype="sendmail" | eval To_count=mvcount(to) | eval From_count=mvcount(from) | eval Cc_count=mvcount(cc)
注意：sender フィールドに 1 つのメールアドレスのみが存在している場合、mvcount(from) は 1 を返します。ま
た、CC アドレスが指定されていない場合、イベントの CC フィールドは存在せず、mvcount(cc) はヌルを返しま
す。
複数値フィールドからの値のフィルタリング
任意の論理演算式を指定して複数値フィールドをフィルタリングするには、mvfilter() 関数を使用します。
この例で、mvfilter() は最後が .net または .org で終了する、すべての email フィールドの値を保持します。
eventtype="sendmail" | eval email=mvfilter(match(email, "\.net$") OR match(email, "\.org$"))
重要：この関数は、1 回に 1 つのフィールドに対してのみ利用できます。
注意：この例は、match() 関数も使用して、引用符内に定義されているパターンを email の値と比較しています。詳
細は、『Search Reference Manual』の eval と where の関数の説明を参照してください。
複数値フィールドから値のサブセットを返す
複数値フィールド内の特定の値または値のサブセットを参照するには、mvindex() 関数を使用します。インデック
ス番号は 0 から始まるため、フィールド内の 3 番目の値を参照する場合は、関数に 2 を指定します。
この例で、mvindex() は Sender が送信した各メールに対して、To フィールド内の最初のメールアドレスを返しま
す。
eventtype="sendmail" from=Sender@* | eval to_first=mvindex(to,0)
送信者 (Sender) のメールの送信先上位 3 件のメールアドレスを取得するには、以下のように指定します。
eventtype="sendmail" from=Sender@* | eval top_three=mvindex(to,0,2)
注意：この場合、top_three はそれ自身が複数値フィールドになります。
イベントの相関
イベントの相関について
イベントの相関は、データ内の一見無関係に見えるイベント間の関係を探すことです。この章では、イベントの相
関に利用できる 3 種類の方法について説明していきます。
時間を使ったイベント間の関係の識別
サブサーチを使ったイベントの相関
トランザクションを使った関連イベントの識別とグループ化
その他の相関手法としては、フィールドルックアップとサーチ言語および associate、contigency、または join コ
マンドの使用などが挙げられます。
時間を使ったイベント間の関係の識別
時間は、問題を判断するために必要不可欠な情報で、この情報は既知であることもしばしばです。Splunk では、
イベント内のベースラインパターンまたは傾向を判別して、それを現在のアクティビティと比較することができま
す。
一連の時間ベースのサーチを実行し、異常なアクティビティを調査、特定し、その後タイムラインを使ってその特
定の期間にドリルインすることができます。同時刻に発生したイベントを調査することで、結果間の相互関係を見
つけ出し、主原因を特定する手がかりにできるかもしれません。
詳細は、このマニュアルの「タイムラインを使ったイベントパターンの調査」を参照してください。
この例は、Splunk チュートリアルの「タイムラインの使用」で取り上げられています。
39
サブサーチについて
サブサーチは、サーチパイプラインを引数に持つサーチです。サブサーチは角括弧で囲まれ、最初に評価されま
す。サブサーチの結果をプライマリ、または外部サーチの引数として使用できます。サブサーチは主に 2 種類の目
的で使用されます。
他のサーチの出力を使って、あるサーチをパラメータ化する (たとえば、特定の URL を訪問した IP アドレ
スから各レコードを検索する)。
別個のサーチを実行するけれども、append コマンドを使って出力を最初のサーチにつなげる。
サブサーチは、サーチで行うアクションや目的が明確で、データの変換を伴わない場合にのみ使用できます。たと
えば、「sourcetype=top | multikv」でサブサーチを使用することはできません。multikv コマンドは、引数にサブ
サーチを予期していません。append や join などの、一部のコマンドはサブサーチを引数として使用することがで
きます。
サブサーチの例
以下の例では、サブサーチを使ってあるサーチをパラメータ化します。過去の時間にもっともアクティブなホス
トからのすべてのイベントを検索したいと考えていますが、毎時間同じホストである訳ではないため、特定のホス
トに対してサーチを実行することはできません。まず、もっともアクティブなホストを識別する必要があります。
sourcetype=syslog earliest=-1h | top limit=1 host | fields + host
このサーチは 1 つのホスト値のみを返します。この例で、結果となるホスト名は「crashy」でした。次に、
「crashy」からのすべてのイベントをサーチすることができます。
sourcetype=syslog host=crashy
この情報が必要な時に毎回 2 つのサーチを実行する代わりに、サブサーチを使ってホスト名を取得し、それを外部
サーチに渡すことができます。
sourcetype=syslog [search sourcetype=syslog earliest=-1h | top limit=1 host | fields + host]
サブサーチのパフォーマンス
サブサーチが巨大な結果テーブルを返すと、それはサーチのパフォーマンスに影響を与えます。サーチと連携動作
する format コマンドを利用して、サーチに渡す結果数を変更することができます。サブサーチの最後に、| format
maxresults = <integer> コマンドを追加してください。詳細は、『Search Command Reference』の format コマンド
の説明を参照してください。
また、limits.conf 内の設定でも、サブサーチの実行時間や返す最大結果数などを制御することができます。
[subsearch]
maxout = <整数>
サブサーチから返される最大結果数。
この値は 10500 未満でなければなりません。
デフォルトは 100 です。
maxtime = <整数>
サブサーチの最大実行時間 (秒)。この時間を過ぎるとサブサーチは完了させられます。
デフォルトは 60 です。
ttl = <整数>
サブサーチの結果をキャッシュに保持する時間。
デフォルトは 300 です。
サーチの実行後、[アクション] メニューの [サーチジョブの検査] を選択することができます。remoteSearch コン
ポーネントまでスクロールすると、サブサーチの結果となる実際のクエリーを確認することができます。詳細は、
『サーチマニュアル』の「サーチジョブ調査」を参照してください。
サブサーチコマンドの結果出力設定
Limits.conf.spec は、サブサーチがデフォルトで最大 100 件の結果を返すことを指定しています。ただし、各コマ
ンドではそのコマンド内のサブサーチのデフォルト最大結果数を変更できるため、実際の出力結果数は場合によっ
て異なります。また、デフォルトの最大出力数は、サーチ式内に展開される目的のサブサーチにのみ適用されま
す。しかし、join や append などのコマンドはこれに該当しません。たとえば append コマンドは、ユーザーがコ
マンドの引数として maxout を指定しない限り、このデフォルト値に優先して、maxresultrows の値を使用しま
す。
回答
何か質問がありますか？「Splunk Answers」から、Splunk コミュニティに寄せられた、サブサーチの使用方法に
40
関する質問と回答をご覧ください。
サブサーチを使ったイベントの相関
サブサーチはあるサーチの結果を取得し、それを別のサーチに使用することで、順次処理のデータ分析を実現して
います。サブサーチを使って、異なるインデックスからのデータや分散環境の Splunk サーバーからのデータも含
めて、イベントセット全体からデータの相関を探したり、イベントを評価することができます。
たとえば、異なるアプリケーションログに由来する、複数のインデックスがある場合を考えてみましょう。これら
のログからのイベントデータは、最低 1 つの共通フィールドを共有している場合もあります。このフィールドの値
を使って、他のインデックス内に存在しない値に基づいて、あるインデックス内のイベントをサーチすることがで
きます。
sourcetype=some_sourcetype NOT [search sourcetype=another_sourcetype | fields field_val]
注意：これは、SQL の「NOT IN」機能と同等です。
SELECT * from some_table
WHERE field_value
NOT IN (SELECT field_value FROM another_table)
サブサーチ結果のフォーマットの変更
サブサーチを使用する場合、サブサーチ結果には黙示的に format コマンドが適用されます。format コマンドは、
サブサーチ結果を単一の線形サーチ文字列に変更します。これは、返されたフィールド内の返された値を、プライ
マリサーチに渡す場合に使用されます。
サブサーチが以下のようなテーブルを返した場合：
| field1
| field2
|
------------------event/row1 | val1_1
| val1_2
|
event/row2 | val2_1
| val2_2
|
format コマンドは以下の文字列を返します。
(field1=val1_1 AND field2=val1_2) OR (field1=val2_1 AND field2=val2_2)
詳細は、『Search Command Reference』の format コマンドの説明を参照してください。
サーチおよびクエリーフィールド
これにはいくつかの例外があります。まず、すべての内部フィールド (先頭がアンダースコア「_*」で始まる
フィールド) は無視され、このように再フォーマットされることはありません。また、「search」および「query」
フィールドは、再フォーマットされたサーチ文字列内にその値が直接表示されます。
「search」の使用
一般的に「search」は、静的なデータを追加する必要がある場合、またはサブサーチ内のデータに eval を実行
し、それをプライマリサーチに渡すような場合に役立ちます。「search」を使用する場合、フィールドの最初の値
が実際のサーチ単語として使用されます。たとえば、上記のテーブルで field2 が「search」の場合、format コマン
ドは以下の文字列を返します。
(field1=val1_1 AND val1_2) OR (field1=val2_1 AND val2_2)
また、「search」を使って、プライマリサーチに渡される実際のサーチ文字列を変更することもできます。
「query」の使用
「query」は、これらの実際のフィールドではなく、サブサーチから返されたフィールドの値を検索する場合に役
立ちます。query フィールドは、format と類似の動作を行います。format のようにフィールド/値のペアを渡す代わ
りに、これは値を渡します。
(val1_1 AND val1_2) OR (val2_1 AND val2_2)
例
特定の Name と関連する clID を探す、以下のサーチを考えてみましょう。次にこの値が、複数のソースのサーチに
用いられます。
index="myindex" [ index="myindex" host="myhost" <Name> | top limit=1 clID | fields + clID ]
41
このサブサーチは、次のような文字列を返します： (
(clID="0050834ja") )
値 0050834ja のみを返したい場合は、以下のサーチを実行します。
index=myindex [ index=myindex host=myhost MyName | top limit=1 clID | fields + clID | rename clID as search ]
フィールドが名前付きサーチ (またはクエリー) の場合、フィールド名は破棄されて、サブサーチ (技術的には、サ
ブサーチの最後にある黙示の | format コマンド) はフィールド名を破棄して ( ( 0050834ja ) ) を返します。たとえ
ば、( ( value1 ) OR ( value2 ) OR ( value3 ) ) のように複数の結果が返されます。
これは、フィールド名が「search」または「query」の場合のみの特殊な事例です。フィールドを別の名前に変更
すると、サブサーチは新しいフィールド名を使用します。
トランザクションについて
トランザクションは、一定期間にまたがる任意の関連イベントのグループです。トランザクションタイプは、設定
されたトランザクションで、Splunk にフィールドとして保存されています。任意の数のデータソースが、複数の
ログエントリにまたがってトランザクションを生成できます。
トランザクションサーチ
トランザクションサーチは、ログに記録された複数のイベントにまたがる任意の物理イベントに注目する場合に役
立ちます。transaction コマンドを使って、トランザクションを定義したり、transactiontypes.conf に設定されてい
るトランザクションオプションに優先する設定を使用したりすることができます。
一般的にトランザクションサーチは、複数のイベントを単一の物理イベントを表す、単一のメタイベントにグルー
プ化する場合に用いられます。たとえば、メモリー不足の問題により、複数のデータベースイベントがログに記録
された場合に、それらをまとめてトランザクションにグループ化することができます。
詳細は、このマニュアルの「イベントの識別とトランザクションへのグループ化」を参照してください。
トランザクションの代わりに stats を使用する場合
トランザクションは、トランザクションデータの総統計を算出するためのもっとも効率的な手段と言う訳ではあり
ません。単一フィールド内のデータにより定義されているトランザクションの総統計を算出する場合は、stats コ
マンドを使用します。
たとえば、session_id フィールドが定義する、トランザクションの期間の統計を算出する場合は、以下のコマンド
を使用します。
* | stats min(_time) AS earliest max(_time) AS latest by session_id | eval duration=latest-earliest | stats
min(duration) max(duration) avg(duration) median(duration) perc95(duration)
同様に、アクセスログ内の clientip 当たりのヒット数を算出する場合は、以下のコマンドを使用します。
sourcetype=access_combined | stats count by clientip | sort -count
また、アクセスログ内の clientip 当たりの一意のセッション (cookie でパラメータ化) 数を算出する場合は、以下の
コマンドを使用します。
sourcetype=access_combined | stats dc(cookie) as sessions by clientip | sort -sessions
stats コマンドの使用方法の詳細は、リファレンスマニュアルの stats コマンドに関する説明を参照してください。
トランザクションおよびマクロサーチ
トランザクションおよびマクロサーチは強力な組み合わせで、トランザクションサーチ内で代替を行うことができ
ます。代替を行うには、トランザクションサーチを実行して、それを $field$ で保存します。
マクロサーチとトランザクションサーチの使用例については、このマニュアルの「サーチマクロの作成と使用」を
参照してください。マクロサーチの詳細は、『Knowledge Manager Manual』の「Design macro searches」を参
照してください。
イベントの識別とトランザクションへのグループ化
Splunk では、関連するイベントをサーチ、識別して、それを「トランザクション (またはセッション)」と呼ばれ
る単一のイベントにグループ化することができます。トランザクションの例を以下に示します。
同じソース、同じホストからの異なるイベント。
同じホストの異なるソースからの異なるイベント。
異なるホスト、異なるソースからの類似イベント。
トランザクションのサーチは、Splunk Web または CLI で transaction サーチコマンドを使って行いま
42
す。transaction コマンドは、グループ化されたイベントを生成します。これをレポートに使用することができま
す。transaction を使用するには、トランザクションタイプ (transactiontypes.conf で設定) を呼び出すか、または
transaction にサーチオプションを設定して、サーチ内にトランザクション制約を定義します。
transaction のサーチオプション
サーチ時に返されるトランザクションは、各イベントの raw テキスト、共有イベントタイプ、およびフィールド
値から成り立っています。トランザクションには、duration および transactiontype フィールドに保存される追加
データも存在しています。
には、トランザクションの期間が含まれています (トランザクション内の最初と最後のイベントのタ
イムスタンプの差)。
transactiontype はトランザクション名です (transactiontypes.conf にトランザクションのスタンザ名で定義)。
duration
は任意のサーチに追加できます。最良のサーチパフォーマンスを確保するために、適切なサーチを作成
して、それをパイプ文字で transaction コマンドに渡してください。詳細は、『Search Reference Manual』の
「transaction」を参照してください。
transaction
コマンドに続けて、以下のオプションを指定できます。注意：一部の transaction オプションは、他の
オプションと一緒に指定することはできません。
transaction
[field-list]
のように、フィールドのカンマ区切りリストです。
設定した場合、同じトランザクション内にあるイベントと判断するには、各イベントに同じフィールドがな
ければなりません。
共通のフィールド名で異なる値を持つフィールドはグループ化されません。
たとえば、...|transaction host を追加した場合、host=mylaptop を持つサーチ結果が host=myserver を持
つサーチ結果と同じトランザクションになることはありません。
host の値を持たないサーチ結果は、host=mylaptop を持つ結果と同じトランザクションになる可能性があ
ります。
...|transaction host,cookie
match=closest
トランザクション定義で使用するマッチタイプを指定します。
現在のところ、値は closest のみをサポートしています。
maxspan=[<integer> s|m|h|d]
トランザクション内のイベント間の最大一時停止期間を設定します。
秒、分、時間、または日単位で指定できます。
例：5s、6m、12h、または 30d。
デフォルトは、maxspan=-1 で、時間範囲は「全時間」となっています。
maxpause=[<integer> s|m|h|d]
トランザクション間の最大一時停止期間を指定します。
トランザクション内のイベント間の一時停止期間は maxpause 未満でなければなりません。
負の値を指定した場合、maxspause 制約は無効になります。
デフォルトは maxpause=-1 です。
startswith=<string>
サーチまたは eval フィルタリング式。あるイベントがこの条件を満たすと、新しいトランザクションの開始
としてマークされます。
例：
startswith="login"
startswith=(username=foobar)
startswith=eval(speed_field < max_speed_field)
startswith=eval(speed_field < max_speed_field/12)
デフォルトは "" です。
endswith=<transam-filter-string>
サーチまたは eval フィルタリング式。あるイベントがこの条件を満たすと、新しいトランザクションの終了
としてマークされます。
例：
endswith="logout"
endswith=(username=foobar)
endswith=eval(speed_field < max_speed_field)
endswith=eval(speed_field < max_speed_field/12)
デフォルトは "" です。
startswith
および endswith の場合、<transam-filter-string> は次の構文で定義されます： "<search-expression>"
(<quoted-search-expression>) | eval(<eval-expression>
43
|
は、引用符を含まない有効なサーチ式です。
は、引用符を含まない有効なサーチ式です。
<eval-expression> は、論理演算式を評価する有効な eval 式です。
<search-expression>
<quoted-search-expression>
例：
サーチ式： (name="foo bar")
サーチ式： "user=mildred"
サーチ式： ("search literal")
eval 論理演算式： eval(distance/time
< max_speed)
トランザクションサーチの例
単一のユーザー (またはクライアント IP アドレス) が一定期間に参照したすべての Web ページをグループ化する
サーチを実行します。
このサーチはアクセスログからイベントを作成し、同じ clientip 値を共有し、相互の発生間隔が 5 分以内のイベン
トからトランザクションを作成します (3 時間の期間内で)。
sourcetype=access_combined | transaction clientip maxpause=5m maxspan=3h
将来のイベントの予測
Splunk による予測分析について
予測分析はさまざまな方法で利用できます。例：
仮想環境のハードウェア要件を判断し、エネルギー消費を予測することで、キャパシティプランニングに役
立ちます。
主原因分析を拡張して、イベント内の異常なパターンを検出し、セキュリティ攻撃を防止します。
主要コンポーネントのモニタリングを強化して、システム障害の検出や機能停止の防止を行います。
Splunk では、レポートやダッシュボードを使って発生するアクティビティをモニターし、そのイベントにドリル
ダウンして、何が起きているのかを調査する主原因分析を行えます。モニターしているイベントに何かパターンや
相関が存在している場合、それを使って将来のアクティビティを予測することができます。
Splunk のサーチ言語には、predict と x11 の 2 種類の予測コマンドが用意されてマイス。predict コマンドでは、異
なる予測アルゴリズムを利用して、単一値または複数値フィールドの将来の値を予想します。x11 アルゴリズムに
由来して名付けられた x11 コマンドでは、時間ベースのデータ内の季節的なパターンを判別し、それをデータか
ら取り除くことで実際の傾向を確認できます。
履歴データに基づいて変数を予測できるようになったら、特定の閾値に基づいて予防的アラートを送信したり、
what-if 分析を実行してさまざまなシナリオを比較することができます。
その他のサーチ方法
サーチマクロの作成と編集
サーチマクロは、保存済みサーチやアドホックサーチを含め、複数の場所で再利用できるひとかたまりのサーチで
す。サーチマクロは、eval ステートメントやサーチ単語など、サーチの任意の部分に利用でき、また完全なコマ
ンドである必要はありません。マクロフィールドが任意の引数を取るかどうかを指定することも可能です。
ここでは、Splunk Web でのサーチマクロの作成、使用方法について説明していきます。サーチマクロの使用方法
と使用理由にについては、『Knowledge Manager manual』の「Design macro searches」を参照してください。
Splunk Web でのサーチマクロの作成
[管理] > [詳細サーチ] で、[新規] をクリックして新しいサーチマクロを作成します。
サーチマクロとその引数の定義
後ほど他のサーチの一部として再利用する、サーチ文字列またはサーチパイプライン内の任意の部分をサーチマク
ロにすることができます。
[宛先 App] は、サーチマクロを制限する App の名前です。デフォルトでは、サーチマクロはサーチ App に
限定されています。
[名前] は、mymacro のようなサーチマクロ名です。サーチマクロが引数を取る場合、名前に引数の数を追加し
てその旨を知らせる必要があります。たとえば、mymacro に 2 つの引数が必要な場合は、mymacro(2) のように
指定する必要があります。同じ名前を持つ複数のサーチマクロを作成できますが、引数の数は異なっていな
44
ければなりません。 foo, foo(1), foo(2), etc.
[定義] は、サーチマクロが他のサーチ内で参照されている場合に、マクロを展開する文字列です。サーチマ
クロに引数が含まれている場合、それが記入され、$arg1$ のようにドル記号でラップされます。
[Eval Generated Definition?] (eval 生成定義？) が選択されている場合、定義 (Definition) はこのマクロの展
開を表す文字列を返す eval 式が予期されます。
[引数] は、引数名のカンマ区切り文字列です。引数名には英数字 a～z、A～Z、0～9、アンダースコア
「_」、およびダッシュ「-」しか使用できません。このリストには、要素を繰り返し指定することはできま
せん。
マクロ定義の先頭にパイプ文字 (|) がある場合、それを UI からのサーチの最初の単語として使用することはできま
せん。例："| metadata type=sources"。UI はマクロ展開を行わず、通常の検索単語と初期パイプを正しく識別でき
ません。UI は、マクロ名がサーチ単語であるかのようにサーチを作成します。この場合、展開後に誤ったメタ
データコマンドが形成され、無効になってしまいます。
マクロ引数に引用符が含まれる場合、サーチ内でマクロを呼ぶ際には引用符をエスケープ処理する必要がありま
す。たとえば、マクロ引数として引用符付きの文字列を渡す場合、`my-macro("He said \"hello!\"")` のように指定
する必要があります。.
引数値の検証：
サーチマクロを起動するために使用する引数値が妥当かどうかを検証することができます。サーチマクロの起動方
法については、次のセクション「保存済みサーチおよびアドホックサーチへのマクロの適用」で説明しています。
[検証式] は、論理演算または文字列を評価する「eval」式の文字列です。
検証式が論理演算式の場合、真 (True) が返された場合に検証が成功になります。偽 (False) またはヌルを返
した場合、検証は失敗し検証エラーメッセージが返されます。
検証式が論理演算式でない場合は、文字列またはヌルを返すことが前提になっています。ヌルが返された場合、検
証は成功したとみなされます。そうでない場合、返された文字列はエラー文字列として表示されます。
保存済みサーチおよびアドホックサーチへのマクロの適用
保存済みサーチまたはアドホックサーチにサーチマクロを入れる場合、左引用符 (アクサングラーブ) 文字を使用
します。たいていの英語版キーボードの場合、この文字はチルダ (~) 文字と同じキーにあります。また、同じ構文
を使って、他のサーチマクロ内のサーチマクロを参照することも可能です。
注意：ダブルクォート (") と同じキーにある垂直引用符文字は使用しないでください。
例 - サーチマクロとトランザクションの組み合わせ
トランザクションおよびマクロサーチを組み合わせれば、トランザクションサーチ/レポートを手軽に作成するこ
とができます。この例は、サーチマクロを使った、定義されたトランザクションに基づくレポートの作成方法を表
しています。
ここで、「makesessions」と言う名前のサーチマクロが、それぞれが相互に 30 分以内に発生した同じ clientip 値
を共有するイベントからのトランザクションセッションを定義しています。
transaction clientip maxpause=30m
このサーチはページビューイベントを取り、サーチマクロ「makesessions」を使ってそれをセッションに分類し
ます。
eventtype=pageview | `makesessions`
このサーチは、各日のセッション当たりのページビュー数のレポートを返します。
eventtype=pageview | `makesessions` | timechart span=1d sum(eventcount) as pageviews count as sessions
同じレポートを作成したいけれどもしばしば異なる期間を使用する場合は、それを期間を引数に持つサーチマクロ
として保存します。このサーチマクロを「pageviews_per_second(1)」と呼ぶことにします。
eventtype=pageview | `makesessions` | timechart $spanarg$ sum(eventcount) as pageviews count as sessions
これで、サーチ App からこのサーチを実行する際に、または保存済みサーチに追加する際に、期間を指定できる
ようになります。
`pageviews_per_second(span=1h)`
カスタムサーチコマンドの作成
この章について
45
Splunk のサーチ言語には、さまざまコマンドが用意されています。それらのコマンドを使って、多彩なデータを
引き出して、それらを異なる手段で表示することができます。イベントの相関の検索、結果の統計の算出、フィー
ルドの評価と結果の並べ替え、データの再フォーマットおよびデータの強化、グラフの作成など、さまざまな作業
を行うためのコマンドが用意されています。さらに、サーチ言語を強化するために、各自のニーズに合わせてこれ
らのコマンドをカスタマイズしたり、独自の処理や計算を実行するための独自のサーチコマンドを開発したりする
ことができます。
この章は、以下の事項を説明しています。
サーチコマンドとその引数の命名方法のガイドライン。
サーチコマンド作成およびそれの Splunk サーチコマンドへの統合方法の概要。
サーチコマンドの権限とアクセス制御の設定方法。
カスタムサーチコマンドの例。
サーチコマンドスタイルガイド
ここでは、カスタムサーチコマンドおよびその引数の命名のガイドライン、そして引数の処理方法について説明し
ていきます。このスタイルガイドは searchproc_style.txt にも記載されています。
カスタムサーチコマンドの命名規則
サーチプロセッサのコマンド名：
英数字を使用し、最初は文字でなければなりません。
ダッシュやアンダースコアなどの、英数字以外の文字を使用することはできません。
引数オプション名：
英数字を使用し、最初は文字でなければなりません (アンダースコアは可)。
論理演算式は肯定的に指定する必要があります。たとえば、hidefield=<bool ではなく showfield=<bool> を使用
します。
大文字小文字区別：
コマンド名は大文字と小文字が区別されます。
フィールド名は、大文字と小文字を区別する必要があります。
キーワードでは、大文字と小文字は区別されません (例：「by」のようなストップワード)。
引数の処理およびチェック方法
一連の引数とそのオプションを取るサーチコマンド (またはプロセッサ) を作成できます。
一連のオプション引数セット (空のセットも可能) を取る単純プロセッサ：
processArguments() では、getOption() 呼び出しで各オプションの値を取得します
例：outputraw (オプションなし)、analyzefields (1 つのオプション引数を取る)
オプションとフィールドのリストまたは他の引数を取るプロセッサ (大部分のコマンドはこのカテゴリに分類)：
フィールドのリストはオプションとして指定するのではなく、引数リストの一部として直接指定する必要が
あります。複数のリストが必要な場合は、キーワードを使ってリストを区切ります。
processArguments() で、まず getOption() を使ってオプションパラメータを取り込みます。次に
getNextArgs() を使って名前変更引数のリストを取得します。getNextArgs() では、必要に応じてストップ
ワードを使用することができます。この場合、特定の単語が見つかると、引数の取得を停止します。
例："mycommand myopt=optval field1 field2 field3 by otherval1 overval2" (「by」がストップワード)。
完全に引用符で囲まれた引数は、キーワードまたはオプションとはみなされません。
外部引数をすべてチェック：
すぺてのプロセッサは、引数処理の最後に「ERRORIFUNUSEDARG」マクロを呼び出して、使用されな
かった外部引数にエラーのフラグが設定されていないことを確認する必要があります。
オプション名のスペル誤りも多いため、意図しない結果を招かないようするためにも、このことが重要にな
ります。
エラーの処理
エラーをパーシングするすべての引数は、解析時に SearchProcessorException() をスローする必要があります。
一般的に、実行時のエラー (例：指定フィールドがイベント内に存在していない) は、実行時に SearchResultsInfo
に INFO/WARN/ERROR メッセージを追加する必要があります。また、実行を停止しないようにする必要があり
ます。
カスタムの Python サーチコマンドスクリプトの場合、commands.conf から以下のように stderr 出力を設定する
ことができます。
46
stderr_dest = log|message|none
デフォルトの stderr_dest = log は、エラー出力が search.log に転送される古い動作です。stderr_dest = message を
使用する場合、stderr 出力の各行がサーチバナーのメッセージとして処理されます。メッセージレベルは、メッ
セージの開始がどうなっているかによって決まります。
情報メッセージは「INFO 」から始まる必要があります。
警告メッセージは「WARN 」から始まります。
デバッグメッセージは「DEBUG 」から始まります。
エラーメッセージは「ERROR 」から始まります。
これらのパターンで始まらないメッセージは、エラーメッセージとして処理されます。
サブパイプラインを取るコマンド
これらのコマンドは、サブパイプラインが自動実行されないように evalArgs() に優先させる設定を行うか、または
handleSearchResultsArgs() に優先させる設定を行って真 (True) を返すようにする必要があります。
複数のパイプラインを処理するコマンドは、コマンドへの入力をイベントのパイプラインとして、指定されている
サブパイプラインをその他の入力として使用する必要があります。例："join [search A] [search B]" ではなく
"search A | join [search B]" とします。
このようなコマンドの例として、join、append、set (set は前のガイドラインに違反していますが) などが挙げられ
ます。
サーチコマンドの作成
カスタムサーチコマンドは、データを読み取り、それを処理して出力する Python スクリプトです。ここでは、
Python スクリプトによる入力と引数の処理規則について説明していきます。
サーチコマンドは以下の条件を満たしていなければなりません。
$SPLUNK_HOME/etc/apps/<app_name>/bin/
名前付き <command>.py
に保管する
サーチコマンド名には、英数字 (a～z、A～Z、および 0～9) のみを使用できます。新しいコマンドに既存のコマン
ドと同じ名前を使用することはできません。
サーチコマンドの種類
カスタムサーチコマンドには、生成およびストリーミングの 2 種類のサブタイプがあります。
生成コマンドは、サーチパイプラインの先頭に使用できるコマンドです。入力 (イベントやサーチ結果など)
を予期していませんし、必要でもありません。代わりに、インデックスからのイベントの取得または生成を
担当します。
ストリーミングコマンドは、各イベントに変換を適用し、その結果をすべてを一度にではなく、一定単位ご
とに出力します (各イベントへのフィールドの追加など)。非ストリーミングコマンドは、それがデータを操
作/減少して出力する前に、すべてのデータが入力として利用できることを前提にしています。
順次出力形式でイベントを生成したり、データを返すコマンドを作成することもできます。
これらは、commands.conf 内の変更可能な設定です。詳細は、「Splunk へのカスタムコマンドの追加」を参照し
てください。
入力の処理
スクリプトへの入力は、純粋な CSV または Intersplunk でなければなりません。Intersplunk では、ヘッダーセク
ションの次に空行があり、それに続けて純粋な CSV 本体が記載されています。
スクリプト入力を解釈するもっとも簡単な方法は、splunk.Intersplunk.readResults を使用することです。これは、3
つのオプションパラメータを取り、dict のリストを返します (入力イベントのリストを表す)。オプションパラメー
タは、「input_buf」、「settings」、および「has_header」です。
「inputbuf」は入力の読み取り場所で、これが None (デフォルト) の場合、sys.stdin が仮定されます。
「settings」は dict で、ここに入力ヘッダー内に見つかった任意の情報を保管します (デフォルトは None
で、この場合設定は記録されません)。
「has_header」は、入力ヘッダーを予期するかどうかを表しており、デフォルトは 真 (True) です。
スクリプトがヘッダーを予期するかどうかを指定するには、enableheader キーを使用します。enableheader キー
のデフォルトは真 (True) です。これは、入力にヘッダーセクションが含まれており、Intersplunk フォーマットを
使用していることを表しています。
スクリプトが入力のヘッダーセクションを予期しない場合 (enableheader が偽 (False)) は、直接 Python csv モ
ジュールを使って入力を読み取ります。例：
47
import csv
r = csv.reader(sys.stdin)
for l in r:
...
この方法の利点は、任意の時点で for ループを中止でき、反復によりその時点までに入力された行のみがメモリー
に読み込まれることです。場合によっては、これがパフォーマンスの向上にもつながります。
出力の送信
Intersplunk を使ってスクリプトの出力を作成することもできます。splunk.Intersplunk.generateErrorResults は文字
列を取り、sys.stdout に正しいエラー出力を書き込みます。splunk.Intersplunk.outputResults は dict オブジェクトの
リストを取り、sys.stdout に適切な CSV 出力を書き込みます。
データを出力するには、以下の文字列を追加します。
splunk.Intersplunk.outputResults(results)
スクリプトの出力は、純粋な CSV であるとみなされます。エラーが発生した場合は、1 つの「ERROR」列と 1
つの行 (見出し行の他に)、およびメッセージのコンテンツを含む CSV が返されます。
エラー処理
スクリプトに supports_getinfo = true が存在している場合を除き、スクリプトに渡される引数 (sys.argv 内) は、
サーチ言語内でコマンドの起動に使用された引数と同じになります。supports_getinfo キーは、スクリプトへの最
初の引数が __GETINFO__ or __EXECUTE__ であることを示しています。これにより、解析時にコマンド引数でスクリプ
トを呼び出して、サーチ実行前に構文エラーを確認することができます。この時点でのエラーは、サーチの実際の
実行を回避します。__GETINFO__ で呼び出した場合は、引数に応じて動的にスクリプトのプロパティ (ストリーミン
グかどうかなど) を指定することができます。
スクリプトで supports_getinfo に「true」が設定されている場合、最初に以下のような呼び出しを実行する必要が
あります。
(isgetinfo, sys.argv) = splunk.Intersplunk.isGetInfo(sys.argv)
このコールにより sys.argv から最初の引数が除去され、GETINFO モードまたは EXECUTE モードかどうかが確
認されます。GETINFO モードの場合、スクリプトは splunk.Intersplunk.outputInfo() を使ってスクリプトのプロパ
ティを返すか、または引数が無効な場合は splunk.Intersplunk.parseError() を使用する必要があります。
outputInfo()
およびその引数の定義は以下のようになります。
def outputInfo(streaming, generating, retevs, reqsop, preop, timeorder=False)
また、commands.conf にこれらの属性を設定することもできます。
Splunk へのカスタムコマンドの追加
サーチコマンドを作成したら、commands.conf を編集してそのコマンドのエントリを作成する必要がありま
す。commands.conf にエントリを追加しない限り、Splunk がカスタムコマンドを認識することはありません。内の
各コマンドの設定オプションについては、『管理マニュアル』の commands.conf.spec を参照してください。ここで
は、ほんの一部のパラメータのみを取り上げています。
新しいスタンザの作成
内の各スタンザは、サーチコマンドの設定を表しています。カスタムスクリプトを単に有効にするス
タンザの例を以下に示します。
commands.conf
[<STANZA_NAME>]
filename = <string>
は、コマンド起動時にサーチ単語として指定するキーワードです。サーチコマンド名には、英数字 (a
～z、A～Z、および 0～9) のみを使用できます。新しいコマンド (ここでは新しいスタンザ) に、既存のコマンドと
同じ名前は使用できません。
STANZA_NAME
属性には、カスタムスクリプト名を指定します。Splunk はこのスクリプトが適切な
ディレクトリにあることを前提にしています。見つからない場合
は、$SPLUNK_HOME/etc/apps/search/bin (Splunk 出荷時に大部分のスクリプトはここに保存される) からスクリプトを
探します。たいていの場合は、スクリプトを app 名前空間内に配置することをお勧めします。
filename
$SPLUNK_HOME/etc/apps/<app_name>/bin/
コマンドの記述
filename 属性は、単にサーチスクリプトの場所を示します。その他の属性を使って、Splunk に追加するコマンド
のタイプを記述することができます。
48
streaming = [true|false]
コマンドがストリーミング対応かどうかを示します。
デフォルトは偽 (false) です。
generating = [true|false|stream]
コマンドが新たなイベントを生成するかどうかを示します。
stream の場合、そのコマンドは新しいイベントを生成し (generating = true)、ストリーム対応 (streaming =
true) となります。
デフォルトは偽 (false) です。
Splunk の再起動
にカスタムコマンドを追加したら、Splunk を再起動する必要があります。カスタムコマンドスクリ
プトまたは commands.conf 内の既存のコマンドのパラメータを編集した場合は、再起動の必要はありません。
commands.conf
カスタムコマンドへのアクセス制御
スクリプトを作成して、commands.conf に追加したら、それの使用を開始することができます。
デフォルトでは、すべてのロールが commands.conf への読み取りアクセス権を持っています。書き込み権は管理者
のみが保有しています。つまり、個別のコマンドに対するアクセス権を明示的に変更しない限り、すべてのロール
が commands.conf に記載されているコマンドを実行できてしまいます。コマンドの使用を特定のロールまたはユー
ザーに制限する場合、[管理] でそのアクセス権を変更するか、または default.meta.conf を編集します。
Splunk Web で編集できる項目
Splunk 管理を使って、App 内で実行させたくないサーチコマンドを無効にすることができます。
1. [管理] >> [詳細サーチ] >> [サーチコマンド] に移動します。
サーチコマンドのテーブルが表示されます。これには、次の情報が記載されています：コマンド名、コマンドを定
義しているスクリプトのファイル名、スクリプトの所有者、所属している App、共有制限、有効になっているかど
うか。
注意：このテーブルには、Python で作成されたサーチコマンドのみが記載されています。
2. サーチコマンドの [ステータス] 列から、[無効] をクリックします。
App 内でコマンドが無効になったことを知らせるメッセージが表示されます。
[管理] ページから、コマンドに対するロールのアクセス権を変更することもできます。
1. サーチコマンドの [共有] 列から、[権限] をクリックします。
サーチコマンドの [権限] ビューが表示されます。このページから、以下の事項を指定できます。
コマンドを現在の App に表示するか、またはすべての App に表示するか。
このコマンドに読み取り、書き込みアクセス権を持つロール。
2. 変更内容は忘れずに保存してください。
設定ファイルで編集できる項目
コマンドに対するアクセス権は、$SPLUNK_HOME/etc/apps/<app_name>/metadata/default.meta ファイルを使って変更する
こともできます。詳細は、『管理マニュアル』の default.meta.conf に関する記事を参照してください。
以下の例は、commands.conf および input コマンド (管理者以外は実行不可) に対する、デフォルトアクセス権を表
しています。
[commands]
access = read : [ * ], write : [ admin ]
export = system
[commands/input]
access = read : [ admin ], write : [ admin ]
サーチスクリプトファイル自体へのアクセス制限も存在しています。これらのコントロールは、[searchscripts] ス
タンザに定義されています。デフォルトで、すべてのロールと App がファイルを参照できますが、編集できるの
は管理者のみとなっています。
49
[searchscripts]
access = read : [ * ], write : [ admin ]
export = system
スタンザの export = system 行は、すべての App および [searchscripts] が commands.conf を利用できるこ
と (グローバル) を表しています。[searchscripts] に global export が指定されていない場合、スクリプト設定
(commands.conf) はすべての App で参照できます。ただし、スクリプトファイル自体は参照できません。
[commands]
カスタムサーチコマンドの例
外部化されたサーチエラー文字列
外部化されたサーチエラー
サーチコマンドのエラー文字列を含め、Splunk で外部化された文字列は、literals.conf 設定ファイルに定義され
ています。Splunk ユーザーと管理者はこのファイルを編集する必要はありません。ただし、Splunk 開発者が既存
の文字列を変更したり、カスタム設定を定義したりすることは可能です。
この設定ファイルは、$SPLUNK_HOME/etc/system/default/literals.conf に存在しています。このファイルは編集しない
でください。このトピックの残りの部分をお読みください。
サーチエラー文字列
ファイル内のサーチエラー文字列用の部分は、以下のテキストで示されています。
# String externalization starts here
この後に、関連するエラー文字列がある、各サーチコマンド用のスタンザが記載されています。たとえば、eval コ
マンドのスタンザは以下のようになります。
[EVAL]
MISSING_ARGS
= Missing arguments. usage: eval dest_key = expression
FAILED_PARSE
= Failed to parse arguments. eval usage: eval dest_key = expression
INVALID_DEST
= Invalid destination key
BOOLEAN_RESULT
= The result of an expression cannot be boolean. Try if([bool expr], [expr], [expr])
BAD_DEST_BRACKETS
= Invalid destination field. {} brackets must be closed
INVALID_OP__S
TYPE_FAIL_CONCAT
= Invalid operator at '%s'
& nbsp;
TYPE_FAIL_DIFF__S
TYPE_FAIL_PLUS
TYPE_FAIL_NUM__S
TYPE_FAIL_BOOL__S
MATCH_FAIL__C
= Typechecking failed. '.' operator only takes strings and numbers
= Typechecking failed. '%s' operator received different types
= Typechecking failed. '+' only takes two strings or two numbers
= Typechecking failed. '%s' only takes numbers
= Typechecking failed. '%s' only takes boolean arguments
= Malformed expression - %c expected
CONSUME_FAIL__S
= Malformed expression - %s expected
INVALID_NUMBER__S
& nbsp;= Invalid number: %s
INVALID_UNARY_OP
= Malformed expression - Invalid unary op
UNEXPECTED_CHAR__C
MISSING_FACTOR
MISSING_TERM
MISSING_COMP_TERM
MISSING_AND
MISSING_OR
INVALID_FUNC_ ARGS__S
BAD_FUNC__S
= Malformed expression - Unexpected character hit in factor: %c
= Malformed expression - Missing factor
= Malformed expression - Missing term
= Malformed expression - Missing comparison term
= Malformed expression - Missing AND term
= Malformed expression - Missing OR term
= Invalid arguments to '%s' function
= Unsupported Function: %s
エラー文字列の上書きまたは定義
literals.conf を編集する前に、設定の仕様とファイルの例を参照してください。
$SPLUNK_HOME/etc/system/README/literals.conf.spec
$SPLUNK_HOME/etc/system/README/literals.conf.example
既存のエラー文字列を上書き、またはカスタムエラー文字列を定義するには、以下のディレクトリに literals.conf
を作成します。
$SPLUNK_HOME/etc/system/local/
既存の文字列を上書きするには、デフォルトの literals.conf からローカルの literals.conf にスタンザ名と属性/値の
ペアをコピーして、ローカル版の literals.conf ファイルで値を編集します。
50
新しいカスタム設定はすべて、literals.conf のローカルコピーに定義します。
重要：literals.conf を不適切に編集すると、Splunk のパフォーマンスに深刻な影響を与える可能性があります。
literals.conf の設定を変更する際のガイドラインを以下に示します。
外部化文字列は、属性名と値のペアで定義されています。属性値のみを変更する必要があります。属性名は
変更しないでください。
文字列に "%s" が含まれている場合、%s のインスタンス追加/削除したり、順序を変更したりしないでくださ
い。
文字列に HTML タグおよびエンティティが含まれている場合は、すべてが適切にエスケープ処理されている
ことを確認してください。
51