cel-programs

cel-programs

使用する場合

以下のタスクでは、このスキルを使用してください。

• エージェントストリームテンプレート cel.yml.hbs の作成または編集
• cel 入力タイプのデータストリームマニフェストの設定
• ページネーション、カーソル管理、認証を含む CEL プログラムの作成
• mito を使った CEL プログラムのローカルテストまたはデバッグ
• CEL ベースのデータストリーム用のモック API を使ったシステムテストの設定
• 新しい CEL ベースのデータストリームの収集ロジックのプロトタイプ作成
• コンテキストを問わず、CEL または mito に関する質問

使用しない場合

以下の作業の主なガイドとして、このスキルを使用しないでください。

• インジェストパイプラインプロセッサーの設計（ingest-pipelines）
• ECS フィールドのマッピング（ecs-field-mappings）
• パッケージのスキャフォールディング（create-integration）
• Elastic スタックを使ったシステムテストの実行（integration-testing → references/system-testing.md）

必須のワークフロー — モック → mito → テンプレート

これは提案ではありません。すべての CEL プログラムは、必ずこの順序で開発してください。 mito を実行中のモックに対して使用し、CEL プログラムを検証するまで、サブエージェントは cel.yml.hbs を書いてはいけません。手順を省略したり順序を入れ替えたりすると、デバッグが非常に難しい障害につながります。

mito を実行する前に、新しい CEL コードを約 10～15 行以上書かないでください。 プログラムはフェーズごとに段階的に構築してください（スケルトン → エラー処理 → イベントマッピング → ページネーション → カーソルガード）。各フェーズの後に mito で検証します。プログラムを一度に大量に書くと、連鎖的なコンパイルエラーが発生し、デバッグが非常に難しくなります。references/cel-incremental-build.md の段階的なアプローチに従ってください。

手順	作業	出力
1. システムテスト用モックを作成する	_dev/deploy/docker/files/config-<stream>.yml に、すべての API エンドポイントに一致するルールを含む elastic/stream 設定を記述します。test-default-config.yml を記述します。	モック設定ファイル、docker-compose サービス、テスト設定
2. モックをローカルで起動する	stream http-server --addr=:8090 --config=...	http://localhost:8090 で実行中のモック
3. プレーンな .cel ファイルと state.json を作成する	CEL プログラムをスタンドアロンの .cel ファイルとして記述します。将来の state: ブロックに含まれるものと同じキーを使い、Handlebars の代わりにテスト用のリテラル値を設定した state.json を作成します。url はローカルモックを指定します。	/tmp または作業ディレクトリ内の program.cel、state.json
4. mito を実行して反復する	references/cel-incremental-build.md に従って段階的に構築します。フェーズ 0：スケルトン → フェーズ 1：エラー処理 → フェーズ 2：イベント → フェーズ 3：ページネーション → フェーズ 4：カーソル。各フェーズの後に mito -data state.json -log_requests program.cel を実行します。mito の出力が正しくなるまで先に進まないでください。	検証済みの CEL プログラム
5. その後に限り cel.yml.hbs を記述する	動作する CEL 式を Handlebars テンプレート内の program: | にコピーします。テスト用のリテラル値を {{var}} 参照に置き換えます。マニフェストを設定します。	最終的なインテグレーションテンプレート

手順 3 の詳細 — テンプレート変数を mito の state に変換する： 将来の cel.yml.hbs に api_key: {{api_key}} や batch_size: {{batch_size}} のような state: ブロックが含まれる場合、mito テスト用の state.json では、同じキー名にテスト用のリテラル値を設定します。

{
  "url": "http://localhost:8090",
  "api_key": "test-key",
  "batch_size": 50,
  "initial_interval": "24h"
}

これは、CEL 入力が実行時に提供する state を再現します。後続の実行時の動作をテストするには、cursor を追加します。

モックを最初に用意するワークフローの詳細、CLI フラグ、実行モデル、品質基準については、references/mito-reference.md を読み込んでください。

---

cel.yml.hbs テンプレートの構成

data_stream/<stream>/agent/stream/cel.yml.hbs にある cel.yml.hbs ファイルは、最終的な CEL 入力設定を生成する Handlebars テンプレートです。以下のセクションがこの順番で含まれています。

interval: {{interval}}
resource.tracer:
  enabled: {{enable_request_tracer}}
  filename: "../../logs/cel/http-request-trace-*.ndjson"
  maxbackups: 5
{{#if proxy_url}}
resource.proxy_url: {{proxy_url}}
{{/if}}
{{#if ssl}}
resource.ssl: {{ssl}}
{{/if}}
{{#if http_client_timeout}}
resource.timeout: {{http_client_timeout}}
{{/if}}
resource.url: <constructed from vars>
state:
  <credentials and pagination config from vars>
redact:
  fields:
    - <sensitive state keys>
max_executions: <number, for heavy pagination>
program: |
  <CEL expression>
tags:
{{#if preserve_original_event}}
  - preserve_original_event
{{/if}}
{{#each tags as |tag|}}
  - {{tag}}
{{/each}}
{{#contains "forwarded" tags}}
publisher_pipeline.disable_host: true
{{/contains}}
{{#if processors}}
processors:
{{processors}}
{{/if}}

Handlebars パターン

パターン	目的
{{var_name}}	変数を直接置換
{{#if var_name}}...{{/if}}	オプション設定用の条件ブロック
{{#each tags as |tag|}}	リスト変数の反復処理
{{#contains "forwarded" tags}}	リストに値が含まれているかを確認

テンプレートの主なフィールド

• resource.url — ベース URL。複数の変数から構成されることがよくあります（例：{{url}}/api/v1/endpoint）
• resource.headers（ga 8.18.1）— すべてのリクエストで共通の静的ヘッダー（Content-Type、Accept、API バージョンヘッダー）。ヘッダーが変化しない場合は、プログラム内ではなくここに設定します。認証ヘッダーより前に適用されます。
• state: — マニフェスト変数が CEL の状態として注入されるブロックです。認証情報やページネーション設定をここに指定します。
• redact.fields — デバッグログでマスクする、シークレットを含む状態キーのリストです。
• max_executions — ページネーションが多いインテグレーション向けに、デフォルトの 1000 を上書きします（例：5000）。
• program: | — CEL 式です。YAML のリテラルブロックスカラーで指定する必要があります。

インテグレーションパッケージでは data_stream.dataset を設定しないでください

インテグレーションパッケージ（type: integration）では、cel.yml.hbs に data_stream.dataset を決して含めず、data_stream.dataset マニフェスト変数も定義しないでください。フレームワークがドキュメントを適切なデータストリームに自動的にルーティングします。data_stream.dataset を設定すると、このルーティングが上書きされ、ドキュメントが誤ったインデックスに格納されます。通常、システムテストで「0 hits」になります。

data_stream.dataset を使用するのは、事前定義されたデータストリームがない入力タイプのパッケージ（type: input）だけです。

データストリームのマニフェスト設定

データストリームの manifest.yml では、CEL 入力ストリームとその変数を定義します。

すべての CEL ストリームに含める標準変数

変数	型	用途
url	text	API のベース URL
interval	text	ポーリング間隔（例：5m）
initial_interval	text	初回実行時の遡及期間（例：24h）
enable_request_tracer	bool	HTTP リクエストのトレースを有効にします
http_client_timeout	text	リクエストのタイムアウト（例：30s）
proxy_url	text	HTTP プロキシ URL
ssl	yaml	TLS 設定
tags	text (multi)	イベントタグ
preserve_original_event	bool	元のイベントを保持します
processors	yaml	Beat プロセッサー

認証に関する変数は API によって異なります（API キー、OAuth の client_id／secret／token_url、ベアラートークンなど）。

enable_request_tracer は入力レベルではなく、データストリームのマニフェストで宣言してください。入力レベルのトレースを有効にすると、ポリシー内のすべてのデータストリームでログが有効になります。

パッケージレベルの変数とデータストリームレベルの変数

• ルート manifest.yml の policy_templates[].inputs[].vars にあるパッケージレベルの変数：ストリーム間で共有されます（例：url、認証情報）。
• data_stream/<stream>/manifest.yml の streams[].vars にあるデータストリームレベルの変数：ストリーム固有です（例：interval、batch_size、initial_interval）。

CEL プログラムの範囲

CEL プログラムの役割は、データ収集のみです。

1. API エンドポイントからデータを取得する
2. ページネーションを処理する — 1 回のポーリングサイクル内にすべてのページをたどる
3. カーソル状態を管理する — タイムスタンプやページトークンを cursor に保存し、次のポーリング間隔で前回の続きから再開できるようにします。これにより、取得済みのイベントを再収集しないようにします。
4. 生イベントを出力する — 各レコードについて {"message": e.encode_json()} を出力する

CEL プログラムでは、以下を処理しません。

• Elasticsearch レベルの重複排除 — 時間範囲の重複によって少数のイベントが重複して収集されても問題ありません。重複排除は CEL プログラムではなく、インジェストパイプラインまたは Elasticsearch の _id ルーティングがインデックス作成時に処理します。
• フィールドのマッピングや変換 — 解析、ECS マッピング、エンリッチメントはインジェストパイプラインが処理します。
• コンテンツによるフィルタリング — API がサーバー側のフィルタリングパラメーターに対応している場合を除き、CEL プログラム内でイベントをフィルタリングしないでください。すべてを出力し、パイプラインに判断させます。

_id、document_id、重複排除のパターンをコードベースで検索しないでください。これらは CEL の対象ではありません。

CEL プログラムの構造パターン

ページネーション戦略の選択

API の動作	パターン	主な指標
合計件数を返し、オフセットに対応	オフセットページネーション	リクエスト／レスポンス内の total_count、offset、limit
タイムスタンプ以降のレコードを返す	タイムスタンプカーソル	時間範囲パラメーターがあり、明示的なページトークンがない
次の URL を含む Link ヘッダーを返す	Link ヘッダー	レスポンスヘッダー内の Link: <url>; rel="next"
レスポンス本文に次ページの URL を返す	次 URL	JSON の next、nextLink、@odata.nextLink フィールド
pageInfo を使用する GraphQL	GraphQL カーソル	pageInfo オブジェクト内の hasNextPage、endCursor
複数段階のサブスクリプション／コンテンツフロー	複数ステップのステートマシン	状態内の作業キューを使った複数の API 呼び出し

カーソルのタイムスタンプ選択 — API が昇順でソートする場合は最後のレコードのタイムスタンプを使用します。降順の場合は最初のレコードを使用し、ソート順が保証されない場合は回帰ガード付きで max() を使用します。

各パターンの完全なコード、パッケージ参照、YAML スニペットについては、references/cel-pagination-patterns.md を参照してください。

認証パターン

3 つの方法があります。ヘッダー（認証情報を state: に保存し、Header マップで渡す）、クエリパラメーター（.format_query() で認証情報を URL に追加する）、署名付きクエリ（CEL で HMAC 署名を計算する）です。設定レベルの auth.oauth2／auth.digest／auth.aws は .do_request() を含むすべてのリクエストに適用されます。auth.basic／auth.token は直接呼び出す場合（get()、post()）にのみ適用されます。プログラム内でトークンを取得するよりも、入力レベルの認証を優先してください。

完全なコード例、オプションのヘッダー構文、設定レベルの認証の適用範囲の詳細については、references/cel-auth-patterns.md を読み込んでください。

状態管理ルール

1. state.url は resource.url 設定から設定されます。出力に含めるか、ハードコードする必要があります
2. cursor は入力の再起動をまたいで永続化される唯一の状態です。ページネーション位置とタイムスタンプはここに保存してください
3. events 配列は評価のたびに削除されます。後続の実行で依存しないでください
4. want_more: true は即時に再評価を行いますが、events が空でない場合に限ります。ページネーション継続のガードレール： 次ページのカーソル／トークンが存在する場合、現在のページで収集したイベント数にかかわらず、必ず want_more: true を設定してください。want_more を size(events) > 0 に結び付けると、ページネーションがひそかに停止します。次のカーソルは有効であり、空の events 配列を出力しても問題ありません。正しいパターンは "want_more": next_cursor != "" です。
5. その他すべての状態キー はセッション内で保持されますが、再起動時に失われます。自動的に引き継ぐには state.with() を使用してください
6. 数値 は状態 JSON 内で浮動小数点数としてシリアライズされます。整数として使用する場合は int() でキャストしてください
7. state.?cursor.last_timestamp.orValue(default) を使ってオプショナルアクセスすると、カーソルがない場合のエラーを防げます
8. シークレット — state 内の機密フィールドには、それぞれ対応する redact エントリーが必要です。state.secret は常に自動でマスキングされます。secret_state が利用可能な場合（v8.19.14 / v9.2.8 / v9.3.3 / v9.4.0）は、そちらを優先してください。
9. カーソルの更新にはイベントの公開が必要です — 入力がカーソルの更新を永続化するのは、少なくとも1つのイベントが公開された場合のみです。プログラムがカーソルを更新しても、イベントを0件返した場合、そのカーソル変更は失われます。
10. リクエスト／レスポンス処理を分岐間で重複させないでください — 初期化分岐（カーソル作成、サブスクリプション、トークン交換）と定常状態分岐の両方で同じフェッチ処理が必要な場合は、共通化してください。2つの方法があります。want_more: true を使って初期化を別の評価に分ける方法（Technique 6 Variant A）と、中間結果マップを使って1回の評価内で分岐を統合する方法（Variant B）です。どちらも有効です。references/cel-code-style.md の Technique 6 と、references/cel-pagination-patterns.md の初期化後に定常状態へ移行するパターンを参照してください。
11. ネストの深さ — いずれの実行パスでも、.as() チェーンの深さは5レベルを超えてはいけません。HTTP プログラムは state.with() 内を2レベル（resp と body）にしてください。カーソルのデフォルト値、ウィンドウ境界、ページトークンは、state.with() の前に事前バインディングとして抽出してください。int(state.batch_size) のような単一使用の値は、.as() でラップせず、呼び出し箇所にインラインで記述してください。平坦化のテクニックと変更前後の例については、references/cel-code-style.md を読み込んでください。

マップのマージとフィールドの削除

with()、with_replace()、with_update()、drop() は汎用的なマップ操作です。状態やカーソルだけでなく、あらゆるマップで使用できます。with() は浅いマージを行い、ネストしたオブジェクトは全体が置き換えられます。そのため、カーソル状態の遷移（サブオブジェクトを省略すると上書きによって削除されます）だけでなく、リクエストヘッダーの構築、レスポンスデータの変換、中間マップの作成にも利用できます。詳細な動作と例については references/cel-code-style.md を参照してください。

イベント出力形式

イベントには "message" だけを含めてください — {"message": e.encode_json()}。@timestamp やその他のフィールドを設定しないでください。フレームワークが @timestamp を追加するため、重複すると ES 9.x でドキュメントがひそかに拒否されます。正しい例と誤った例については references/cel-idioms.md を参照してください。

レスポンス処理

resp.Body.decode_json() — 古いランタイムバージョンでは bytes(resp.Body) でラップする必要がありましたが、現在は不要です。resp.Body.decode_json() を直接使用してください。

エラー処理

すべての CEL プログラムで HTTP エラーを処理する必要があります。形式は 2 種類あります。

• 単一オブジェクトのエラー（再試行）： "events": {"error": {...}} — ERROR レベルでログを記録し、ステータスを縮退状態に設定して、カーソルを削除します。これにより、次回の評価で再試行されます。データを収集できなかった場合に使用します。
• 配列のエラー（続行）： "events": [{"error": {...}}] — カーソルは更新されます。エラーを過ぎて続行する場合に使用します。取り込みパイプラインに terminate プロセッサーが必要です（ES 8.16.0 以降）。

エラーメッセージの形式："METHOD path: body-or-status"。コード例：references/cel-idioms.md。

プレースホルダーイベント

実際のイベントがない状態でカーソルを進める場合は、プレースホルダー（[{"retry": true}]）を出力し、processors: セクションに - drop_event.when.equals.retry: true のエントリーを追加して、インデックス作成前に破棄されるようにします。パターン全体と代替方法については、references/cel-idioms.md を参照してください。

レート制限と再試行

CEL プログラムにレート制限や再試行ロジックを実装しないでください。 rate_limit() の呼び出し、"rate_limit" の状態伝播、429 専用の分岐、再試行ループは使用しないでください。これらは、わずかな効果に対してネストや複雑さが過剰になります。

API にレート制限が明記されている場合は、cel.yml.hbs に設定のみの YAML 設定を使用します。

resource.rate_limit.limit: 10   # max requests per second
resource.rate_limit.burst: 5    # max burst above sustained rate

カスタムの再試行動作が必要な場合は、設定のみの YAML 設定を使用します。

resource.retry.max_attempts: 5    # default: 5
resource.retry.wait_min: 1s       # default: 1s
resource.retry.wait_max: 60s      # default: 60s

入力フレームワークが、どちらも透過的に適用します。これらの設定を追加するタイミングについては、references/cel-rate-limiting.md のガイダンスを参照してください。

型安全性

dyn() は避けてください — 型チェックが無効になります。実際にはほとんど必要ありません。

すべての数値は float64 です — CEL 入力では、すべての数値が float64 として送信されます。1e7 以上の数値は、Elasticsearch で科学表記になります。整数として扱うフィールドは、CEL プログラムまたは取り込みパイプラインで文字列に変換してください。安全な整数の範囲：[−(2^53 − 1)、2^53 − 1]。

デバッグ支援機能

• debug(tag, value) — DEBUG レベルで cel_debug にログを記録します。
• try(expr) / is_error(value) — プログラムをクラッシュさせずに構造化されたエラー処理を行います。
• failure_dump（ga 8.18.0）— 失敗時に評価状態全体をダンプします。注：ダンプに秘密情報が含まれる場合があります。
• remaining_executions（ga 9.2）— max_executions の予算内で残っている評価回数です。

---

Mito CLI

Mito（github.com/elastic/mito）は、ローカルで CEL を評価する CLI です。mito でテストされていない CEL プログラムは受け入れられません。 このスキルの冒頭にある必須ワークフロー（モック → mito → テンプレート）に従ってください。プログラムが mito の検証に合格するまで、cel.yml.hbs を作成しないでください。

インストール方法、CLI フラグ、入力状態の構造、実行モデル、モック優先のワークフロー全手順、mito と統合テストの対応関係、品質基準については、references/mito-reference.md を読み込んでください。

---

データの匿名化

リポジトリにコミットするすべてのデータは、完全に匿名化する必要があります。 これには、マニフェスト変数のデフォルト値（https://api.example.com を使用）、CEL 状態の例示値、モック API 応答、CEL 出力から作成したパイプラインテスト用フィクスチャ、mito のプロトタイプ作成時に取得したサンプルペイロードが含まれます。

匿名化ポリシー全体とプレースホルダーの規則については、anonymize-logs スキルを参照してください。

他のスキルへの引き継ぎ

• integration-testing → references/system-testing.md でシステムテストを実施します（モック API は CEL 開発時にすでに用意されています）
• integration-testing → references/pipeline-testing.md で CEL が生成したイベントに対する取り込みパイプラインの動作を検証します
• create-integration スキルでパッケージ全体のレイアウトを確認します

参考ファイル

重要：これらの参考ファイルには、実際に動作するコード例とパターンが含まれています。上記の概要だけでは、正しい CEL プログラムを書くには不十分です。コードを書く前に、関連する参考資料を必ず読み込んでください。

CEL プログラムを作成する際は、次の 5 つを必ずこの順序で読み込んでください（テンプレートより先にモックと mito を確認します）。

ファイル	内容	読み込み順
references/cel-system-tests.md	elastic/stream を使用したモック API のセットアップ、docker-compose の設定、ルール形式、変数キャプチャのパターン、GraphQL モックの例、hit_count の計算、ヒット数が 0 件になるエラーのデバッグ	1 番目 — CEL を記述する前に必要です
references/cel-incremental-build.md	必須の段階的なビルド手順（骨組み → エラー処理 → イベント → ページネーション → カーソル）、コンパイルエラーの原因となる構文のアンチパターン（bytes()、parse_time()、タプル、対応していない括弧）、デバッグのガイダンス	2 番目 — この段階的な手順に必ず従ってください。骨組みを検証する前にプログラム全体を書いてはいけません
references/mito-reference.md	Mito の CLI フラグ、入力状態の構造、モック優先のワークフロー、テンプレート変数から state.json への変換、拡張ライブラリのクイックリファレンス、構文上の注意点、testscript ハーネス	3 番目 — プログラムの開発と検証に必要です
references/cel-template-examples.md	対応するマニフェスト設定を含む、動作する cel.yml.hbs の完全な例（最小限の GET、タイムスタンプカーソルによるページネーション、OAuth、GraphQL カーソル） — これらは最終出力です。mito の検証に合格するまでテンプレートを書かないでください	4 番目 — ワークフローのステップ 5 でのみ必要です
references/cel-code-style.md	ネストの規律：HTTP コアの 3 階層ルール、6 つのフラット化／構造化テクニック（共有ロジックのための中間結果マップを含む）、浅いマージのセマンティクス、clobber によるカーソルの名前空間化、マージ戦略（with／with_replace／with_update）、drop()、適切に構造化された参考インテグレーションへのリンク — 複数行の CEL を書く前に必ず読むこと	5 番目 — 構造を最初から正しくするため、CEL プログラムを書く前に読んでください

タスクに応じて、以下を読み込みます：

ファイル	読み込むタイミング
references/cel-pagination-patterns.md	ページネーションロジックを書く場合（コード付きの6つのパターンすべて）
references/cel-auth-patterns.md	認証を実装する場合（ヘッダー、クエリパラメーター、署名、設定レベルの認証パターン）
references/cel-rate-limiting.md	レート制限ポリシーを決める場合（設定のみで対応する方法、resource.rate_limit.* と resource.retry.* の設定を追加するタイミング）
references/cel-idioms.md	よく使うイディオム、HTTP リクエストのパターン、構造上の規約をすばやく確認する場合
references/cel-polymorphic-patterns.md	認証、ヘッダー、レート制限について、純粋な CEL、mito ライブラリ、設定のいずれを使うか選択する場合（バージョンタグ付き）
references/cel-expression.md	式固有のリファレンス（インターフェースの契約、変換の指針（Python→CEL）、段階的なビルドフェーズ、コア構造、イベント出力、エラー処理、ページネーション、状態管理、構文規則、品質チェックリスト）
references/cel-taxonomy.md	分類体系の確認（ページネーションと状態管理のクラス、複雑性を最小限に抑える原則、スキルの用語への対応付け、test-api.py から分類する方法）
references/cel-complexity-baselines.md	ceplx による316個のプログラム調査に基づく、パターンクラスごとの複雑性ベースライン、スキップのしきい値、レビュアーによる異議申し立ての例、診断結果の解釈
references/expression-builder-subagent-guidance.md	cel-expression-builder のサブエージェント運用マニュアル。test-api.py を検証済みの .cel ファイルと分類結果に変換します。テンプレート、マニフェスト、モックには触れません。
references/reviewer-subagent-guidance.md	cel-expression-reviewer のサブエージェント運用マニュアル。生成された CEL を複雑性ベースラインおよびソースへの忠実性に照らして確認し、具体的な異議を示すか、承認します。
references/cel-function-reference.md	拡張ごとに利用可能な CEL 関数と、それぞれが最初に導入された mito のバージョンを調べる場合
references/builder-subagent-guidance.md	cel-program-builder オーケストレーターのサブエージェント運用マニュアル。担当範囲、スキルの読み込み順序、モック完全性ゲートを含むモック優先・mito 段階的導入の9ステップのワークフロー、cel-expression-builder への委任、報告の契約を記載しています。オーケストレーターはタスクプロンプトでこのファイルのパスを渡してサブエージェントを起動します。サブエージェントは新しいコンテキストで自身がこのファイルを読み込みます。この内容をタスクプロンプトに埋め込んだり、貼り付けたりしないでください。

関連項目：CEL 入力ドキュメント · Mito ライブラリのドキュメント · Mito リポジトリ · CEL 言語仕様