将 Logstash Pipeline 从 Azure Event Hubs 迁移到 OTel Collector Kafka Receiver

Elasticsearch
0 阅读6分钟

作者：来自 Elastic Álex Cámara

逐步指南：将 Logstash pipeline 从 Azure Event Hubs 插件迁移到 OpenTelemetry Collector Kafka receiver。

介绍

本文是《Logstash Azure Event Hubs 到 Kafka input plugin 迁移》的配套指南，介绍另一种迁移路径：使用 OpenTelemetry Collector 的 kafka receiver 替换 logstash-input-azure_event_hubs，从 Azure Event Hubs 的 Kafka endpoint 消费数据。

关于迁移原因、认证注意事项，以及 offset 管理等关键行为变化，请参考原始文章。

参考：关于 OTel Kafka receiver 的详细配置选项或参数默认值，请参阅 Kafka Receiver README。

配置转换

TLS 配置

Azure Event Hubs 要求所有 Kafka 连接都必须通过 9093 端口使用 TLS。tls: {} 配置块会启用默认 TLS 设置（系统 CA 证书、无客户端证书），这已经足够满足 Azure Event Hubs 的要求。如果省略该配置块，连接将失败，因为 broker 期望进行 TLS handshake。

编码（Encoding）

encoding 字段用于控制 receiver 如何解析每条 Kafka 消息 payload。对于从 Azure Event Hubs 消费的事件，最常见的选项包括：

  • text：将 payload 解码为文本，并作为日志记录的 body 插入。默认使用 UTF-8；如果需要其他字符集，可使用 text_（例如 text_shift_jis）
  • raw：按原始字节形式直接插入日志记录 body
  • json：将 payload 解码为 JSON，并作为日志记录 body 插入
  • azure_resource_logs：将 Azure Resource Logs 格式转换为 OpenTelemetry 格式

此外，还支持 otlp_proto、otlp_json，以及 trace 专用格式（jaeger_proto、zipkin_json 等）。完整列表请参阅 Kafka Receiver README。

基础配置

最小配置示例：通过 SASL/PLAIN 从单个 Event Hub 消费日志。

`

1.  receivers:
2.    kafka:
3.      brokers:
4.        - "<NAMESPACE>.servicebus.windows.net:9093"
5.      group_id: "<CONSUMER_GROUP_NAME>"
6.      auth:
7.        sasl:
8.          username: "$ConnectionString"
9.          password: "Endpoint=sb://<NAMESPACE>.servicebus.windows.net/;SharedAccessKey
10.          mechanism: "PLAIN"
11.      tls: {}
12.      logs:
13.        topics:
14.          - "<EVENT_HUB_NAME>"
15.        encoding: text

`AI写代码![](https://csdnimg.cn/release/blogv2/dist/pc/img/runCode/icon-arrowwhite.png)

高级配置

多 Event Hubs 示例配置如下：

`

1.  receivers:
2.    kafka/eh1:
3.      brokers:
4.        - "<NAMESPACE>.servicebus.windows.net:9093"
5.      group_id: "<CONSUMER_GROUP_1>"
6.      auth:
7.        sasl:
8.          username: "$ConnectionString"
9.          password: "Endpoint=sb://<NAMESPACE>.servicebus.windows.net/;SharedAccessKey
10.          mechanism: "PLAIN"
11.      tls: {}
12.      logs:
13.        topics:
14.          - "<EVENT_HUB_1>"
15.        encoding: text

17.    kafka/eh2:
18.      brokers:
19.        - "<NAMESPACE>.servicebus.windows.net:9093"
20.      group_id: "<CONSUMER_GROUP_2>"
21.      auth:
22.        sasl:
23.          username: "$ConnectionString"
24.          password: "Endpoint=sb://<NAMESPACE>.servicebus.windows.net/;SharedAccessKey
25.          mechanism: "PLAIN"
26.      tls: {}
27.      logs:
28.        topics:
29.          - "<EVENT_HUB_2>"
30.        encoding: text

`AI写代码![](https://csdnimg.cn/release/blogv2/dist/pc/img/runCode/icon-arrowwhite.png)

配置参数映射

下面这一部分将 logstash-input-azure_event_hubs 的参数逐项映射到 OpenTelemetry Collector kafka receiver 的等效配置。

1）checkpoint_interval：直接映射到 autocommit.interval。

单位差异：Azure 的 checkpoint_interval 以秒为单位，而 OTel 的 autocommit.interval 需要使用 duration 字符串格式（例如 10s、500ms）。

Azure 配置示例：

`

1.  input {
2.      azure_event_hubs {
3.          # ... other params ...
4.          checkpoint_interval => 10 # Default 5
5.      }
6.  }

`AI写代码

OTel receiver 等效配置如下：

`

1.  receivers:
2.    kafka:
3.      # ... other params ...
4.      autocommit:
5.        interval: 10s # Default 1s

`AI写代码

2）initial_position：映射到 initial_offset。

Azure 配置示例：

`

1.  input {
2.      azure_event_hubs {
3.          initial_position => "end"
4.      }
5.  }

`AI写代码

OTel receiver 等效配置如下：

`

1.  receivers:
2.    kafka:
3.      initial_offset: latest

`AI写代码

值映射如下：

Azure 值OTel 值
beginningearliest
endlatest（默认）
look_back不直接支持

注意：由于 Kafka receiver 无法读取旧的 Blob Storage checkpoint，它会将此次迁移视为首次连接。为了避免重复处理 legacy 插件已经消费过的数据，在初始部署时应将 initial_offset 设置为 latest。

3）max_batch_size：没有直接的一对一映射。

在 OTel 中，事件批处理的最大值不能由 receiver 直接控制。receiver 只负责控制每次 fetch 请求读取的数据量，通过 min_fetch_size、max_fetch_size 和 max_fetch_wait 来调节。

真正的事件批处理发生在 processing 层，由 batch processor 在 pipeline 阶段进行聚合。

单位说明：

  • min_fetch_size / max_fetch_size：字节（bytes）

  • max_fetch_wait：duration 字符串（例如 250ms）

  • send_batch_size：记录数量

  • timeout：duration 字符串（例如 5s）

Azure 配置示例：

`

1.  input {
2.      azure_event_hubs {
3.          max_batch_size => 125
4.      }
5.  }

`AI写代码

OTel receiver 示例配置如下：

`

1.  receivers:
2.    kafka:
3.      max_fetch_size: 2097152  # bytes (2 MiB)
4.      max_fetch_wait: 250ms

6.  processors:
7.    batch:
8.      send_batch_size: 125  # number of log records

`AI写代码

4）threads：无直接映射。

Event Hubs 通过 partition 来分配工作负载。单个 Collector 的 Kafka client 可以并行读取多个 partition，因为底层 Kafka client（franz-go）会使用内部 goroutine 并发处理 partition 数据流。这种并发是内部实现的，不通过用户可配置的 threads 参数控制。

5）decorate_events：Kafka receiver 不支持该功能。

性能对比

以下结果使用与配套文章中相同的测试环境：相同的 Event Hub 命名空间、相同数量的 partition，以及相同的 batch / thread 配置。绝对数值会因环境不同而变化，但关键在于相对差异。

组件Payload吞吐量（events/s）
Logstash azure_event_hubs plugin100B~5700
OTel Collector kafka receiver100B~10900
Logstash azure_event_hubs plugin1KB~1500
OTel Collector kafka receiver1KB~1900
Logstash azure_event_hubs plugin10KB~170
OTel Collector kafka receiver10KB~190

跨所有 payload 大小来看，OTel Collector kafka receiver 的吞吐量均优于 Logstash azure_event_hubs plugin，其中在小 payload（100B）场景下提升最大（约 1.9 倍），因为此时协议开销占主导；随着 payload 增大，优势逐渐收敛（1KB 约 1.3 倍，10KB 约 1.1 倍）。

不过，它仍未达到配套文章中Logstash kafka plugin 的吞吐水平，但在所有测试场景中都优于旧版 azure_event_hubs plugin。

与此同时，OTel 路径还移除了 Blob Storage 和 GPv2 依赖，从架构层面减少了两类需要部署、加固与监控的基础设施组件。

结论

两种迁移路径都能：

  • 消除 Blob Storage checkpoint 依赖

  • 提升相较 legacy azure_event_hubs plugin 的吞吐性能

其中：

  • Logstash kafka plugin：迁移成本最低（配置改动最小、offset 模型保持一致），且在测试中吞吐最高，适合追求“低摩擦升级”的场景

  • OTel Collector kafka receiver：适合希望彻底移除 Logstash、并统一到 OpenTelemetry 体系的架构。它以较低峰值吞吐和缺少 decorate_events 等能力为代价，换取一个 vendor-neutral 的 ingestion 层，并可与同一 Collector 中的其他 OTel pipeline 并行运行

下一步

随着 GPv1 在 2026 年 10 月退役日期临近，尽早开始迁移可以减少仍依赖存储基础设施的维护成本。

如在迁移过程中遇到问题：

相关资源

原文：www.elastic.co/observabili…

avatar
文章
阅读
粉丝