文档首页

租户端存储日志服务（CLS）操作指南

配置索引

最近更新时间: 2025-01-15 17:01:00

索引配置是使用日志服务进行检索分析的充分条件，只有开启索引，才能进行检索和分析。而且，设置不同的索引规则，也会产生不同的日志检索和分析表现效果。本文档会详细介绍索引的配置规则及原理。

日志服务的索引类型如下：

类别	描述	如何配置
全文索引	全文索引将原始日志拆分成多个分词进行索引构建，检索日志时基于分词进行查询，例如输入 `error` 表示查询包含 `error` 关键词的日志。如果您使用 Loglistener 以单行/多行全文的方式采集日志，需开启全文索引才能进行日志检索	控制台：在索引配置页面中，开启全文索引。
键值索引	键值索引将原始日志按键值对（即 key-value）进行索引构建，检索日志时基于键值方式进行查询，例如输入 `level:error` 表示查询 `level` 字段中为 `error`的日志。	控制台：在索引配置页面中，开启键值索引，并填写对应的字段名称（即键名称 key），例如 `level`。
元数据索引	元数据索引本质也是键值索引，但键名称会以`__TAG__`作为前缀字段进行标识，例如输入`__TAG__.client:192.168.10.10` 表示查询元数据中 `client` 字段为`192.168.10.10` 的日志。	控制台：在索引配置页面中，开启键值索引，并填写对应元数据字段名（即键名称 key），例如 `__TAG__.client`。

日志服务内置保留字段，包括采集源IP： __SOURCE__、采集文件： __FILENAME__，时间戳：__TIMESTAMP__，均会自动创建索引（该部分不计算索引流量，因此不会增加用户的费用成本），保留字段的详细说明如下：

内置字段	描述说明	费用
`__FILENAME__`	日志采集的文件名，可以利用该字段过滤文件名，例如`__FILENAME__:/var/log/access.log` 查询 `/var/log/access.log` 文件的日志。	自动创建索引，但不会计算索引流量，不会增加费用
`__SOURCE__`	日志采集的源IP，可以利用该字段过滤主机，例如 `__SOURCE__:192.168.10.10` 查询`192.168.10.10` 主机的日志	自动创建索引，但不会计算索引流量，不会增加费用
`__TIMESTAMP__`	日志时间戳，日志分析时可能会用到该字段	自动创建索引，但不会计算索引流量，不会增加费用
`__TAG__`	元数据字段的前缀，用于区别原始日志内容。	需要手动配置，会计算索引流量，计费参考计费说明

全文索引

全文索引是按照关键词进行检索的一种索引类型。全文索引会根据分词符规则，将原始日志内容的所有字段值内容拆分成诺干个关键词，然后构建索引。因此，若不指定键名称（即字段名key）进行关键词查询时，会根据全文索引进行检索。

配置项	描述说明
全文分词符	对原始日志内容进行分词的字符集合，控制台默认填入分词符`@&()='",;:<>[]{}/ \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

检索命中的判定规则为：命中日志必须包含至少一个关键词，具体可参考以下示例：

查询示例1：输入200进行查询，该条示例日志被命中，因为该日志包含 200 关键词。
查询示例2：输入 /online/sample 进行查询，不可以检索出该示例日志，因为/ 是CLS 检索语法保留符号(正则表达式标识符)，需要用\ 进行转义输入 \/online\/sample 。由于/被包含在全文索引分词符里面，所以\/online\/sample实际的查询逻辑是 online OR sample，所以可能会命中其他带有online或sample关键字的日志。
查询示例3：输入"/online/sample" 进行查询，可以检索出该示例日志。因为"" 也是CLS 检索语法保留符号，"/online/sample" 所包含的 / 、online、sample均视为普通字符，无需再转义。由于 /被包含在全文索引分词符里，"/online/sample" 的查询逻辑是 online AND sample 且词序不变，但 "/online/sample" 可能会命中其他日志内容，比如会命中/online/sample/abc。

键值索引

键值索引是根据键值对（key-value）进行索引构建，每个字段名（键名称）可以配置索引规则：包括数据类型、分词符、统计开启等。进行键值查询的时候，必须指定字段名，查询语法格式为:key:value，比如status:200。若不指定字段名，则会当成全文检索处理。

说明：日志服务内置保留字段，包括采集源IP： __SOURCE__、采集文件： __FILENAME__、时间戳：__TIMESTAMP__ ，默认配置键值索引，键值索引分词符为空，并开启统计，此部分不算作索引流量，因此不收费。

配置项	功能描述	说明
数据类型	字段的数据类型。比如，`text `类型支持模糊查询，`long、double` 类型支持范围查询。	long - 整型（Int 64） double - 浮点型（64 bit） text - 字符串
分词符	用于检索时的字段值分词规则，根据定义的字符集合对每个字段进行关键词切分。	默认分词符：`@&()='",;:<>[]{}/ \n\t\r`
开启统计	启用后，可对字段进行统计分析，如 `group by ${key}`，`sum(${key})` 等分析，详细请参见日志分析。	默认关闭
大小写敏感	切分后的关键词，查询时是否对大小写敏感；比如，切分后的关键词为`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	`@&()='",;:<>[]{}/ \n\t\r`
request	`@&()='",;:<>[]{}/ \n\t\r`
status	`@&()='",;:<>[]{}/ \n\t\r`
time	`@&()='",;:<>[]{}/ \n\t\r`

查询示例1：输入IP:10.20.20.10 ，可以检索出该示例日志，因为分词符不包含点号，10.20.20.10 视作一个关键词。
查询示例2：输入request：GET /online/sample，不可以检索出该示例日志，因为/ 是CLS 检索语法保留符号(正则表达式标识符)，需要转义输入 request:GET \/online\/sample 。由于/被包含在reqeust 的索引分词符里面，所以request:GET \/online\/sample实际的查询逻辑是 request:GET OR request:online OR request:sample，所以可能会命中其他带有日志。
查询示例3：输入 request:"GET /online/sample"，可以检索出该示例日志。由于"" 也是CLS 检索语法保留符号，所以request:"GET /online/sample" 所包含的GET、 / 、online、sample均视为普通字符，无需再转义。但是， / 被包含在request的索引分词符里，request:"GET /online/sample" 的查询逻辑是 request:（GET AND online AND sample） 且保持词序不变，可能还会命中其他日志内容，比如request:GET /online/sample/abc。

元数据索引

上传日志到日志服务时，元数据通过 LogTag 字段传递，而原始日志内容通过 Log 字段传递。所有通过LogTag 传递的数据，配置索引时，均需配置元数据索引。元数据索引其实也归属键值索引，索引规则以及配置方式与键值索引相同，唯一差别在于，元数据字段有特定前缀__TAG__.进行标识，比如配置client 元数据字段的索引为 __TAG__.client。

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

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"，可以检索到该示例日志。

注意事项

索引关闭时采集的日志数据将无法被检索。
从开启索引到支持日志检索功能需经过一分钟延时。
存储数据的存储时间与日志集所设置的保存时间一致。
索引规则发生修改，仅对后续写入的新数据生效，已构建好的旧数据索引不会更新。
查询和分析仅基于一种索引规则。因此，索引规则一旦发生修改，可能会导致之前相同的查询分析语句计算出不同结果，因为新索引规则导致查询分析的数据范围发生了变化。