产品动态
公告
使用 Kafka 数据订阅采集日志
日志服务（Cloud Log Service，CLS）目前已支持主动订阅自建 Kafka 或腾讯云 CKafka 生产的日志。本文将介绍如何通过 Kafka 数据订阅将日志接入日志服务。
前提条件
已有可用的自建 Kafka 集群或腾讯云 CKafka 集群。
Kafka 版本 > 0.10.2.0。
操作步骤
步骤1：登录控制台
1. 登录 日志服务控制台。
2. 在左侧导航栏中，单击日志主题，进入日志主题管理页面。
步骤2：创建 Kafka 数据订阅任务
1. 在日志主题管理页中，找到目标日志主题，单击日志主题名称，进入日志主题详情页。
2. 在日志主题详情页中， 选择采集配置页签， 找到 Kafka 数据订阅配置。
3. 单击新增，创建 Kafka 数据订阅任务。
步骤3：配置 Kafka 数据订阅任务
1. 在配置集群步骤中， 首先选择目标 Kafka 类型， 支持选择腾讯 CKafka 与自建 Kafka。
2. 基于选中 Kafka 类型， 参考如下说明配置对应参数：
参数 | 是否必填 | 说明 |
Ckafka 实例 | 是 | 选择目标 Ckafka 实例 。 |
Kafka Topic 列表 | 是 | 单选或多选 Kafka Topic。 |
消费组 | 否 | 若为空，将自动创建消费组，命名规则为 cls-${taskid}。若不为空，则使用指定的消费组消费。 注意： 若为空，确保 Kafka 集群可自动创建消费组。 若不空，请确保当前指定消费组没有被其他任务消费，否则会导致数据缺失。 |
起始位置 | 是 | 最早：从最早的 offset 开始消费。 最晚：从最新的 offset 开始消费。 注意：起始位置仅支持创建订阅任务时配置，后续不可修改。 |
参数 | 是否必填 | 说明 |
访问方式 | 是 | 支持选择通过内网地址或公网地址访问您的自建 Kafka 集群。 |
网络服务类型 | 是 | 若访问方式为通过内网地址访问，需指定目标自建 Kafka 集群 的网络服务类型： CVM CLB 云联网（内测中， 如需使用请 提交工单 我们） 专线网关 （内测中， 如需使用请 提交工单 我们） 说明： |
所属网络 | 是 | 当网络服务类型选择为 CVM 或 CLB 时，需选择 CVM 或 CLB 所在的 VPC 实例。 |
服务地址 | 是 | 填写目标 Kafka 的公网 IP 地址或域名。 注意： |
私网域名解析 | 否 | |
是否需要鉴权 | 是 | 目标 Kafka 集群是否需要鉴权才能访问。 |
协议类型 | 是 | 若目标 Kafka 集群需要鉴权才能访问，则需选择鉴权协议类型： plaintext sasl_plaintext sasl_ssl ssl |
认证机制 | 是 | 若目标 Kafka 集群需要鉴权才能访问，且协议类型为 sasl_plaintext 或 sasl_ssl，则需选择鉴权认证机制： PLAIN SCRAM-SHA-256 SCRAM-SHA-512 |
用户名/密码 | 是 | 若目标 Kafka 集群需要鉴权才能访问，且协议类型为 sasl_plaintext 或 sasl_ssl，则需填写访问目标 Kafka 集群所需的用户名与密码。 |
客户端 SSL 认证 | 是 | |
服务端 SSL 认证 | 是 | |
Kafka Topic 列表 | 是 | 填写单个或多个 Kafka Topic；多个 Topic 通过逗号隔开。 |
消费组 | 否 | 若为空，将自动创建消费组，命名规则为 cls-${taskid}。若不为空，则使用指定的消费组消费。 注意： 若为空，确保 Kafka 集群可自动创建消费组。 若不空，请确保当前指定消费组没有被其他任务消费，否则会导致数据缺失。 |
起始位置 | 是 | 最早：从最早的 offset 开始消费。 最晚：从最新的 offset 开始消费。 注意：起始位置仅支持创建订阅任务时配置，后续不可修改。 |
3. 完成集群配置之后，可单击预览，如下图所示：
4. 确认集群配置无误后，单击下一步进入订阅规则配置步骤。
5. 在订阅规则配置步骤中，配置如下参数：
参数 | 是否必填 | 说明 |
配置名称 | 是 | Kafka 数据订阅配置名称。 |
数据提取模式 | 是 | |
日志样例 | 是 | 若数据提取模式选择为单行完全正则，需手动填写或自动获取一条日志样例，用于验证正则表达式，并提取键值。 |
正则表达式 | 是 | |
抽取结果 | 是 | 若数据提取模式选择为单行完全正则，需配置或修改基于正则表达式提取出来的字段的字段名。 |
手动验证 | 否 | 若数据提取模式选择为单行完全正则，可选择额外填写单条或多条日志样例来验证正则表达式的正确性。 |
上传解析失败日志 | 是 | 若数据提取模式选择为 JSON 或单行完全正则，若开启上传解析失败日志，在日志解析失败时，LogListener 会上传解析失败的日志；若关闭，则会丢弃解析失败的日志。 |
解析失败日志的键名称 | 是 | 若开启了上传解析失败日志，您可指定一个字段名作为 Key，解析失败的日志将作为您指定字段的 Value 进行上传。 |
编码格式 | 是 | 基于您的日志，您可选择以下两种编码格式： UTF-8 GBK |
使用默认时间 | 是 | 开启后将使用系统当前时间或 Kafka 消息时间戳作为日志的时间戳；关闭则将使用日志中的时间字段作为日志时间戳。 |
默认时间来源 | 是 | 当开启了使用默认时间，您可以选择以下两默认事件作为日志时间戳： 系统当前时间 Kafka 消息时间戳 |
时间字段 | 是 | 当关闭了使用默认时间，且数据提取模式为 JSON 或正则时，您可以指定日志中代表时间的字段名，该字段的值将会用作日志的时间戳。 |
时间提取正则 | 是 | 当关闭了使用默认时间，且数据提取模式单行全文时，您可通过正则表达式定义日志中代表时间的字段。 注意：若正则匹配到多个字段， 将使用第一个。 例子：日志原文为：message with time 2022-08-08 14:20:20，则您可以设置提取时间正则为\\d\\d\\d\\d-\\d\\d-\\d\\d\\d\\d:\\d\\d:\\d\\d |
时间字段格式 | 是 | |
时间字段时区 | 是 | 当关闭了使用默认时间，并确认了日志中的时间字段与格式，需选择以下两种不同的时区标准： UTC (协调世界时) GMT (格林威治标准时间) |
解析失败使用时间 | 是 | 当关闭了使用默认时间，若时间提取正则或时间字段格式解析失败，支持用户选择以下两种默认时间代替作为日志时间戳： 系统当前时间 Kafka 消息时间戳 |
过滤器 | 否 | 过滤器的目的是根据业务需要添加日志采集过滤规则，以帮助您筛选出有价值的日志数据。支持以下过滤规则： 等于：仅采集指定字段值匹配指定字符的日志。支持完全匹配，或正则匹配。 不等于：仅采集指定字段值不匹配指定字符的日志。支持完全匹配，或正则匹配。 字段存在：仅采集指定字段存在的日志。 字段不存在：仅采集指定字段不存在的日志。 例如，您希望原始 JSON 格式日志内容中 response_code 为400或500的所有日志数据被采集，那么 key 处配置 response_code，过滤规则选择等于，value 处配置400|500。 注意： 多条过滤条件之间关系是"与"逻辑，若同一 key 名配置多条过滤条件，规则会被覆盖。 |
Kafka 元数据 | 否 | 支持勾选以下4种 Kafka 相关元数据与日志一起上传： kafka_topic kafka_partition kafka_offset kafka_timestamp 注意： 若日志原文中存在与以上元数据同名的字段，将会被覆盖。 |
6. 完成订阅规则配置后，您可单击预览，预览导出结果。如下图所示：
如您需要对采集到的 CLS 日志进一步处理，如结构化、脱敏、过滤，然后再写入日志主题，您可点击页面下方的数据加工，添加数据加工，最后配置索引。
7. 预览无误后， 单击下一步，进入索引配置步骤。
8. 在索引配置页面，设置如下信息。
索引状态：确认是否开启。
注意
若要对日志进行检索，索引状态需未开启，否则无法检索日志。
全文索引：全文索引将日志全文整体切分为多个分词进行索引构建，检索时直接通过关键词进行检索（即全文检索），例如使用
error检索所有出现过 error 的日志。配置项 | 功能描述 |
全文分词符 | 对原始日志进行分词的字符集合，仅支持英文符号，控制台默认分词符为 @&?|#()='",;:<>[]{}/ \\n\\t\\r\\\\。 |
大小写敏感 | 检索时是否对大小写敏感。例如日志为 Error，若大小写敏感，则使用 error 无法检索到该条日志。 |
是否包含中文 | 日志中包含中文且需要对中文进行检索时可开启该功能。例如日志为“用户登录接口超时”，若未开启该功能，搜索 "超时"无法检索到该日志，只有完整地搜索"用户登录接口超时"才能检索到该日志，开启该功能后便可通过搜索“超时”检索到该日志。 |
键值索引：键值索引将原始日志按字段（即 key:value）分别切分为多个分词进行索引构建，检索时基于键值方式进行检索（即键值检索），例如使用
level:error AND timeCost:>1000检索日志级别(level)为 error 且耗时(timeCost)大于1000ms的日志。某些日志中还包含一类特殊的“元数据字段”，这类字段配置索引的方式与普通字段一致。配置项 | 功能描述 |
字段名称 | 字段名称，单个日志主题键值索引最多可添加300个字段。 仅支持字母、数字、下划线和-./@，且不能以下划线开头。 |
字段类型 | 字段的数据类型，包括 text、long、double 三种类型。 text 类型支持使用通配符进行模糊检索，不支持范围比较。 long、double 类型支持范围比较，不支持模糊检索。 |
分词符 | 对字段值进行分词的字符集合，仅支持英文符号，控制台默认分词符为 @&?|#()='",;:<>[]{}/ \\n\\t\\r\\\\。 |
包含中文 | 字段中包含中文且需要对中文进行检索时可开启该功能。例如日志为“message:用户登录接口超时”，若未开启该功能，使用 message:"超时"无法检索到该日志，只有使用message:"用户登录接口超时"才能检索到该日志，开启该功能后便可使用message:"超时"检索该日志。 |
开启统计 | 开启后可对该字段使用 SQL 进行统计分析，text 类型字段开启统计时，如果值过长，仅前32766个字符参与统计运算。 开启统计不会额外产生费用，建议您开启。 |
大小写敏感 | 检索时是否对大小写敏感例如日志为“level:Error”，若大小写敏感，则使用 level:error无法检索到该条日志。 |
说明：
9. 完成索引配置后，单击提交，即可完成 Kafka 数据订阅任务的创建。
步骤4：查看 Kafka 数据订阅任务
完成 Kafka 数据订阅任务后，您可在日志主题详情页 > 采集配置页签中找到所有已创建的 Kafka 数据订阅任务。
步骤5：检索分析日志
完成 Kafka 数据订阅任务后，即可开始使用日志的检索与分析，以及更高阶的仪表盘告警等功能了。
检索分析
监控告警
仪表盘
数据加工
规格与限制
最佳实践
附录
正则表达式自动生成
1. 在弹出的正则表达式自动生成模态视图中，根据实际的检索分析需求，选中需要提取 key-value 的日志内容，并在弹出的文本框中，输入键(key)名，单击确认提取。如下图所示：
2. 系统将自动对该部分内容提取一个正则表达式，自动提取结果会出现在 key-value 表格中。如下图所示：
3. 重复步骤1，直到提取完所有的 key-value 对。 如下图所示：
4. 单击确定，系统将根据提取好的 key-value 对自动生成完整的正则表达式。 如下图所示：
数据提取模式
Kafka 数据订阅提供多种解析方式，如下表所示：
假设您的一条 JSON 日志原始数据为：
{"remote_ip":"10.135.46.111","time_local":"22/Jan/2019:19:19:34 +0800","body_sent":23,"responsetime":0.232,"upstreamtime":"0.232","upstreamhost":"unix:/tmp/php-cgi.sock","http_host":"127.0.0.1","method":"POST","url":"/event/dispatch","request":"POST /event/dispatch HTTP/1.1","xff":"-","referer":"http://127.0.0.1/my/course/4","agent":"Mozilla/5.0 (Windows NT 10.0; WOW64; rv:64.0) Gecko/20100101 Firefox/64.0","response_code":"200"}
经过日志服务结构化处理后，该条日志将变为如下：
agent: Mozilla/5.0 (Windows NT 10.0; WOW64; rv:64.0) Gecko/20100101 Firefox/64.0body_sent: 23http_host: 127.0.0.1method: POSTreferer: http://127.0.0.1/my/course/4remote_ip: 10.135.46.111request: POST /event/dispatch HTTP/1.1response_code: 200responsetime: 0.232time_local: 22/Jan/2019:19:19:34 +0800upstreamhost: unix:/tmp/php-cgi.sockupstreamtime: 0.232url: /event/dispatchxff: -
单行全文日志是指一行日志内容为一条完整的日志。日志服务在采集的时候，将使用换行符 \\n 来作为一条日志的结束符。为了统一结构化管理，每条日志都会存在一个默认的键值__CONTENT__，但日志数据本身不再进行日志结构化处理，也不会提取日志字段，日志属性的时间项由日志采集的时间决定。
假设一条日志原始数据为：
Tue Jan 22 12:08:15 CST 2019 Installed: libjpeg-turbo-static-1.2.90-6.el7.x86_64
采集到日志服务的数据为：
__CONTENT__:Tue Jan 22 12:08:15 CST 2019 Installed: libjpeg-turbo-static-1.2.90-6.el7.x86_64
单行完全正则格式通常用来处理结构化的日志，指将一条完整日志按正则方式提取多个 key-value 的日志解析模式。
假设一条日志原始数据为：
10.135.46.111 - - [22/Jan/2019:19:19:30 +0800] "GET /my/course/1 HTTP/1.1" 127.0.0.1 200 782 9703 "http://127.0.0.1/course/explore?filter%5Btype%5D=all&filter%5Bprice%5D=all&filter%5BcurrentLevelId%5D=all&orderBy=studentNum" "Mozilla/5.0 (Windows NT 10.0; WOW64; rv:64.0) Gecko/20100101 Firefox/64.0" 0.354 0.354
配置的正则表达式为如下：
(\\S+)[^\\[]+(\\[[^:]+:\\d+:\\d+:\\d+\\s\\S+)\\s"(\\w+)\\s(\\S+)\\s([^"]+)"\\s(\\S+)\\s(\\d+)\\s(\\d+)\\s(\\d+)\\s"([^"]+)"\\s"([^"]+)"\\s+(\\S+)\\s(\\S+).*
采集到日志服务的数据为：
body_bytes_sent: 9703http_host: 127.0.0.1http_protocol: HTTP/1.1http_referer: http://127.0.0.1/course/explore?filter%5Btype%5D=all&filter%5Bprice%5D=all&filter%5BcurrentLevelId%5D=all&orderBy=studentNumhttp_user_agent: Mozilla/5.0 (Windows NT 10.0; WOW64; rv:64.0) Gecko/20100101 Firefox/64.0remote_addr: 10.135.46.111request_length: 782request_method: GETrequest_time: 0.354request_url: /my/course/1status: 200time_local: [22/Jan/2019:19:19:30 +0800]upstream_response_time: 0.354
自建 Kafka 内网接入配置说明
CVM 类型接入
1. 如果您的 kafka broker 节点均部署在同一个 VPC 下的 CVM 上，可以使用该种方式进行接入。
2. 单个 CVM 上的 broker 节点配置信息如下：
例如：CVM 节点在 VPC 内的 IP 地址为 10.0.0.2，broker 端口为 9092。其它节点采用相同配置并替换掉 IP 即可。
listener.security.protocol.map=CVM:PLAINTEXTlisteners=CVM://10.0.0.2:9092advertised.listeners=CVM://10.0.0.2:9092
3. CLS 控制台配置订阅任务时在自建 Kafka > 内网访问中，网络服务类型选择 CVM 类型，VPC 选择该 CVM 对应的 VPC ID，内网服务地址填写 10.0.0.2:9092即可。
CLB 类型接入
1. 如果您的 kafka broker 节点均部署在同一个 VPC 下的 CVM/TKE 节点，可以使用该种方式进行接入。
2. 需要先按每个 broker 一对一创建对应的 CLB 实例，并配置 TCP 类型的监听器，监听端口最好与 kafka broker 的端口一致，便于管理。
3. 单个 CVM/TKE 上 broker 节点配置信息如下所示（例：CVM/TKE 在 VPC 内 IP 地址为 10.0.0.2，节点对应的 CLB 地址为 10.0.0.12，broker 端口为 29092）
listener.security.protocol.map=CLB:PLAINTEXTlisteners=CLB://10.0.0.2:29092advertised.listeners=CLB://10.0.0.12:29092
其它节点同样配置并替换掉 IP 即可：
4. CLS 控制台配置订阅任务时在自建Kafka->内网访问中，网络服务类型选择 CLB 类型，VPC 选择该 CLB 对应的 VPC ID，内网服务地址填写 10.0.0.12:29092即可。
5. 在 TKE 场景下，可能会在 broker 配置中使用私网域名作为监听地址，此时需要使用私有域名解析能力进行处理。详请请参见 私网域名解析。
私网域名解析
1. 有些场景下，期望使用私网域名进行 kafka 的访问，例如 TKE 场景，节点 IP 是不固定的，需要配置域名进行访问，如下配置：
listener.security.protocol.map=DOMAIN:PLAINTEXTlisteners=DOMAIN://10.0.0.2:9092advertised.listeners=DOMAIN://broker1.cls.tencent.com:9092
2. 为了便于此类场景直接接入 CLS，CLS 提供了私网域名解析功能来做域名解析映射。
3. 例如这里使用 CLB 来关联后端 rs，CLB 地址为 10.0.0.12，那么就需要在 自建 Kafka 订阅任务配置 中增加一条私网域名解析, 即：
域名：broker1.cls.tencent.com
IP: 10.0.0.12
4. 如果多个 broker 节点都是使用这种访问策略，则均需添加私网域名解析。
5. 配置了私网域名解析后，自建 Kafka 订阅任务配置 中内网服务地址则只需填写 broker1.cls.tencent.com:9092 即可。
文档反馈