机器数据分析平台

  • 机器数据分析平台 > 使用文档 > 搜索手册 > 字段查找 > 字段查找规则

    字段查找规则

    最近更新时间:2021-12-06 19:31:25

    字段查找规则
    查找通过匹配添加查找表中的字段来丰富您的搜索数据,字段查找规则可以定义基于csv文件、外部脚本及KV存储类型的查找,需要定义查找表中的信息以及该信息如何与事件数据中的字段相匹配。一个查找表可以配置多个查找规则。创建查找规则后,您可以在搜索中调用lookup命令进行查找。


    CSV查找规则

    CSV类型的字段查找规则基于csv静态文件,需要上传csv查找表文件并基于该文件创建查找规则,通常情况下适用于数据量较小且相对静态的查找源,通过匹配事件数据中的字段和表文件中的字段,将csv表文件中对应的字段值输出到事件中。

    创建CVS查找规则

    CSV查找规则的创建流程如下:
    1、点击设置 > 查找管理 > 查找规则进入查找规则管理列表;
    2、点击新建按钮配置查找规则,选择匹配类型为CSV文件,具体配置如下:

    配置 说明
    目标应用 选择查找规则所存储的目标应用,对应的查找表文件需要保存在应用程序所在目录中
    名称 输入字段查找规则名称,唯一标识该对象
    查找类型 选择基于文件作为查找类型,可以支持基于四种查找类型定义字段查找规则:表文件、kv存储、外部脚本
    表文件 选择已有CSV表文件,或可以新建表文件
    自动查找 编辑自动查找配置,具体参见本节下文自动查找
    时序查找 配置基于时序的字段查找,当CSV文件包含时序字段,可以勾选配置基于时间的查找使CSV查找具备时间限制,具体参见本节下文时间查找
    高级配置 编辑字段查找高级配置,具体参见本节下文高级配置

    3、点击保存完成基于CSV文件的查找规则的创建,可以在查找规则列表中进行查看,默认权限为个人所有。

    P.s.在配置基于CSV文件的查找规则前,您需要先上传用于匹配查找的csv表文件,并将该表文件访问权限设置为在APP内或全局范围共享。

    配置CSV查找规则权限

    完成查找规则的创建后,可以针对具体查找规则配置权限来定义可以在哪些应用范围内共享给哪些用户角色使用,具体配置步骤如下:

    1. 点击设置—>查找管理—>查找规则进入查找规则管理列表;
    2. 在列表中选择要配置权限的查找规则,点击授权按钮。
    3. 在“设置权限”配置框中,选择在APP内或者全局范围内哪些用户角色可以对该查找规则进行查看/访问、编辑或删除权限;
    4. 点击保存完成权限配置。

    注:查找表文件的权限必须等同于或高于使用这些文件的查找规则的权限。

    KV存储查找规则

    KV存储查找规则可以将APP中KV存储数据表里的字段进行查找并输出至您的事件数据中,完成查找规则定义后使用lookup,inputlookup,及outputlookup算子进行调用,KV存储查找规则通常适用于更新频率较高或者较大的lookup表。
    创建基于KV存储的查找规则具体配置步骤如下:
    1、创建KV存储数据表。KV存储表将您的数据存储为键值对。创建KV存储查找时,数据表至少包含两个字段,其中一个字段作为输入字段与搜索数据中字段进行匹配。当在搜索中调用lookup命令进行查找时指定输入匹配字段,当事件中输入字段值与KV存储表中指定字段的值匹配时,该KV存储表中其他对应字段的值将输出到搜索数据中。用户可以使用API进行创建数据表、插入数据、查询数据、删除数据、修改数据等数据管理操作;
    2、点击设置 > 查找管理 > 查找规则进入查找规则管理列表;
    3、点击新建按钮配置查找规则,选择匹配类型为KV存储,具体配置如下:

    配置 说明
    目标应用 选择查找规则所存储的目标应用,对应的查找表文件需要保存在应用程序所在目录中
    名称 输入字段查找规则名称,唯一标识该对象
    查找类型 选择基于KV存储作为查找类型,可以支持基于四种查找类型定义字段查找规则:表文件、kv存储、外部脚本
    数据表 KV存储的数据表集合
    支持字段 输入要支持的字段,以逗号","分隔
    自动查找 编辑自动查找配置,具体参见本节下文自动查找
    时序查找 配置基于时序的字段查找,当CSV文件包含时序字段,可以勾选配置基于时间的查找使CSV查找具备时间限制,具体参见本节下文时间查找
    高级配置 编辑字段查找高级配置,具体参见本节下文高级配置

    4、点击保存完成基于KV存储的查找规则的创建,可以在查找规则列表中进行查看,默认权限为个人所有。

    KV存储查找对比CSV文件查找
    CSV文件:

    • 适用于小文件或较少修改数据的文件
    • 支持区分大小写的字段查找
    • 更易于手动修改- 需要完全重写文件以进行编辑操作
    • 不支持REST API访问

    KV存储:

    • 支持针对单条记录的更新
    • 不支持不区分大小写的字段查找
    • 支持 REST API 访问

    配置外部脚本查找规则权限

    完成查找规则的创建后,可以针对具体查找规则配置权限来定义可以在哪些应用范围内共享给哪些用户角色使用,具体配置步骤如下:

    1. 点击设置 > 查找管理 > 查找规则进入查找规则管理列表;
    2. 在列表中选择要配置权限的查找规则,点击授权按钮。
    3. 在“设置权限”配置框中,选择在APP内或者全局范围内哪些用户角色可以对该查找规则进行查看/访问、编辑或删除权限;
    4. 点击保存完成权限配置。

    外部脚本查找规则

    定义基于外部脚本的查找规则后,在执行查找时调用外部脚本,可以使用python脚本或二进制可执行文件来匹配查找外部源查找表的字段,并输出到搜索数据中。具体脚本实现参见查找外部脚本
    创建外部脚本查找规则具体配置步骤如下:
    1、编辑查找脚本,如pisatest.py,并将脚本添加到./app/{app_name}/bin目录下;
    2、点击设置 > 查找管理 > 查找规则进入查找规则管理列表;
    3、点击新建按钮配置查找规则,选择匹配类型为外部脚本,具体配置如下:

    配置 说明
    目标应用 选择查找规则所存储的目标应用,对应的查找表文件需要保存在应用程序所在目录中
    名称 输入字段查找规则名称,唯一标识该对象
    查找类型 选择基于外部脚本作为查找类型,可以支持基于四种查找类型定义字段查找规则:表文件、kv存储、外部脚本
    脚本命令 请输入要执行的命令和参数,参数是传递给脚本的字段名称,命令必须是位于./app/{app_name}/bin中的Python脚本或二进制可执行文件,如dns_lookup.py clienthost clientip
    支持字段 输入要支持的字段,以逗号","分隔,支持字段”必须完全匹配外部脚本中有的字段,lookup才能输出
    自动查找 编辑自动查找配置,具体参见本节下文自动查找
    时序查找 配置基于时序的字段查找,当CSV文件包含时序字段,可以勾选配置基于时间的查找使CSV查找具备时间限制,具体参见本节下文时间查找
    高级配置 编辑字段查找高级配置,具体参见本节下文高级配置

    4、点击保存完成基于外部脚本的查找规则的创建,可以在查找规则列表中进行查看,默认权限为个人所有。

    配置外部脚本查找规则权限

    完成查找规则的创建后,可以针对具体查找规则配置权限来定义可以在哪些应用范围内共享给哪些用户角色使用,具体配置步骤如下:

    1. 点击设置 > 查找管理 > 查找规则进入查找规则管理列表;
    2. 在列表中选择要配置权限的查找规则,点击授权按钮。
    3. 在“设置权限”配置框中,选择在APP内或者全局范围内哪些用户角色可以对该查找规则进行查看/访问、编辑或删除权限;
    4. 点击保存完成权限配置。

    外部查找脚本

    外部脚本可以是Python脚本或二进制可执行脚本(如C++可执行文件),脚本中定义如何获取外部源数据作为查找表。外部脚本必须以csv表的格式输入输出数据,传递的脚本参数是输入输出csv表的表头。
    以DNS_lookup为例,定义一个外部脚本来创建一个lookup表,里面包括clienthost,clientip字段。csv表中数据如下:

    clienthost,clientip
    10.200.20.22,cs2
    10.200.20.39,cs19
    ...,...
    

    点击下载dns示例脚本

    注:当脚本中引用了CSV文件,文件路径必须相对于脚本所在的目录。

    自动查找

    手动查找配置完成后需要在搜索中调用lookup命令运行。配置自动查找,则查找在每次搜索时针对相应搜索数据自动运行,无需使用lookup命令。
    在查找规则配置时勾选自动查找,具体配置如下:

    配置 说明
    来源类型 填写来源类型名称,表示自动查找应用的数据范围
    输入字段 将搜索结果的某字段对应到查找中的字段。前输入框输入查找表中的字段名称,后输入框输入搜索结果中的字段名称
    输出字段 将查找表中的字段输出到搜索结果中,可以添加多个。前输入框输入查找表中的字段名称,后输入框输入用户希望输出到搜索结果中的字段名称,即将输出字段重命名
    覆盖字段值 默认不勾选,表示如果搜索结果中存在该输出字段,则保留原搜索结果中的字段值;勾选后查找表的输出字段值覆盖搜索结果中的字段值

    避免自动查找引用循环

    在配置自动查找时,当查找的输入/输出字段在同一查找规则或相关查找规则间中被重复引用时,可能会发生引用循环。在对应搜索时您将收到自动查找定义的查找引用循环的错误提示。
    例如,以下自动查找规则设置会导致引用循环:

    • 在事件中用于匹配的输入字段与输出字段名相同,如输入和输出字段都是type。
        lookup_sales slaes_type as type ouputnew type
    
    • 当定义两个或多个相关自动查找规则,输出字段留空时默认将查找表中所有不是匹配字段的字段作为输出字段,可能会遇到更复杂的引用循环。例如,多个查找组合后出现:f1 ← f3 ← f2 ← f1。
      例如,配置一个查找表fields(包含字段:f1,f2,f3,f4 ),设置以下两个基于fields查找表的自动查找规则:
        lookup_fields1 f1 as f2 ouput
        lookup_fields2 f1 as f3 ouputnew f4
    

    时间查找

    如果查找表中有时间字段,可以创建基于时间的字段查找,也称为时间查找,三种查找表类型都支持配置基于时间的查找。
    基于时间的查找将数据搜索结果中的时间戳与查找表中的时间戳进行匹配,然后将匹配的数据添加到搜索结果中。用户还可以定义时间偏移范围,基于数据搜索结果中的时间定义匹配查找表的时间范围。
    在查找规则配置时勾选时间查找,具体配置如下:

    配置 说明
    时间字段 指定查找表中的时间戳字段。搜索按时间降序匹配查找表中第一条匹配数据,最大匹配数默认为1
    时间格式 指定时间格式,默认为UTC格式
    时间偏移 可以指定事件可能晚于查找匹配项的最短和最⻓时间的偏移,默认没有最⼤偏移(默认值为3000000000),默认最⼩偏移是0。根据搜索数据时间戳的偏移计算最早和最晚的时间值,来确定查找的时间范围限制,在这个时间窗口内,搜索按时间降序去查找匹配项直到满足最大匹配数,默认最大匹配数为1:最早 = 事件时间戳 -最大偏移,最新 = 事件时间戳 -最小偏移

    高级配置

    支持编辑最小匹配数、最大匹配数、默认匹配、匹配类型、过滤条件等高级配置。具体配置如下:

    配置 说明
    最小匹配数 查找输入字段最小匹配数量,默认为0
    最大匹配数 查找输入字段最小匹配数量,默认为100,针对时间查找默认为1
    默认匹配 当查找匹配数小于最小匹配数时输入默认匹配值,默认为空字符串
    大小写敏感 默认勾选,表示对字段值大小写敏感
    匹配类型 可以选择精准匹配或通配符匹配。默认为精准匹配,则用户搜索结果数据需要跟查找表对应字段精准匹配。选择通配符匹配,则需要输入匹配字段,多个字段以逗号“,”分隔
    过滤条件 当查找表非常大时,如果您只需要查找表中⼀个⼦集时,可以输入包含带有布尔表达式及⽐较运算符(==、 !=、>、<、<=、 >=、OR、AND 和 NOT)的搜索查询进行预过滤,例如 (userID>500) AND (userName=“Pan*”),以提升搜索性能

    查找示例

    CSV文件查找示例

    该示例中定义了一个基于CSV文件的lookup查找HTTP状态码,针对Web访问日志,用户可以基于查找表http_status.csv进行查找,该查找将事件中的http_status_code字段与查找表中对应列相匹配,在Web访问日志中输出相应的http_status_name和http_status_description字段。CSV表文件中内容示例:

    http_status_code http_status_name http_status_description
    100 Continue 继续。客户端应继续其请求

    点击下载该http_status_code.csv文件
    使用步骤如下:
    1、点击设置 > 查找管理 > 查找表文件进入查找表文件管理列表,创建CSV文件http_status.csv:选择目标应用,浏览选择对应CSV文件,选择提取方式,输入文件名称http_status后点击保存;
    image.png
    2、点击设置 > 查找管理 > 查找规则进入查找规则管理列表,创建基于该CSV文件的查找规则http_status:选择目标应用,输入规则名称http_status,查找类型选择基于文件,选择前面创建的表文件http_status.csv,点击保存。
    image.png
    3、(可选)可以将查找配置为自动运行。勾选自动查找,将查找应用于sourcetype=Apache的数据上,输入字段配置为http_status_code > status_code(左侧输入框为csv表中字段,右侧输入框为搜索数据中字段),输出字段是查找表中要添加到事件中的字段:http_status_description > status_description(左侧输入框为csv表中要输出的字段,右侧输入框为要输出到搜索数据中的字段名);
    4、(可选)可以选择配置最小匹配数、最大匹配数、默认匹配、过滤条件等高级配置项;
    5、定义查找后,可以在搜索中使用lookup命令调用它,例如运行以下搜索,在包含http_status_code字段的Apache访问日志access_log中添加http_status_description。

    repo="apache"| lookup http_status http_status_code as status_code output http_status_description as status_description
    

    外部脚本查找示例

    该示例中定义了一个基于python脚本的查找规则DNS_lookup查找域名对应的IP地址。定义一个外部脚本来创建一个lookup表,里面包括clienthost,clientip字段。csv表中数据如下:

    clienthost,clientip
    10.200.20.22,cs2
    10.200.20.39,cs19
    ...,...
    

    点击下载示例脚本dns_lookup.py

    注:当脚本中引用了CSV文件,文件路径必须相对于脚本所在的目录。

    使用步骤如下:
    1、编辑查找脚本,并将脚本dns_lookup.py添加到./app/search/bin目录下;
    2、点击设置 > 查找管理 > 查找规则进入查找规则管理列表,创建基于外部脚本的查找规则dns_lookup:选择目标应用,输入规则名称dns_lookup,查找类型选择基于外部脚本,输入脚本命令及支持字段clienthost,clientip,点击保存。
    3、(可选)可以将查找配置为自动运行。勾选自动查找,将查找应用于sourcetype=_internal的数据上,输入字段配置为clienthost > clienthost(左侧输入框为csv表中字段,右侧输入框为搜索数据中字段),输出字段是查找表中要添加到事件中的字段clientip > clientip(左侧输入框为csv表中要输出的字段,右侧输入框为要输出到搜索数据中的字段名);
    4、(可选)可以选择配置最小匹配数、最大匹配数、默认匹配、过滤条件等高级配置项;
    5、定义查找后,可以在搜索中使用lookup命令调用它,例如运行以下搜索,在包含host字段的日志中添加ip。

    repo="_internal"| lookup dns_lookup clienthost as host output clientip as ip
    
    以上内容是否对您有帮助?
  • Qvm free helper
    Close