XPath MessagePack 输入数据格式
使用 xpath_msgpack 输入数据格式，它由 XPath 解析器插件 提供，并结合 XPath 表达式将 MessagePack 数据解析为 Telegraf 指标。
有关支持的 XPath 函数的信息，请参阅 底层 XPath 库。
注意： 字段的类型使用 XPath 函数指定。唯一例外是需要在 fields_int 部分指定的整数字段。
支持的数据格式
| name | data_format 设置 | 注释 |
|---|---|---|
| 可扩展标记语言 (XML) | "xml" | |
| JSON | "xpath_json" | |
| MessagePack | "xpath_msgpack" | |
| Protocol-buffers | "xpath_protobuf" | 查看附加参数 |
Protocol-buffers 附加设置
要使用 protocol-buffer 格式，您需要为解析器指定附加（强制）属性。这些选项在此处进行描述。
xpath_protobuf_file（必填）
使用此选项指定 protocol-buffer 定义文件（.proto）的名称。
xpath_protobuf_type（必填）
此选项包含用于反序列化要解析的数据的顶级消息文件。通常，它由 protocol-buffer 定义文件中的 package 名称和 message 名称组合而成，格式为 <package name>.<message name>。
xpath_protobuf_import_paths（可选）
如果您在 .proto 文件中导入其他 protocol-buffer 定义（即使用 import 语句），则可以使用此选项指定用于搜索导入的定义文件（或文件）的路径。默认情况下，仅在 .（当前工作目录）中搜索导入，通常是启动 telegraf 时的目录。
假设您有一个目录（例如 /data/my_proto_files），其中包含多个 protocol-buffer 定义（例如 A.proto、B.proto 和 C.proto），并且您的顶级文件（例如 A.proto）至少导入了一个其他定义。
syntax = "proto3";
package foo;
import "B.proto";
message Measurement {
...
}您应该使用以下设置
[[inputs.file]]
files = ["example.dat"]
data_format = "xpath_protobuf"
xpath_protobuf_file = "A.proto"
xpath_protobuf_type = "foo.Measurement"
xpath_protobuf_import_paths = [".", "/data/my_proto_files"]
...xpath_protobuf_skip_bytes（可选）
此选项允许在尝试解析 protocol-buffer 消息之前跳过一定数量的字节。当原始数据具有标头（例如消息长度）或在 GRPC 消息的情况下，此选项非常有用。
这是一个已知的标头及其对应的 xpath_protobuf_skip_bytes 值的列表
| name | setting | 注释 |
|---|---|---|
| GRPC 协议 | 5 | GRPC 为长度前缀消息添加了一个 5 字节的标头 |
| PowerDNS 日志记录 | 2 | 发送的消息包含一个 2 字节的标头，其中包含消息长度 |
配置
[[inputs.file]]
files = ["example.xml"]
## 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 = "xml"
## PROTOCOL-BUFFER definitions
## Protocol-buffer definition file
# xpath_protobuf_file = "sparkplug_b.proto"
## Name of the protocol-buffer message type to use in a fully qualified form.
# xpath_protobuf_type = "org.eclipse.tahu.protobuf.Payload"
## List of paths to use when looking up imported protocol-buffer definition files.
# xpath_protobuf_import_paths = ["."]
## Number of (header) bytes to ignore before parsing the message.
# xpath_protobuf_skip_bytes = 0
## Print the internal XML document when in debug logging mode.
## This is especially useful when using the parser with non-XML formats like protocol-buffers
## to get an idea on the expression necessary to derive fields etc.
# xpath_print_document = false
## Allow the results of one of the parsing sections to be empty.
## Useful when not all selected files have the exact same structure.
# xpath_allow_empty_selection = false
## Get native data-types for all data-format that contain type information.
## Currently, protobuf, msgpack and JSON support native data-types
# xpath_native_types = false
## Multiple parsing sections are allowed
[[inputs.file.xpath]]
## Optional: XPath-query to select a subset of nodes from the XML document.
# metric_selection = "/Bus/child::Sensor"
## Optional: XPath-query to set the metric (measurement) name.
# metric_name = "string('example')"
## Optional: Query to extract metric timestamp.
## If not specified the time of execution is used.
# timestamp = "/Gateway/Timestamp"
## Optional: Format of the timestamp determined by the query above.
## This can be any of "unix", "unix_ms", "unix_us", "unix_ns" or a valid Golang
## time format. If not specified, a "unix" timestamp (in seconds) is expected.
# timestamp_format = "2006-01-02T15:04:05Z"
## Optional: Timezone of the parsed time
## This will locate the parsed time to the given timezone. Please note that
## for times with timezone-offsets (e.g. RFC3339) the timestamp is unchanged.
## This is ignored for all (unix) timestamp formats.
# timezone = "UTC"
## Optional: List of fields to convert to hex-strings if they are
## containing byte-arrays. This might be the case for e.g. protocol-buffer
## messages encoding data as byte-arrays. Wildcard patterns are allowed.
## By default, all byte-array-fields are converted to string.
# fields_bytes_as_hex = []
## Tag definitions using the given XPath queries.
[inputs.file.xpath.tags]
name = "substring-after(Sensor/@name, ' ')"
device = "string('the ultimate sensor')"
## Integer field definitions using XPath queries.
[inputs.file.xpath.fields_int]
consumers = "Variable/@consumers"
## Non-integer field definitions using XPath queries.
## The field type is defined using XPath expressions such as number(), boolean() or string(). If no conversion is performed the field will be of type string.
[inputs.file.xpath.fields]
temperature = "number(Variable/@temperature)"
power = "number(Variable/@power)"
frequency = "number(Variable/@frequency)"
ok = "Mode != 'ok'"在此配置模式下，您需要明确指定要从数据中抓取的字段和标签。
一个配置可以包含多个xpath子节（例如，file 插件可以多次处理 xml 字符串）。有关 XPath 查询的详细信息和帮助，请参阅 XPath 语法和底层库的函数。考虑使用 XPath 测试器，如 xpather.com 或 Code Beautify 的 XPath 测试器来帮助开发和调试您的查询。
配置（批量）
与上述配置不同，字段也可以以批量方式指定。因此，与在某个部分中指定字段不同，您可以定义用于确定指标中字段名称和值的 name 和 value 选择器。
[[inputs.file]]
files = ["example.xml"]
## 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 = "xml"
## PROTOCOL-BUFFER definitions
## Protocol-buffer definition file
# xpath_protobuf_file = "sparkplug_b.proto"
## Name of the protocol-buffer message type to use in a fully qualified form.
# xpath_protobuf_type = "org.eclipse.tahu.protobuf.Payload"
## List of paths to use when looking up imported protocol-buffer definition files.
# xpath_protobuf_import_paths = ["."]
## Print the internal XML document when in debug logging mode.
## This is especially useful when using the parser with non-XML formats like protocol-buffers
## to get an idea on the expression necessary to derive fields etc.
# xpath_print_document = false
## Allow the results of one of the parsing sections to be empty.
## Useful when not all selected files have the exact same structure.
# xpath_allow_empty_selection = false
## Get native data-types for all data-format that contain type information.
## Currently, protobuf, msgpack and JSON support native data-types
# xpath_native_types = false
## Multiple parsing sections are allowed
[[inputs.file.xpath]]
## Optional: XPath-query to select a subset of nodes from the XML document.
metric_selection = "/Bus/child::Sensor"
## Optional: XPath-query to set the metric (measurement) name.
# metric_name = "string('example')"
## Optional: Query to extract metric timestamp.
## If not specified the time of execution is used.
# timestamp = "/Gateway/Timestamp"
## Optional: Format of the timestamp determined by the query above.
## This can be any of "unix", "unix_ms", "unix_us", "unix_ns" or a valid Golang
## time format. If not specified, a "unix" timestamp (in seconds) is expected.
# timestamp_format = "2006-01-02T15:04:05Z"
## Field specifications using a selector.
field_selection = "child::*"
## Optional: Queries to specify field name and value.
## These options are only to be used in combination with 'field_selection'!
## By default the node name and node content is used if a field-selection
## is specified.
# field_name = "name()"
# field_value = "."
## Optional: Expand field names relative to the selected node
## This allows to flatten out nodes with non-unique names in the subtree
# field_name_expansion = false
## Tag specifications using a selector.
## tag_selection = "child::*"
## Optional: Queries to specify tag name and value.
## These options are only to be used in combination with 'tag_selection'!
## By default the node name and node content is used if a tag-selection
## is specified.
# tag_name = "name()"
# tag_value = "."
## Optional: Expand tag names relative to the selected node
## This allows to flatten out nodes with non-unique names in the subtree
# tag_name_expansion = false
## Tag definitions using the given XPath queries.
[inputs.file.xpath.tags]
name = "substring-after(Sensor/@name, ' ')"
device = "string('the ultimate sensor')"请注意：生成的字段始终为字符串类型。
也可以指定两种字段指定方式的混合。在这种情况下，显式定义的标签和字段优先于批量实例，如果两者使用相同的标签或字段名称。
metric_selection（可选）
您可以指定一个 XPath 查询来从 XML 文档中选择一组节点，每个节点用于生成带有指定字段、标签等的新指标。
后续查询中的相对查询相对于 metric_selection。要指定绝对路径，请以斜杠（/）开头查询。
指定 metric_selection 是可选的。如果未指定，所有相对查询都相对于 XML 文档的根节点。
metric_name（可选）
通过指定 metric_name，您可以使用给定 XPath 查询的结果来覆盖指标/测量名称。如果未指定，则使用默认指标名称。
timestamp, timestamp_format, timezone（可选）
默认情况下，所有创建的指标都使用当前时间。要从 XML 文档中的值设置时间，您可以在 timestamp 中指定一个 XPath 查询，并在 timestamp_format 中设置格式。
timestamp_format 可以设置为 unix、unix_ms、unix_us、unix_ns，或可接受的 Go “参考时间”。有关如何设置时间格式的详细信息和示例，请参阅 Go time 包。如果省略 timestamp_format，则假定 timestamp 查询的结果为 unix 格式。
timezone 设置将用于在给定时区中定位解析后的时间。这对于不包含时区信息的时间非常有用，例如 2023-03-09 14:04:40 且不在 UTC（这是默认设置）的情况。也可以将 timezone 设置为 Local，这将使用配置的主机时区。
对于带有时间信息的格式（例如 RFC3339），生成的时戳将保持不变。对于所有 unix 时间戳格式，timezone 设置将被忽略。
tags 子节
采用 tag name = query 格式的 XPath 查询，用于向指标添加标签。指定的路径可以是绝对路径（以 / 开头）或相对路径。相对路径使用当前选定的节点作为参考。
注意： 标签查询的结果将始终转换为字符串。
fields_int 子节
采用 field name = query 格式的 XPath 查询，用于向指标添加整数类型的字段。指定的路径可以是绝对路径（以 / 开头）或相对路径。相对路径使用当前选定的节点作为参考。
注意： field_int 查询的结果将始终转换为 int64。如果查询结果无法转换，则转换将失败！
fields 子节
采用 field name = query 格式的 XPath 查询，用于向指标添加非整数字段。指定的路径可以是绝对路径（以 / 开头）或相对路径。相对路径使用当前选定的节点作为参考。
字段的类型在 XPath 查询中使用类型转换函数（如 number()、boolean() 或 string()）指定。如果在查询中没有执行转换，则字段类型为字符串。
注意：即使您将文本转换为浮点数，路径转换函数也始终会成功！
field_selection, field_name, field_value（可选）
您可以指定一个 XPath 查询来选择一组构成指标字段的节点。指定的路径可以是绝对路径（以 / 开头）或相对于当前选定节点。field_selection 选择的每个节点都会在指标中构成一个新字段。
每个字段的名称和值可以使用可选的 field_name 和 field_value 查询来指定。查询相对于选定的字段（除非以 / 开头）。如果未指定，字段名称默认为节点名称，字段值默认为选定字段节点的内容。
注意：field_name 和 field_value 查询仅在指定了 field_selection 时才进行评估。
指定 field_selection 是可选的。这是一种指定字段的替代方法，特别适用于节点名称预先未知或需要指定大量字段的文档。这些选项也可以与上述字段规范结合使用。
注意：即使您将文本转换为浮点数，路径转换函数也始终会成功！
field_name_expansion（可选）
当设置为 true 时，使用 field_selection 选择的字段名将相对于选定节点扩展为路径。例如，如果我们选择所有叶节点作为字段，而这些叶节点没有唯一的名称，则这是必需的。如果您选择的字段中存在重复名称，则应将此设置为 true。
tag_selection, tag_name, tag_value（可选）
您可以指定一个 XPath 查询来选择一组构成指标标签的节点。指定的路径可以是绝对路径（以 / 开头）或相对于当前选定节点。tag_selection 选择的每个节点都会在指标中构成一个新标签。
每个标签的名称和值可以使用可选的 tag_name 和 tag_value 查询来指定。查询相对于选定的标签（除非以 / 开头）。如果未指定，标签名称默认为节点名称，标签值默认为选定标签节点的内容。注意：tag_name 和 tag_value 查询仅在指定了 tag_selection 时才进行评估。
指定 tag_selection 是可选的。这是一种指定标签的替代方法，特别适用于节点名称预先未知或需要指定大量标签的文档。这些选项也可以与上述标签规范结合使用。
tag_name_expansion（可选）
当为true时，使用 tag_selection 选择的标签名称会相对于选定节点进行路径扩展。如果我们例如选择所有叶节点作为标签，而这些叶节点没有唯一的名称，则此项是必需的。也就是说，如果您选择的标签中存在重复名称，则应将此项设置为 true。
示例
此 example.xml 文件用于下面的配置示例
<?xml version="1.0"?>
<Gateway>
<Name>Main Gateway</Name>
<Timestamp>2020-08-01T15:04:03Z</Timestamp>
<Sequence>12</Sequence>
<Status>ok</Status>
</Gateway>
<Bus>
<Sensor name="Sensor Facility A">
<Variable temperature="20.0"/>
<Variable power="123.4"/>
<Variable frequency="49.78"/>
<Variable consumers="3"/>
<Mode>busy</Mode>
</Sensor>
<Sensor name="Sensor Facility B">
<Variable temperature="23.1"/>
<Variable power="14.3"/>
<Variable frequency="49.78"/>
<Variable consumers="1"/>
<Mode>standby</Mode>
</Sensor>
<Sensor name="Sensor Facility C">
<Variable temperature="19.7"/>
<Variable power="0.02"/>
<Variable frequency="49.78"/>
<Variable consumers="0"/>
<Mode>error</Mode>
</Sensor>
</Bus>基本解析
此示例显示了 xml 解析器的基本用法。
配置
[[inputs.file]]
files = ["example.xml"]
data_format = "xml"
[[inputs.file.xpath]]
[inputs.file.xpath.tags]
gateway = "substring-before(/Gateway/Name, ' ')"
[inputs.file.xpath.fields_int]
seqnr = "/Gateway/Sequence"
[inputs.file.xpath.fields]
ok = "/Gateway/Status = 'ok'"输出
file,gateway=Main,host=Hugin seqnr=12i,ok=true 1598610830000000000在tags定义中，使用 XPath 函数 substring-before() 来仅提取空格之前的子字符串。要获取 /Gateway/Sequence 的整数值，我们必须使用 fields_int 部分，因为没有 XPath 表达式可以将节点值转换为整数（只有浮点数）。
ok 字段通过指定一个比较 /Gateway/Status 的查询结果与字符串ok的查询来填充布尔值。使用 XPath 语法中可用的类型转换来指定字段类型。
时间和指标名称
这是一个使用 XML 文档本身的时间和指标名称的示例。
配置
[[inputs.file]]
files = ["example.xml"]
data_format = "xml"
[[inputs.file.xpath]]
metric_name = "name(/Gateway/Status)"
timestamp = "/Gateway/Timestamp"
timestamp_format = "2006-01-02T15:04:05Z"
[inputs.file.xpath.tags]
gateway = "substring-before(/Gateway/Name, ' ')"
[inputs.file.xpath.fields]
ok = "/Gateway/Status = 'ok'"输出
Status,gateway=Main,host=Hugin ok=true 1596294243000000000除了基本解析示例外，指标名称被定义为 /Gateway/Status 节点的名称，并且时间戳是从 XML 文档派生的，而不是使用执行时间。
多节点选择
对于包含例如多个设备指标的 XML 文档（如 example.xml 中的 Sensor），可以使用节点选择生成多个指标。此示例显示了如何为示例中的每个Sensor生成指标。
配置
[[inputs.file]]
files = ["example.xml"]
data_format = "xml"
[[inputs.file.xpath]]
metric_selection = "/Bus/child::Sensor"
metric_name = "string('sensors')"
timestamp = "/Gateway/Timestamp"
timestamp_format = "2006-01-02T15:04:05Z"
[inputs.file.xpath.tags]
name = "substring-after(@name, ' ')"
[inputs.file.xpath.fields_int]
consumers = "Variable/@consumers"
[inputs.file.xpath.fields]
temperature = "number(Variable/@temperature)"
power = "number(Variable/@power)"
frequency = "number(Variable/@frequency)"
ok = "Mode != 'error'"输出
sensors,host=Hugin,name=Facility\ A consumers=3i,frequency=49.78,ok=true,power=123.4,temperature=20 1596294243000000000
sensors,host=Hugin,name=Facility\ B consumers=1i,frequency=49.78,ok=true,power=14.3,temperature=23.1 1596294243000000000
sensors,host=Hugin,name=Facility\ C consumers=0i,frequency=49.78,ok=false,power=0.02,temperature=19.7 1596294243000000000使用 metric_selection 选项，我们选择 XML 文档中的所有 Sensor 节点。请注意，所有字段和标签定义都相对于这些选定的节点。时间戳定义是一个例外，它是相对于 XML 文档的根节点。
批量字段处理与多节点选择
对于包含大量字段的指标的 XML 文档，或者字段事先未知（例如，example.xml 中未知的 Variable 节点集），可以使用字段选择器。此示例显示了如何为示例中的每个Sensor生成指标，并从Variable节点派生字段。
配置
[[inputs.file]]
files = ["example.xml"]
data_format = "xml"
[[inputs.file.xpath]]
metric_selection = "/Bus/child::Sensor"
metric_name = "string('sensors')"
timestamp = "/Gateway/Timestamp"
timestamp_format = "2006-01-02T15:04:05Z"
field_selection = "child::Variable"
field_name = "name(@*[1])"
field_value = "number(@*[1])"
[inputs.file.xpath.tags]
name = "substring-after(@name, ' ')"输出
sensors,host=Hugin,name=Facility\ A consumers=3,frequency=49.78,power=123.4,temperature=20 1596294243000000000
sensors,host=Hugin,name=Facility\ B consumers=1,frequency=49.78,power=14.3,temperature=23.1 1596294243000000000
sensors,host=Hugin,name=Facility\ C consumers=0,frequency=49.78,power=0.02,temperature=19.7 1596294243000000000使用 metric_selection 选项，我们选择 XML 文档中的所有 Sensor 节点。对于每个Sensor，我们然后使用 field_selection 选择传感器所有子节点作为字段节点。请注意，字段选择是相对于选定节点进行的。对于每个选定的字段节点，我们使用 field_name 和 field_value 来分别确定字段的名称和值。field_name 从节点的第一个属性派生名称，而 field_value 从第一个属性派生值并将其结果转换为数字。
此页面是否有帮助？
感谢您的反馈！
支持和反馈
感谢您成为我们社区的一员！我们欢迎并鼓励您对 Telegraf 和本文档提出反馈和 bug 报告。要获取支持，请使用以下资源
具有年度合同或支持合同的客户可以 联系 InfluxData 支持。