Splunk HTTP Event Collector と Apache APISIX の統合

テクノロジーの進化とエンタープライズアーキテクチャの進展に伴い、システムの複雑さは増しています。ログは、ユーザーが選択、運用、保守プロセスにおいてコストを削減できるよう、さまざまな分析エンジンをサポートし、互換性を持つことができます。ログベースの分析と監視は、システムの安定性を確保するための基盤として非常に重要な役割を果たします。

Apache APISIXは、優れたパフォーマンスを発揮するAPIゲートウェイであるだけでなく、コミュニティユーザーとのデータおよびログ運用保守に関するコミュニケーションを通じて、ほとんどの主流なオープンソースおよび商用ログソリューションをサポートしています。これには、HTTP Logger、TCP Logger、Kafka Logger、UDP Logger、RocketMQ Logger、SkyWalking Logger、Aliyun Cloud Logging(SLS)、Google Cloud Loggingなどが含まれます。

現在、Apache APISIXのLoggerサポートマトリックスに新たに追加されたのは、Splunk HEC Loggingです。

この記事では、Apache APISIXでSplunk HECサービスを設定して使用する方法について説明します。

Splunk HTTP Event Collectorについて

Splunkは、機械データの全文検索エンジンであり、さまざまなアプリケーションからデータを収集、インデックス化、検索、分析するために使用できます。DB Enginesの検索エンジンランキングによると、Splunkは現在2位に位置しており、広く使用されている全文検索ソフトウェアです。SplunkはElasticSearchと同様に、準リアルタイムのデータストリームを提供し、中断のない検索結果を提供します。

Splunk HTTP Event Collector (HEC)は、Splunkが提供するHTTPイベントコレクターで、HTTP(S)プロトコルを使用してデータやアプリケーションイベントをSplunkに送信する機能を提供します。

splunk-hec-loggingプラグインについて

splunk-hec-loggingは、Apache APISIXのリクエストログをSplunkに転送して分析および保存するために使用されます。有効にすると、Apache APISIXはログフェーズ中にリクエストコンテキスト情報を取得し、Splunk Event Data Formatにシリアライズしてバッチキューに送信します。キュー内のデータは、バッチキューごとの最大処理容量がトリガーされたとき、またはバッファをリフレッシュする最大時間に達したときにSplunk HECにコミットされます。

splunk-hec-loggingプラグインの使用方法

Splunkの設定

Splunk Enterpriseのデプロイ

Splunkのインストールガイドを参照してデプロイしてください。この記事ではDockerを使用したデプロイをデモンストレーションします。

Dockerコマンドのパラメータは以下の通りです。

docker run -p 18088:8088 -p 18000:8000 \    # 8088はHECポート、8000は管理バックエンドポート
  -e "SPLUNK_PASSWORD=your-password" \      # 管理者ログインパスワード
  -e "SPLUNK_START_ARGS=--accept-license" \ # ライセンス条項の受け入れ（SplunkはデフォルトでEnterprise Trial Licenseを提供します）
  -e "SPLUNK_HEC_TOKEN=your-hec-token" \    # デフォルトのHECトークンを設定、これによりデフォルトのHECが設定後に作成されます
  -itd --rm --name splunk-example splunk/splunk:latest

コマンドパラメータの詳細は、Docker Splunk Documentationで説明されています。

Splunk HECの設定

DockerではデフォルトのHECがすでに設定および作成されているため、ここでは作成プロセスについては説明しません。手動での作成プロセスの詳細については、ドキュメントを参照してください: Set up and use HTTP Event Collector in Splunk Web。

Splunk EnterpriseにログインしてHECを確認

ブラウザからDockerのマッピングポートにアクセスします。管理バックエンドの8000ポートをホストの18000ポートにマッピングする必要があるため、操作中にホスト上の「ループバックアドレスとポート」を使用してブラウザからアクセスできます。例: http://127.0.0.1:18000、ログインのデフォルトユーザー名はadminで、パスワードは上記の例で環境変数に設定したSPLUNK_PASSWORDの値です。

以下の図のように表示されれば、ログイン成功です。

Splunk UI

画面右上の「Settings > Data Inputs」をクリックして、デフォルトのHECが正常に設定されているか確認します。

Default HEC

HTTP Event CollectorのInputs列にHECの数が表示されていれば、設定成功です。

the number of HECs

この時点で、HTTP Event CollectorをクリックしてHECの詳細リストに入り、HECのToken情報を確認できます。

HECs Token information

Token Valuesは、上記のDocker環境変数で設定したSPLUNK_HEC_TOKENの値です。

Apache APISIXの設定

splunk-hec-loggingプラグインの有効化

以下のコマンドを実行してsplunk-hec-loggingプラグインを有効にします。

curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
    "plugins":{
        "splunk-hec-logging":{
            "endpoint":{
                // HECエンドポイント
                "uri":"http://127.0.0.1:18088/services/collector",
                // HECトークン
                "token":"BD274822-96AA-4DA6-90EC-18940FB2414C"
            },
            // バッチキューバッファをリフレッシュする最大時間（秒）
            "inactive_timeout":2,
             // バッチキューごとの最大ログエントリ数
            "batch_max_size":10
        }
    },
    "upstream":{
        "type":"roundrobin",
        "nodes":{
            "127.0.0.1:1980":1
        }
    },
    "uri":"/splunk.do"
}'

プラグインパラメータは以下の表で説明されています。

名前	必須	デフォルト値	説明
endpoint	はい	N/A	Splunk HECエンドポイント設定情報
endpoint.uri	はい	N/A	Splunk HECイベント収集API
endpoint.token	はい	N/A	Splunk HEC識別トークン
endpoint.channel	いいえ	N/A	Splunk HEC送信チャネル識別、参照: About HTTP Event Collector Indexer Acknowledgment
endpoint.timeout	いいえ	10	Splunk HECデータ送信タイムアウト（秒）。
ssl_verify	いいえ	TRUE	SSL認証を有効にする、参照: OpenResty Documentation。
max_retry_count	いいえ	0	処理パイプラインから削除される前の最大リトライ回数。
retry_delay	いいえ	1	実行が失敗した場合に処理実行を遅延させる秒数。
buffer_duration	いいえ	60	バッチ内の最古のエントリの最大期間（秒）を最初に処理する必要があります。
inactive_timeout	いいえ	5	バッファをリフレッシュする最大時間（秒）。
batch_max_size	いいえ	1000	バッチキューごとの最大エントリ数。

リクエストの送信

以下のコマンドを実行してSplunkにリクエストを送信します。

$ curl -i http://127.0.0.1:9080/splink.do
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Date: Fri, 10 Dec 2021 09:57:52 GMT
Server: APISIX/2.11.0

Hello, Splunk HEC Logging

ログの確認

Splunkコンソールにログインし、「Search & Reporting」をクリックします。

Splunk console

検索ボックスにsource="apache-apisix-splunk-hec-logging"と入力して、送信されたリクエストログをクエリします。

query the logs

splunk-hec-loggingプラグインの無効化

splunk-hec-logging設定を削除してプラグインを無効にします。

curl http://127.0.0.1:9080/apisix/admin/routes/1  -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
    "uri":"/logging.do",
    "upstream":{
        "type":"roundrobin",
        "nodes":{
            "127.0.0.1:1980":1
        }
    },
    "plugins":{
    }
}'

まとめ

Apache APISIXは現在、より多くのサービスとの統合をサポートするための追加プラグインの開発にも取り組んでいます。興味がある場合は、GitHub Discussionでディスカッションを開始するか、メーリングリストを通じてコミュニケーションを取ってください。