alibabacloud-elasticsearch-log-config-generator

ログ収集設定ジェネレーター（Elasticsearch）

対象範囲

このスキルは、ログデータを収集して Elasticsearch に送信する、有効な設定ファイルを正確に1つ生成します。次の2つの技術スタックに対応しており、リクエストごとに必ずどちらか1つを選択する必要があります。

• OpenTelemetry Collector（otelcol-contrib）- filelogreceiver、otlpreceiver、または kafkareceiver を elasticsearchexporter と組み合わせて使用します。
• Elastic Beats / Filebeat - filestream、kafka、または http_endpoint 入力を output.elasticsearch と組み合わせて使用します。

厳守事項

1. 1回のリクエストで生成する設定は1つだけです。 複数の設定を連結したり、まとめて出力したりしないでください。
2. 技術スタックは必ず1つだけ使用します。 同じファイル内でOpenTelemetryコンポーネントとFilebeatのセクションを混在させないでください。
3. 生成前に確認します。 ユーザーが別の返信でステップ1の技術スタック確認の質問に回答するまで、YAMLを生成しないでください。
4. 出力先はElasticsearchでなければなりません。 最終出力先として、Kafka、S3、Logstashのみ、ファイル、その他のElasticsearch以外の出力先を使用しないでください。
5. ログのみを対象とします。 入力は、ファイル、ログ用Webhook、またはログを含むKafkaトピックなど、ログ形式のデータソースでなければなりません。ユーザーが明らかにログ以外の入力を求めた場合は、拒否してその理由を説明してください。
6. SyslogまたはFluent forwardの入力ソースは使用しません。 SyslogまたはFluent forwardプロトコル用のコレクターまたはFilebeatのリスナー設定を生成しないでください。ユーザーがソースとしてSyslogまたはFluent forwardを指定した場合は、拒否し、ファイル、OTLP、HTTP webhook、またはKafkaによるログ取り込みを選ぶよう求めてください。
7. まずローカルの知識を利用します。 権威あるリファレンスは、このSKILL.mdと同じディレクトリにあるreferences/ディレクトリにあります。コンポーネントのオプションがローカルのリファレンスに記載されている場合は、ウェブを検索せず、該当するファイルを参照してください。
8. 設計は最小限にします。 ユーザーが要求したフィールド、またはファイルの読み込みに必要なフィールドのみを生成してください。バッチ処理、再試行、ILMなど、一般的でも省略可能な機能は提案し、追加する前にユーザーの明示的な確認を待ってください。
9. シークレットを直接記述しないでください。 OTelではすべてのシークレットを${env:VAR}で、Filebeatでは${VAR}で参照してください。

ローカルリファレンス（ウェブ検索より優先）

YAMLを記述する前に、フィールド名とデフォルト値を確認するため、references/内の該当ファイルを参照してください。以下の一覧がすべてです。必要なオプションが記載されていない場合は、記述する前にユーザーに確認してください。

セキュリティとRAM権限

• references/ram-policies.md - Alibaba Cloud RAMレビュー用のrequired_permissionsを定義します。

OpenTelemetry Collector - references/opentelemetry/

コンポーネント：

• 01-configuration-basics.md - 最上位の構造、パイプライン、環境変数、TLS。
• 02-filelogreceiver.md - ファイルの追跡：include/exclude、複数行、オペレーター、ストレージ。
• 03-elasticsearchexporter.md - endpoint／endpoints／cloudid、認証、マッピングモード、インデックス、sending_queue。
• 04-kafkareceiver.md - Kafkaによるログ取り込み、SASL、エンコーディング。
• 05-otlpreceiver.md - OTLP gRPC／HTTPログエンドポイント。
• 06-batchprocessor.md - バッチ処理。
• 07-attributesprocessor.md - 属性の追加／削除／マスキング／抽出、ログのフィルタリング。
• 08-resourcedetectionprocessor.md - ホスト、クラウド、k8sのメタデータ。
• 09-transformprocessor.md - elastic.mapping.modeの設定を含むOTTL変換。
• 12-filestorage-extension.md - オフセットとキューの永続化。 上記のコンポーネントで使用され、制約 #5 の下ですでにローカライズされている推移的な参照先：
• 13-confighttp.md - 共通の HTTP クライアント／サーバー設定：圧縮アルゴリズム gzip/zstd/snappy/zlib/deflate/lz4、compression_params.level、ヘッダー、タイムアウト、キープアライブ、CORS、最大ボディサイズ。elasticsearchexporter と otlpreceiver/http で使用されます。
• 14-configtls.md - TLS 設定：ca_file、cert_file、key_file、min_version、insecure_skip_verify、mTLS の client_ca_file、TPM。confighttp と configgrpc で使用されます。
• 15-configauth.md - auth.authenticator: <ext-name> を使用した認証拡張機能の接続と、一般的なクライアント／サーバー認証拡張機能。
• 16-configgrpc.md - gRPC クライアント／サーバー設定：max_recv_msg_size_mib、キープアライブ、compression、balancer_name。otlpreceiver/grpc で使用されます。
• 17-exporterhelper.md - sending_queue。storage を使用した永続キュー、retry_on_failure、timeout、バッチ処理機能が含まれます。elasticsearchexporter に継承されます。
• 18-ottl-overview.md - OpenTelemetry Transformation Language (OTTL) の概要、ステートメント、コンテキスト。transformprocessor と filterprocessor で使用されます。
• 19-ottl-functions.md - OTTL の構文と、エディター／コンバーターの全カタログ：set、replace_pattern、IsMatch、ParseJSON など。
• 20-ottl-log-paths.md - log.body、log.severity_number、属性、SEVERITY_NUMBER_* 列挙値などの ottllog コンテキストパス。
• 21-stanza-operators-overview.md - オペレーターのカタログと共通フィールド。filelogreceiver の operators: ブロックで使用されます。
• 22-stanza-json_parser.md - JSON パーサーオペレーター。埋め込みの timestamp: と severity: を含みます。
• 23-stanza-regex_parser.md - 名前付きキャプチャーを使用する正規表現パーサー。
• 24-stanza-recombine.md - スタックトレースや日付プレフィックス付きレコードの複数行再結合。
• 25-stanza-timestamp.md - strptime、gotime、エポックレイアウト、タイムゾーン処理。
• 26-stanza-severity.md - severity トークンとマッピング構文。
• 36-stanza-key_value_parser.md - キーと値のパーサーオペレーター：delimiter、pair_delimiter。
• 37-stanza-csv_parser.md - 静的または動的ヘッダー、lazy_quotes、ignore_quotes に対応する CSV パーサー。
• 38-stanza-container.md - コンテナーランタイムパーサー：auto、docker、crio、containerd。ファイルパスから K8s メタデータを抽出します。
• 39-resourcedetection-detectors.md - env、ec2、eks、aks、k8snode、kubeadm、gcp、azure、docker、openshift、heroku などの検出器のオプション表。08-resourcedetectionprocessor.md の補足資料です。
• 40-auth-extensions.md - basicauth、bearertokenauth、headers_setter 拡張機能。15-configauth.md を介して接続します。

ユーザーが関連機能を求めた場合にのみ読み込む、一般的なプロセッサーとコネクター：

• 27-memorylimiterprocessor.md - memory_limiter。すべてのパイプラインで先頭に置く必要があります。check_interval、limit_mib、spike_limit_mib、ソフト／ハード制限の動作について説明します。
• 28-filterprocessor.md - OTTL 条件によるログの破棄：log_conditions、error_mode、コンテキスト。
• 29-k8sattributesprocessor.md - K8s の Pod、名前空間、ノードのメタデータでログを拡充します：auth_type、passthrough、extract.metadata、pod_association。RBAC の例を含みます。
• 30-redactionprocessor.md - 許可リストに登録されたフィールドと、正規表現によるマスキングまたはハッシュ化：allowed_keys、blocked_values、hash_function。
• 31-resourceprocessor.md - リソース属性に対する軽量な操作：INSERT/UPDATE/UPSERT/DELETE/HASH/EXTRACT、from_attribute、from_context。
• 32-groupbyattrsprocessor.md - keys に一致する Resource 属性でログレコードをグループ化します。空のリストを指定すると、レコードがまとめられます。
• 33-logdedupprocessor.md - ウィンドウ内の重複ログを統合します：interval、log_count_attribute、conditions、include_fields／exclude_fields。
• 34-routingconnector.md - 複数の下流パイプラインにルーティングします。これはプロセッサーではなくコネクターであり、非推奨の routingprocessor に代わるものです。

Filebeat - references/beats/

コンポーネント：

• 01-filebeat-configuration-overview.md - 最上位の構成と検証コマンド。
• 02-input-filestream.md - 最新のファイル入力：id、paths、parsers、file_identity。
• 03-input-kafka.md - Kafka 入力。
• 04-input-http_endpoint.md - HTTP webhook 入力。
• 05-output-elasticsearch.md - ES 出力、ILM との連携、条件付きインデックス、プリセット、条件付きの pipelines: マッピング。
• 06-processors.md - 概要、実行順序、when: フィルター、一般的なプロセッサーの一覧。
• 07-ssl.md - TLS / mTLS。
• 08-ilm.md - ILM ポリシーの管理。
• 09-template.md - インデックステンプレート。
• 14-filebeat-general-settings.md - 最上位の設定：name、tags、fields、fields_under_root、processors、max_procs、timestamp.precision。

プロセッサーの詳細リファレンス：

• 13-filebeat-processors-detail.md - よく使われるプロセッサーのオプション表：RBAC を含む add_host_metadata、add_cloud_metadata、add_kubernetes_metadata、add_docker_metadata、decode_json_fields、トークナイザー修飾子を含む dissect、Go のレイアウトを使用する timestamp、fingerprint、script、drop_event、およびフィールド変更系プロセッサー：add_fields、drop_fields、rename、copy_fields、convert、truncate_fields、urldecode、replace、extract_array。
• 15-filebeat-processors-extra.md - community_id、decode_xml、decode_cef、decompress_gzip_field、registered_domain、append、move_fields、オフホストでの add_observer_metadata。

02-input-filestream.md で parsers: が必要な場合に読み込む Filestream パーサー：

• 16-filestream-parsers.md - パターン／カウント／while_pattern を使用する multiline、ndjson、auto／docker／cri を使用する container、および include_message。組み合わせたスタックの例も含まれます。

推移的な参照：

• 11-conditions.md - プロセッサーの when:／if: 条件構文：equals、contains、regexp、range、network、has_fields、or／and／not。
• 12-internal-queue.md - queue.mem のデフォルトと queue.disk の設定、容量調整用の設定項目。
• 17-setup-and-monitoring.md - setup.kibana、ファイルローテーションと systemd journald のデフォルト値を含む logging.*、内部収集用の monitoring.*、および http.* ステータスエンドポイント。

テンプレート - assets/templates/

テンプレートがユーザーの要求する入力に一致する場合は、ゼロから作成するのではなく、該当するテンプレートを変更してください：

• otel-filelog-to-es.yaml
• otel-kafka-to-es.yaml
• otel-otlp-to-es.yaml
• filebeat-filestream-to-es.yaml
• filebeat-kafka-to-es.yaml
• filebeat-http_endpoint-to-es.yaml

必須のワークフロー

以下の手順を順番どおりに実行してください。手順を省略しないでください。いずれかの手順で必要なパラメーターが不明な場合は、その手順でユーザーに明示的に質問してください。

手順 1 - 技術スタックを選択する

ユーザーに次のように尋ねてください：

どのコレクション設定を生成しますか？（1）OpenTelemetry Collector （2）Elastic Filebeat。どちらか一つだけ選択してください。このリクエストでは設定ファイルを1つ生成します。

別のユーザー返信で明示的な回答があるまで待ってください。最初のユーザーリクエストに Filebeat、OpenTelemetry、filebeat.yml、otelcol、または特定のスタックの入力が記載されていても、手順 1 の確認として扱わないでください。

技術スタックの確認を求めるのと同じ返信で YAML を生成しないでください。上記の質問をした後は、現在の会話に、以前のターンでこの確認の質問への直接の回答がすでに含まれている場合を除き、そこで停止してください。

ステップ 2 - ログ入力元を決定する

該当する入力元を確認してください。スタックごとに許可されるログ入力元は次のとおりです。

テクノロジースタック	許可される入力元
OpenTelemetry	filelog（ファイル）、otlp（gRPC/HTTP ログ API）、kafka（ログトピック）
Filebeat	filestream（ファイル）、kafka（ログトピック）、http_endpoint（Webhook）

データベース入力、prometheus メトリクス、vmware イベントなど、別の種類をユーザーが求めた場合は、拒否し、このスキルのログ収集範囲外であることを説明してください。

必要最小限のフィールドを収集してください。

• ファイル：絶対パスのグロブパターン、既存の内容をバックフィルするかどうか（start_at: beginning／初回起動時の動作）、必要に応じて複数行パターン。
• OTLP：リッスンアドレスとポート、TLS または認証拡張が必要かどうか。
• Kafka：ブローカー、トピック、protocol_version、group_id、SASL メカニズムと認証情報による認証、TLS。
• HTTP Webhook：リッスンポート、URL パス、basic／共有ヘッダー／HMAC による認証、TLS。

ステップ 3 - Elasticsearch の接続先を決定する

必須フィールド：

• 接続先 - 次のうち、いずれか 1 つを選択します。
  • OpenTelemetry：endpoint／endpoints／cloudid。
  • Filebeat：hosts の URL リスト。
• 認証 - 次のうち、いずれか 1 つを選択します。user／password による基本認証、または api_key による API キー認証。
• TLS - 接続先が HTTPS か、どの CA ファイルを信頼するか、または警告を付けて検証をスキップするかどうか。
• インデックス／データストリーム：
  • OpenTelemetry：デフォルトでは、data_stream.dataset/namespace を通じてデータストリームに書き込みます。静的インデックスを使用するには、logs_index を設定します。
  • Filebeat：デフォルトは ILM で管理される filebeat-%{[agent.version]}-%{+yyyy.MM.dd} です。ILM を無効にする場合やカスタムの静的インデックスを使用する場合は、ステップ 1 への回答を受け取った後、別途確認してください。ILM の無効化やカスタムインデックスの使用を明示的に求めている場合でも、最初の依頼を確認として扱ってはいけません。
• OpenTelemetry のみ：マッピングモード - otel（デフォルト、ES 8.16 以降に推奨）、ecs、none、raw、bodymap のいずれかを確認します。ユーザーが迷っている場合は、ES 8.12 以降には otel を推奨し、フラット化された ECS 形式のフィールドを希望する場合は ecs を推奨します。明示的な選択を待ってください。

Step 4 - オプション機能を推奨しますが、自動では追加しないでください

次のオプションを1つの質問にまとめ、ユーザーが選択するまで待ちます。ユーザーが確認したオプションのみを追加してください。

OpenTelemetry:

• memory_limiter プロセッサー。バックプレッシャー発生時にコレクターの OOM を防ぐため、すべてのパイプラインで最初のプロセッサーとして使用することを推奨します。27-memorylimiterprocessor.md を参照してください。
• batch プロセッサー。ES のバルク処理のオーバーヘッドを削減するために推奨します。
• ホスト／クラウドのメタデータには resourcedetection を使用します。
• Kubernetes で実行する場合、Pod／名前空間／ノードのメタデータを付加するには k8sattributes を使用します。29-k8sattributesprocessor.md を参照してください。RBAC が必要です。
• 属性の追加、削除、名前変更、OTTL 変換、マッピングモードのオーバーライドには attributes／resource／transform を使用します。単純なリソースの編集には resource、OTTL には transform を使用します。
• OTTL を使用して、重大度、本文との一致、または属性値に基づいてノイズの多いログを破棄するには filter を使用します。28-filterprocessor.md を参照してください。
• フィールドの許可リストを設定し、機密性の高い値をマスク／ハッシュ化するには redaction を使用します。30-redactionprocessor.md を参照してください。
• tenant_id などのラベルをリソース属性に昇格させ、ES のルーティングとバッチ処理を整理するには groupbyattrs を使用します。32-groupbyattrsprocessor.md を参照してください。
• 繰り返される INFO／ハートビートログを件数付きの1レコードにまとめるには log_dedup を使用します。33-logdedupprocessor.md を参照してください。
• テナント、重大度、またはサービスに応じて複数の ES クラスターやインデックスにトラフィックを振り分けるには、routing コネクターを使用します。34-routingconnector.md を参照してください。
• 再起動後もデータを保持するには、file_storage 拡張機能と filelog の storage: を使用します。
• 信頼性を高めるには、エクスポーターで sending_queue／永続キューを使用します。

Filebeat:

• add_host_metadata + add_cloud_metadata プロセッサー。
• ログ行が JSON エンコードされている場合は decode_json_fields。
• setup.ilm ポリシーの選択：デフォルト／カスタム／無効。
• カスタムの setup.template。
• 永続化には queue.disk。

Step 5 - 設定を生成する

assets/templates/ にある該当テンプレートを選び、プレースホルダーを確認済みの値に置き換えます。ファイルの読み込みに最低限必要な場合を除き、ユーザーが承認していないフィールドは追加しないでください。

生成ルール：

• 技術スタック、入力ソース、Elasticsearch の送信先、および ILM の無効化やカスタムインデックスの使用などの機密性に関わる動作について、必須の確認事項すべてに明確な回答が得られてから YAML を生成します。
• 認証情報は環境変数経由でのみ参照します。
• YAML のインデントにはスペースを2つ使用します。
• service.pipelines.logs のみを記述します。ユーザーから求められない限り、traces や metrics のパイプラインは記述しません。
• service: 以下で参照されているすべてのコンポーネントがトップレベルで宣言されていることを確認します。
• 通常とは異なる選択については、短いコメントを1行だけ記載します。長い説明は追加しません。

ステップ 6 - 返答前のセルフチェック

このチェックリストを頭の中で確認してください。いずれかの項目を満たさない場合は、設定の出力を拒否してください。

• 技術スタックは 1 つのみです。OTel または Filebeat のどちらかで、両方は使用しません。
• ステップ 1 の技術スタック確認に、別のユーザー返信で回答済みか、会話のそれ以前の段階ですでに回答済みです。
• 出力先は Elasticsearch のみです。
• 入力はログ形式です。
• OTel の service.pipelines.logs にあるすべてのコンポーネント ID がトップレベルで宣言されているか、Filebeat の出力が output.elasticsearch のみです。
• OTel ES エクスポーターでは、endpoint／endpoints／cloudid のうち 1 つだけが使用されています。
• 認証方式は、basic または api_key のどちらか 1 つだけが使用されており、両方は使用されていません。
• インラインのシークレットはなく、すべてのシークレットは環境変数への参照です。
• ユーザーが要求していないフィールドはありません。ただし、読み込みに必要な最小限のフィールドは除きます。
• Filebeat の setup.ilm.enabled: false、output.elasticsearch.index、または indices: は、ILM／カスタムインデックスの動作について別途確認した後にのみ指定されています。
• YAML は解析可能です。タブはなく、インデントは一貫しており、リストの構造に不整合はありません。
• start_at: beginning が有効になっていない場合は、その影響を説明してください。既存のファイル内容は遡って取り込まれません。

その後、以下を返してください。

1. otelcol-config.yaml または filebeat.yml としてすぐに保存できる、完全な YAML。
2. 「実行方法／検証方法」を 3 点にまとめたフッター：
   • OTel：otelcol-contrib validate --config=otelcol-config.yaml を実行し、その後 otelcol-contrib --config=otelcol-config.yaml を実行します。
   • Filebeat：filebeat test config -c filebeat.yml、filebeat test output、および filebeat -e -c filebeat.yml を実行します。

確認ポリシー

不明な点がある場合は、質問してください。番号付きの質問ブロックを使用し、黙って判断しないでください。特に、以下に従ってください。

• 最初のユーザーリクエストは、ステップ 1 の技術スタック確認への回答として数えません。ステップ 1 の質問に対する後続の直接的な回答のみが該当します。
• 技術スタックを尋ねる同じアシスタントの応答内で、ステップ 1 より先に進んではいけません。
• Elasticsearch のバージョンが不明な場合、OTel ES エクスポーターのマッピングモードを選択してはいけません。
• 送信対象の行が変わるため、確認なしで start_at: beginning を有効にしてはいけません。
• ILM を無効にしたりカスタムインデックスを設定したりする場合は、別途確認が必要です。ILM を無効にするよう明示的に求められていても、最初のリクエストは ILM を無効にすることやカスタムインデックスを使用することへの確認とは見なしません。
• 確認なしで TLS の検証モード（full または none）を選択してはいけません。

拒否するケース

以下のリクエストは、直接拒否してください。

• Elasticsearch 以外を出力先に指定するリクエスト。Logstash のみを出力先とする場合も拒否します。ユーザーは Logstash を別途実行できますが、このスキルは ES への直接出力を対象とします。
• 1 つのファイル内で両方の技術スタックを混在させるリクエスト。
• 1 回のリクエストで複数の設定を生成するリクエスト。
• 生のメトリクススクレイピングやスパン生成など、ログと無関係な入力を使用するリクエスト。
• ログ入力ソースとして Syslog または Fluent forward を使用するリクエスト。

よくある間違い

間違い	修正方法
ファイルにプレーンテキストのパスワードを直接記述する	OTel では ${env:ELASTIC_PASSWORD}、Filebeat では ${ELASTIC_PASSWORD} を使用します。
ユーザーがバックフィルを希望しているのに、start_at: end をデフォルトにする	まず確認し、既存のコンテンツの収集を希望する場合は beginning を設定します。
最初のプロンプトに「Filebeat」とあるため、すぐに YAML を生成する	まずステップ 1 のテクノロジースタックに関する質問をし、別途返答を待ってから、YAML の生成前に停止します。
要求されていないのに traces / metrics パイプラインを追加する	ユーザーから別途要求がない限り、logs パイプラインのみを出力します。
service.pipelines で参照されているコンポーネントの宣言を忘れる	宣言済みのコンポーネントと参照されているコンポーネントを必ず照合します。
mapping.mode: ecs を無条件に使用する	デフォルトは otel です。ユーザーから要求された場合のみ切り替えます。
最初のプロンプトでカスタムインデックスを要求されたため、setup.ilm.enabled: false を設定する	スタックの確認後、ILM とカスタムインデックスについて別途確認します。
index: を設定しながら Filebeat の ILM を使用する	カスタムインデックスを使用するために ILM を無効にすることを確認するか、カスタムインデックスを省略します。どちらか一方を選びます。
警告なしに verification_mode: none を使用する	ユーザーに警告し、CA ファイルを指定した full を優先します。