alibabacloud-elasticsearch-log-config-generator

日志采集配置生成器（Elasticsearch）

范围

此技能会生成一个有效的配置文件，用于采集日志数据并将其发送到 Elasticsearch。它支持两种技术栈，每次请求必须且只能选择一种：

• OpenTelemetry Collector（otelcol-contrib）——使用 filelogreceiver、otlpreceiver 或 kafkareceiver，并搭配 elasticsearchexporter。
• Elastic Beats / Filebeat——使用 filestream、kafka 或 http_endpoint 输入，并搭配 output.elasticsearch。

严格约束

1. 每次请求只生成一个配置。 不要串联或批量生成多个配置。
2. 只能使用一种技术栈。 切勿在同一个文件中混用 OpenTelemetry 组件和 Filebeat 配置段。
3. 生成前先确认。 用户必须在单独的回复中回答第 1 步的技术栈确认问题，之后才能生成 YAML。
4. 输出目标必须是 Elasticsearch。 最终输出切勿使用 Kafka、S3、仅支持 Logstash 的目标、文件或任何其他非 Elasticsearch 目标。
5. 仅限日志。 输入必须是日志类数据源：文件、日志 Webhook，或包含日志的 Kafka 主题。如果用户要求明显不属于日志的输入，请拒绝并说明原因。
6. 不支持 Syslog 或 Fluent forward 输入源。 不要生成用于 Syslog 或 Fluent forward 协议的 Collector 或 Filebeat 监听器配置。如果用户要求以 Syslog 或 Fluent forward 为数据源，请拒绝，并让其改为选择文件、OTLP、HTTP Webhook 或 Kafka 日志采集。
7. 优先使用本地知识。 权威参考资料位于与此 SKILL.md 同级的 references/ 目录中。如果某个组件选项已在本地资料中说明，就不要搜索网络；请读取 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 ——OTTL 转换，包括设置 elastic.mapping.mode。
• 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 - ottllog 上下文路径，例如 log.body、log.severity_number、属性和 SEVERITY_NUMBER_* 枚举。
• 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、epoch 布局和时区处理。
• 26-stanza-severity.md - severity 标记和映射语法。
• 36-stanza-key_value_parser.md - 键值解析器运算符：delimiter、pair_delimiter。
• 37-stanza-csv_parser.md - CSV 解析器，支持静态或动态标头、lazy_quotes 和 ignore_quotes。
• 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 - 最常用处理器的选项表：add_host_metadata、add_cloud_metadata、带 RBAC 的 add_kubernetes_metadata、add_docker_metadata、decode_json_fields、带 tokenizer 修饰符的 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 - 带有 pattern / count / 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、logging.*（包括文件轮转和 systemd journald 默认设置）、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。请选择其中一项；此请求将生成一个配置文件。

等待用户在单独的回复中明确作答。即使用户最初的请求提到了 Filebeat、OpenTelemetry、filebeat.yml、otelcol 或特定技术栈的输入，也不要将其视为对步骤 1 的确认。

询问用户确认技术栈时，不要在同一条回复中生成 YAML。除非当前对话的先前轮次中已包含对该确认问题的直接回答，否则在提出上述问题后停止。

第 2 步 - 确定日志输入源

询问适用的输入方式。各技术栈允许的日志输入如下：

技术栈	允许的输入
OpenTelemetry	filelog（文件）、otlp（gRPC/HTTP 日志 API）、kafka（日志主题）
Filebeat	filestream（文件）、kafka（日志主题）、http_endpoint（Webhook）

如果用户要求其他类型的输入，例如数据库输入、Prometheus 指标或 VMware 事件，请拒绝并说明这超出了此技能的日志采集范围。

收集必需的最少字段：

• 文件：绝对 glob 路径；是否回填现有内容（start_at: beginning / 首次启动行为）；必要时提供多行模式。
• OTLP：监听地址和端口；是否需要 TLS 或身份验证扩展。
• Kafka：代理、主题、protocol_version、group_id、使用 SASL 机制和凭据进行身份验证、TLS。
• HTTP Webhook：监听端口、URL 路径、使用 basic / 共享请求头 / HMAC 进行身份验证、TLS。

第 3 步 - 确定 Elasticsearch 目标

必需字段：

• 连接 - 只能选择一项：
  • OpenTelemetry：endpoint / endpoints / cloudid。
  • Filebeat：hosts URL 列表。
• 身份验证 - 只能选择一项：使用 user/password 进行 basic 身份验证，或使用 api_key 配置 API 密钥。
• TLS - 端点是否使用 HTTPS、信任哪个 CA 文件，或是否应跳过验证并发出警告。
• 索引 / 数据流：
  • OpenTelemetry：默认通过 data_stream.dataset/namespace 写入数据流。若要使用静态索引，请设置 logs_index。
  • Filebeat：默认使用由 ILM 管理的 filebeat-%{[agent.version]}-%{+yyyy.MM.dd}。在禁用 ILM 或使用自定义静态索引之前，请在第 1 步得到答复后另行询问并确认。即使用户明确要求关闭 ILM，最初的请求也不算作禁用 ILM 或使用自定义索引的确认。
• 仅适用于 OpenTelemetry：映射模式 - 确认使用 otel（默认，推荐用于 ES 8.16+）、ecs、none、raw 或 bodymap。如果用户不确定，对于 ES 8.12+，建议使用 otel；如果用户希望使用扁平化的 ECS 风格字段，则建议使用 ecs。等待用户明确选择。

步骤 4 - 推荐可选功能，但不要自动添加

将以下选项合并到一个问题中，并等待用户选择。只添加用户确认的选项。

OpenTelemetry：

• memory_limiter 处理器，建议作为每个管道中的第一个处理器，以防止在背压情况下 Collector OOM；参见 27-memorylimiterprocessor.md。
• batch 处理器，建议用于减少 ES 批量处理开销。
• resourcedetection，用于检测主机／云环境元数据。
• k8sattributes，在 Kubernetes 中运行时用于附加 Pod／命名空间／节点元数据；参见 29-k8sattributesprocessor.md；需要 RBAC。
• attributes / resource / transform，用于添加、删除或重命名属性、执行 OTTL 转换，以及覆盖映射模式。简单的资源编辑使用 resource；OTTL 使用 transform。
• filter，通过 OTTL 按严重级别、正文匹配或属性值丢弃嘈杂日志；参见 28-filterprocessor.md。
• redaction，用于设置字段允许列表，并对敏感值进行遮蔽／哈希处理；参见 30-redactionprocessor.md。
• groupbyattrs，用于将 tenant_id 等标签提升为资源属性，以便更整洁地进行 ES 路由和批量处理；参见 32-groupbyattrsprocessor.md。
• log_dedup，用于将重复的 INFO／心跳日志合并为一条记录，并附带计数；参见 33-logdedupprocessor.md。
• routing 连接器，用于按租户、严重级别或服务将流量分发到多个 ES 集群或索引；参见 34-routingconnector.md。
• file_storage 扩展，以及 filelog 上的 storage:，用于在重启后保留数据。
• Exporter 上的 sending_queue / 持久化队列，用于提高可靠性。

Filebeat：

• add_host_metadata + add_cloud_metadata 处理器。
• 日志行采用 JSON 编码时使用 decode_json_fields。
• setup.ilm 策略选项：默认／自定义／禁用。
• 自定义 setup.template。
• 使用 queue.disk 实现持久化。

步骤 5 - 生成配置

选择 assets/templates/ 下匹配的模板，并将占位符替换为已确认的值。不要引入用户未批准的字段，除非这些字段是文件能够加载所必需的最低要求。

生成规则：

• 只有在所有必需的确认项都得到明确答复后，才能生成 YAML：技术栈、输入源、Elasticsearch 目标，以及任何敏感行为（例如禁用 ILM 或使用自定义索引）。
• 只能通过环境变量引用凭据。
• YAML 使用 2 个空格缩进。
• 只编写 service.pipelines.logs；除非用户提出要求，否则不要编写 traces 或 metrics 管道。
• 确认 service: 下引用的每个组件都已在顶层声明。
• 对不常见的选择添加一行简短注释；不要添加冗长说明。

步骤 6 - 返回前自检

在心中逐项检查。若有任何一项不符合要求，请拒绝输出配置：

• 只使用一种技术栈：OTel 或 Filebeat，绝不同时使用。
• 已在单独的用户回复中确认步骤 1 中的技术栈，或在对话前文中已确认。
• 输出仅指向 Elasticsearch。
• 输入符合日志格式。
• 对于 OTel，service.pipelines.logs 中的每个组件 ID 都已在顶层声明；对于 Filebeat，output.elasticsearch 是唯一的输出。
• OTel ES exporter 中仅使用 endpoint / endpoints / cloudid 之一。
• 仅使用一种身份验证方式：basic 或 api_key，绝不同时使用。
• 不包含内联密钥；所有密钥均引用环境变量。
• 不包含用户未要求的字段，但加载所需的最少字段除外。
• 只有在单独确认 ILM / 自定义索引行为后，才会出现 Filebeat setup.ilm.enabled: false、output.elasticsearch.index 或 indices:。
• YAML 可解析：不使用制表符、缩进一致、列表完整。
• 如果未启用 start_at: beginning，请说明其影响：不会补采文件中已有的内容。

然后返回：

1. 完整的 YAML，可直接保存为 otelcol-config.yaml 或 filebeat.yml。
2. 包含三点的“如何运行 / 验证”页脚：
   • 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 之后的操作。
• ES 版本未知时，不要选择 OTel ES exporter 的映射模式。
• 未经确认，不要启用 start_at: beginning，因为这会改变发送的日志行。
• 未经单独确认，不要禁用 ILM 或设置自定义索引。即使用户在最初的请求中明确要求关闭 ILM，该请求也不算作确认。
• 未经确认，不要选择 TLS 验证模式 full 或 none。

拒绝情形

直接拒绝以下请求：

• 输出到 Elasticsearch 以外的任何目标。也拒绝仅输出到 Logstash 的请求；用户可以单独运行 Logstash，但此技能面向直接输出到 ES。
• 在同一个文件中混用两种技术栈。
• 在单个请求中生成多个配置。
• 使用与日志无关的输入，例如原始指标抓取或 Span 生成。
• 使用 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。