二进制输入数据格式
使用用户指定的配置的 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。
在为过滤器部分的 match 值指定时，这一点尤其重要。
条目定义
entries 数组指定如何将消息解析为度量名称、时间戳、标签和字段。
measurement 规范
当将 assignment 设置为 "measurement" 时，提取的值将用作指标名称，覆盖其他规范。type 设置假定为 "string"，并且可以省略，类似于 name 选项。有关详细信息和其他选项，请参阅 string 类型处理。
time 规范
当将 assignment 设置为 "time" 时，提取的值将用作指标的时间戳。所有创建的指标的默认值是当前时间。
type 设置指定包含的时间戳的时间格式。使用以下任一选项：
unix(默认)unix_msunix_usunix_ns- Go “参考时间”。有关设置时间格式的详细信息和更多示例，请参阅 Go time 包。
对于 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 分别表示固定长度和 null 终止字符串。任何其他设置都将被解释为匹配字符串末尾的字节的十六进制序列。终止序列将从结果中移除。
bool 类型处理
默认情况下，bool 类型假定长度为一位。您可以使用 bits 设置指定任何其他长度。在将值解释为布尔值时，任何零值都是 false，任何非零值都是 true。
省略数据
可以通过设置 omit = true 来省略部分数据。在这种情况下，您只需要使用 type 或 bits 设置指定要省略的块的长度。所有其他选项都可以省略。
过滤器定义
过滤器可用于将数据长度或内容与指定引用进行匹配。有关详细信息，请参阅 示例部分。您还可以通过指定过滤器的多个 section 条目来检查消息的多个部分。每个 section 将单独匹配。所有部分都必须匹配才能应用配置。
length 和 length_min 选项
使用 length 选项，过滤器将检查解析后的数据是否具有确切的给定字节数。否则，配置将不被应用。同样，对于 length_min，数据必须至少有给定数量的字节才能生成匹配。
selection 列表
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 1658835984000000000metricB 由于数据中缺少信息而使用解析时间作为时间戳。另外两个指标使用从数据派生的时间戳。
此页面是否有帮助？
感谢您的反馈！
支持和反馈
感谢您成为我们社区的一员！我们欢迎并鼓励您对 Telegraf 和本文档提出反馈和 bug 报告。要获取支持，请使用以下资源
具有年度合同或支持合同的客户可以 联系 InfluxData 支持。