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

作者：来自 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 消费日志。

receivers:
  kafka:
    brokers:
      - "<NAMESPACE>.servicebus.windows.net:9093"
    group_id: "<CONSUMER_GROUP_NAME>"
    auth:
      sasl:
        username: "$ConnectionString"
        password: "Endpoint=sb://<NAMESPACE>.servicebus.windows.net/;SharedAccessKeyName=<ACCESS_KEY_NAME>;SharedAccessKey=<ACCESS_KEY>"
        mechanism: "PLAIN"
    tls: {}
    logs:
      topics:
        - "<EVENT_HUB_NAME>"
      encoding: text

高级配置

多 Event Hubs 示例配置如下：

receivers:
  kafka/eh1:
    brokers:
      - "<NAMESPACE>.servicebus.windows.net:9093"
    group_id: "<CONSUMER_GROUP_1>"
    auth:
      sasl:
        username: "$ConnectionString"
        password: "Endpoint=sb://<NAMESPACE>.servicebus.windows.net/;SharedAccessKeyName=<KEY_1>;SharedAccessKey=<ACCESS_KEY_1>"
        mechanism: "PLAIN"
    tls: {}
    logs:
      topics:
        - "<EVENT_HUB_1>"
      encoding: text

  kafka/eh2:
    brokers:
      - "<NAMESPACE>.servicebus.windows.net:9093"
    group_id: "<CONSUMER_GROUP_2>"
    auth:
      sasl:
        username: "$ConnectionString"
        password: "Endpoint=sb://<NAMESPACE>.servicebus.windows.net/;SharedAccessKeyName=<KEY_2>;SharedAccessKey=<ACCESS_KEY_2>"
        mechanism: "PLAIN"
    tls: {}
    logs:
      topics:
        - "<EVENT_HUB_2>"
      encoding: text

配置参数映射

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

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

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

Azure 配置示例：

input {
    azure_event_hubs {
        # ... other params ...
        checkpoint_interval => 10 # Default 5
    }
}

OTel receiver 等效配置如下：

receivers:
  kafka:
    # ... other params ...
    autocommit:
      interval: 10s # Default 1s

2）initial_position：映射到 initial_offset。

Azure 配置示例：

input {
    azure_event_hubs {
        initial_position => "end"
    }
}

OTel receiver 等效配置如下：

receivers:
  kafka:
    initial_offset: latest

值映射如下：

Azure 值	OTel 值
beginning	earliest
end	latest（默认）
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 配置示例：

input {
    azure_event_hubs {
        max_batch_size => 125
    }
}

OTel receiver 示例配置如下：

receivers:
  kafka:
    max_fetch_size: 2097152  # bytes (2 MiB)
    max_fetch_wait: 250ms

processors:
  batch:
    send_batch_size: 125  # number of log records

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 plugin	100B	~5700
OTel Collector kafka receiver	100B	~10900
Logstash azure_event_hubs plugin	1KB	~1500
OTel Collector kafka receiver	1KB	~1900
Logstash azure_event_hubs plugin	10KB	~170
OTel Collector kafka receiver	10KB	~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 月退役日期临近，尽早开始迁移可以减少仍依赖存储基础设施的维护成本。

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

• 使用问题或配置帮助：可在 OpenTelemetry Collector GitHub Discussions 或 Elastic Discuss forum 提问

• Kafka receiver 的 bug 或异常行为：在 opentelemetry-collector-contrib 仓库提交 issue

相关资源

• Kafka receiver 文档：OTel Collector kafka receiver 的完整配置参考

• Azure Event Hubs input plugin 文档：旧插件的完整参考

• Logstash Azure Event Hubs to Kafka input plugin migration：迁移到 logstash-input-kafka 的替代路径

• Azure Event Hubs for Apache Kafka 概览：Event Hubs Kafka endpoint 官方说明

• Event Hubs quotas and tier comparison：Kafka 协议支持所需的服务层级说明

原文：https://www.elastic.co/observability-labs/blog/migrate-logstash-pipelines-from-azure-event-hubs-to-otel-collector-kafka-receiver