⚡

FluentBitConfigGenerator fluentbit-generator

这是一个全面的工具包，用于生成最佳实践 Fluent Bit 配置。当创建新的 Fluent Bit 配置、实施日志收集流水线、构建生产就绪的遥测配置时使用此技能。

云原生架构 0 次安装 0 次浏览 更新于 3/4/2026

Fluent Bit 配置生成器

概述

这个技能提供了一个全面的工作流程，用于生成内置最佳实践的 Fluent Bit 配置。生成完整的流水线或单独的部分（SERVICE, INPUT, FILTER, OUTPUT, PARSER）时，使用正确的语法、最佳性能设置和自动验证。

Fluent Bit 是一个快速且轻量级的遥测代理，用于日志、指标和跟踪。它是 CNCF（云原生计算基金会）的一部分，通常用于 Kubernetes 环境中的日志聚合、转发和处理。

何时使用此技能

在以下情况下调用此技能：

  • 从头开始创建新的 Fluent Bit 配置
  • 实施日志收集流水线（INPUT → FILTER → OUTPUT）
  • 使用元数据丰富配置 Kubernetes 日志收集
  • 设置日志转发到目的地（Elasticsearch, Loki, S3, Kafka, CloudWatch 等）
  • 构建多行日志解析以跟踪堆栈
  • 将现有日志配置转换为 Fluent Bit
  • 实施自定义解析器以进行结构化日志记录
  • 使用需要文档查找的 Fluent Bit 插件
  • 用户要求“创建”、“生成”、“构建”或“配置”Fluent Bit 配置
  • 设置具有过滤器和转换的遥测流水线

配置生成工作流程

按照这个工作流程生成 Fluent Bit 配置。根据用户需求进行调整：

第一阶段：理解需求

收集有关日志基础设施需求的信息：

  1. 用例识别：

    • Kubernetes 日志收集（DaemonSet 部署）
    • 应用日志转发
    • 系统日志收集（syslog, systemd）
    • 多行日志解析（堆栈跟踪，JSON 日志）
    • 来自多个源的日志聚合
    • 指标收集和转发

  2. 输入源：

    • tail（文件尾随）
    • systemd（systemd 日志）
    • tcp/udp（网络输入）
    • forward（Fluent 协议）
    • http（HTTP 端点）
    • kubernetes（K8s 容器日志）
    • docker（Docker 容器日志）
    • syslog
    • exec（命令执行）

  3. 处理要求：

    • 解析（JSON, regex, logfmt）
    • 多行处理（堆栈跟踪）
    • 过滤（grep, modify, lua）
    • 丰富（Kubernetes 元数据）
    • 转换（nest, rewrite_tag）
    • 限制（速率限制）

  4. 输出目的地：

    • Elasticsearch
    • Grafana Loki
    • AWS S3/CloudWatch
    • Kafka
    • HTTP 端点
    • 文件
    • stdout（调试）
    • forward（Fluent 协议）
    • Prometheus 远程写入

  5. 性能和可靠性：

    • 缓冲限制（内存限制）
    • 刷新间隔
    • 重试逻辑
    • TLS/SSL 要求
    • 工作线程（并行性）

如果信息缺失或不清晰，请使用 AskUserQuestion。

脚本与手动生成

步骤 1：首先验证脚本功能：

# 必需：运行 --help 检查是否支持您的用例
python3 scripts/generate_config.py --help

步骤 2：对于支持的用例，优先使用 generate_config.py 以保持一致性和测试过的模板：

# 为支持的用例生成配置
python3 scripts/generate_config.py --use-case kubernetes-elasticsearch --output fluent-bit.conf
python3 scripts/generate_config.py --use-case kubernetes-opentelemetry --cluster-name my-cluster --output fluent-bit.conf

支持的用例： 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.

步骤 3：在以下情况下使用手动生成（第 3-8 阶段）：

  • 用例不受脚本支持（通过 --help 验证）
  • 需要自定义插件或复杂的过滤器链（例如，grep 过滤日志级别）
  • 需要非标准配置
  • 用户明确请求手动配置

记录您的决定： 当选择手动生成时，明确说明为什么脚本不适用（例如，“选择手动生成，因为脚本不支持 grep 过滤日志级别”）。

手动生成前的示例咨询

在编写任何手动配置之前必需：

  1. 确定最匹配的示例 从 examples/ 目录：

    • 对于 Kubernetes + Elasticsearch：阅读 examples/kubernetes-elasticsearch.conf
    • 对于 Kubernetes + Loki：阅读 examples/kubernetes-loki.conf
    • 对于 Kubernetes + OpenTelemetry：阅读 examples/kubernetes-opentelemetry.conf
    • 对于应用日志和多行：阅读 examples/application-multiline.conf
    • 对于 syslog 转发：阅读 examples/syslog-forward.conf
    • 对于 S3 输出：阅读 examples/file-tail-s3.conf
    • 对于 Kafka 输出：阅读 examples/http-input-kafka.conf
    • 对于多目的地：阅读 examples/multi-destination.conf
    • 对于 Prometheus 指标：阅读 examples/prometheus-metrics.conf
    • 对于 Lua 过滤：阅读 examples/lua-filtering.conf
    • 对于流处理：阅读 examples/stream-processor.conf
    • 对于生产设置：阅读 examples/full-production.conf

  2. 使用 Read 工具阅读示例文件 以了解：

    • 部分结构和排序
    • 参数值和最佳实践
    • 注释和文档样式

  3. 阅读 examples/parsers.conf 以获取解析器定义 - 重用现有解析器而不是重新创建它们。

  4. 使用示例作为模板 - 复制相关部分并根据用户需求进行自定义。

第二阶段：插件文档查找（如适用）

如果配置需要特定插件或自定义输出目的地：

  1. 确定需要文档的插件：

    • 自定义输出插件（专有系统）
    • 较少使用的输入插件
    • 复杂的过滤器配置
    • 特定日志格式的解析器模式
    • 云提供商集成（AWS, GCP, Azure）

  2. 首先尝试上下文 7 MCP（首选）：

    使用 mcp__context7__resolve-library-id 与 "fluent-bit" 或 "fluent/fluent-bit"
然后使用 mcp__context7__get-library-docs 与：
- context7CompatibleLibraryID: /fluent/fluent-bit-docs（或 /fluent/fluent-bit）
- topic: 插件名称和配置（例如，"elasticsearch 输出配置"）
- page: 1（如果需要，获取额外页面）

  3. 如果上下文 7 失败，则退回到 WebSearch：

    搜索查询模式：
"fluent-bit" "<plugin-type>" "<plugin-name>" "configuration" "parameters" site:docs.fluentbit.io

示例：
"fluent-bit" "output" "elasticsearch" "configuration" 网站：docs.fluentbit.io
"fluent-bit" "filter" "kubernetes" "configuration" 网站：docs.fluentbit.io
"fluent-bit" "parser" "multiline" "configuration" 网站：docs.fluentbit.io

  4. 提取关键信息：

    • 必需参数
    • 可选参数和默认值
    • 配置示例
    • 性能调整选项
    • 常见陷阱和最佳实践

第三阶段：SERVICE 部分配置

始终以 SERVICE 部分开始 - 这定义了全局行为：

[SERVICE]
    # 刷新间隔（秒） - 多久将数据刷新到输出
    # 较低的值 = 较低的延迟，较高的 CPU 使用率
    # 推荐：大多数用例使用 1-5 秒
    Flush        1

    # 守护进程模式 - 作为后台进程运行（容器中关闭）
    Daemon       Off

    # 日志级别：关闭，错误，警告，信息，调试，跟踪
    # 推荐：生产中使用信息，调试用于故障排除
    Log_Level    info

    # 可选：将 Fluent Bit 自身的日志写入文件
    # Log_File     /var/log/fluent-bit.log

    # 解析器配置文件（如果使用自定义解析器）
    Parsers_File parsers.conf

    # 启用内置 HTTP 服务器以进行指标和健康检查
    # 推荐用于 Kubernetes 就绪/存活探针
    HTTP_Server  On
    HTTP_Listen  0.0.0.0
    HTTP_Port    2020

    # 启用存储指标端点
    storage.metrics on

    # 工作线程数量（0 = 自动检测 CPU 核心）
    # 增加以适应高容量环境
    # workers      0

关键 SERVICE 参数：

  • Flush（1-5 秒）：较低的实时性，较高的批处理效率
  • Log_Level：生产中使用 info，故障排除时使用 debug
  • HTTP_Server：启用以进行健康检查和指标
  • Parsers_File：引用外部解析器定义
  • storage.metrics：启用以监控缓冲区/存储指标

第四阶段：INPUT 部分配置

为数据源创建 INPUT 部分。常见模式：

Kubernetes Pod 日志（DaemonSet）

[INPUT]
    Name              tail
    Tag               kube.*
    Path              /var/log/containers/*.log
    # 排除 Fluent Bit 自身的日志以防止循环
    Exclude_Path      /var/log/containers/*fluent-bit*.log
    Parser            docker
    DB                /var/log/flb_kube.db
    Mem_Buf_Limit     50MB
    Skip_Long_Lines   On
    Refresh_Interval  10
    Read_from_Head    Off

关键 INPUT 模式：

  1. tail 插件（最常见）：

    • Path：文件路径或通配符模式
    • Tag：路由标签用于过滤器/输出
    • Parser：日志格式的预解析器（docker, cri, json）
    • DB：用于崩溃恢复的位置数据库
    • Mem_Buf_Limit：每个输入的内存限制（防止 OOM）
    • Skip_Long_Lines：跳过 > 32KB 的行（防止挂起）
    • Read_from_Head：从开头开始（新日志仅设置为 false）

  2. systemd 插件：

[INPUT]
    Name              systemd
    Tag               host.*
    Systemd_Filter    _SYSTEMD_UNIT=kubelet.service
    Read_From_Tail    On
  1. http 插件（webhook 接收器）：
[INPUT]
    Name          http
    Tag           app.logs
    Listen        0.0.0.0
    Port          9880
    Buffer_Size   32KB
  1. forward 插件（Fluent 协议）：
[INPUT]
    Name          forward
    Tag           forward.*
    Listen        0.0.0.0
    Port          24224

INPUT 的最佳实践：

  • 始终为 tail 输入设置 Mem_Buf_Limit 以防止内存问题
  • 使用 DB 跟踪文件位置
  • 设置适当的 Tag 模式进行路由
  • 使用 Exclude_Path 以防止日志循环
  • 启用 Skip_Long_Lines 以增强鲁棒性

第五阶段：FILTER 部分配置

为日志处理和丰富创建 FILTER 部分：

Kubernetes 元数据丰富

[FILTER]
    Name                kubernetes
    Match               kube.*
    Kube_URL            https://kubernetes.default.svc:443
    Kube_CA_File        /var/run/secrets/kubernetes.io/serviceaccount/ca.crt
    Kube_Token_File     /var/run/secrets/kubernetes.io/serviceaccount/token
    Kube_Tag_Prefix     kube.var.log.containers.
    Merge_Log           On
    Keep_Log            Off
    K8S-Logging.Parser  On
    K8S-Logging.Exclude On
    Labels              On
    Annotations         Off
    Buffer_Size         0

关键 FILTER 模式：

  1. kubernetes 过滤器（元数据丰富）：

    • Merge_Log：将 JSON 日志解析为结构化字段
    • Keep_Log：保留原始日志字段（Off 节省空间）
    • K8S-Logging.Parser：尊重 Pod 解析器注释
    • K8S-Logging.Exclude：尊重 Pod 排除注释
    • Labels：在输出中包含 Pod 标签
    • Annotations：包含 Pod 注释（可选，增加大小）

  2. 解析器过滤器（结构化解析）：

[FILTER]
    Name          parser
    Match         *
    Key_Name      log
    Parser        json
    Reserve_Data  On
    Preserve_Key  Off
  1. grep 过滤器（包含/排除）：
[FILTER]
    Name          grep
    Match         *
    # 仅包括错误日志
    Regex         level (error|fatal|critical)
    # 排除健康检查日志
    Exclude       path /health
  1. modify 过滤器（添加/移除字段）：
[FILTER]
    Name          modify
    Match         *
    Add           cluster_name production
    Add           environment prod
    Remove        _p
  1. nest 过滤器（重构）：
[FILTER]
    Name          nest
    Match         *
    Operation     lift
    Nested_under  kubernetes
    Add_prefix    k8s_
  1. multiline 过滤器（堆栈跟踪）：
[FILTER]
    Name          multiline
    Match         *
    multiline.key_content log
    multiline.parser      java, python, go
  1. throttle 过滤器（速率限制）：
[FILTER]
    Name          throttle
    Match         *
    Rate          1000
    Window        5
    Interval      1m
  1. lua 过滤器（自定义脚本）：
[FILTER]
    Name    lua
    Match   *
    script  /fluent-bit/scripts/filter.lua
    call    process_record

示例 Lua 脚本（/fluent-bit/scripts/filter.lua）：

function process_record(tag, timestamp, record)
    -- 添加自定义字段
    record["custom_field"] = "custom_value"

    -- 转换现有字段
    if record["level"] then
        record["severity"] = string.upper(record["level"])
    end

    -- 过滤特定记录（返回 -1 以丢弃）
    if record["message"] and string.match(record["message"], "DEBUG") then
        return -1, timestamp, record
    end

    -- 返回修改后的记录
    return 1, timestamp, record
end

FILTER 的最佳实践：

  • 顺序很重要：解析器在修改器之前
  • 在 K8s 环境中使用 Kubernetes 过滤器以丰富元数据
  • 早期解析 JSON 日志以启用基于字段的过滤
  • 为多集群设置添加集群/环境标识符
  • 使用 grep 在流水线早期减少数据量
  • 实施限制以防止下游过载

第六阶段：OUTPUT 部分配置

为目的地系统创建 OUTPUT 部分：

Elasticsearch

[OUTPUT]
    Name              es
    Match             *
    Host              elasticsearch.default.svc
    Port              9200
    # 带有日期的索引模式
    Logstash_Format   On
    Logstash_Prefix   fluent-bit
    Retry_Limit       3
    # 缓冲配置
    storage.total_limit_size 5M
    # TLS 配置
    tls               On
    tls.verify        Off
    # 认证
    HTTP_User         ${ES_USER}
    HTTP_Passwd       ${ES_PASSWORD}
    # 性能调整
    Buffer_Size       False
    Type              _doc

Grafana Loki

[OUTPUT]
    Name              loki
    Match             *
    Host              loki.default.svc
    Port              3100
    # 从元数据中提取标签
    labels            job=fluent-bit, namespace=$kubernetes['namespace_name'], pod=$kubernetes['pod_name'], container=$kubernetes['container_name']
    label_keys        $stream
    # 移除 Kubernetes 元数据以减少有效负载大小
    remove_keys       kubernetes,stream
    # 自动 Kubernetes 标签
    auto_kubernetes_labels on
    # 行格式
    line_format       json
    # 重试配置
    Retry_Limit       3

AWS S3

[OUTPUT]
    Name              s3
    Match             *
    bucket            my-logs-bucket
    region            us-east-1
    total_file_size   100M
    upload_timeout    10m
    use_put_object    Off
    # 压缩
    compression       gzip
    # 带有时间格式化的路径结构
    s3_key_format     /fluent-bit-logs/%Y/%m/%d/$TAG[0]/%H-%M-%S-$UUID.gz
    # IAM 角色认证（推荐）
    # 或使用 AWS 凭据
    # 从环境或 IAM 角色加载 AWS 凭据
    Retry_Limit       3

Kafka

[OUTPUT]
    Name              kafka
    Match             *
    Brokers           kafka-broker-1:9092,kafka-broker-2:9092
    Topics            logs
    # 消息格式
    Format            json
    # 时间戳键
    Timestamp_Key     @timestamp
    # 重试配置
    Retry_Limit       3
    # 队列配置
    rdkafka.queue.buffering.max.messages     100000
    rdkafka.request.required.acks            1

AWS CloudWatch Logs

[OUTPUT]
    Name              cloudwatch_logs
    Match             *
    region            us-east-1
    log_group_name    /aws/fluent-bit/logs
    log_stream_prefix from-fluent-bit-
    auto_create_group On
    Retry_Limit       3

OpenTelemetry (OTLP)

[OUTPUT]
    Name                 opentelemetry
    Match                *
    Host                 opentelemetry-collector.observability.svc
    Port                 4318
    # 使用 HTTP 协议进行 OTLP
    logs_uri             /v1/logs
    # 添加资源属性
    add_label            cluster my-cluster
    add_label            environment production
    # TLS 配置
    tls                  On
    tls.verify           Off
    # 重试配置
    Retry_Limit          3

Prometheus Remote Write

[OUTPUT]
    Name              prometheus_remote_write
    Match             *
    Host              prometheus.monitoring.svc
    Port              9090
    Uri               /api/v1/write
    # 为所有指标添加标签
    add_label         cluster my-cluster
    add_label         environment production
    # TLS 配置
    tls               On
    tls.verify        Off
    # 重试配置
    Retry_Limit       3
    # 压缩
    compression       snappy

HTTP 端点

[OUTPUT]
    Name              http
    Match             *
    Host              logs.example.com
    Port              443
    URI               /api/logs
    Format            json
    # TLS
    tls               On
    tls.verify        On
    # 认证
    Header            Authorization Bearer ${API_TOKEN}
    # 压缩
    Compress          gzip
    # 重试配置
    Retry_Limit       3

stdout（调试）

[OUTPUT]
    Name              stdout
    Match             *
    Format            json_lines

关键 OUTPUT 模式：

  1. 常见参数：

    • Name：输出插件名称
    • Match：要匹配的标签模式（支持通配符）
    • Retry_Limit：重试次数（0 = 无限）
    • storage.total_limit_size：磁盘缓冲限制

  2. 缓冲和重试配置：

    # 内存缓冲（默认）
storage.type      memory

# 文件系统缓冲（高可靠性）
storage.type      filesystem
storage.path      /var/log/fluent-bit-buffer/
storage.total_limit_size 10G

# 重试配置
Retry_Limit       5

  3. TLS 配置：

    tls               On
tls.verify        On
tls.ca_file       /path/to/ca.crt
tls.crt_file      /path/to/client.crt
tls.key_file      /path/to/client.key

OUTPUT 的最佳实践：

  • 始终设置 Retry_Limit（大多数情况下为 3-5）
  • 使用环境变量进行认证：${ENV_VAR}
  • 生产中启用 TLS
  • 设置 storage.total_limit_size 以防止磁盘耗尽
  • 可用时使用压缩（gzip）
  • 对于 Kubernetes：使用服务 DNS 名称
  • 如有需要，添加多个输出以实现冗余

第七阶段：PARSER 部分配置

重要：首先检查 examples/parsers.conf 然后再创建自定义解析器。示例目录包含适用于常见用例的生产就绪解析器定义。

步骤 1：阅读现有的解析器文件：

# 阅读 examples/parsers.conf 文件以查看可用的解析器
Read examples/parsers.conf

步骤 2：尽可能重用现有解析器。 examples/parsers.conf 包括：

  • docker - Docker JSON 日志格式
  • json - 通用 JSON 日志
  • cri - CRI 容器运行时格式
  • syslog-rfc3164 - Syslog RFC 3164
  • syslog-rfc5424 - Syslog RFC 5424
  • nginx - Nginx 访问日志
  • apache - Apache 访问日志
  • apache_error - Apache 错误日志
  • mongodb - MongoDB 日志
  • multiline-java - Java 堆栈跟踪
  • multiline-python - Python 回溯
  • multiline-go - Go 恐慌跟踪
  • multiline-ruby - Ruby 异常

步骤 3：仅在现有解析器不匹配您的日志格式时 才创建自定义解析器。

示例自定义解析器定义（仅在需要时）：

# parsers.conf - 在现有解析器旁边添加自定义解析器

[PARSER]
    Name        custom-app
    Format      regex
    Regex       ^(?<timestamp>\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}) \[(?<level>\w+)\] (?<message>.*)$
    Time_Key    timestamp
    Time_Format %Y-%m-%d %H:%M:%S

解析器类型：

  1. JSON：适用于 JSON 格式的日志
  2. Regex：适用于自定义日志格式
  3. LTSV：适用于 LTSV（带标签的制表符分隔值）
  4. Logfmt：适用于 logfmt 格式
  5. MULTILINE_PARSER：适用于多行日志（堆栈跟踪）

PARSER 的最佳实践：

  • 重用 examples/parsers.conf - 复制和扩展而不是从头开始
  • 使用内置解析器时（docker, cri, json）
  • 彻底测试 regex 模式
  • 设置 Time_Key 和 Time_Format 以获得正确的时间戳
  • 使用 MULTILINE_PARSER 用于堆栈跟踪
  • 在 SERVICE 部分引用解析器文件

第八阶段：完整配置结构

一个生产就绪的 Fluent Bit 配置遵循此结构：

fluent-bit.conf          # 主配置文件
parsers.conf             # 自定义解析器定义（可选）

在编写新配置之前，请咨询 examples/ 目录 以获取生产就绪的模板：

  • 审查与您的用例匹配的 examples/ 文件
  • 将它们用作起点并根据需要进行自定义
  • 参考 examples/parsers.conf 以获取解析器定义

示例完整配置（Kubernetes 到 Elasticsearch）：

# fluent-bit.conf

[SERVICE]
    Flush         1
    Daemon        Off
    Log_Level     info
    Parsers_File  parsers.conf
    HTTP_Server   On
    HTTP_Listen   0.0.0.0
    HTTP_Port     2020
    storage.metrics on

[INPUT]
    Name              tail
    Tag               kube.*
    Path              /var/log/containers/*.log
    Exclude_Path      /var/log/containers/*fluent-bit*.log
    Parser            docker
    DB                /var/log/flb_kube.db
    Mem_Buf_Limit     50MB
    Skip_Long_Lines   On
    Refresh_Interval  10

[FILTER]
    Name                kubernetes
    Match               kube.*
    Kube_URL            https://kubernetes.default.svc:443
    Kube_CA_File        /var/run/secrets/kubernetes.io/serviceaccount/ca.crt
    Kube_Token_File     /var/run/secrets/kubernetes.io/serviceaccount/token
    Kube_Tag_Prefix     kube.var.log.containers.
    Merge_Log           On
    Keep_Log            Off
    K8S-Logging.Parser  On
    K8S-Logging.Exclude On
    Labels              On
    Annotations         Off

[FILTER]
    Name          modify
    Match         *
    Add           cluster_name my-cluster
    Add           environment production

[FILTER]
    Name          nest
    Match         *
    Operation     lift
    Nested_under  kubernetes

[OUTPUT]
    Name              es
    Match             *
    Host              elasticsearch.logging.svc
    Port              9200
    Logstash_Format   On
    Logstash_Prefix   k8s
    Retry_Limit       3
    storage.total_limit_size 5M
    tls               On
    tls.verify        Off

第九阶段：最佳实践和优化

将这些最佳实践应用于所有生成的配置：

性能优化

  1. 缓冲管理：

    • 在输入上设置 Mem_Buf_Limit（默认 32MB 可能导致 OOM）
    • 对于高可靠性场景使用 storage.type filesystem
    • 设置 storage.total_limit_size 以防止磁盘耗尽
    • 推荐：每个输入 50-100MB，总磁盘缓冲 5-10GB

  2. 刷新和批处理：

    • Flush 1-5：在延迟和效率之间取得平衡
    • 较低刷新 = 较低延迟，较高 CPU/网络
    • 较高刷新 = 更好的批处理，更高的内存使用

  3. 工作线程：

    • 默认（0）自动检测 CPU 核心
    • 对于高容量环境增加
    • 调整前监控 CPU 使用情况

  4. 压缩：

    • 为网络输出启用压缩（gzip）
    • 减少 70-90% 的带宽
    • 轻微的 CPU 开销

可靠性

  1. 重试逻辑：

    • 在所有输出上设置 Retry_Limit 3-5
    • 对于关键日志使用文件系统缓冲
    • 考虑多个输出以实现冗余

  2. 健康检查：

  3. 数据库文件：

    • 对于 tail 输入使用 DB 参数
    • 启用位置跟踪跨重启
    • 在 Kubernetes 中存储在持久卷中

安全

  1. TLS/SSL：

    • 生产中始终启用 TLS（tls On）
    • 默认为 tls.verify On 用于生产部署
    • 使用 tls.verify Off 仅在以下情况下：
      • 内部 Kubernetes 集群流量与自签名证书
      • 开发/测试环境
      • 没有适当的 CA 证书（添加解释原因的注释）
    • 使用 tls.verify Off 时，总是添加解释原因的注释：
      tls               On
tls.verify        Off  # 内部集群具有自签名证书
    • 使用环境变量进行认证

  2. 凭据：

    • 从不硬编码密码
    • 使用环境变量：${VAR_NAME}
    • 或 Kubernetes 密钥挂载为环境变量

  3. RBAC（Kubernetes）：

    • 授予 ServiceAccount 最小权限
    • 只需要读取 pods/namespaces 的权限
    • 不需要写权限

资源限制

  1. 内存：

    • 设置每个输入的限制：Mem_Buf_Limit 50MB
    • Kubernetes 限制：典型 DaemonSet 为 200-500MB
    • 监控实际使用情况并调整

  2. CPU：

    • 通常 CPU 使用率低（每节点 5-50m）
    • 日志突发期间峰值
    • 根据工作负载设置请求/限制

  3. 磁盘：

    • 仅用于文件系统缓冲
    • 推荐：每节点 5-10GB
    • 使用 storage.metrics on 监控

日志最佳实践

  1. 结构化日志记录：

    • 首选应用程序中的 JSON 日志
    • 更容易解析和查询
    • 比 regex 更好的性能

  2. 日志级别：

    • 在应用程序中使用适当的日志级别
    • 使用 grep 过滤器过滤嘈杂的日志
    • 减少体积 = 降低成本

  3. 避免日志循环：

    • 排除 Fluent Bit 自身的日志
    • 使用 Exclude_Path 模式
    • 如果需要，使用标签过滤

第十阶段：验证生成的配置

始终使用 devops-skills:fluentbit-validator 技能验证生成的配置：

调用 devops-skills:fluentbit-validator 技能以验证配置：
1. 语法验证（部分格式，键值对）
2. 必填字段检查
3. 插件参数验证
4. 标签一致性检查
5. 解析器引用验证
6. 安全检查（明文密码）
7. 最佳实践建议
8. 干运行测试（如果可用 fluent-bit 二进制文件）

遵循 devops-skills:fluentbit-validator 工作流程以识别和修复任何问题。

验证清单：

  • 配置语法正确（INI 格式）
  • 所有必需参数都存在
  • 插件名称有效
  • 标签在各部分之间一致
  • 解析器文件和引用存在
  • 设置了缓冲限制
  • 配置了重试限制
  • 生产中启用了 TLS
  • 没有硬编码的凭据
  • 内存限制合理

如果验证失败，请修复问题并重新验证，直到所有检查通过。

错误处理

常见问题和解决方案

  1. 配置语法错误：

    • 检查部分标题：[SECTION] 格式
    • 验证键值缩进（空格，不是制表符）
    • 检查插件名称中的拼写错误
    • 使用验证器进行语法检查

  2. 内存问题（OOM）：

    • 在所有 tail 输入上设置 Mem_Buf_Limit
    • 如果内存受限，则减少缓冲限制
    • 启用文件系统缓冲以应对溢出
    • 检查 Kubernetes 内存限制

  3. 缺少日志：

    • 验证文件路径是否存在
    • 检查文件权限（读取权限）
    • 验证过滤器/输出中的标签匹配
    • 检查 DB 文件的位置跟踪
    • 查看 Exclude_Path 模式

  4. 解析器失败：

    • 使用样本日志测试 regex 模式
    • 验证解析器文件是否在 SERVICE 中引用
    • 检查 Time_Format 是否与日志时间戳匹配
    • 启用调试日志以查看解析器错误

  5. Kubernetes 元数据缺失：

    • 验证 RBAC 权限（ServiceAccount, ClusterRole）
    • 检查 Kube_URL 是否正确（通常为 https://kubernetes.default.svc:443）
    • 验证 Kube_CA_File 和 Kube_Token_File 路径
    • 检查 Kube_Tag_Prefix 是否与输入标签匹配

  6. 输出连接失败：

    • 验证主机和端口是否正确
    • 检查网络连接（DNS 解析）
    • 如果启用了 TLS，请验证 TLS 配置
    • 检查认证凭据
    • 查看重试限制设置

  7. 高 CPU 使用率：

    • 减少刷新频率
    • 简化 regex 解析器
    • 减少过滤器复杂性
    • 考虑工作线程

  8. 磁盘已满（缓冲）：

    • 设置 storage.total_limit_size
    • 监控磁盘使用情况
    • 清理旧缓冲文件
    • 调整刷新间隔

沟通指南

生成配置时：

  1. 解释结构 - 描述配置部分及其目的
  2. 记录决策 - 解释为什么选择某些插件或设置
  3. 突出定制 - 指出应定制的参数
  4. 提供示例 - 展示如何根据不同场景使用配置
  5. 参考文档 - 在有帮助时链接到相关 Fluent Bit 文档
  6. 主动验证 - 始终验证生成的配置并修复问题
  7. 安全提醒 - 强调凭据和 TLS 要求
  8. 性能注释 - 解释缓冲限制和刷新间隔

与 devops-skills:fluentbit-validator 集成

生成任何 Fluent Bit 配置后，自动调用 devops-skills:fluentbit-validator 技能 以确保质量：

步骤：
1. 生成 Fluent Bit 配置
2. 调用 devops-skills:fluentbit-validator 技能并使用配置文件
3. 查看验证结果
4. 修复识别的任何问题
5. 重新验证直到所有检查通过
6. 提供生成的配置和验证状态的摘要

这确保所有生成的配置遵循最佳实践并且准备投入生产。

资源

scripts/

generate_config.py

  • 生成 Fluent Bit 配置的 Python 脚本
  • 基于模板的方法，包含常见用例
  • 支持 13 个用例：
    • kubernetes-elasticsearch - K8s 日志到 Elasticsearch
    • kubernetes-loki - K8s 日志到 Loki
    • kubernetes-cloudwatch - K8s 日志到 CloudWatch
    • kubernetes-opentelemetry - K8s 日志到 OpenTelemetry（NEW）
    • application-multiline - 应用日志与多行解析
    • syslog-forward - Syslog 转发
    • file-tail-s3 - 文件尾随到 S3
    • http-kafka - HTTP webhook 到 Kafka
    • multi-destination - 多个输出目的地
    • prometheus-metrics - Prometheus 指标收集（NEW）
    • lua-filtering - Lua 脚本过滤（NEW）
    • stream-processor - 流处理器用于分析（NEW）
    • custom - 最小自定义模板
  • 用法：python3 scripts/generate_config.py --use-case kubernetes-elasticsearch --output fluent-bit.conf

examples/

包含生产就绪的示例配置：

  • kubernetes-elasticsearch.conf - K8s 日志到 Elasticsearch 与元数据丰富
  • kubernetes-loki.conf - K8s 日志到 Loki 与标签
  • kubernetes-opentelemetry.conf - K8s 日志到 OpenTelemetry 收集器（OTLP/HTTP）
  • application-multiline.conf - 应用日志与堆栈跟踪解析
  • syslog-forward.conf - Syslog 收集和转发
  • file-tail-s3.conf - 文件尾随到 S3 与压缩
  • http-input-kafka.conf - HTTP webhook 到 Kafka
  • multi-destination.conf - 日志到多个输出（Elasticsearch + S3）
  • prometheus-metrics.conf - 指标收集和 Prometheus 远程写入
  • lua-filtering.conf - 自定义 Lua 脚本过滤和转换
  • stream-processor.conf - 类似 SQL 的流处理用于分析
  • parsers.conf - 自定义解析器示例（JSON, regex, 多行）
  • full-production.conf - 完整的生产设置
  • cloudwatch.conf - AWS CloudWatch 集成

文档来源

基于以下综合研究：