|
1 | | -# Splunk CLIツール (splunk-cli) |
| 1 | +# splunk-cli |
2 | 2 |
|
3 | | -**splunk-cli**は、SplunkのREST APIと対話するための、Go言語で書かれた強力かつ軽量なコマンドラインインターフェース(CLI)ツールです。ターミナルから直接、またはスクリプト経由で、SPL(Search Processing Language)クエリの実行、検索ジョブの管理、そして結果の取得を効率的に行うことができます。 |
| 3 | +Splunk REST API のパイプ対応 CLI クライアント。SPL 検索の実行、ジョブ管理、結果の取得をターミナルから直接行える。 |
4 | 4 |
|
5 | | -## 主な機能 |
| 5 | +[English README is here](README.md) |
6 | 6 |
|
7 | | -- **自動化**: シェルスクリプトやCI/CDジョブからSplunkの検索をトリガーし、結果を後続の処理に渡すことができます。 |
8 | | -- **効率性**: Web UIを開くことなく、コマンド一つで迅速にデータを確認できます。 |
9 | | -- **柔軟な認証**: コマンドライン引数、環境変数、設定ファイル、そして安全な対話プロンプトと、多様な方法で認証情報を管理できます。 |
10 | | -- **長時間のジョブ管理**: 非同期実行モデル(`start`, `status`, `results`)により、完了までに数時間かかるような重い検索ジョブも、ターミナルを占有することなく管理できます。 |
11 | | -- **Appコンテキスト**: `--app`フラグを使用することで、特定のAppコンテキストで検索を実行でき、Appに閉じたlookupなどを利用できます。 |
| 7 | +## 特徴 |
12 | 8 |
|
13 | | -## インストール |
14 | | - |
15 | | -`splunk-cli`のインストール方法は2つあります。 |
| 9 | +- **同期検索** — `run` でクエリを実行し、完了を待って結果を出力 |
| 10 | +- **非同期検索** — `start` → `status` → `results` で長時間ジョブを管理 |
| 11 | +- **パイプ対応** — JSON 出力を `jq`、`json-to-table` 等と組み合わせ可能 |
| 12 | +- **柔軟な認証** — トークン、ユーザー名/パスワード、環境変数、設定ファイル |
| 13 | +- **App コンテキスト** — `--app` フラグで App 固有のルックアップやナレッジオブジェクトを使用 |
| 14 | +- **Ctrl+C 対応** — 実行中のジョブをキャンセルするかバックグラウンド継続するか選択可能 |
16 | 15 |
|
17 | | -### 1. リリースから(推奨) |
18 | | - |
19 | | -[GitHubリリースページ](https://github.com/magifd2/splunk-cli/releases)から、お使いのOS(macOS, Linux, Windows)に対応したコンパイル済みのバイナリをダウンロードできます。 |
| 16 | +## インストール |
20 | 17 |
|
21 | | -### 2. ソースから |
| 18 | +[リリースページ](https://github.com/nlink-jp/splunk-cli/releases) からビルド済みバイナリをダウンロード。 |
22 | 19 |
|
23 | | -Goがインストールされている環境であれば、ソースコードからビルドすることも可能です。 |
| 20 | +またはソースからビルド: |
24 | 21 |
|
25 | 22 | ```bash |
26 | | -# リポジトリをクローン |
27 | | -git clone https://github.com/magifd2/splunk-cli.git |
| 23 | +git clone https://github.com/nlink-jp/splunk-cli.git |
28 | 24 | cd splunk-cli |
29 | | - |
30 | | -# ビルドを実行 |
31 | 25 | make build |
32 | | - |
33 | | -# 実行ファイルは dist/ ディレクトリに生成されます (例: dist/macos/splunk-cli) |
| 26 | +# バイナリ: dist/splunk-cli |
34 | 27 | ``` |
35 | 28 |
|
36 | | -## 使い方 |
| 29 | +## クイックスタート |
37 | 30 |
|
38 | | -### 設定 |
| 31 | +```bash |
| 32 | +# 認証情報の設定 |
| 33 | +export SPLUNK_HOST="https://your-splunk.example.com:8089" |
| 34 | +export SPLUNK_TOKEN="your-token" |
39 | 35 |
|
40 | | -最も便利な使い方は、設定ファイルを作成することです。 |
| 36 | +# 検索の実行 |
| 37 | +splunk-cli run --spl "index=_internal | head 10" |
41 | 38 |
|
42 | | -**パス**: `~/.config/splunk-cli/config.json` |
| 39 | +# jq にパイプ |
| 40 | +splunk-cli run --spl "index=main | stats count by sourcetype" | jq . |
43 | 41 |
|
44 | | -**内容例**: |
45 | | -```json |
46 | | -{ |
47 | | - "host": "https://your-splunk-instance.com:8089", |
48 | | - "token": "your-splunk-token-here", |
49 | | - "app": "search", |
50 | | - "insecure": true, |
51 | | - "httpTimeout": "60s", |
52 | | - "limit": 100 |
53 | | -} |
| 42 | +# stdin から SPL を読み込み |
| 43 | +cat query.spl | splunk-cli run -f - |
54 | 44 | ``` |
55 | 45 |
|
56 | | -### 設定の優先順位 |
57 | | - |
58 | | -設定は以下の優先順位で評価されます。強いものが優先されます。 |
| 46 | +## 設定 |
59 | 47 |
|
60 | | -1. **コマンドラインフラグ (グローバル)** (例: `--config <path>`) |
61 | | -2. **コマンドラインフラグ (コマンド固有)** (例: `--host <URL>`) |
62 | | -3. **環境変数** (例: `SPLUNK_HOST`, `SPLUNK_APP`) |
63 | | -4. **設定ファイル** |
| 48 | +設定例ファイルをコピー: |
64 | 49 |
|
65 | | -### グローバルフラグ |
| 50 | +```bash |
| 51 | +mkdir -p ~/.config/splunk-cli |
| 52 | +cp config.example.toml ~/.config/splunk-cli/config.toml |
| 53 | +chmod 600 ~/.config/splunk-cli/config.toml |
| 54 | +``` |
66 | 55 |
|
67 | | -これらのフラグはどのコマンドでも使用できます: |
| 56 | +```toml |
| 57 | +# ~/.config/splunk-cli/config.toml |
| 58 | +[splunk] |
| 59 | +host = "https://your-splunk.example.com:8089" |
| 60 | +token = "your-token" |
| 61 | +# app = "search" |
| 62 | +# insecure = false |
| 63 | +# http_timeout = "30s" |
| 64 | +# limit = 0 |
| 65 | +``` |
68 | 66 |
|
69 | | -- `--config <path>`: カスタム設定ファイルへのパス。デフォルトの `~/.config/splunk-cli/config.json` を上書きします。 |
70 | | -- `--version`: バージョン情報を表示して終了します。 |
| 67 | +**優先順位(高い順):** CLI フラグ → 環境変数 → 設定ファイル |
71 | 68 |
|
72 | | -### コマンド一覧 |
| 69 | +| 環境変数 | 説明 | |
| 70 | +|---|---| |
| 71 | +| `SPLUNK_HOST` | Splunk サーバー URL(ポート含む) | |
| 72 | +| `SPLUNK_TOKEN` | Bearer トークン(推奨) | |
| 73 | +| `SPLUNK_USER` | ユーザー名(Basic 認証) | |
| 74 | +| `SPLUNK_PASSWORD` | パスワード(Basic 認証) | |
| 75 | +| `SPLUNK_APP` | 検索の App コンテキスト | |
73 | 76 |
|
74 | | -`splunk-cli`は、タスクに応じたコマンドを提供します。 |
| 77 | +## 使い方 |
75 | 78 |
|
76 | | -#### `run` |
| 79 | +``` |
| 80 | +splunk-cli [command] |
| 81 | +
|
| 82 | +コマンド: |
| 83 | + run SPL 検索を実行し結果を出力(同期) |
| 84 | + start SPL 検索を非同期で開始し SID を出力 |
| 85 | + status 検索ジョブのステータスを確認 |
| 86 | + results 完了した検索ジョブの結果を取得 |
| 87 | +
|
| 88 | +グローバルフラグ: |
| 89 | + -c, --config string 設定ファイルパス(デフォルト: ~/.config/splunk-cli/config.toml) |
| 90 | + --host string Splunk サーバー URL(env: SPLUNK_HOST) |
| 91 | + --token string Bearer トークン(env: SPLUNK_TOKEN) |
| 92 | + --user string ユーザー名(env: SPLUNK_USER) |
| 93 | + --password string パスワード(env: SPLUNK_PASSWORD) |
| 94 | + --app string App コンテキスト(env: SPLUNK_APP) |
| 95 | + --owner string ナレッジオブジェクトオーナー(デフォルト: nobody) |
| 96 | + --limit int 最大結果数(0 = 全件) |
| 97 | + --insecure TLS 証明書検証をスキップ |
| 98 | + --http-timeout duration リクエストごとの HTTP タイムアウト(例: 30s, 2m) |
| 99 | + --debug デバッグログを有効化 |
| 100 | + -v, --version バージョン情報を表示 |
| 101 | +``` |
77 | 102 |
|
78 | | -検索を開始し、完了まで待って結果を表示します。 |
| 103 | +### `run` — 同期検索 |
79 | 104 |
|
80 | | -**使用例**: |
81 | 105 | ```bash |
82 | | -# 過去1時間のデータを10件に絞って検索 |
| 106 | +# 時間範囲を指定して検索 |
83 | 107 | splunk-cli run --spl "index=_internal" --earliest "-1h" --limit 10 |
84 | 108 |
|
85 | | -# ファイルからSPLを読み込んで検索 |
86 | | -cat my_query.spl | splunk-cli run -f - |
87 | | -``` |
| 109 | +# ファイルから SPL を読み込み |
| 110 | +splunk-cli run -f query.spl |
88 | 111 |
|
89 | | -- `--spl <string>`: 実行するSPLクエリ。 |
90 | | -- `--file <path>` / `-f <path>`: SPLクエリをファイルから読み込みます。パスに`-`を指定すると標準入力から読み込みます。 |
91 | | -- `--earliest <time>`: 検索の開始時刻。(-1h, @d, 1672531200など) |
92 | | -- `--latest <time>`: 検索の終了時刻。(now, @d, 1672617600など) |
93 | | -- `--timeout <duration>`: ジョブ全体のタイムアウト時間。(10m, 1h30mなど) |
94 | | -- `--limit <int>`: 最大取得件数 (0を指定すると全件取得)。 |
95 | | -- `--silent`: 進捗メッセージを非表示にします。 |
| 112 | +# stdin から SPL |
| 113 | +echo 'index=main | stats count' | splunk-cli run -f - |
| 114 | + |
| 115 | +# タイムアウト付き |
| 116 | +splunk-cli run --spl "index=main | stats count by host" --timeout 5m |
| 117 | +``` |
96 | 118 |
|
97 | | -> **💡 Ctrl+C の挙動**: `run`の実行中に `Ctrl+C` を押すと、ジョブをキャンセルするか、バックグラウンドで実行し続けるかを選択できます。 |
| 119 | +| フラグ | 説明 | |
| 120 | +|---|---| |
| 121 | +| `--spl <string>` | 実行する SPL クエリ | |
| 122 | +| `-f, --file <path>` | ファイルから SPL を読み込み(`-` で stdin) | |
| 123 | +| `--earliest <time>` | 開始時刻(例: `-1h`, `@d`, エポック) | |
| 124 | +| `--latest <time>` | 終了時刻(例: `now`, `@d`, エポック) | |
| 125 | +| `--timeout <duration>` | ジョブ全体のタイムアウト(例: `10m`, `1h`) | |
| 126 | +| `--limit <int>` | 最大結果数(0 = 全件) | |
| 127 | +| `--silent` | 進行状況メッセージを抑制 | |
98 | 128 |
|
99 | | -#### `start` |
| 129 | +> **Ctrl+C**: `run` 実行中に Ctrl+C を押すと、ジョブのキャンセルまたはバックグラウンド継続を選択できます。 |
100 | 130 |
|
101 | | -検索ジョブを開始し、ジョブID (SID) のみを標準出力に表示して即座に終了します。 |
| 131 | +### `start` — 非同期検索 |
102 | 132 |
|
103 | | -**使用例**: |
104 | 133 | ```bash |
105 | | -export JOB_ID=$(splunk-cli start --spl "index=main | stats count by sourcetype") |
106 | | -echo "Job started with SID: $JOB_ID" |
| 134 | +JOB_ID=$(splunk-cli start --spl "index=main | stats count by sourcetype") |
| 135 | +echo "Started: $JOB_ID" |
107 | 136 | ``` |
108 | 137 |
|
109 | | -#### `status` |
| 138 | +### `status` — ジョブステータス確認 |
110 | 139 |
|
111 | | -指定したSIDのジョブの状態を確認します。 |
112 | | - |
113 | | -**使用例**: |
114 | 140 | ```bash |
115 | 141 | splunk-cli status --sid "$JOB_ID" |
116 | 142 | ``` |
117 | 143 |
|
118 | | -#### `results` |
119 | | - |
120 | | -完了したジョブの結果を取得します。`jq`のようなツールと組み合わせると便利です。 |
| 144 | +### `results` — ジョブ結果取得 |
121 | 145 |
|
122 | | -**使用例**: |
123 | 146 | ```bash |
124 | | -# 指定したジョブの結果を50件まで取得 |
125 | 147 | splunk-cli results --sid "$JOB_ID" --limit 50 --silent | jq . |
126 | 148 | ``` |
127 | 149 |
|
128 | | -- `--sid <string>`: ジョブの検索ID (SID)。 |
129 | | -- `--limit <int>`: 最大取得件数 (0を指定すると全件取得)。 |
130 | | - |
131 | | -### 共通フラグ |
| 150 | +## ビルド |
132 | 151 |
|
133 | | -ほとんどのコマンドで利用できる共通フラグです。 |
134 | | - |
135 | | -- `--host <url>`: SplunkサーバーのURL。 |
136 | | -- `--token <string>`: 認証トークン。 |
137 | | -- `--user <string>`: ユーザー名。 |
138 | | -- `--password <string>`: パスワード(指定しない場合はプロンプトで入力を求められます)。 |
139 | | -- `--app <string>`: 検索を実行するAppのコンテキスト。 |
140 | | -- `--owner <string>`: App内のナレッジオブジェクトの所有者。デフォルトは`nobody`。 |
141 | | -- `--limit <int>`: 最大取得件数 (0を指定すると全件取得)。デフォルトは0(全件取得)です。 |
142 | | -- `--insecure`: TLS証明書の検証をスキップします。 |
143 | | -- `--http-timeout <duration>`: 個々のAPIリクエストのタイムアウト時間。(30s, 1mなど) |
144 | | -- `--debug`: 詳細なデバッグ情報を表示します。 |
145 | | -- `--version`: バージョン情報を表示します。 |
146 | | - |
147 | | -## 開発 |
148 | | - |
149 | | -このプロジェクトは、共通の開発タスクに `Makefile` を使用しています。 |
| 152 | +```bash |
| 153 | +make build # 現在のプラットフォーム → dist/splunk-cli |
| 154 | +make build-all # 全プラットフォーム → dist/ |
| 155 | +make test # ユニットテスト |
| 156 | +make check # vet → lint → test → build |
| 157 | +make integration-test # 統合テスト(Podman + Splunk コンテナが必要) |
| 158 | +make splunk-down # Splunk テストコンテナを停止 |
| 159 | +make clean # dist/ を削除 |
| 160 | +``` |
150 | 161 |
|
151 | | -- `make build`: 全てのターゲットプラットフォーム(macOS, Linux, Windows)のバイナリをビルドします。 |
152 | | -- `make test`: テストを実行します。 |
153 | | -- `make lint`: リンター(`golangci-lint`)を実行します。 |
154 | | -- `make vulncheck`: 既知の脆弱性をスキャンします(`govulncheck`)。 |
155 | | -- `make clean`: ビルド成果物を削除します。 |
| 162 | +詳細は [BUILD.md](BUILD.md) を参照。 |
156 | 163 |
|
157 | 164 | ## ライセンス |
158 | 165 |
|
159 | | -このプロジェクトは **MIT License** の下で公開されています。詳細は [LICENSE](LICENSE) ファイルをご覧ください。 |
160 | | - |
161 | | ---- |
162 | | - |
163 | | -*このツールは、Googleの大規模言語モデルであるGeminiとの対話を通じて初期構築および開発されました。* |
| 166 | +MIT License — [LICENSE](LICENSE) を参照。 |
0 commit comments