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 定义的文件的绝对路径列表。当使用多个文件时，请确保按照依赖关系的相反顺序排列文件，以便在另一个类引用每个类之前加载它。

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

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`

编辑

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

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

`pb3_encoder_autoconvert_types`

编辑

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

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

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

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

仅适用于 protobuf 版本 3。

`pb3_set_oneof_metainfo`

编辑

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

将有关为 oneof 字段选择的类的信息添加到 [@metadata][pb_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 编解码器插件 »