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

配置索引

最近更新时间: 2024-06-12 15:06: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"，可以检索到该示例日志。

注意事项

  1. 索引关闭时采集的日志数据将无法被检索。

  2. 从开启索引到支持日志检索功能需经过一分钟延时。

  3. 存储数据的存储时间与日志集所设置的保存时间一致。

  4. 索引规则发生修改，仅对后续写入的新数据生效，已构建好的旧数据索引不会更新。

  5. 查询和分析仅基于一种索引规则。因此，索引规则一旦发生修改，可能会导致之前相同的查询分析语句计算出不同结果，因为新索引规则导致查询分析的数据范围发生了变化。