二进制输入数据格式
使用用户指定的配置的 binary 输入数据格式将二进制协议解析为 Telegraf 指标。
配置
[[inputs.file]]
files = ["example.bin"]
## Data format to consume.
## Each data format has its own unique set of configuration options, read
## more about them here:
## https://github.com/influxdata/telegraf/blob/master/docs/DATA_FORMATS_INPUT.md
data_format = "binary"
## Do not error-out if none of the filter expressions below matches.
# allow_no_match = false
## Specify the endianness of the data.
## Available values are "be" (big-endian), "le" (little-endian) and "host",
## where "host" means the same endianness as the machine running Telegraf.
# endianess = "host"
## Interpret input as string containing hex-encoded data.
# hex_encoding = false
## Multiple parsing sections are allowed
[[inputs.file.binary]]
## Optional: Metric (measurement) name to use if not extracted from the data.
# metric_name = "my_name"
## Definition of the message format and the extracted data.
## Please note that you need to define all elements of the data in the
## correct order with the correct length as the data is parsed in the order
## given.
## An entry can have the following properties:
## name -- Name of the element (e.g. field or tag). Can be omitted
## for special assignments (i.e. time & measurement) or if
## entry is omitted.
## type -- Data-type of the entry. Can be "int8/16/32/64", "uint8/16/32/64",
## "float32/64", "bool" and "string".
## In case of time, this can be any of "unix" (default), "unix_ms", "unix_us",
## "unix_ns" or a valid Golang time format.
## bits -- Length in bits for this entry. If omitted, the length derived from
## the "type" property will be used. For "time" 64-bit will be used
## as default.
## assignment -- Assignment of the gathered data. Can be "measurement", "time",
## "field" or "tag". If omitted "field" is assumed.
## omit -- Omit the given data. If true, the data is skipped and not added
## to the metric. Omitted entries only need a length definition
## via "bits" or "type".
## terminator -- Terminator for dynamic-length strings. Only used for "string" type.
## Valid values are "fixed" (fixed length string given by "bits"),
## "null" (null-terminated string) or a character sequence specified
## as HEX values (e.g. "0x0D0A"). Defaults to "fixed" for strings.
## timezone -- Timezone of "time" entries. Only applies to "time" assignments.
## Can be "utc", "local" or any valid Golang timezone (e.g. "Europe/Berlin")
entries = [
{ type = "string", assignment = "measurement", terminator = "null" },
{ name = "address", type = "uint16", assignment = "tag" },
{ name = "value", type = "float64" },
{ type = "unix", assignment = "time" },
]
## Optional: Filter evaluated before applying the configuration.
## This option can be used to mange multiple configuration specific for
## a certain message type. If no filter is given, the configuration is applied.
# [inputs.file.binary.filter]
# ## Filter message by the exact length in bytes (default: N/A).
# # length = 0
# ## Filter the message by a minimum length in bytes.
# ## Messages longer of of equal length will pass.
# # length_min = 0
# ## List of data parts to match.
# ## Only if all selected parts match, the configuration will be
# ## applied. The "offset" is the start of the data to match in bits,
# ## "bits" is the length in bits and "match" is the value to match
# ## against. Non-byte boundaries are supported, data is always right-aligned.
# selection = [
# { offset = 0, bits = 8, match = "0x1F" },
# ]
#
#
在此配置模式下，您可以显式指定要从数据中解析的字段和标签。
一个配置可以包含多个 binary 子节。 例如，file 插件可以多次处理二进制数据。 这在处理不同的消息类型时非常有用（与过滤器一起使用）。
注意： filter 部分需要放置在 entries 定义之后，否则条目将被分配给 filter 部分。
通用选项和说明
allow_no_match（可选）
通过指定 allow_no_match，您允许解析器静默忽略与任何给定配置过滤器不匹配的数据。 如果您只想收集可用消息的子集，这将非常有用。
endianness（可选）
这指定数据的字节序。 如果未指定，解析器将回退到“主机”字节序，假设消息和 Telegraf 机器共享相同的字节序。 或者，您可以显式指定大端格式 ("be") 或小端格式 ("le")。
hex_encoding（可选）
如果 true，则输入数据被解释为包含十六进制编码数据的字符串，例如 C0 C7 21 A9。 该值不区分大小写，可以处理空格，但不允许使用 0x 或 x 等前缀。
非字节对齐的值提取
在 filter 和 entries 定义中，都可以在非字节边界提取值。 例如，您可以提取从位偏移 8 开始的 3 位。 在这些情况下，结果将被屏蔽和移位，以便生成的字节值右对齐。 如果您的 3 位是 101，则生成的字节值是 0x05。
在 filter 部分中指定 match 值时，这一点尤其重要。
条目定义
entries 数组指定如何将消息解析为指标名称、时间戳、标签和字段。
measurement 规范
当将 assignment 设置为 "measurement" 时，提取的值将用作指标名称，覆盖其他规范。 type 设置假定为 "string"，并且可以像 name 选项一样省略。 有关详细信息和其他选项，请参阅 string 类型处理。
time 规范
当将 assignment 设置为 "time" 时，提取的值将用作指标的时间戳。 对于所有创建的指标，默认值为当前时间。
type 设置指定包含的时间戳的时间格式。 使用以下格式之一
对于 unix 格式及其衍生格式，底层值假定为 64 位整数。 bits 设置可用于指定其他长度设置。 所有其他时间格式都假定要提取固定长度的 string 值。 字符串的长度使用 type 中的 format 设置自动确定。
timezone 设置将提取的时间转换为给定的时区值。 默认情况下，时间将被解释为 utc。 其他有效值包括 local（为机器配置的本地时区）或有效的时区规范（例如，Europe/Berlin）。
tag 规范
当将 assignment 设置为 "tag" 时，提取的值将用作标签。 name 设置是标签的名称，type 默认为 string。 当指定其他类型时，提取的值首先被解释为给定的类型，然后转换为 string。
bits 设置可用于指定要提取的数据的长度，并且对于固定长度的 string 类型是必需的。
field 规范
当将 assignment 设置为 "field" 或省略 assignment 设置时，提取的值将用作字段。 name 设置用作字段的名称，type 用作字段值的类型。
bits 设置可用于指定要提取的数据的长度。 默认情况下，使用与 type 对应的长度。 使用这些类型时，请参阅 string 和 bool 特定部分。
string 类型处理
默认情况下，字符串被假定为固定长度的字符串。 在这种情况下，bits 设置是强制性的，用于指定字符串的长度，单位为位。
为了处理动态字符串，可以使用 terminator 设置来指定终止字符串的字符。 fixed 和 null 这两个命名选项分别指定固定长度和空终止字符串。 任何其他设置都被解释为与字符串结尾匹配的十六进制字节序列。 终止序列将从结果中删除。
bool 类型处理
默认情况下，bool 类型被假定为长度为一位。 您可以使用 bits 设置指定任何其他长度。 当将值解释为布尔值时，任何零值都为 false，任何非零值都为 true。
省略数据
可以通过设置 omit = true 来省略部分数据。 在这种情况下，您只需通过使用 type 或 bits 设置来指定要省略的块的长度。 可以跳过所有其他选项。
过滤器定义
过滤器可用于将数据的长度或内容与指定的参考进行匹配。 有关详细信息，请参阅 示例部分。 您还可以通过为过滤器指定多个 section 条目来检查消息的多个部分。 然后分别匹配每个 section。 所有部分都必须匹配才能应用配置。
length 和 length_min 选项
使用 length 选项，过滤器检查解析的数据是否正好具有给定的字节数。 否则，不应用配置。 类似地，对于 length_min，数据必须至少具有给定的字节数才能生成匹配项。
selection 列表
选择可以与长度约束一起使用或不使用长度约束来匹配数据的内容。 在这里，offset 和 bits 属性指定要检查的数据的开始和长度。 这两个值都以位为单位，允许非字节对齐的值提取。 提取的数据根据以 HEX 指定的给定 match 值进行检查。
如果指定了多个 selection 条目，则所有选择都必须匹配才能应用配置。
示例
在以下示例中，我们使用了一个二进制协议，其中包含三种不同的小端格式消息
消息 A 定义
+--------+------+------+--------+--------+------------+--------------------+--------------------+
| ID | type | len | addr | count | failure | value | timestamp |
+--------+------+------+--------+--------+------------+--------------------+--------------------+
| 0x0201 | 0x0A | 0x18 | 0x7F01 | 0x2A00 | 0x00000000 | 0x6F1283C0CA210940 | 0x10D4DF6200000000 |
+--------+------+------+--------+--------+------------+--------------------+--------------------+
消息 B 定义
+--------+------+------+------------+
| ID | type | len | value |
+--------+------+------+------------+
| 0x0201 | 0x0B | 0x04 | 0xDEADC0DE |
+--------+------+------+------------+
消息 C 定义
+--------+------+------+------------+------------+--------------------+
| ID | type | len | value x | value y | timestamp |
+--------+------+------+------------+------------+--------------------+
| 0x0201 | 0x0C | 0x10 | 0x4DF82D40 | 0x5F305C08 | 0x10D4DF6200000000 |
+--------+------+------+------------+------------+--------------------+
所有消息都由一个 4 字节的标头组成，其中包含第 3 个字节中的消息类型和一个特定于消息的主体。 要解析这些消息，您可以使用以下配置
[[inputs.file]]
files = ["messageA.bin", "messageB.bin", "messageC.bin"]
data_format = "binary"
endianess = "le"
[[inputs.file.binary]]
metric_name = "messageA"
entries = [
{ bits = 32, omit = true },
{ name = "address", type = "uint16", assignment = "tag" },
{ name = "count", type = "int16" },
{ name = "failure", type = "bool", bits = 32, assignment = "tag" },
{ name = "value", type = "float64" },
{ type = "unix", assignment = "time" },
]
[inputs.file.binary.filter]
selection = [{ offset = 16, bits = 8, match = "0x0A" }]
[[inputs.file.binary]]
metric_name = "messageB"
entries = [
{ bits = 32, omit = true },
{ name = "value", type = "uint32" },
]
[inputs.file.binary.filter]
selection = [{ offset = 16, bits = 8, match = "0x0B" }]
[[inputs.file.binary]]
metric_name = "messageC"
entries = [
{ bits = 32, omit = true },
{ name = "x", type = "float32" },
{ name = "y", type = "float32" },
{ type = "unix", assignment = "time" },
]
[inputs.file.binary.filter]
selection = [{ offset = 16, bits = 8, match = "0x0C" }]
上面的配置为每种消息类型都有一个 [[inputs.file.binary]] 部分，并在每个部分中使用过滤器，通过比较第 3 个字节（包含消息类型）来应用正确的配置。 这会产生以下输出
metricA,address=383,failure=false count=42i,value=3.1415 1658835984000000000
metricB value=3737169374i 1658847037000000000
metricC x=2.718280076980591,y=0.0000000000000000000000000000000006626070178575745 1658835984000000000
由于数据中缺少信息，metricB 使用解析时间作为时间戳。 其他两个指标使用从数据派生的时间戳。
此页面是否对您有帮助？
感谢您的反馈！
支持和反馈
感谢您成为我们社区的一份子！ 我们欢迎并鼓励您提供关于 Telegraf 和本文档的反馈和错误报告。 要获得支持，请使用以下资源
拥有年度合同或支持合同的客户可以联系 InfluxData 支持。