Logging Docs
  • 简体中文

    • 如何调优 aggregate-vector Sink

    aggregate-vector 从 Kafka 读取记录，并将其写入 ClickHouse 或 OpenSearch。其批处理、缓冲、重试和并发默认值适用于绝大多数集群。当平台默认配置不适用时——例如 ClickHouse 抛出 TooManyParts、OpenSearch 触发批量熔断器，或者您希望 collector 牺牲延迟以换取更大的刷新量——平台会在 PlatformLogForward.spec.aggregateVector.sinks.* 上提供调优参数。

    每个字段都是可选的。未设置的字段将遵循平台默认基线；升级从未使用过这些调优参数的集群不会产生任何变化。

    log-storage-operator 会在每次变更时协调 PlatformLogForward，并在调优参数发生变化时自动滚动更新 aggregate-vector。无需执行 kubectl rollout restart。

    目录

    开始之前何时调优ClickHouse sink 参数OpenSearch sink 参数示例 — ClickHouse示例 — OpenSearch应用并验证相关主题

    开始之前

    • 已在存储集群上安装 Alauda Container Platform Log Storage Management，且 PlatformLogForward/platform-default 为 Ready。请参阅安装。
    • 使用 kubectl edit platformlogforward platform-default 编辑 PlatformLogForward。

    何时调优

    参数作用域取决于后端

    仅当 PlatformLogForward.spec.externalStorage.type 为 clickhouse 时，才会呈现 spec.aggregateVector.sinks 下的 clickhouse 块。仅当类型为 opensearch 时，才会呈现 opensearch 块。在运行中的集群上为另一后端设置参数不会产生任何提示或效果——这些值会保留在 CR 中，但永远不会传递到 Vector。在编辑前，请使用 kubectl get platformlogforward platform-default -o jsonpath='{.spec.externalStorage.type}' 验证后端。

    当您在生产环境中观察到某个特定症状时，可以使用这些调优参数。不要预先更改默认值。

    症状Sink可考虑的字段
    ClickHouse 日志频繁显示 TooManyParts / max_partitions_per_insert_blockClickHouserequestConcurrency（降低为固定值）、batchMaxEvents（增大刷新量）
    ClickHouse HTTP 413 Payload Too LargeClickHousebatchMaxBytes（降低）
    审计摄取延迟过高ClickHouse 或 OpenSearchbatchTimeoutSecs（降低）
    即使存储后端看起来处于空闲状态，Kafka 堆积量仍在增加任一bufferMaxEvents（增大）
    Pod 内存压力或 Killed 事件出现在 aggregate-vector 上任一bufferMaxEvents（减小）
    OpenSearch 批量熔断器触发（network.breaker.inflight_requests）OpenSearchbatchMaxBytes（降低）
    OpenSearch 集群滚动更新或 GC 暂停导致临时写入失败OpenSearchrequestRetryMaxDurationSecs（最高可达 3600）
    OpenSearch 反复触发 es_rejected_execution_exception，导致您这边出现“重复索引”告警OpenSearchretryPartial: false（请参阅注意事项）

    如果您的症状不在此列表中，请先收集存储端错误，再进行调优；没有具体原因就更改参数通常会使情况变得更糟。

    ClickHouse sink 参数

    在 spec.aggregateVector.sinks.clickhouse 下设置。

    字段类型默认值何时更改
    batchMaxEventsinteger（≥ 1）50000当 CH 集群报告存在过多小型数据 part 时，增大此值以使 ClickHouse 刷新批次更大且频率更低。如果刷新延迟很重要，则对审计日志降低此值。
    batchMaxBytesinteger（≥ 1024）52428800（50 MB）当 ClickHouse 返回 413 Payload Too Large，或到 CH 的网络速度过慢以至于大批量刷新会触发超时时，降低此值。
    batchTimeoutSecsinteger（≥ 1）60对实时性敏感的日志类型（通常是审计日志）降低此值。
    bufferMaxEventsinteger（≥ 1）50000当摄取管道过于频繁地对 Kafka 消费施加反压时，增大此值。当 Pod 内存限制较为紧张时，降低此值。
    bufferWhenFullblock | drop_newestblock仅对于允许平台丢弃最新事件而不是对 Kafka 施加反压的非合规工作负载，才将其更改为 drop_newest。
    requestConcurrencyadaptive | fixed | 正整数adaptive（Vector 默认值）当 ClickHouse 无法跟上自适应并发时，将其设置为类似 "4" 的固定正整数（典型的明显迹象是 TooManyParts）。
    requestRetryAttemptsinteger（≥ -1）-1（无限）仅当您需要针对 CH 反复失败进行告警，而不是透明重试时，才将其限制为正整数。
    requestRetryMaxDurationSecsinteger（≥ 1）30对于 ClickHouse 会滚动更新或存在 30–120 秒短暂中断窗口的集群，将其增大至 3600。

    注意：

    • Vector 的 buffer.type 始终为 memory，不可调优。Kafka 是持久缓冲区；在 Vector 内增加第二个磁盘缓冲区只会重复持久性保障，并不会提供额外安全性。当内存缓冲区填满时，Vector 会对 Kafka source 施加反压，记录仍保留在 broker 上；Vector 重启后会从上次提交的 offset 重新处理这些记录。
    • requestConcurrency 接受三种形式：字符串 "adaptive" 或 "fixed"，或者以字符串形式写入的正整数（例如 "4"）。平台会将带引号的字符串渲染为带引号的字符串，并将整数字符串在 Vector 配置中渲染为不带引号的整数。

    OpenSearch sink 参数

    在 spec.aggregateVector.sinks.opensearch 下设置。相同的参数也适用于旧版 Elasticsearch 后端（output.type: elasticsearch）。

    字段类型默认值何时更改
    batchMaxBytesinteger（≥ 1024）5242880（5 MB）最重要的 OpenSearch 参数。在具有较大堆内存的 OpenSearch 集群上，将其增大至 10485760（10 MB）；当您看到批量请求 breaker（network.breaker.inflight_requests）伴随 HTTP 429 触发时，将其降低。
    batchMaxEventsinteger（≥ 1）100000很少是主要的限流因素；batchMaxBytes 和 batchTimeoutSecs 通常会先触发刷新。如果希望由事件数量驱动刷新，则降低此值。
    batchTimeoutSecsinteger（≥ 1）60对实时性敏感的日志类型降低此值。
    bufferMaxEventsinteger（≥ 1）50000当 OpenSearch 处于空闲状态但 Kafka 堆积量不断增加时，增大此值；当 Pod 内存紧张时，降低此值。
    requestRetryMaxDurationSecsinteger（≥ 1）3600（1 h）默认值适用于 OpenSearch 滚动更新和 GC 暂停。仅当 OpenSearch 环境非常稳定，且 1 小时的重试窗口会产生噪声时才降低此值；增大此值很少有用。
    retryPartialbooleantrue是否重试项目级部分失败（es_rejected_execution_exception、too_many_requests），而不是静默丢弃。除非有明确理由选择退出，否则保留 true。

    retryPartial: false 注意：仅当您有充分理由时才禁用部分失败重试（例如，您的监控无法容忍重试可能触发的重复索引告警），并且您已验证平台的幂等 bulk.action = create + 文档 _id 模式会消除重复记录。在较早的 ACP 版本中，默认值实际上为 false，某个生产集群因此静默丢弃了 79,000 条记录；当前默认值 true 正是为了防止此类事故。

    注意：

    • Vector 的 buffer.type 为 memory，而 buffer.when_full 为 block；二者均不可调优。相关原因请参阅 ClickHouse sink 的注意事项。
    • compression: gzip、bulk.action: create 和 api_version: v8 由平台固定，因为它们体现了 OpenSearch 写入路径的不变量（压缩可将网络传输量减少 3–5 倍；create + 文档 _id 可确保重试具有幂等性；v8 可避免使用已移除的 _type 字段，而 OpenSearch 3.7 会拒绝该字段）。这些参数不会作为可调参数公开。

    示例 — ClickHouse

    apiVersion: log.alauda.io/v1alpha1
kind: PlatformLogForward
metadata:
  name: platform-default
spec:
  output:
    type: clickhouse
  externalStorage:
    type: clickhouse
    secretRef:
      name: platform-default-ch-conn
      namespace: cpaas-system
  externalMessageQueue:
    type: kafka
    secretRef:
      name: platform-default-mq-conn
      namespace: cpaas-system
  aggregateVector:
    replicas: 3
    sinks:
      clickhouse:
        # ClickHouse reports frequent small parts; let the flush build larger.
        batchMaxBytes: 20971520          # 20 MiB
        batchMaxEvents: 200000
        batchTimeoutSecs: 30
        # The pipeline back-pressures Kafka too often; grow the buffer while
        # keeping block so no record is dropped.
        bufferMaxEvents: 200000
        bufferWhenFull: block
        # Production ClickHouse rolls occasionally; give retries an hour of budget.
        requestRetryMaxDurationSecs: 3600
        # ClickHouse TooManyParts; move from adaptive to fixed 4-way concurrency.
        requestConcurrency: "4"

    示例 — OpenSearch

    apiVersion: log.alauda.io/v1alpha1
kind: PlatformLogForward
metadata:
  name: platform-default
spec:
  externalStorage:
    type: opensearch
    secretRef:
      name: platform-default-os-conn
      namespace: cpaas-system
  externalMessageQueue:
    type: kafka
    secretRef:
      name: platform-default-mq-conn
      namespace: cpaas-system
  aggregateVector:
    replicas: 3
    sinks:
      opensearch:
        # Large-heap OpenSearch cluster; take 10 MiB flushes for better throughput.
        batchMaxBytes: 10485760
        # The pipeline back-pressures Kafka too often; grow the buffer.
        bufferMaxEvents: 200000
        # Keep the default 1-hour retry window for OpenSearch rolls.
        requestRetryMaxDurationSecs: 3600
        # Only set this to false when your monitoring cannot tolerate the
        # duplicate-index alert triggered by transparent partial retry,
        # and after you have verified that the bulk.action=create idempotent
        # path holds in your data.
        # retryPartial: false

    应用并验证

    保存资源后：

    kubectl get platformlogforward platform-default -w

    Ready 列应保持为 True。log-storage-operator 会将新的 Vector 配置渲染到 cpaas-system 中的 aggregate-vector-config ConfigMap，并滚动更新 aggregate-vector Deployment。

    验证新值是否已写入 Vector 的配置：

    kubectl -n cpaas-system get cm aggregate-vector-config \
  -o jsonpath='{.data.vector\.toml}' | grep -A 4 '\[sinks'

    如果您设置的某个参数未出现在 ConfigMap 中，请检查字段名称以及 PLF 状态条件中是否存在验证错误。

    相关主题