« Plain 编解码插件 Rubydebug 编解码插件 »
Elastic 文档 ›Logstash 参考 [8.14] ›编解码插件

Protobuf 编解码插件

编辑

Protobuf 编解码插件编辑

  • 插件版本：v1.3.0
  • 发布日期：2023-09-20
  • 变更日志

有关其他版本，请参阅 版本化插件文档。

安装编辑

对于默认情况下未捆绑的插件，可以通过运行 bin/logstash-plugin install logstash-codec-protobuf 轻松安装。有关更多详细信息，请参阅 使用插件。

获取帮助编辑

有关插件的问题，请在 讨论 论坛中发布主题。对于错误或功能请求，请在 Github 中打开问题。有关 Elastic 支持的插件列表，请参阅 Elastic 支持矩阵。

描述编辑

此编解码器将 protobuf 编码的消息转换为 logstash 事件，反之亦然。它支持 protobuf 版本 2 和 3。

该插件需要将 protobuf 定义编译为 ruby 文件。
对于 protobuf 2，请使用 ruby-protoc 编译器。
对于 protobuf 3，请使用 官方 google protobuf 编译器。

以下显示了从 kafka 流解码事件的用法示例（protobuf v2）

kafka
{
  topic_id => "..."
  key_deserializer_class => "org.apache.kafka.common.serialization.ByteArrayDeserializer"
  value_deserializer_class => "org.apache.kafka.common.serialization.ByteArrayDeserializer"
  codec => protobuf
  {
    class_name => "Animals::Mammals::Unicorn"
    class_file => '/path/to/pb_definitions/some_folder/Unicorn.pb.rb'
    protobuf_root_directory => "/path/to/pb_definitions/"
  }
}

protobuf v3 的解码器用法示例

kafka
{
  topic_id => "..."
  key_deserializer_class => "org.apache.kafka.common.serialization.ByteArrayDeserializer"
  value_deserializer_class => "org.apache.kafka.common.serialization.ByteArrayDeserializer"
  codec => protobuf
  {
    class_name => "Animals.Mammals.Unicorn"
    class_file => '/path/to/pb_definitions/some_folder/Unicorn_pb.rb'
    protobuf_root_directory => "/path/to/pb_definitions/"
    protobuf_version => 3
  }
}

该编解码器可以在输入和输出插件中使用。
在 kafka 输入插件中使用编解码器时，请按上述方式设置反序列化器类。
在输出插件中使用编解码器时

  • 确保在 protobuf 定义中包含所有所需的字段，包括时间戳。使用 mutate 过滤器从事件中删除不是 protobuf 定义一部分的字段。如果事件包含不在 protobuf 定义中的字段，则编码将失败。
  • 在加载 protobuf 定义以进行编码时，目前不支持 @ 符号作为字段名称。确保在 protobuf 文件中将时间戳字段命名为 timestamp 而不是 @timestamp。Logstash 事件字段将在转换之前去除前导 @。
  • 值为 nil 的字段将自动从事件中删除。空字段不会被删除。
  • 建议将配置选项 pb3_encoder_autoconvert_types 设置为 true。否则，任何数据与 protobuf 定义之间的类型不匹配都会导致事件丢失。自动类型转换不会改变您的数据。它只是尝试将明显相同的数据转换为预期的数据类型，例如将整数转换为浮点数（如果预期为浮点数），或将“true”/“false”字符串转换为布尔值（如果预期为布尔值）。
  • 写入 Kafka 时：设置序列化器类：value_serializer => "org.apache.kafka.common.serialization.ByteArraySerializer"

编码器用法示例（protobufg v3）

kafka
  {
    codec => protobuf
    {
      class_name => "Animals.Mammals.Unicorn"
      class_file => '/path/to/pb_definitions/some_folder/Unicorn_pb.rb'
      protobuf_root_directory => "/path/to/pb_definitions/"
      protobuf_version => 3
    }
    value_serializer => "org.apache.kafka.common.serialization.ByteArraySerializer"
  }
}

Protobuf 编解码器配置选项编辑

设置 输入类型 必需

class_name

字符串

是

class_file

字符串

否

protobuf_root_directory

字符串

否

include_path

数组

否

protobuf_version

数字

是

stop_on_error

布尔值

否

pb3_encoder_autoconvert_types

布尔值

否

 

class_name编辑

  • 这是一个必需的设置。
  • 值类型为 字符串
  • 此设置没有默认值。

要解码的类的完全限定名称。请注意，模块分隔符根据 protobuf 版本的不同而不同。对于 protobuf v2，请使用双冒号

class_name => "Animals::Mammals::Unicorn"

对于 protobuf v3，请使用单点

class_name => "Animals.Mammals.Unicorn"

对于 protobuf v3，您可以从生成的 protobuf ruby 文件末尾的 Descriptorpool 注册中复制类名。它包含类似于以下内容的行

Animals.Mammals.Unicorn = Google::Protobuf::DescriptorPool.generated_pool.lookup("Animals.Mammals.Unicorn").msgclass

如果您的类引用其他定义：您只需要在此处添加主类的名称。

class_file编辑

  • 值类型为 字符串
  • 此设置没有默认值。

包含所有已编译 protobuf 文件的目录的绝对路径。如果 protobuf 定义分布在多个文件夹中，则此路径需要指向包含所有这些文件夹的文件夹。

protobuf_root_directory编辑

  • 值类型为 字符串
  • 此设置没有默认值。

包含主类 (class_name) 或其任何依赖项的所有引用/使用的依赖项的根目录的绝对路径。必须与 class_file 设置一起使用，并且不能与旧的加载机制 include_path 一起使用。

示例

 pb3
   ├── header
   │   └── header_pb.rb
   ├── messageA_pb.rb

在这种情况下，messageA_pb.rb 包含来自 header/header_pb.rb 的嵌入式消息。如果 class_file 设置为 messageA_pb.rb，并且 class_name 设置为 MessageA，则 protobuf_root_directory 必须设置为 /path/to/pb3，其中包含这两个定义。

include_path编辑

  • 值类型为 数组
  • 此设置没有默认值。

用于向后兼容的旧版 protobuf 定义加载机制：包含 protobuf 定义的文件的绝对路径列表。当使用多个文件时，请确保以相反的依赖顺序排列文件，以便在其他文件引用类之前加载每个类。

示例：一个名为 Unicorn 的类引用另一个名为 Wings 的 protobuf 类

module Animal
  module Mammal
    class Unicorn
      set_fully_qualified_name "Animal.Mammal.Unicorn"
      optional ::Bodypart::Wings, :wings, 1
      optional :string, :name, 2
      ...

将配置为

include_path => ['/path/to/pb_definitions/wings.pb.rb','/path/to/pb_definitions/unicorn.pb.rb']

请注意，protobuf v2 文件以 .pb.rb 结尾，而为 protobuf v3 编译的文件以 _pb.rb 结尾。

不能与 protobuf_root_directory 或 class_file 一起使用。

protobuf_version编辑

  • 值类型为 数字
  • 默认值为 2

协议缓冲区版本。有效设置是 2、3。

stop_on_error编辑

在遇到不可解码的消息时停止整个管道。

pb3_encoder_autoconvert_types编辑

将数据类型转换为与 protobuf 定义匹配（如果可能）。protobuf 编码器库对数据类型非常严格。例如，一个事件有一个整数字段，但 protobuf 定义期望一个浮点数。这会导致异常，并且事件将丢失。

此功能尝试将数据类型转换为 protobuf 定义的期望值，而不会修改任何数据。它可能尝试进行的转换示例

`"true"
字符串 ⇒ true :: 布尔值`
`17
整数 ⇒ 17.0 :: 浮点数`
`12345
数字 ⇒ "12345" :: 字符串`

仅适用于 protobuf 版本 3。

pb3_set_oneof_metainfo编辑

向 [@metadata][pb_oneof] 添加有关为 oneof 字段选择了哪些类的元信息。将添加一个名为 [@metadata][pb_oneof][FOO] 的新字段，其中 FOO 是 oneof 字段的名称。

示例值：对于 protobuf 定义

    oneof :horse_type do
      optional :unicorn, :message, 2, "UnicornType"
      optional :pegasus, :message, 3, "PegasusType"
    end

字段 [@metadata][pb_oneof][horse_type] 将设置为 pegasus 或 unicorn。仅适用于 protobuf 版本 3。

« Plain 编解码插件 Rubydebug 编解码插件 »