操作指南

API 文档

有奖征文|投稿上云技术实践,赢取价值5000元大奖> HOT

概述

索引配置是使用日志服务(Cloud Log Service,CLS)进行检索分析的必要条件,只有开启索引才能对日志进行检索分析。而且不同的索引规则也会产生不同的日志检索分析效果,本文档会详细介绍索引的配置规则及原理。

索引配置的核心是对原始日志进行 分词,以快速且便捷的根据特定的检索条件检索日志,同时在索引配置中还可以针对特定的字段“开启统计”,便于使用 SQL 对日志进行统计分析。日志服务包含以下三类索引:

类别 描述 配置方式
全文索引 全文索引将原始日志整体切分为多个分词进行索引构建,检索时直接通过关键词进行检索(即全文检索)
例如输入 error 表示检索包含 error 关键词的日志
控制台:在索引配置页面中,开启全文索引
键值索引 键值索引将原始日志按字段(即 key:value)分别切分为多个分词进行索引构建,检索时基于键值方式进行检索(即键值检索)
例如输入 level:error 表示检索 level 字段中包含 error的日志
控制台:在索引配置页面中,开启键值索引,并填写对应的字段名称(即key),例如 level
元数据索引 元数据索引也是键值索引的一种,但字段名称会以__TAG__作为前缀进行标识,常用于对日志进行分类
例如输入__TAG__.region:"ap-beijing" 表示检索元数据中 region 字段为ap-beijing 的日志
控制台:在索引配置页面中,开启键值索引,并填写对应元数据字段名城(即 key),例如 __TAG__.region
注意:

  • 配置索引会产生相应的索引流量费用及索引存储费用,详情可参见 计费概述。如需节省日志服务使用成本,可参见 节省产品使用成本
  • 索引关闭时采集的日志数据无法被检索,从开启索引到支持日志检索分析约存在一分钟左右的延迟。
  • 只有键值索引中“开启统计”的字段支持使用 SQL 进行统计分析。
  • 索引规则编辑(包括新增/编辑/删除字段、调整分词符配置等在内的所有操作)后仅对新写入的日志生效,已有数据不会更新。

前提条件

使用 Loglistener 采集日志时,如果采集配置中提取模式为单行全文或多行全文,日志原文存储在__CONTENT__字段中,仅支持配置全文索引。如需为其中的部分内容配置键值索引或开启统计,需在采集配置中进行 日志结构化 处理,使用除单行全文和多行全文以外的日志采集提取模式。

全文索引

全文索引将原始日志整体切分为多个分词进行索引构建,检索时直接通过关键词进行检索(即全文检索)。

配置项 功能描述
全文分词符 对原始日志进行分词的字符集合,仅支持英文符号,控制台默认分词符 @&?|#()='",;:<>[]{}/ \n\t\r
大小写敏感 检索时是否对大小写敏感
例如日志为 Error,若大小写敏感,则使用 error 无法检索到该条日志
是否包含中文 日志中包含中文且需要对中文进行检索时可开启该功能
例如日志原文为“用户登录接口超时”,若未开启该功能,搜索“超时”无法检索到该日志,只有完整的搜索“用户登录接口超时”才能检索到该日志,开启该功能后便可通过搜索“超时”检索到该日志

例如,一条完整的日志如下所示:

10.20.20.10;[2018-07-16 13:12:57];GET /online/sample HTTP/1.1;200

若使用 分隔符模式 提取日志字段,则上传到日志服务的结构化日志为:

IP: 10.20.20.10
request: GET /online/sample HTTP/1.1
status: 200
time: [2018-07-16 13:12:57]

若全文分词符为 @&()='",;:<>[]{}/ \n\t\r(包含空格),则原始日志的所有字段值会切分为如下关键词(每行表示一个关键词):

10.20.20.10
GET
online
sample
HTTP
1.1
200
2018-07-16
13
12
57

在上述的索引配置下,使用以下的检索条件,获得的结果如下:

  • 检索条件 A:
    \/online\/login
    • 其中\用于转义/符号(该符号为检索语法保留符号,因此需要转义)。
    • 转义后的/符号是分词符,因此实际的检索条件为 online OR login,日志中只要包含 online login,即符合检索条件。
    • 上述示例日志符合该检索条件。
  • 检索条件 B:
    "/online/login"
    • 由于双引号的存在,/符号无需再进行转义。
    • 双引号内的内容同样会分为两个词,但双引号表示日志需同时存在这两个词,且两个词顺序严格一致才符合检索条件。
    • 上述示例日志不包含login不符合该检索条件。
  • 检索条件 C:
    "/online/sample"
    • 上述示例日志同时包含onlinesample,且顺序与检索条件一致,符合该检索条件。

键值索引

键值索引将原始日志按字段(即 key:value)分别切分为多个分词进行索引构建,检索时基于键值方式进行检索(即键值检索)。进行键值检索的时候,必须指定字段名,语法格式为key:value,例如status:200。若不指定字段名,则会当成全文检索处理。

为满足最基本的日志检索要求,日志服务针对部分内置保留字段自动创建键值索引,但不会产生索引流量,不会增加费用,具体如下:

内置保留字段 说明
__FILENAME__ 日志采集的文件名,可以利用该字段检索特定文件下的日志,例如__FILENAME__:"/var/log/access.log" 检索 /var/log/access.log 文件的日志
__SOURCE__ 日志采集的源 IP,可以利用该字段检索特定机器下的日志,例如 __SOURCE__:192.168.10.10 检索192.168.10.10 机器的日志
__TIMESTAMP__ 日志时间戳(毫秒级别 Unix 时间戳),按时间范围检索日志时,将自动使用该时间对日志进行检索,在控制台显示为“日志时间”
__PKG_LOGID__ 日志在 日志组 中的 ID,用于 上下文检索,不建议单独使用
配置项 功能描述 说明
字段名称 结构化日志 中的字段名称 -
数据类型 字段的数据类型,包括text、long、double三种类型,其中text类型支持使用通配符进行模糊检索,long、double 类型支持通过数值范围进行检索 long - 整型(Int 64)
double - 浮点型(64 bit)
text - 字符串
分词符 对字段值进行分词的字符集合,仅支持英文符号 控制台默认分词符 @&?|#()='",;:<>[]{}/ \n\t\r
包含中文 字段中包含中文且需要对中文进行检索时可开启该功能。
例如日志原文为“用户登录接口超时”,若未开启该功能,搜索“超时”无法检索到该日志,只有完整的搜索“用户登录接口超时”才能检索到该日志,开启该功能后便可通过搜索“超时”检索到该日志
-
开启统计 启用后可对该字段使用SQL进行统计分析,如 group by ${key}sum(${key}) 属于键值索引功能的一部分,不单独计费
大小写敏感 检索时是否对大小写敏感
例如日志为 level:Error,若大小写敏感,则使用level:error 无法检索到该条日志
-

例如,一条完整的日志如下所示:

10.20.20.10;[2018-07-16 13:12:57];GET /online/sample HTTP/1.1;200

若使用 分隔符模式 提取日志字段,则上传到日志服务的结构化日志为:

IP: 10.20.20.10
request: GET /online/sample HTTP/1.1
status: 200
time: [2018-07-16 13:12:57]

若键值索引的配置如下:

字段名称 字段类型 分词符 包含中文 开启统计
IP text @&()='",;:<>[]{}/ \n\t\r
request text @&()='",;:<>[]{}/ \n\t\r
status long
time text @&()='",;:<>[]{}/ \n\t\r

在上述的索引配置下,使用以下的检索条件,获得的结果如下:

  • 检索条件 A:
    request:\/online\/login
    • 其中\用于转义/符号(该符号为检索语法保留符号,因此需要转义)。
    • 转义后的/符号是分词符,因此实际的检索条件为 online OR login,日志中只要包含 online login,即符合检索条件。
    • 上述示例日志符合该检索条件。
  • 检索条件 B:
    request:"/online/login"
    • 由于双引号的存在,/符号无需再进行转义。
    • 双引号内的内容同样会分为两个词,但双引号表示日志需同时存在这两个词,且两个词顺序严格一致才符合检索条件。
    • 上述示例日志不包含login不符合该检索条件。
  • 检索条件 C:
    request:"/online/sample"
    • 上述示例日志同时包含onlinesample,且顺序与检索条件一致,符合该检索条件。

此外,针对开启了统计的字段,还可以使用 SQL 对日志进行统计分析:

  • 检索分析语句 A:
    request:"/online/login" | select count(*) as logCounts
    统计 request 为 "/online/login" 的日志条数。
  • 检索分析语句 B:
    * | select count(*) as logCounts,request group by request order by count(*) desc limit 10
    统计日志条数最大的10个 request。

元数据索引

上传日志到日志服务时,元数据通过 LogTag 字段传递(详情可参见 上传结构化日志 中的LogTag字段 ),而原始日志内容通过 Log 字段传递。所有通过LogTag 传递的数据,配置索引时,均需配置元数据索引。元数据索引其实也归属键值索引,索引规则以及配置方式与键值索引相同,唯一差别在于,元数据字段有特定前缀__TAG__.进行标识,例如配置region 元数据字段的索引为 __TAG__.region

例如一条完整的日志如下所示:

10.20.20.10;[2018-07-16 13:12:57];GET /online/sample HTTP/1.1;200
若使用 分隔符模式 提取日志字段,且携带元数据 region:ap-beijing,则上传到日志服务的结构化日志为:
IP: 10.20.20.10
request: GET /online/sample HTTP/1.1
status: 200
time: [2018-07-16 13:12:57]
__TAG__.region:ap-beijing
其中,元数据的索引配置规则:

字段名称 分词符
__TAG__.region @&()='",;:<>[]{}/ \n\t\r

检索示例:输入__TAG__.region:"ap-beijing",可以检索到该示例日志。

高级设置

为满足部分特殊使用场景,索引配置提供如下高级设置。实际使用过程中,建议您采用推荐配置。通过控制台新建索引配置时,也会默认采用推荐配置。

配置项 含义 推荐配置
内置保留字段包含至全文索引 包含:全文索引包含__FILENAME____HOSTNAME____SOURCE__这三个内置字段,可直接使用全文检索的方式检索相关日志字段,例如"/var/log/access.log"
不包含:全文索引不包含任何内置字段,只能使用键值检索的方式检索相关日志字段,例如__FILENAME__:"/var/log/access.log"
包含
元数据字段包含至全文索引 包含:全文索引包含元数据字段(前缀为__TAG__的字段),可直接使用全文检索的方式检索相关日志字段,例如ap-beijing
不包含:全文索引不包含任何元数据字段,只能使用键值检索的方式检索相关日志字段,例如__TAG__.region:ap-beijing。低频日志主题不支持键值检索,此时将无法检索这些字段
仅包含开启键值索引元数据字段:全文索引包含开启了键值索引的元数据字段,不包含未开启键值索引的元数据字段。低频日志主题无该选项
包含
日志创建索引异常存储 日志创建索引过程中,如果存在日志原文格式异常或索引配置与日志原文不匹配,可能会导致索引创建失败,导致日志无法被检索和查看,此时可将日志的异常部分存储到指定字段(默认为 RAWLOG)中,以避免日志丢失。
详细处理规则参见 创建索引异常日志处理规则
启用

操作步骤

编辑索引配置

  1. 登录 日志服务控制台
  2. 在左侧导航栏中,单击日志主题,进入日志主题列表页面。
  3. 单击需要配置索引的日志主题ID/名称,进入日志主题管理页面。
  4. 选择索引配置页签, 单击编辑,进入编辑索引配置页面。
  5. 根据实际需求,编辑索引配置,单击确定即可保存该索引配置。
    编辑索引配置过程中,您还可以单击自动配置,系统将自动获取采集到的最近1条日志作为样例,并将其中的字段解析为键值索引。您可以在自动配置的基础上进行微调,快速获取最终的索引配置信息。

导入索引配置

  1. 登录 日志服务控制台
  2. 在左侧导航栏中,单击日志主题,进入日志主题列表页面。
  3. 单击需要配置索引的日志主题ID/名称,进入日志主题管理页面。
  4. 选择索引配置页签,单击导入配置规则
  5. 在对话框中,选择需要导入的日志主题索引配置,单击确定,将选中的日志主题的索引配置填写至当前日志主题的索引配置中。
  6. 确认无误后,单击确定,即可保存当前日志主题索引配置。

附录

JSON 字段解析规则

在存储过程中,为了避免日志中的 JSON 字段层级过多、对象过多或对象类型不一致,导致日志存储失败,CLS 将仅解析多层 JSON 字段至索引所配置的层级(未修改过索引配置的存量日志主题不受影响),其他层级会以字符串形式存储和展示。该功能升级仅影响原始日志检索结果(即检索语句中仅包含检索条件,不包含 SQL 语句),不影响统计分析结果(即 SQL 结果)。

下面以实际日志为例,详细介绍解析规则。

样例日志:

共三个字段,kye1 为普通字段,kye2 和 kye3 为多层 JSON 字段。

{
    "kye1": "http://www.example.com",
    "kye2": {
        "address": {
            "country": "中国",
            "city": {
                "name": "北京",
                "code": "065001"
            }
        },
        "contact": {
            "phone": {
                "home": "188xxxxxxxx",
                "work": "187xxxxxxxx"
            },
            "email": "xxx@xxx.com"
        }
    },
    "kye3": {
        "address": {
            "country": "中国",
            "city": {
                "name": "北京",
                "code": "065001"
            }
        },
        "contact": {
            "phone": {
                "home": "188xxxxxxxx",
                "work": "187xxxxxxxx"
            },
            "email": "xxx@xxx.com"
        }
    }
}

索引配置

键值索引配置如下图,键值索引配置字段为 kye1 和 kye2.address,kye3 未配置键值索引。

控制台检索分析效果

JSON 代码:

Table 样式:

  • kye2.address 整体显示为字符串,没有进一步展开其下的属性和对象。
  • kye2.contact 虽然没有配置键值索引,但由于索引配置到了 kye2.address,kye2.contact 作为同层级对象,同样整体显示为字符串。
  • kye3 未配置键值索引,所以没有展开任何属性和对象。

控制台展示日志时提供了 JSON 格式化功能,可将字符串形式的 JSON 字段按层级显示,但该功能仅为控制台显示效果,实际的字段仍为字符串,这一点可在下文的 API 检索分析结果中体现出来。

API 检索分析结果效果

使用 检索分析⽇志 API 时,输出参数中的 Results 参数值如下(其他参数不受影响,无变化):

{
  "Time": 1645065742008,
  "TopicId": "f813385f-aee0-4238-xxxx-c99b39aabe78",
  "TopicName": "TestJsonParse",
  "Source": "172.17.0.2",
  "FileName": "/root/testLog/jsonParse.log",
  "PkgId": "5CB847DA620DB3D4-10D",
  "PkgLogId": "65536",
  "HighLights": [],
  "Logs": null,
  "LogJson": "{\"kye1\":\"http://www.example.com\",\"kye2\":{\"address\":\"{\\\"country\\\":\\\"中国\\\",\\\"city\\\":{\\\"name\\\":\\\"北京\\\",\\\"code\\\":\\\"065001\\\"}}\",\"contact\":\"{\\\"phone\\\":{\\\"home\\\":\\\"188xxxxxxxx\\\",\\\"work\\\":\\\"187xxxxxxxx\\\"},\\\"email\\\":\\\"xxx@xxx.com\\\"}\"},\"kye3\":\"{\\\"address\\\":{\\\"country\\\":\\\"中国\\\",\\\"city\\\":{\\\"name\\\":\\\"北京\\\",\\\"code\\\":\\\"065001\\\"}},\\\"contact\\\":{\\\"phone\\\":{\\\"home\\\":\\\"188xxxxxxxx\\\",\\\"work\\\":\\\"187xxxxxxxx\\\"},\\\"email\\\":\\\"xxx@xxx.com\\\"}}\"}"
}

  • kye2.address 为字符串,因此其值被转义为字符串。
  • kye2.contact 作为 kye2.address 的同层级对象,虽然未配置键值索引,其值同样被转义为字符串。
  • kye3 未配置键值索引,所以整体被转义为字符串。

如果您在使用代码处理 检索分析⽇志 的 API 输出参数,请注意此处的转义符,避免处理逻辑出现异常。为方便您对比功能升级前后的 API 输出参数变化细节,升级前的 API 输出参数如下:

{
  "Time": 1645065742008,
  "TopicId": "f813385f-aee0-4238-xxxx-c99b39aabe78",
  "TopicName": "zhengxinTestJsonParse",
  "Source": "172.17.0.2",
  "FileName": "/root/testLog/jsonParse.log",
  "PkgId": "25D0A12F620DBB64-D3",
  "PkgLogId": "65536",
  "HighLights": [],
  "Logs": null,
  "LogJson": "{\"kye1\":\"http://www.example.com\",\"kye2\":{\"address\":\"{\\\"city\\\":{\\\"code\\\":\\\"065001\\\",\\\"name\\\":\\\"北京\\\"},\\\"country\\\":\\\"中国\\\"}\",\"contact\":{\"phone\":{\"work\":\"187xxxxxxxx\",\"home\":\"188xxxxxxxx\"},\"email\":\"xxx@xxx.com\"}},\"kye3\":{\"address\":{\"country\":\"中国\",\"city\":{\"code\":\"065001\",\"name\":\"北京\"}},\"contact\":{\"phone\":{\"work\":\"187xxxxxxxx\",\"home\":\"188xxxxxxxx\"},\"email\":\"xxx@xxx.com\"}}}"
}

创建索引异常日志处理规则

日志创建索引过程中,如果日志原文格式异常或索引配置与日志原文不匹配,可能会导致索引创建失败,无法被检索和查看这些日志。此时,可将日志的异常部分存储到指定字段(默认为 RAWLOG)中,以避免日志丢失。

下面以实际日志为例,详细介绍处理规则。

会导致创建索引异常的日志

  • 样例日志1:
    如下日志,city 对象下的 name 及 code 未使用双引号包裹。
    {
        "kye1": "http://www.example.com",
        "kye2": {
            "address": {
                "country": "中国",
                "city": {
                    name: "北京", //格式错误,缺失双引号
                    code: "065001" //格式错误,缺失双引号
                }
            }
        }
    }
  • 样例日志2:
    如下日志,索引配置中添加了kye2.address.city.name字段,但实际上 city 为字符串,并没有子级对象。
    {
        "kye1": "http://www.example.com",
        "kye2": {
            "address": {
                "country": "中国",
                "city": "北京" //city为字符串,并没有子级对象name
            }
        }
    }
  • 样例日志3:
    如下日志,索引配置中添加了kye2.address.city字段,但实际上 address 为数组,并没有 city 这一子级对象,CLS 不支持为数组内的对象创建索引。
    {
        "kye1": "http://www.example.com",
        "kye2": {
            "address": [{ //address为数组,并没有city这一子级对象
                "country": "中国",
                "city": "北京"
            }, {
                "country": "中国",
                "city": "上海"
            }]
        }
    }

处理规则

在索引配置的高级设置中启用日志创建索引异常存储功能后,CLS 若遇到上述异常日志,将尽可能的根据索引规则解析日志并创建索引,同时将日志中的错误部分存储到指定的字段(默认为 RAWLOG)。
例如如下日志,索引配置中包含kye1kye2.address.city两个字段。

{
    "kye1": "http://www.example.com",
    "kye2": {
        "address": [{ //address为数组,并没有city这一子级对象
            "country": "中国",
            "city": "北京"
        }, {
            "country": "中国",
            "city": "上海"
        }]
    }
}
kye1字段可正常解析并创建索引,kye2字段由于和索引配置不一致,无法正常解析,则该字段将会转为字符串并存储至 RAWLOG 字段下。可在控制台看到如下日志:
kye1   : http://www.example.com
RAWLOG : {"kye2":"{\"address\":[{\"country\":\"中国\",\"city\":\"北京\"},{\"country\":\"中国\",\"city\":\"上海\"}]}"}
可直接使用全文检索的方式检索该日志(例如"中国"),也可以为 RAWLOG 添加键值索引,使用键值索引的方式检索该日志(例如RAWLOG:"中国")。通过RAWLOG:*还可以检索到所有存在创建索引异常的日志,帮助您合理的调整日志输出格式及索引配置。

目录