文档文档 (Documentation)

Grok 输入数据格式 (Grok input data format)

使用 grok 数据格式来解析使用类似正则表达式语言的分行数据。

有关 grok 模式的介绍,请参阅 Logstash 文档中的 Grok 基础知识 (Grok Basics)。grok 解析器使用略微修改过的 logstash grok 模式,使用以下格式

%{<capture_syntax>[:<semantic_name>][:<modifier>]}

capture_syntax 定义了用于解析输入行的 grok 模式,semantic_name 用于命名字段或标签。扩展 modifier 控制解析项转换的数据类型或其他特殊处理。

默认情况下,所有命名的捕获都转换为字符串字段。如果模式没有语义名称,则不会被捕获。时间戳修饰符可用于将捕获转换为解析指标的时间戳。如果未解析时间戳,则将使用当前时间创建指标。

您必须每行至少捕获一个字段。

  • 可用修饰符 (Available modifiers)
    • string (字符串) (默认值,如果未指定任何内容)
    • int (整数)
    • float (浮点数)
    • duration (持续时间) (例如,5.23ms 转换为 int 纳秒)
    • tag (标签) (将字段转换为标签)
    • drop (丢弃) (完全丢弃该字段)
    • measurement (指标名称) (使用匹配的文本作为指标名称)
  • 时间戳修饰符 (Timestamp modifiers)
    • ts (这将自动学习时间戳格式)
    • ts-ansic (“Mon Jan _2 15:04:05 2006”)
    • ts-unix (“Mon Jan _2 15:04:05 MST 2006”)
    • ts-ruby (“Mon Jan 02 15:04:05 -0700 2006”)
    • ts-rfc822 (“02 Jan 06 15:04 MST”)
    • ts-rfc822z (“02 Jan 06 15:04 -0700”)
    • ts-rfc850 (“Monday, 02-Jan-06 15:04:05 MST”)
    • ts-rfc1123 (“Mon, 02 Jan 2006 15:04:05 MST”)
    • ts-rfc1123z (“Mon, 02 Jan 2006 15:04:05 -0700”)
    • ts-rfc3339 (“2006-01-02T15:04:05Z07:00”)
    • ts-rfc3339nano (“2006-01-02T15:04:05.999999999Z07:00”)
    • ts-httpd (“02/Jan/2006:15:04:05 -0700”)
    • ts-epoch (自 Unix 纪元以来的秒数,可能包含小数)
    • ts-epochnano (自 Unix 纪元以来的纳秒数)
    • ts-epochmilli (自 Unix 纪元以来的毫秒数)
    • ts-syslog (“Jan 02 15:04:05”,解析时间设置为当前年份)
    • ts-“CUSTOM” (自定义)

CUSTOM (自定义) 时间布局必须用引号引起来,并且是 “参考时间” 的表示形式,即 Mon Jan 2 15:04:05 -0700 MST 2006。要匹配逗号小数点,可以使用句点。例如,%{TIMESTAMP:timestamp:ts-"2006-01-02 15:04:05.000"} 可用于匹配 "2018-01-02 15:04:05,000"。要匹配逗号小数点,可以在模式字符串中使用句点。有关更多详细信息,请参阅 https://golang.ac.cn/pkg/time/#Parse。

Telegraf 有许多自己的 内置模式 (built-in patterns),以及对大多数 Logstash 的核心模式 (Logstash’s core patterns) 的支持。Golang 正则表达式不支持lookahead (先行断言) 或 lookbehind (后行断言)。不支持依赖于这些的 Logstash 模式。

有关构建和测试模式的帮助,请参阅 创建模式的提示 (tips for creating patterns)

配置 (Configuration)

[[inputs.file]]
  ## Files to parse each interval.
  ## These accept standard unix glob matching rules, but with the addition of
  ## ** as a "super asterisk". ie:
  ##   /var/log/**.log     -> recursively find all .log files in /var/log
  ##   /var/log/*/*.log    -> find all .log files with a parent dir in /var/log
  ##   /var/log/apache.log -> only tail the apache log file
  files = ["/var/log/apache/access.log"]

  ## The dataformat to be read from files
  ## 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 = "grok"

  ## This is a list of patterns to check the given log file(s) for.
  ## Note that adding patterns here increases processing time. The most
  ## efficient configuration is to have one pattern.
  ## Other common built-in patterns are:
  ##   %{COMMON_LOG_FORMAT}   (plain apache & nginx access logs)
  ##   %{COMBINED_LOG_FORMAT} (access logs + referrer & agent)
  grok_patterns = ["%{COMBINED_LOG_FORMAT}"]

  ## Full path(s) to custom pattern files.
  grok_custom_pattern_files = []

  ## Custom patterns can also be defined here. Put one pattern per line.
  grok_custom_patterns = '''
  '''

  ## Timezone allows you to provide an override for timestamps that
  ## don't already include an offset
  ## e.g. 04/06/2016 12:41:45 data one two 5.43µs
  ##
  ## Default: "" which renders UTC
  ## Options are as follows:
  ##   1. Local             -- interpret based on machine localtime
  ##   2. "Canada/Eastern"  -- Unix TZ values like those found in https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
  ##   3. UTC               -- or blank/unspecified, will return timestamp in UTC
  grok_timezone = "Canada/Eastern"

  ## When set to "disable" timestamp will not incremented if there is a
  ## duplicate.
  # grok_unique_timestamp = "auto"

  ## Enable multiline messages to be processed.
  # grok_multiline = false

时间戳示例 (Timestamp Examples)

此示例输入和配置使用自定义时间戳转换解析文件

2017-02-21 13:10:34 value=42
[[inputs.file]]
  grok_patterns = ['%{TIMESTAMP_ISO8601:timestamp:ts-"2006-01-02 15:04:05"} value=%{NUMBER:value:int}']

此示例输入和配置使用 Unix 时间的时间戳解析文件

1466004605 value=42
1466004605.123456789 value=42
[[inputs.file]]
  grok_patterns = ['%{NUMBER:timestamp:ts-epoch} value=%{NUMBER:value:int}']

此示例使用内置转换和自定义模式解析文件

Wed Apr 12 13:10:34 PST 2017 value=42
[[inputs.file]]
  grok_patterns = ["%{TS_UNIX:timestamp:ts-unix} value=%{NUMBER:value:int}"]
  grok_custom_patterns = '''
    TS_UNIX %{DAY} %{MONTH} %{MONTHDAY} %{HOUR}:%{MINUTE}:%{SECOND} %{TZ} %{YEAR}
  '''

此示例输入和配置使用与任何特定标准都不匹配的自定义时间戳转换来解析文件

21/02/2017 13:10:34 value=42
[[inputs.file]]
  grok_patterns = ['%{MY_TIMESTAMP:timestamp:ts-"02/01/2006 15:04:05"} value=%{NUMBER:value:int}']

  grok_custom_patterns = '''
    MY_TIMESTAMP (?:\d{2}.\d{2}.\d{4} \d{2}:\d{2}:\d{2})
  '''

对于时间戳本身没有偏移量的情况,可以使用 timezone 配置变量来表示偏移量。默认情况下(timezone 省略、空白或设置为 "UTC"),时间被视为在 UTC 时区。如果指定为 timezone = "Local",则时间戳将根据当前机器时区配置进行处理。最后,如果使用 Unix 时区 (timezones) 列表中的时区,grok 将相应地偏移时间戳。

TOML 转义 (TOML Escaping)

将模式保存到配置文件时,请记住不同的 TOML 字符串 (string) 类型以及每种类型的转义规则。除了 grok 语法要求的转义之外,还必须应用这些转义规则。使用带有 ''' 的多行文字语法可能很有用。

以下配置示例将解析此输入文件

|42|\uD83D\uDC2F|'telegraf'|

由于 | 是 grok 语言中的特殊字符,因此我们必须对其进行转义才能获得文字 |。对于基本的 TOML 字符串,必须转义反斜杠等特殊字符,这要求我们再次转义反斜杠。

[[inputs.file]]
  grok_patterns = ["\\|%{NUMBER:value:int}\\|%{UNICODE_ESCAPE:escape}\\|'%{WORD:name}'\\|"]
  grok_custom_patterns = "UNICODE_ESCAPE (?:\\\\u[0-9A-F]{4})+"

我们不能对模式使用文字 TOML 字符串,因为我们无法在其中匹配 '。但是,它对于自定义模式效果很好。

[[inputs.file]]
  grok_patterns = ["\\|%{NUMBER:value:int}\\|%{UNICODE_ESCAPE:escape}\\|'%{WORD:name}'\\|"]
  grok_custom_patterns = 'UNICODE_ESCAPE (?:\\u[0-9A-F]{4})+'

多行文字字符串允许我们编码模式

[[inputs.file]]
  grok_patterns = ['''
    \|%{NUMBER:value:int}\|%{UNICODE_ESCAPE:escape}\|'%{WORD:name}'\|
  ''']
  grok_custom_patterns = 'UNICODE_ESCAPE (?:\\u[0-9A-F]{4})+'

创建模式的提示 (Tips for creating patterns)

复杂的模式可能难以阅读和编写。有关构建和调试 grok 模式的帮助,请参阅以下工具

我们建议使用以下步骤来构建和测试 Telegraf 和您的数据的新模式

  1. 在您的 Telegraf 配置中,执行以下操作以帮助您隔离和查看捕获的指标

    • 配置写入 stdout 的文件输出

      [[outputs.file]]
        files = ["stdout"]
      
    • 在测试时禁用其他输出。

    请记住,文件输出仅在每个 flush_interval 打印一次。

  2. 对于输入,从包含单行数据的示例文件开始,然后删除除该行的第一个标记或片段之外的所有内容。

  3. 在您的 Telegraf 配置中,添加模式中与上一步骤中的数据片段匹配的部分。

  4. 运行 Telegraf 并验证指标是否已成功解析。

  5. 如果成功,请将下一个标记添加到数据文件,更新 Telegraf 中的模式配置,然后重新测试。

  6. 一次继续一个标记,直到整个行都成功解析。

性能 (Performance)

性能在很大程度上取决于您使用的正则表达式,但是有一些技巧可以提供帮助

  • 避免使用诸如 %{DATA} 之类的始终匹配的模式。

  • 如果可能,请将 ^$ 锚点添加到您的模式

    [[inputs.file]]
      grok_patterns = ["^%{COMBINED_LOG_FORMAT}$"]
    

此页面对您有帮助吗?

感谢您的反馈!


Flux 的未来 (The future of Flux)

Flux 即将进入维护模式。您可以继续像目前一样使用它,而无需对代码进行任何更改。

阅读更多 (Read more)

现已全面上市 (Now Generally Available)

InfluxDB 3 Core 和 Enterprise

快速启动。更快扩展。(Start fast. Scale faster.)

获取更新 (Get the Updates)

InfluxDB 3 Core 是一个开源、高速、最近数据引擎,可实时收集和处理数据,并将其持久化到本地磁盘或对象存储。InfluxDB 3 Enterprise 以 Core 的基础为构建,增加了高可用性、读取副本、增强的安全性以及数据压缩,从而实现更快的查询和优化的存储。InfluxDB 3 Enterprise 的免费层级可供非商业家庭或业余爱好者使用。

有关更多信息,请查看