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"

编码器用法示例（Protobuf 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* 引用另一个 Protobuf 类 *Wings*

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

Protocol Buffers 版本。有效设置为 2、3。

`stop_on_error`

编辑

值类型为布尔值
默认值为 false

遇到无法解码的消息时停止整个管道。

`pb3_encoder_autoconvert_types`

编辑

值类型为布尔值
默认值为 true

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

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

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

仅适用于 Protobuf 版本 3。

`pb3_set_oneof_metainfo`

编辑

值类型为布尔值
默认值为 false

向 [@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 编解码插件 »