二进制输入数据格式
使用用户指定配置的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 插件可以多次处理二进制数据。 这在使用 filters 时可以用于处理不同的消息类型。
注意: filter 部分需要放置在 entries 定义 之后，否则条目将被分配到过滤器部分。
一般选项和备注
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。
在指定过滤器部分的 match 值时，这一点尤为重要。
条目定义
数组 entries 指定了如何将消息解析为测量名称、时间戳、标签和字段。
measurement 规格
当将 assignment 设置为 "measurement" 时，提取的值将作为度量名称使用，覆盖其他规格。type 设置假定为 "string"，并且可以省略，类似于 name 选项。有关详细信息和其他选项，请参见 string 类型处理。
time 规格
当将 assignment 设置为 "time" 时，提取的值用于度量的时间戳。默认值是所有创建的度量的 当前时间。
设置type指定包含时间戳的时间格式。
使用以下之一：
对于 unix 格式及其衍生形式，假定底层值是一个64位整数。bits 设置可用于指定其他长度设置。所有其他时间格式假定提取一个固定长度的 string 值。字符串的长度通过 type 中的格式设置自动确定。
该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 属性指定要检查的数据的开始和长度。两个值都是以 位 为单位，允许进行非字节对齐的值提取。提取的数据将与在十六进制中指定的给定 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字节头和一个特定消息体组成，消息类型位于第三个字节。要解析这些消息，您可以使用以下配置：
[[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由于数据中缺乏信息，使用解析时间作为时间戳。其他两个指标使用从数据中派生的时间戳。