SplunkのAdd-on Builderで自前のアドオンを作成してみる(REST API編)

2020.01.21

オペレーション部 江口です。

Splunkでデータ入力を行うためのアドオンの作成を助けてくれるツール、Add-on Builderについてご紹介したいと思います。

Splunkアドオンとは

Splunkは、任意のダッシュボードや機能拡張を行うアプリケーション(Splunk App)をユーザがインストールできます(自前で開発もできます)。 そのAppの一種で、任意のデータを入力する機能を拡張するものを「アドオン」と言っています。 スクリプト(シェルスクリプトやPython)を実行し、任意のAPIを実行してデータを取得したり、任意に加工するなどの処理を行ってSplunkに渡す処理を行えます。

Splunk Add-on Builderとは

このSplunkアドオンの開発を助けてくれるツールがSplunk Add-on Builderです。これ自体がSplunkにインストールするアプリとして提供されていて、Splunkbaseで入手できます。

https://splunkbase.splunk.com/app/2962/

詳しい使い方については、Splunkの公式ドキュメントで詳しく説明されています。

https://docs.splunk.com/Documentation/AddonBuilder/latest/UserGuide/Overview

開発を助けるいろいろな機能が利用できるのですが、この記事ではとりあえず一番簡単なREST APIでデータを入力するアドオンの作成を通じて、Addーon Builderの基本的な使い方をご紹介します。

この記事で作成するアドオン

REST APIと書きましたが、実際のところURLを叩いて実行結果としてJSONが返ってくるならば指摘できると思われます。 ということで、この記事では、AWSのサービスの状態をJSONで取得する下記のURLを試しに使ってみたいと思います。(手軽に思われたので)

https://status.aws.amazon.com/data.json

ちなみに実行時に返ってくるJSONデータは以下のようなものです。

{
    "archive":[
        {
             "service_name":"Auto Scaling (N. Virginia)", 
             "summary":"[RESOLVED] Increased API Error Rates", 
             "date":"1525914401", 
             "status":1, 
             "details":"", 
             "description":"<div><span class="yellowfg"> 6:06 PM PDT</span> We are investigating increased API error rates in the US-EAST-1 Region.</div><div><span class="yellowfg"> 6:26 PM PDT</span> We are continuing to investigate increased API error rates in the US-EAST-1 Region</div><div><span class="yellowfg"> 7:24 PM PDT</span> We have identified the root cause of the elevated API error rates and can confirm that most customers have recovered. We are continuing to work towards full resolution.</div><div><span class="yellowfg"> 7:40 PM PDT</span> Between 5:42 PM and 7:04 PM PDT, we experienced increased API error rates in the US-EAST-1 Region. The issue has been resolved and the service is operating normally.</div>", 
             "service":"autoscaling-us-east-1" 
        },
    (略)
    "current":[
    ]
}

archiveに過去の障害の情報が、currentには現行の障害の情報が入ってきます。アドオンを作成すると、このJSONデータをSplunkに取り込ませることができるようになります。

Add-on Builderのインストール

まずはAdd-on Builderのインストールですが、前述のようにSplunk Appの一種ですので、他のAppと方法は変わりません。

Splunkの「Appの管理」-「Browse more apps」から「Add-on Builder」で検索して見つけるか、もしくはSplunkbaseのAppページからファイルとしてダウンロードし「Install app from file」からインストールを行います。

インストールすると、アプリケーションのメニューに「Splunk Addーon Builder」が追加されますので、クリックしてメインメニューへと移動してみましょう。

アドオンの作成

新しいアドオンを作るには、Addーon Builderのメインメニューから「New Add-on」をクリックします。

名前やバージョンなど、アドオンの基本情報の入力画面が表示されます。

内部的には、ここに設定した名前を使ってこのアドオンのアプリケーション用ディレクトリが作成されます。具体的なパスは$SPLUNK_HOME/etc/apps/TA-アドオン名です。

データ入力の設定

登録すると、そのアドオンの設定画面に遷移します。

画面から「Configure Data Collection」をクリックすると、データ入力方法の画面に遷移します。

データ入力の種類は3種類から選択可能です。

  1. REST API
  2. Shell Commands
  3. Python code

「REST API」はすでに説明したように、URLを指定してREST APIを叩き、その実行結果をSplunkに保存します。 「Shell Commands」「Python code」はそれぞれシェルコマンド、Pythonスクリプトの実行結果をSplunkに保存します。 単純にREST APIの実行結果を保存できれば良いのであれば「REST API」を、サーバ内でシェルで取得できる範囲の情報であれば「Shell Commands」を、複雑な処理が必要であれば「Python code」を使う、といった使い分けになるかと思います。ここでは「REST API」を選択して進めます。

プロパティ、パラメータの指定

入力方法を指定すると、プロパティ、パラメータの指定画面に遷移します。この画面には3つのタブがあります。

  1. Data Input Properties
  2. Data Input Parameters
  3. Add-on Setup Parameters

「Data Input Properties」は入力したデータのソースタイプの指定や、データを取得する間隔などの値を指定します。

「Data Input Parameters」は、ユーザに入力してもらう任意のパラメータを指定する画面で、入力フォームを作成することができます。ここで定義したパラメータのセットは、ユーザ側では複数定義が可能です。

「Add-on Setup Parameters」は、「Data Input Parameters」と似ていますが、アドオン全体のグローバルな設定の入力フォームを作成できます。「Data Input Parameters」はユーザが複数の定義を作成であるのに対して、こちらはグローバルな設定のため定義は1つのみ、という点が異なります。プリセットとして、プロキシサーバの設定、グローバルアカウント設定が用意されています。

「Data Input Parameters」「Add-on Setup Parameters」は有用な設定ですが、この記事では非常に単純なURLを指定するため特に利用せず、「Data Input Properties」に基本的な情報のみ入力しました。

REST API設定

次の画面では、具体的なREST APIの情報を指定します。URL、メソッド、パラメータ、ヘッダ等です。 今回は、「REST URL」にhttps://status.aws.amazon.com/data.json、メソッドに「GET」を指定しました。

設定後、「テスト」をクリックすると、指定URLへのアクセスが試行され、無事情報が取得できれば結果が「Output」欄に表示されます。

設定にはURL、メソッドなどのREST APIへアクセスするための項目のほか、「Event extraction settings」という抽出のための設定があります。ここではイベントの受け取ったJSONデータのどの部分を取得するか、を「JSON path」という項目で指定できます(指定しなければ、JSONデータすべてが一つのイベントとして記録されます)。

このJSON pathの書式は公式ドキュメントの下記ページに掲載されています。

https://docs.splunk.com/Documentation/AddonBuilder/3.0.1/UserGuide/ConfigureDataCollection#JSON_path_formats

たとえば、JSONデータのルート直下「current」フィールド下の各エントリのみを抽出したい場合は、$.current.[*]と記述します。$がルートを表し、固定のフィールド名は.フィールド名と指定。.[*]を記述することで、指定フィールド下の各配列を取得することができます。0番目の値を指定して取得したい場合は[0]などと直接指定します。サービスのステータスとしては、現在問題が起こっている情報のみ取得できれば良いと考え、ここでは$.current.[*]を指定してみました。

保存

指定や抽出に問題がなければ、「完了」を押すと入力の設定が保存されます。設定の適用には一度Splunkプロセスの再起動が必要となります。

作成したアドオンの利用とエクスポート

Splunkを再起動すると、前章で作成したデータ入力が有効になり、「Data Input Properties」で定義した間隔で情報を取得、Splunkにイベントを保存していきます。

サーチでイベント情報を確認してみると、以下のようにきちんと情報が表示されました。

また、作成したアドオンがAppとしてメニュー上に表示されるようになります。

Add-on Builderのメニュー画面では、アドオンのエクスポートも可能になっています。アプリの情報の下のメニューから「エクスポート」をクリックすると、tgz形式でアドオンがダウンロードできます。ダウンロードしたアドオンは、「Appの管理」メニューの「Install app from file」から他のSplunkでインストールができるようになります。

Splunkbaseでパブリックに配布するには、隣のメニューにある「Validate & Package」で問題ないかを検証・パッケージングする必要がありますが、このエクスポートでとりあえず社内などローカルに展開することはできるようになりました。

終わりに

以上、ざっとSplunk Add-on Builderでの簡単なアドオンの作成例を紹介しました。複雑な処理が必要な場合はPythonスクリプトを記述する必要があり、その場合はこれよりは若干手間がかかります。そちらも別の記事でいずれ紹介したいと思います。ともあれ、このツールを利用するとSplunkのアドオンが比較的楽に作成できる、という点が理解いただけたならうれしいです。