kubesense-spl

KubeSense SPL

KubeSense MCP サーバーが必要です。接続と認証については、kubesense-mcp を参照してください。 このツールは logs モジュールに対する RBAC を解決します。

SPL はログ専用です。 トレースやメトリクス用の SPL はありません。kubesense-traces と kubesense-metrics を使用してください。

ツール

ツール	使用する場面	戻り値
get-trace-or-log-fields (signal: "logs")	動的属性キーを見つける場合 — 列名ではありません。下記を参照してください	対象期間のフィールドカタログ
validate-spl	クエリを渡す前	valid と、コンパイル後の ClickHouse SQL
execute-spl	自分で質問に回答する場合	行（TSV）、最大 1000 件

実行前に検証してください。 SPL のパーサーは、未知のフィールドも未知の関数も受け入れるため、名前が間違っていてもコンパイルされ、実行時に失敗します。その時点では、すでにスキャンのコストが発生しています。 validate-spl はスキャンのコストがかからないため、この順序で組み合わせれば低コストですが、逆の順序では無駄が生じます。

execute-spl には clusters と時間範囲が必要ですが、validate-spl にはどちらも必要ありません。質問を表現できる場合は、search-logs または analyze-logs を優先してください。これらは、SPL エンドポイントでは適用できない名前空間レベルおよびワークロードレベルのアクセスルールを適用します。そのため、スコープが制限されたロールでは、どちらの SPL ツールも一切使用できません。

フィールド名は他のすべてのツールとは逆です

KubeSense の他のすべてのインターフェース — search-logs、analyze-logs、SQL エンドポイント、フィールドカタログ — では、カタログラベルを受け入れ、ストレージ列名を拒否します。SPL はその逆です。

SPL で使用する名前	他のすべてのツールで使用する名前
level	type
pod_name	instance
cluster	domain
container_name（または container）	container
node_name（または node）	node
host	— node_name とは異なる列です。どちらも存在します

SPL が認識する完全な一覧：timestamp（または @timestamp）・body（または @message）・level・ cluster・namespace・workload・pod_name（または @logstream）・container_name（または container）・node_name（または node）・host・service・source・format・env_type・ raw・@loggroup（= workload）。

警告

SPL に region、app_version、instance、type、domain、body_length、kuid はありません。 SPL が認識しない名前はエラーになりません。むき出しの列名として ClickHouse に渡されるため、クエリは解析およびコンパイルを通過し、実行時になって初めて失敗します。

警告

get-trace-or-log-fields は SPL 用としては正しくない名前を返します。 カタログラベルの type、 instance、domain を返しますが、SPL はこれらを受け入れません。動的属性 キーの特定にのみ使用し、それらは log_processed.<key> として指定してください。列については、上の表を使用してください。

動的属性

解析された JSON フィールドには、log_processed. プレフィックスを付けてアクセスします。これは SQL エンドポイントの @attr に相当する SPL の表現です。

filter log_processed.status = "500"
| stats count(*) as errors by log_processed.url

解決の優先順は、文字列属性 → 浮動小数点数属性 → JSON として解析された本文です。

パイプライン

| で区切られたコマンドを左から右へ読みます。

"connection refused"
| filter level = "ERROR" AND namespace = "production"
| stats count(*) as errors by workload
| sort errors desc
| head 20

コマンド： fields · filter（別名は where、search） · parse · rex · eval · stats · timechart · dedup · head · tail · sort · limit · rename · table · top · rare。 引用符で囲まれた単独の文字列はメッセージ本文全体を対象にした全文検索で、最初に指定する必要があります。# で コメントを開始します。

順序には意味があり、見た目だけの問題ではありません。 stats の前にある filter は WHERE になり、同じ filter でも stats の後にある場合は集計結果に対する HAVING になります。

filter level = "ERROR" | stats count(*) as n by workload | filter n > 100

stats / timechart の集計関数： count(*) · sum · avg · min · max · dc （個別カウント） · median · mode · range · stdev · stdevp · var · sumsq · latest · earliest · values · list · perc<N>。

警告

パーセンタイルは perc95(x) であり、p95(x) ではありません。 p95 は関数ではありません。不明なフィールドと同様に、コンパイルは成功して実行時に失敗します。また、KubeSense 独自の SPL マニュアルでも以前は誤った形式がしばらく掲載されていたため、古い例に残っています。

timechart では span=<N><s|m|h|d> を指定し、バケット列の名前は _time になります。

timechart span=5m count(*) as errors by workload

時間範囲はサーバーが管理します

時間範囲とクラスターフィルターはクエリではなく、リクエストに基づいてサーバーが適用します。タイムスタンプ条件は記述しないでください。これは、$__timeFilter(timestamp) が必須となる SQL エンドポイントとは逆です。

必ず検証する

SPL のパーサーは ClickHouse で実行できる範囲を超えて受け入れるため、ここでは validate-spl は形式的な手順ではありません。

間違い	解析できる？	コンパイルできる？	検出方法
filter level =（構文エラー）	✗	—	解析
filter region = "x"（不明なフィールド）	✓	✓	validate-spl のみ
stats p95(x)（不明な関数）	✓	✓	validate-spl のみ
log_processed.typo	✓	✓	なし — null を返す

validate-spl は行をスキャンせずに、実際のログテーブルに照らしてすべての識別子と関数を解決し、コンパイル済み SQL を ## translated_sql の下に返します。必ず確認してください。pod_name が意図した列に解決されたことを確認する方法です。

属性キーだけは確認できません。誤った log_processed.<key> は、SQL 側で誤った @attr を指定した場合とまったく同様に、何も通知せず null を返します。まず get-trace-or-log-fields でキーを確認してください。

制限

• パイプラインの末尾が | head N、| tail N、または | limit N でない限り、最大 1000 行です。
• 読み取り専用です。ファイルシステム、ネットワーク、システム関数は拒否されます。
• 特定のクラスター、名前空間、またはワークロードにスコープが限定されたロールでは利用できません。SPL エンドポイントが適用できるのはクラスターのフィルターのみで、より細かなルールを強制できないためです。search-logs / analyze-logs を使用してください。これらは細かなルールを適用できます。

使用例

ワークロードごとのエラー数を多い順に表示

filter level = "ERROR"
| stats count(*) as errors by workload
| sort errors desc

タイムアウトを見つけて内容を読む

"timeout"
| filter workload = "checkout"
| fields timestamp, pod_name, body
| head 50

名前空間ごとの時間経過に伴うエラー率

filter level = "ERROR"
| timechart span=5m count(*) as errors by namespace

JSON フィールドからレイテンシのパーセンタイルを計算

filter log_processed.duration_ms > 0
| stats perc95(log_processed.duration_ms) as p95, avg(log_processed.duration_ms) as mean by log_processed.route
| sort p95 desc

構造化されていない行からフィールドを抽出

"APICallLogs:"
| parse 'Path:* Method:* StatusCode:*' as path, method, code
| filter code != "200"
| stats count(*) as errors by path, code

ルール

1. カタログ上のラベルではなく、ストレージ上の名前を使います。type ではなく level、instance ではなく pod_name、domain ではなく cluster を使用します。
2. get-trace-or-log-fields は属性キー専用です。列名は SPL 用ではありません。
3. クエリを引き渡す前、または実行する前に validate-spl を呼び出し、返された translated_sql を確認します。
4. p95(x) ではなく、perc95(x) を使用します。
5. 時間やクラスターのフィルターは記述しないでください。どちらもサーバーが適用します。
6. 引用符で囲まれた単独の検索文字列は、パイプラインの先頭に指定します。
7. stats の前の filter は WHERE、stats の後の filter は HAVING になります。
8. 集計は SPL で行います。件数を数えるために生の行を要求しないでください。上限は 1000 行です。
9. 解析済みの JSON フィールドには log_processed.<key> を使います。間違ったキーを指定すると、エラーではなく null が返されます。
10. 対象はログのみです。トレースとメトリクスには SPL がありません。