Soliton NKのウェブ操作画面には、Ingesterによって蓄積されたデータから、検索し、検索結果を表示する機能があります。しかし、この機能で、自分がやりたいことがすぐできるのかよく分からなかったりするので、用意されてる機能にどんなコマンドやオプションがあるのかを、この種の操作手法に慣れてない初心者（この記事の執筆者レベル）向けまとめました。

基本的な検索・結果表示手法

検索と検索結果表示のやり方を指定する文字列の事をクエリ（Query）といいます。クエリは、「検索するデータ範囲」「検索の方法と条件」「検索によって抽出された結果の表示方法」という3種類の事柄をこの順番で指定するのが基本系です。
「検索の方法と条件」は、「検索の方法と条件A」での検索結果を、次の「検索の方法と条件B」でさらに検索するという具合に、検索手法を連ねることもできます。「検索の方法と条件」を連ね、最後に「検索結果表示」の機能までのデータ受け渡しは、パイプラインを表す"|"で表現されます。

クエリの例

クエリは、具体的には例えば、

tag=reddit json Body | eval len(Body) < 20 | table Body

というような表記になります。

「検索するデータ範囲」の指定方法

一番左側（データ受け渡しの上流側）に記載されている、"tag=reddit"が、「検索するデータ範囲」に当たり、蓄積されたデータの中で、"reddit"というタグが付いているデータを検索対象とするという意味になります。

"reddit"というタグが付いているデータに加えて、"hackernews"というタグが付いているデータも検索範囲に含めたい場合は、

tag=reddit,hackernews

というように、コンマで区切りながらタグを複数指定することができます。また、タグをワイルドカードの指定"*"を用いて表現することができ、例えば、タグの文字列として syslog-http- で始まるものは全て検索対象としたい場合には、

tag=syslog-http-*

と表記できます。ワイルドカードを使ったタグ表記と、コンマ切りでの複数タグの指定は併用できますので、こういう表現もできます。

tag=syslog-http-*,syslog-firewall-*

「検索の方法と条件」の指定方法

「検索の方法と条件」は、用いる検索モジュールと、その検索モジュール毎に設けられている検索条件指定を記述します。上で例として挙げたクエリの中では、"json"と"eval"が検索機能の指定にあたります。

"json"の後に次ぐ、"Body"や、"eval"の後に次ぐ、"len(Body) < 20"が、検索条件を引数指定してる形になっています。

tag=reddit,hackernews tag=reddit json Body | tag=hackernews json body as Body | eval len(Body) < 20 | table Body

また、上の例のように、検索モジュールの呼び出しの前に追加のタグ仕様を置くことにより、多くの検索モジュールをクエリタグ全体のサブセットで動作させることができます。

「検索結果表示」の指定方法

パイプラインで繋がれたクエリの記述の最も右側（下流側）に、表示モジュールと、表示モジュール毎に必要な、表示内容や表示スタイルを引数指定します。先ほども挙げたクエリ；

tag=reddit,hackernews tag=reddit json Body | tag=hackernews json body as Body | eval len(Body) < 20 | table Body

において、tableが表示モジュールで、Bodyフィールドの内容を単一の列に表示するように指示がなされています。

列挙値

列挙値とは、検索パイプライン内で作成される一時的なデータセットのことです。次のパイプラインでは、いくつかの列挙値が作成されています。

tag=reddit json Body | langfind -e Body | count by lang | sort by count desc | table lang count

最初に、jsonモジュールはredditのタグの付された生のエントリをJSONでパースし、「Body」要素を引き出して、Bodyという名前の列挙値に格納します。次に、langfindモジュールはBody列挙値にアクセスし、どのような言語が用いられているか解析し、その結果を、langという名前の新しい列挙値に格納します。次に、countモジュールはlang列挙値を読み取り、その中にどのような値が何回出現するかという回数をカウントし、その結果をcountという名前の列挙値に格納します。その後は、count列挙値の結果を回数の多い順（降順）に並べ替え、それをtable表示モジュールによって表形式にして表示します。

特殊文字を含む文字列の引数指定

Gravwellの各種モジュールに引数指定するときは、特殊文字に注意する必要があります。ほとんどのモジュールは、スペース、タブ、改行、および次の文字を区切り文字として扱います：!#$%&'()*+,-./:;<=>?@

これらの文字を含む文字列を引数指定したい場合、引数を二重引用符で囲みます。

json "search-id"
grep "dank memes"

二重引用符を引数の中に使用する必要がある場合は、二重引用符をエスケープしてください。例えば、grep によって、二重引用符を検索したい場合は次のように記述することになります。

grep "\","

検索モジュール

検索モジュールは、パススルーモードでデータを操作します。つまり、検索対象のエントリデータを読み取って何らかのデータ操作（データ抽出、変更、並べ替えなど）を実行し、その結果のエントリをパイプラインによって下流のモジュールに渡します。

汎用フラグ

次の汎用フラグは、検索モジュール群共通に使えるフラグです。：

-e ： 検索モジュールが読み取るデータとして、エントリのデータフィールドからではなく、指定された列挙値から読み取るよう指定します。例えば、次の検索クエリでは、HTTPパケットのペイロードからJSONフィールドを読み取ろうとします。

tag=pcap packet tcp.Payload | json -e Payload user.email

-r ： Resourcesシステム内のリソースを指定します。これは通常、geoipモジュールで使用されるGeoIPマッピングテーブルなど、モジュールで使用される追加データを格納するために使用されます。
-v： 通常のパス/ドロップの操作指定を反転させることを指定します。たとえば、grepモジュールは通常、特定のパターンに一致するエントリを下流に渡し、一致しないエントリをドロップしますが、 -vフラグを指定すると、一致するエントリがドロップされ、一致しないエントリが下流に渡されます。
-s： 「厳格」モードを示します。通常、複数の絞り込み条件が指定されている時は、絞り込み条件のいずれか1つが満たされた場合、下流にエントリを渡しますが、strictフラグを設定すると、すべての絞り込み条件が満たされた場合にのみエントリが渡されます。たとえば、requireモジュールは通常、指定された必要な列挙値のいずれか含むエントリを下流に渡しますが、-s フラグが記述されてる場合には、指定されたすべての列挙値を含むエントリのみを下流に渡します。
-p： 「許容」モードを示します。デフォルトではパターンとフィルターが一致しないときにモジュールがエントリーをドロップする場合、p フラグの指定によって通過を許可することができます。regexモジュールや、GROKモジュールではこのpフラグが役立ちます。

汎用列挙値

次の列挙値は、すべてのエントリで使用できます。これらは実際には生のエントリ自体のプロパティについた名前ですが、列挙値の名前として扱うことができます。

SRC： エントリデータのソース。
TAG： エントリに添付されたタグ。
TIMESTAMP： エントリのタイムスタンプ。
DATA： 実際のエントリデータ。
NOW： 現在の時刻。

これらはユーザー定義の列挙値と同じように使用できるため、table foo bar DATA NOW というようにに記述して一覧表示する時に効果的です。

検索モジュール一覧

検索モジュールには次のようなものがあります。これらはSolitonNKのデータ分析の中核をなす機能であり、単機能的なものから、複雑なデータ操作ができるものまで様々あります。そして、SolitonNKのバージョンアップに伴って機能強化されたり、新しいモジュールが追加されたりします。

abs：指定された列挙値の絶対値を取ります。
alias：既存の列挙値に別名を追加で割り当てることができます。
anko：evalの補足として、より強力なスクリプト環境を提供します。
ax：事前抽出ルールを使用して、他のモジュールの機能を呼び出してデータからフィールドを抽出するラッパーモジュールです。
base64：base64値のエンコードとデコードが行えます。
canbus：CANメッセージ（車両データ）からフィールドを抽出します。
cef：CEF（Common Event Format）は、データプロバイダーやデータ強化システムで使用されるデータハンドリング方法です。
count：レコードのインスタンスをカウントします。レコード内のデータに対して算術演算は実行されません。
csv：コンマ区切り値からデータを抽出およびフィルタリングすることができます。
diff：diffモジュールは、列挙値の差分を出します。現在のエントリで2つの列挙値の差分を出す"ノーマルモード"と、現在のエントリの列挙値と、前のエントリの同じ列挙値の差分を出す"一時モード"の２種類のモードがあります。
entropy：経時的なフィールド値のエントロピーを計算します。
eval：検索および列挙値でANDおよびORロジックを実行するために最も汎用的に用いられます。
fields：検索エントリから列挙された値にデータを抽出およびフィルタリングし、後で使用できるようにします。
first/last：検索データから最も早い時刻のエントリまたは最も遅い時刻のエントリを示します。
geoip：MaxMind GeoIPデータベースを使用して、IPアドレスに対応する地理的位置情報を抽出します。おおよその緯度/経度、都市名、国名、大陸名を抽出できます。また、ASN番号とIPに関連付けられたASN組織を抽出することもできます。
grep：（Unicodeではない）テキスト文字列を検索する非常に基本的なパイプラインモジュールです。
grok：複雑なテキスト構造からデータを抽出する際、正規表現全体を複雑に組み合わせて抽出条件を毎回指定する代わりに、それらの正規表現に名前を割り当てユーザーが代わりに名前を指定できるようにします。
hexlify：データをASCII 16進表現にエンコードします。
ip：列挙値をIPタイプに変換し、オプションでフィルタリングすることができます。
ipexist：指定されたIPアドレスが含まれたエントリが存在するか、高速にチェックします。
ipfix：未加工のIPFIXおよびNetflow V9データフレームを抽出およびフィルタリングすることができ、ネットワークフローの迅速な識別、ポートでのフィルタリング、または集約フローの動作の一般的な監視を可能にします。
iplookup：サブネットをキーとして使用してIPアドレスデータを分類します。これにより、簡便なルックアップテーブルを生成できます。
j1939：J1939は、IDコードとオフセット値を伴った、canbusプロトコル拡張です。
join：2つ以上の列挙値を単一の列挙値に結合できます。
json：検索エントリから列挙された値にデータを抽出およびフィルタリングするために使用されます。
kv：検索エントリからKey-Value形式のデータを抽出およびフィルタリングして、さらに分析するための列挙値にします。
langfind：テキストを自然言語処理します
length：エントリデータまたは列挙値のいずれかの長さ（バイト単位）を算出します。
limit：指定された数のエントリを通過させます。
lookup：静的データソースのデータの分類と変換を行うために使用されます。
lower：テキストを小文字に変換します。
Math (list of math modules)：パイプライン上で動作して各種の統計分析を実行します。
max：対象レコードから最大値を返します。
mean：対象レコードの平均値を返します。
min：対象レコードから最小値を返します。
namedfields：検索エントリからバイトシーケンスで区切られたレコードからフィールドを抽出し、特定のデータ形式にわかりやすい名前を付けます。
netflow：生のnetflowデータフレームを抽出およびフィルタリングでき、ネットワークフローの迅速な識別、ポートでのフィルタリング、または集約フローの動作の一般的な監視を可能にします。
packet：イーサネット、IPv4、IPv6、TCP、およびUDPパケットからフィールドを抽出します。
packetlayer：パケット処理への非常に堅牢なインターフェイスを提供します。
regex：正規表現を使用してテキストデータを照合するパイプラインモジュールです。
require：パイプラインのエントリを調べ、特定の列挙フィールドを持たないエントリをすべて削除するフィルタです。
slice：エントリ/列挙値内のオフセットを指定し、オプションでそれらのバイトを特定の型にキャストすることにより、エントリまたは列挙値からバイトを抽出します。
sort：Gravwell検索パイプラインのすべてが一時的にソートされます。
split：エントリまたは列挙値の内容を複数のエントリに分割できます。
src：すべてのエントリが持つユニバーサルメタデータアイテムであるソースに基づいてエントリをフィルタリングするために使用されます。
stats：複数の統計解析を同時に行うことができます。
stddev：対象レコードから標準偏差情報を返します。
strings：エントリデータまたは列挙値から、指定範囲の最小長の文字列を検索します。
subnet：IPアドレスからサブネットを抽出します。
sum：レコードの値を加算していきます。
syslog：Simple Relay ingesterで取り込まれたRFC 5424形式の syslogメッセージからフィールドを抽出します。
taint：汚染分析とフロー追跡に使用されます。
unique：クエリデータから重複エントリを排除します。
upper：テキストを大文字に変換します。
variance：対象レコードの分散情報を返します。
winlog：XML形式のWindowsログデータ専用の抽出ツールです。
words：分割文字で区切られたテキストワードを検索するテキストマッチングエンジンです。
xml：XMLデータからコンポーネントを列挙値に抽出できます。

表示モジュール

表示モジュールは、検索モジュールパイプラインからデータを受けとり、整理してユーザーに表示します。表示モジュールは、データの経時インデックスを提供します。これを利用して、元の検索内でタイムスパンを移動し、ゼロに合わせることができます。レンダラーは、オプションで検索結果を保存できます。検索結果は、再び開いて表示したり、Gravwellの別のインスタンスに渡すこともできます。これは、データのビューをアーカイブしたり、保存された元データの有効期限が切れたり意図的に削除された後も、分析結果を参照するのに役立ちます。

汎用列挙値

すべての表示モジュールで、次の汎用列挙値が使えます。

SRC： データのソース。
TAG： データに添付されたタグ。
TIMESTAMP： エントリに関連付けられたタイムスタンプ

表示モジュール一覧

表示モジュールには次のようなものがあります

チャート、グラフ、およびゲージの表示

chart：データを折れ線グラフ、棒グラフなどとして表示します。

fdg：力指向モデルによるグラフ表示。

stackgraph：積み上げグラフを表示します。

gauge：ゲージ（アナログ計器）表示や数値表示をします。

表およびテキストの表示

table：列挙値の表を表示します。
text：最小限の書式設定でエントリの本文を出力します。
raw ：生データをそのままテキスト出力します。
pcap：ネットワークパケットの内容の概要を表示します。

地図の表示

pointmap / heatmap マップ上のヒートマップまたは個々のポイントを表示します。

point2point 出発地と宛先地の両方を持つデータエントリを表示します。

最後に

以上で、SolitonNKで、どのようなデータ解析ができるのか、機能概要は掴めるようになったのではないでしょうか。

Soliton NKを試したい人はの下の Soliton NK 公式サポートサイトでお申し込み下さい。

Soliton NK について、今後記事を追加していく予定です。