tencent cloud

日志服务

动态与公告
产品动态
公告
新手指引
产品简介
产品概述
产品优势
地域和访问域名
规格与限制
基本概念
购买指南
计费概述
产品定价
按量计费（后付费）
欠费说明
清理日志服务资源
成本优化
常见问题
快速入门
一分钟入门指南
入门指南
使用 Demo 日志快速体验 CLS
操作指南
资源管理
权限管理
日志采集
指标采集
日志存储
指标存储
检索分析（日志主题）
检索分析（指标主题）
仪表盘
数据处理
投递与消费
监控告警
云产品中心
DataSight 独立控制台
历史文档
实践教程
日志采集
检索分析
仪表盘
监控告警
投递和消费
成本优化
开发者指南
通过 iframe 内嵌 CLS（旧方案）
通过 Grafana 使用 CLS
API 文档
History
Introduction
API Category
Making API Requests
Topic Management APIs
Log Set Management APIs
Index APIs
Topic Partition APIs
Machine Group APIs
Collection Configuration APIs
Log APIs
Metric APIs
Alarm Policy APIs
Data Processing APIs
Kafka Protocol Consumption APIs
CKafka Shipping Task APIs
Kafka Data Subscription APIs
COS Shipping Task APIs
SCF Delivery Task APIs
Scheduled SQL Analysis APIs
COS Data Import Task APIs
Data Types
Error Codes
常见问题
健康监测问题解释
采集相关
检索分析相关
其他问题
服务等级协议
CLS 政策
隐私协议
数据处理和安全协议
联系我们
词汇表
文档日志服务操作指南检索分析（日志主题）索引配置

索引配置

PDF
聚焦模式
字号
最后更新时间： 2025-11-19 20:15:33

概述

索引配置是使用日志服务（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
注意：
如果分词过长，仅会对其中前10000个字符建立索引，超出部分无法进行检索，但仍会完整存储日志。

大小写敏感
检索时是否对大小写敏感例如日志为 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"
上述示例日志同时包含online和sample，且顺序与检索条件一致，符合该检索条件。

键值索引

键值索引将原始日志按字段（即 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 机器的日志
__HOSTNAME__
日志来源机器名称，可以利用该字段检索特定机器下的日志，需使用2.7.4及以上版本的 Loglistener 才会采集该字段。
__TIMESTAMP__
日志时间戳（毫秒级别 Unix 时间戳），按时间范围检索日志时，将自动使用该时间对日志进行检索，在控制台显示为“日志时间”
__PKG_LOGID__
日志在 日志组 中的 ID，用于 上下文检索，不建议单独使用
配置项
功能描述
说明
字段名称
结构化日志 中的字段名称。
注意：
单个日志主题键值索引最多可添加300个字段。

-
数据类型
字段的数据类型，包括 text、long、double三种类型，其中 text类型支持使用通配符进行模糊检索，long、double 类型支持通过数值范围进行检索。
注意：
1. long 类型字段支持数据范围为-1E15 ~ 1E15，超出该范围的数据可能会丢失精度或不支持检索,超长数值字段索引配置建议：
如果不需要通过数值范围比较来检索该字段，可将该字段存储为 text 类型。
如果需要通过数值范围比较来检索该字段，可将该字段存储为 double 类型，可能会丢失部分精度。
2. double 类型字段支持数据范围为-1.79E+308 ~ +1.79E+308，如果浮点数编码位数超过64位，会造成精度丢失。

long - 整型（Int 64） double - 浮点型（64 bit）double text - 字符串
分词符
对字段值进行分词的字符集合，仅支持英文符号。
注意：
如果分词过长，仅会对其中前10000个字符建立索引，超出部分无法进行检索，但仍会完整存储日志。

控制台默认分词符 @&?|#()='",;:<>[]{}/ \\n\\t\\r
包含中文
字段中包含中文且需要对中文进行检索时可开启该功能。例如日志原文为“用户登录接口超时”，若未开启该功能，搜索“超时”无法检索到该日志，只有完整的搜索“用户登录接口超时”才能检索到该日志，开启该功能后便可通过搜索“超时”检索到该日志。
-
开启统计
启用后可对该字段使用 SQL 进行统计分析，如 group by ${key}，sum(${key}) 等。
注意：
text 类型字段开启统计时，如果值过长，仅前32766个字符参与统计运算（即 SQL）。如果字段包含中文，超出32766字符时该日志将丢失，建议存在该可能性时为该字段关闭统计。

属于键值索引功能的一部分，不单独计费
大小写敏感
检索时是否对大小写敏感
例如日志为 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"
上述示例日志同时包含online和sample，且顺序与检索条件一致，符合该检索条件。
此外，针对开启了统计的字段，还可以使用 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。

自动配置

开启自动配置开关后，将自动把日志内的字段添加到键值索引字段列表中，包括日志中新增的字段。
添加字段时，将根据字段值自动判断字段类型，将字段类型设置为 text、long 或 double，并使用如下配置。如果以下配置不满足使用需求（例如字段类型不正确），可在添加后的字段上手动修改。
字段类型
分词符
包含中文
开启统计
text
@&?|#()='",;:<>[]{}/ \\n\\t\\r\\\\
包含
开启
long
不涉及
不涉及
开启
double
不涉及
不涉及
开启
说明：
日志字段名称仅支持字母、数字、下划线和-./@，且不能以下划线开头，不符合该规则的字段不会添加到键值索引字段列表中。
日志字段为 json 字符串时，默认不会解析 json。如需将 json 中的子级字段添加至键值索引，请手动添加其中的任意子级字段，后续将自动把该子级字段的同级别字段添加到键值索引字段列表中。
例如原始日志共三个字段：
key1:textValue
key2:123
key3:{"ip":"123.123.123.132","url":"class/132.html","detail":{"status_code":"500","id":13}}
自动添加的键值索引字段列表为：
字段名称
字段类型
分词符
包含中文
开启统计
key1
text
@&?|#()='",;:<>[]{}/ \\n\\t\\r\\\\
包含
开启
key2
long
不涉及
不涉及
开启
key3
text
@&?|#()='",;:<>[]{}/ \\n\\t\\r\\\\
包含
开启
如果手动将字段 key3 修改为 key3.ip，将自动把 ip 同级的字段 url 及 detail 添加到键值索引字段列表中，最终的列表为：
字段名称
字段类型
分词符
包含中文
开启统计
key1
text
@&?|#()='",;:<>[]{}/ \\n\\t\\r\\\\
包含
开启
key2
long
不涉及
不涉及
开启
key3.ip
text
@&?|#()='",;:<>[]{}/ \\n\\t\\r\\\\
包含
开启
key3.url
text
@&?|#()='",;:<>[]{}/ \\n\\t\\r\\\\
包含
开启
key3.detail
text
@&?|#()='",;:<>[]{}/ \\n\\t\\r\\\\
包含
开启

元数据索引

上传日志到日志服务时，元数据通过 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"。
不包含：全文索引不包含上述三个内置字段，只能使用键值检索，例如__FILENAME__:"/var/log/access.log"。
包含
元数据字段包含至全文索引
包含：全文索引包含所有元数据字段（前缀为__TAG__的字段），可直接使用全文检索的方式检索相关日志字段，例如ap-beijing。
不包含：全文索引不包含任何元数据字段，只能使用键值检索的方式检索相关日志字段，例如__TAG__.region:ap-beijing。低频日志主题不支持键值检索，此时将无法检索这些字段。
仅包含开启键值索引元数据字段：全文索引包含开启了键值索引的元数据字段，不包含未开启键值索引的元数据字段，低频日志主题无该选项。
包含
日志创建索引异常存储规则
日志创建索引过程中如果出现异常，CLS 为了确保日志不丢失，会将原始日志存储在__RAWLOG__中。如果此时仅部分字段创建索引失败，可将失败的部分存储在指定字段中（默认为 RAWLOG_FALL_PART），详见 日志创建索引异常处理规则。
启用

操作步骤

编辑索引配置

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 未配置键值索引。
控制台检索分析效果
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\\"}}}"
}

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

日志创建索引过程中，如果原始日志格式异常或索引配置与原始日志不匹配，可能会导致索引创建失败，此时 CLS 为了确保日志不丢失，会将原始日志存储在 __RAWLOG__中，作为兜底的异常处理方式。__RAWLOG__仅支持全文检索（需开启全文索引），不支持键值检索、键值索引及统计分析。产生异常的日志，开启全文索引后，仍按照原始日志全文计算索引流量、索引存储及对应费用，不产生额外费用。
索引创建异常包含两类情况：
1. 日志中所有的字段均未按照索引配置成功创建索引，此时日志中仅具备__RAWLOG__字段，只能使用全文检索。
2. 日志中部分字段未成功创建索引，部分字段成功创建索引，此时日志中既具备__RAWLOG__字段，又具备创建索引成功的部分字段（该部分字段支持正常配置键值索引及统计分析）。在“索引配置-高级设置”中还可以将异常部分的字段存储在指定字段中（默认为 RAWLOG_FALL_PART，支持配置键值索引及统计分析）。
CLS 会不断优化索引配置对原始日志的兼容性，尽量避免日志出现上述异常情况。随着产品迭代升级，具体的异常处理规则可能会发生变化。

上一篇: 关联外部数据下一篇: 重建索引

帮助和支持

本页内容是否解决了您的问题？

填写满意度调查问卷，共创更好文档体验。

文档反馈