December 13, 2016 工程

在 Kibana 脚本化 fields 中使用 Painless

作者 Tanya Bragin

Kibana 提供了一些强大的方法,用于搜索和可视化 Elasticsearch 中存储的数据。为了实现可视化,Kibana 会搜索 Elasticsearch mapping 中定义的 field,并以图表的形式将它们作为选项呈现给用户。但是,如果你忘记在 schema 中将一个重要的值定义为单独的 field 会怎么样呢?或者,如果你想把两个 field 合并到一起该怎么办呢?这时就可以使用 Kibana 脚本化 field。

其实,脚本化 field 最早出现于 Kibana 4 初期。当时只能依靠 Elasticsearch 中专门处理数字值的脚本语言 Lucene Expressions来定义它们。因此,只能在有限的用例子集中发挥脚本化 field 的功能。在 Kibana 5.0 中,Elasticsearch 引入了 Painless,这是一种安全而又强大的脚本语言,允许操作各种数据类型,Kibana 5.0 中的脚本化 field 因而变得更加强大。

接下来,这篇博客将带你了解如何为常见用例创建脚本化 field。在此期间,我们将依托来自 Kibana 入门教程的数据集,并使用在可以免费加速的 Elastic Cloud中运行的 Elasticsearch 和 Kibana 实例。

下面的视频将带你了解如何在 Elastic Cloud 中快速启动个人 Elasticsearch 和 Kibana 实例以及如何向其中加载示例数据集。

脚本化 field 的工作原理

Elasticsearch 允许每次请求时指定脚本化 field。Kibana 在此基础上进行了改进,在 Management(管理)区域定义一个脚本化 field,即可在后续用户界面的多个位置使用。请注意,尽管 Kibana 会将脚本化 field 与其在 .kibana index 中的其他配置存储在一起,但是此配置专属于 Kibana,而且 Elasticsearch 的 API 用户不会接触到 Kibana 脚本化 field。

当你要在 Kibana 中定义脚本化 field 时,需要选择脚本语言,你可以从 Elasticsearch 节点上安装的所有启用了动态脚本的语言中进行选择。默认情况下,5.0 中有“expression”和“painless”可供选择,2.x 中则只有“expression”。你也可以安装其他脚本语言并为它们启用动态脚本,但是不建议这样做,因为无法将它们充分地进行 沙盒封装,因此已被弃用。

脚本化 field 一次可以操作一个 Elasticsearch 文档,但是可以在这个文档中引用多个 field。因此,可以使用脚本化 field 将多个 field 合并或转换到一个单独的文档中,但是不能对多个文档执行计算(例如:时间序列运算)。Painless 和 Lucene expressions 都能够对存储在 doc_values中的 field 执行操作。因此在处理字符串数据时,需要将字符串存储到 keyword数据类型。基于 Painless 的脚本化 field 也不能直接操作 _source

在 Management(管理)区域定义脚本化 field 之后,用户可以借鉴与 Kibana 其他部分的其他 field 的交互方式,采用与之相同的方式与脚本化 field 进行交互。脚本化 field 将自动出现在 Discover(探索)field 列表中,并且将在 Visualize(可视化)中可用,用于创建可视化。Kibana 只需在查询时将脚本化 field 定义传递给 Elasticsearch,进行求值。得出的数据集将会与 Elasticsearch 返回的其他结果合并,并以表格或图表的形式呈现给用户。

撰写这篇博客时,脚本化 field 的使用存在一些已知的限制。你可以将 Kibana 可视化生成器中可用的大部分 Elasticsearch 聚合应用到脚本化 field,最著名的 significant terms aggregation(重要术语聚合)除外。你还可以通过 Discover(探索)、Visualize(可视化)和 Dashboard(仪表板)中的过滤栏过滤脚本化 field,但是正如我们下面所介绍的那样,你需要小心编写合适的脚本,确保能够返回定义良好的值。与此同时,务必参阅下面的“最佳实践”章节,确保使用脚本化 field 时不会破坏环境的稳定。

下面的视频展示了如何使用 Kibana 创建脚本化 field。

脚本化 field 示例

本小节展示了 Kibana 中一些常见场景下的 Lucene expressions 和 Painless 脚本化 field 示例。如上所述,这些示例以来自 Kibana 入门教程的数据集为基础,并且假定你使用的是 Elasticsearch 和 Kibana 5.1.1,因为在之前的版本中,某些类型的脚本化 field 中存在一些与过滤和排序相关的已知问题。

由于 Elasticsearch 5.0 默认启用 Lucene expressions 和 Painless,因此脚本化 fields 在大部分情况下应该都能够开箱即用。唯一例外的是那些需要对 fields 进行基于正则表达式的解析的脚本,这些脚本需要你在 elasticsearch.yml中设置下面的设置,为 Painless 打开正则表达式匹配: script.painless.regex.enabled: true

对单个 field 执行计算

  • 示例:由字节计算出千字节
  • 语言:expressions
  • 返回类型:数字
 doc['bytes'].value / 1024

注意:切记 Kibana 脚本化 fields 一次只能处理一个单独的文档,因此无法在脚本化 fields 中进行时间序列运算。

返回数字的日期运算

  • 示例:将日期解析成小时时间
  • 语言:expressions
  • 返回类型:数字

Lucene expressions 提供了大量开箱即用的 日期处理函数。但是,由于 Lucene expressions 只能返回数字值,因此我们必须使用 Painless 来返回基于字符串的星期值(如下所示)。

 doc['@timestamp'].date.hourOfDay

注意:上面的脚本将返回 1-24

doc['@timestamp'].date.dayOfWeek

注意:上面的脚本将返回 1-7

合并两个字符串值

  • 示例:合并源和目标或名字和姓氏
  • 语言:painless
  • 返回类型:字符串
 doc['geo.dest.keyword'].value + ':' + doc['geo.src.keyword'].value

注意:由于脚本化 field 需要操作doc_values中的 field,因此我们上面使用的是 .keyword 版本的字符串。

引入逻辑运算

  • 示例:为所有超过 10000 字节的文档返回标签“big download”
  • 语言:painless
  • 返回类型:字符串
 if (doc['bytes'].value > 10000) { 
    return "big download";
}
return "";

注意:引入逻辑运算时,确保每个执行路径都具有良好定义的返回语句和良好定义的返回值(而非 null)。例如,在 Kibana 过滤器中使用上述脚本化 field 时,如果最后没有返回语句或者语句返回 null,都会出现编译错误。另外还请注意,Kibana 脚本化 field 中不支持将逻辑运算分解成函数。

返回子串

  • 示例:返回 URL 中最后一个斜线后面的部分
  • 语言:painless
  • 返回类型:字符串
 def path = doc['url.keyword'].value;
if (path != null) {
    int lastSlashIndex = path.lastIndexOf('/');
    if (lastSlashIndex > 0) {
    return path.substring(lastSlashIndex+1);
    }
}
return "";

注意:尽量避免使用正则表达式提取子串,因为 indexOf() 操作占用的资源更少,更不易出错。

使用正则表达式匹配字符串,并对匹配进行操作

  • 示例:如果在 field“referer”中找到子串“error”,则返回字符串“error”,否则返回字符串“no error”。
  • 语言:painless
  • 返回类型:字符串
if (doc['referer.keyword'].value =~ /error/) { 
return "error"
} else {
return "no error"
}

注意:简化的正则表达式语法对基于正则表达式匹配的条件句有用。

匹配字符串并返回该匹配

  • 示例:返回域,即 field “host”中最后一个点后面的字符串。
  • 语言:painless
  • 返回类型:字符串
def m = /^.*\.([a-z]+)$/.matcher(doc['host.keyword'].value);
if ( m.matches() ) {
   return m.group(1)
} else {
   return "no match"
}

注意:通过正则表达式 matcher() 函数定义对象,可以提取与正则表达式相匹配的字符组并将它们返回。

匹配数字并返回该匹配

  • 示例:返回 IP 地址的第一个八位组(存储为字符串)并将它视为一个数字。
  • 语言:painless
  • 返回类型:数字
 def m = /^([0-9]+)\..*$/.matcher(doc['clientip.keyword'].value);
if ( m.matches() ) {
   return Integer.parseInt(m.group(1))
} else {
   return 0
}

注意:在脚本中返回正确的数据类型是很重要的。正则表达式匹配返回的是字符串,即便匹配的是数字依然返回字符串,因此返回时应该显式地将它转换成整数。

返回字符串的日期运算

  • 示例:将日期解析成星期值再解析成字符串
  • 语言:painless
  • 返回类型:字符串
LocalDateTime.ofInstant(Instant.ofEpochMilli(doc['@timestamp'].value), ZoneId.of('Z')).getDayOfWeek().getDisplayName(TextStyle.FULL, Locale.getDefault())

注意:由于 Painless 支持 Java 所有的原生类型,因此通过它可以获取与这些类型相关的原生函数,例如 LocalDateTime(),这在执行更加高级的日期运算时有用。

最佳实践

如你所见,Painless 脚本化语言提供了一些强大的方法,能够通过 Kibana 脚本化 field 从存储在 Elasticsearch 中的任意 field 提取出有用的信息。但是,能力越大,责任越大。

接下来,我们将围绕 Kibana 脚本化 field 的使用,简要地介绍了一些最佳实践。

  • 始终使用开发环境测试脚本化 field。由于你在 Kibana 的 Management(管理)区域保存脚本化 field 之后,它们就会立即激活(例如:它们会出现该索引模式的 Discover(探索)界面,供所有用户使用),因此不应该直接在生产环境中开发脚本化 field。我们建议先在开发环境中试用你的语法,在模拟环境中评估脚本化 field 对实际数据集和数据卷的影响,然后才能将它们提升到生产环境。
  • 当你相信脚本化 field 能够为你的用户提供价值时,可以考虑对你的 ingest 进行修改,以便在索引时从 field 中提取新数据。这将节省 Elasticsearch 在查询时的处理工作量,并且将为 Kibana 用户实现更快的响应时间。你还可以使用 Elasticsearch 中的 _reindex API 重新索引现有数据。