fluentbit-generator

Fluent Bit 設定ジェネレーター

トリガーガイダンス

ユーザーから次のいずれかを依頼された場合に、このスキルを使用します。

• Fluent Bit の設定（fluent-bit.conf、parsers.conf）を作成または更新する
• ログパイプライン（INPUT -> FILTER -> OUTPUT）を構築する
• メタデータの拡充を伴う Kubernetes ロギングを設定する
• ログ／メトリクスを Elasticsearch、Loki、CloudWatch、S3、Kafka、OTLP、または Prometheus remote write に送信する
• パーサー、複数行、lua、またはストリーム処理の動作を実装する

検証のみの依頼には、このスキルを使用しないでください。その場合は fluentbit-validator を使用してください。

実行フロー

次の順序に正確に従ってください。ステージを省略しないでください。

ステージ 1：作業コンテキストの設定と事前確認

次の決定的なコマンドパターンのいずれかを使用します。

# Option A (recommended): run from this skill directory
cd /Users/akinozer/GolandProjects/cc-devops-skills/devops-skills-plugin/skills/fluentbit-generator
python3 scripts/generate_config.py --help

# Option B: run from any cwd with absolute paths
python3 /Users/akinozer/GolandProjects/cc-devops-skills/devops-skills-plugin/skills/fluentbit-generator/scripts/generate_config.py --help

事前確認：

• python3 が使用可能であることを確認します。
• スクリプトのヘルプがエラーなく読み込まれることを確認します。
• 相対出力パスを使用する場合は、意図した対象の cwd から実行します。

フォールバック：

• python3 またはスクリプトを実行できない場合は、examples/ のテンプレートを使用する手動生成フロー（ステージ 4）に切り替えます。

ステージ 2：確認事項への質問（明示的なテンプレート）

生成前に、次の項目を確認します。

必須の質問：

1. 主な用途は何ですか？ kubernetes、application logs、syslog、http ingest、metrics、または custom のいずれですか？
2. 入力：ソースとパス／ポートは何ですか（例：tail /var/log/containers/*.log）？
3. 出力：宛先プラグインとエンドポイント（ホスト、ポート、uri/topic/index/bucket）は何ですか？
4. 信頼性／セキュリティ要件：TLS の有効／無効、再試行の要件、バッファリングの上限はどうしますか？
5. 環境コンテキスト：クラスター名、環境名、クラウドリージョン（該当する場合）は何ですか？

任意ですが重要な質問：

1. 想定するログ形式は何ですか？ json、regex、cri、docker、複数行のスタックトレースなどがあります。
2. スループットのプロファイルはどうしますか？ 低／中／高のいずれで、許容できるレイテンシはどの程度ですか？
3. 制約はありますか？ オフライン環境、バイナリの不足、読み取り専用ファイルシステムなどがあります。

必須の回答が不足している場合は、生成前に要点を絞った追加質問をしてください。

ステージ 3：スクリプト生成と手動生成の選択

次の判断表を使用します。

条件	選択肢
リクエストが組み込みの用途に該当し、サポートされているフラグだけで対応できる	スクリプトを使用（ステージ 5）
スクリプトのフラグに含まれない、一般的でないプラグインオプションが必要	手動生成（ステージ 4）
複雑な複数フィルターチェーン、カスタムパーサー／lua ロジック、または特殊なプラグイン調整が必要	手動生成（ステージ 4）
環境内でスクリプトを実行できない（Python／権限の不足）	手動生成（ステージ 4）
ユーザーが手作業で設定を作成するよう明示的に依頼している	手動生成（ステージ 4）

スクリプトでサポートされている用途：

• kubernetes-elasticsearch
• kubernetes-loki
• kubernetes-cloudwatch
• kubernetes-opentelemetry
• application-multiline
• syslog-forward
• file-tail-s3
• http-kafka
• multi-destination
• prometheus-metrics
• lua-filtering
• stream-processor
• custom

どちらを選択したか、また、もう一方の選択肢を使用しなかった理由を必ず明示してください。

ステージ 4：手動生成（スクリプトが最適でない場合）

1. まず、examples/ にある最も近いテンプレートを読みます。
2. 新しいパーサーを定義する前に、examples/parsers.conf を読みます。
3. 次の順序で設定を組み立てます。

• [SERVICE]
• [INPUT]
• [FILTER]
• [OUTPUT]
• パーサー定義（必要な場合）

4. サンプルにある、正常に動作することが確認済みのセクションを再利用し、必要なパラメーターのみをカスタマイズします。
5. セクション間でタグとパーサーの参照に一貫性を保ちます。

必須のローカルテンプレート選択：

• Kubernetes + Elasticsearch：examples/kubernetes-elasticsearch.conf
• Kubernetes + Loki：examples/kubernetes-loki.conf
• Kubernetes + CloudWatch：examples/cloudwatch.conf
• Kubernetes + OpenTelemetry：examples/kubernetes-opentelemetry.conf
• アプリケーションの複数行ログ：examples/application-multiline.conf
• Syslog 転送：examples/syslog-forward.conf
• ファイルから S3：examples/file-tail-s3.conf
• HTTP から Kafka：examples/http-input-kafka.conf
• 複数の宛先：examples/multi-destination.conf
• メトリクス：examples/prometheus-metrics.conf
• Lua フィルタリング：examples/lua-filtering.conf
• ストリームプロセッサー：examples/stream-processor.conf
• パーサー：examples/parsers.conf

フォールバック：

• 一致するサンプルがない場合は、scripts/generate_config.py --use-case custom の出力形式をベースにして、手動で拡張します。

ステージ 5：スクリプト生成コマンド（決定論的なサンプル）

出力パスが絶対パスでない場合は、スキルディレクトリから実行します。

cd /Users/akinozer/GolandProjects/cc-devops-skills/devops-skills-plugin/skills/fluentbit-generator

# Kubernetes -> Elasticsearch
python3 scripts/generate_config.py \
  --use-case kubernetes-elasticsearch \
  --cluster-name prod-cluster \
  --environment production \
  --es-host elasticsearch.logging.svc \
  --es-port 9200 \
  --output output/fluent-bit.conf

# Kubernetes -> OpenTelemetry
python3 scripts/generate_config.py \
  --use-case kubernetes-opentelemetry \
  --cluster-name prod-cluster \
  --environment production \
  --otlp-endpoint otel-collector.observability.svc:4318 \
  --output output/fluent-bit-otlp.conf

# File tail -> S3
python3 scripts/generate_config.py \
  --use-case file-tail-s3 \
  --log-path /var/log/app/*.log \
  --s3-bucket my-logs-bucket \
  --s3-region us-east-1 \
  --output output/fluent-bit-s3.conf

フォールバック：

• スクリプトで必須オプションがサポートされていない場合は、その不足点を記録してステージ 4 に切り替えます。

ステージ 6：プラグインのドキュメントを検索する際のフォールバック順序

プラグインの動作やパラメーターが不明な場合は、次の順序を厳守します。

1. Context7（最初に使用）

• Fluent Bit のドキュメントのライブラリー ID を解決します。
• プラグイン固有の設定詳細を照会します。

2. Fluent Bit 公式ドキュメント（2 番目に使用）

• https://docs.fluentbit.io/manual およびプラグイン固有のページを使用します。
• ブログよりも公式のプラグインリファレンスを優先します。

3. ウェブ検索（最後に使用）

• Context7 と公式ドキュメントが利用できない、または不完全な場合に限り使用します。
• 公式ドキュメントを引用またはリンクしている情報源を優先します。

検索を打ち切るタイミング：

• 必要なパラメーターと検証済みのサンプルが 1 つ見つかった時点で、検索を打ち切ります。
• すべての情報源が利用できない場合は、ローカルの examples/ を使い、前提条件を明確に記載します。

ステージ 7：検証とフォールバック動作

主な検証方法：

• 生成後に fluentbit-validator を実行します。

バリデーターが利用できない場合は、ローカルのフォールバックチェックを実行します。

# Syntax/format smoke check when fluent-bit is installed
fluent-bit -c <generated-config> --dry-run

# Optional execution test
fluent-bit -c <generated-config>

fluent-bit バイナリが見つからない場合：

• 次の項目を手動で静的チェックします。
  • セクションヘッダーが有効である（[SERVICE]、[INPUT]、[FILTER]、[OUTPUT]）
  • 必須のプラグインキーが存在する
  • タグと一致パターンに整合性がある
  • 参照されているパーサー名およびファイルが正しい
  • ハードコードされた認証情報がない
• 実行時検証をスキップしたこととその理由を報告します。

ステージ 8：応答の要件

常に次の内容を返します。

1. 使用した生成方法（script または manual）とその理由。
2. 生成したファイルと、選択した主なプラグイン。
3. 検証結果（または、フォールバックチェックの実施内容を添えた明示的なスキップ理由）。
4. 前提条件、未解決のリスク、および次にカスタマイズする項目。

完了条件

次のすべてを満たした場合にのみ、このスキルの実行は完了です。

• トリガーとの適合性が明示的に確認されている。
• 必要なフィールドを記録した、または前提条件を記載した確認用質問が作成されている。
• スクリプトと手動のどちらを選んだかが明確で、その理由が示されている。
• プラグインの検索で、Context7 -> 公式ドキュメント -> 必要に応じてウェブ、という決定論的な順序が使われている。
• 作業ディレクトリを考慮した安全なコマンド例が提示されている。
• 不足しているツールやドキュメント、ネットワークの制約に対してフォールバック動作が適用されている。
• 検証が実行されている（または、明確な理由と実施した静的チェックを添えてスキップされている）。
• 最終応答に生成物、検証結果、および次にカスタマイズする項目が含まれている。

ローカルリソース

• スクリプト：scripts/generate_config.py
• テンプレート：examples/*.conf
• パーサーのベースライン：examples/parsers.conf
• サンプル出力ディレクトリ：output/

新しい構造を導入する前に、まずこれらのリソースを使用してください。