腾讯云日志服务CLS从入门到实战：全方位对接使用指南

apphuang2026年07月17日 13:26:4554

一、认识腾讯云日志服务CLS

在云原生与微服务架构日益普及的今天，应用程序产生的日志数据呈指数级增长。传统的运维方式——登录到每台服务器上使用grep、awk等命令手工排查问题，在数十台甚至上百台服务器的规模下几乎不可行。腾讯云日志服务（Cloud Log Service，CLS）正是为解决这一痛点而设计的一站式日志数据解决方案，提供从日志采集、存储、检索分析、实时消费到日志投递的全方位服务。

CLS采用高可用的分布式架构设计，对日志数据进行多冗余备份存储，防止单节点服务宕机导致数据不可用，提供达99.9%的服务可用性。用户无需关注扩缩容等资源问题，五分钟即可快速便捷接入，享受日志与指标的采集、存储、加工、检索分析、消费投递、生成仪表盘、告警等全方位稳定可靠的服务。

1.1 CLS的核心概念

在使用CLS之前，需要理解以下几个核心概念：

日志集（Logset）：日志集是日志服务中的资源管理单元，用于资源隔离和控制，一个日志集可以理解为一个项目。
日志主题（Topic）：日志主题是日志数据的收集、存储和查询单元，一个日志集可以包含多个日志主题，每个日志主题对应一类服务或一种日志类型。
机器组（Machine Group）：机器组用于统一管理一组日志源机器，通过将服务器IP地址加入机器组，可以批量对多台机器进行日志采集配置。
LogListener：LogListener是CLS提供的专用日志采集客户端，部署在日志源服务器上，可实现快速无侵入式地把日志数据采集到日志服务中。

需要先登录腾讯云控制台，点击：腾讯云控制台，还没有账号，点击：注册后再关联，已有账号点击：登录后再关联

1.2 CLS的计费模式

CLS默认采用按量计费方式，先使用后付费，按照各计费项的实际用量以天为单位进行计量、结算、扣费和出账。同时CLS也提供资源包这种优惠套餐，先购买后使用，资源包支持CLS所有计费项的抵扣，结算时系统将优先从资源包抵扣各计费项，超出部分按量计费。2022年9月5日后开通CLS的新用户可免费领取一定额度的试用资源。

二、开通服务与准备工作

2.1 开通CLS服务

首先，您需要在腾讯云官网申请开通日志服务。登录腾讯云控制台后，在产品与服务中找到"日志服务"或直接搜索CLS，进入产品页面后单击"立即开通"即可。开通服务本身不产生费用，费用在后续使用日志采集和存储时才会产生。如果您没有合适的资源来采集日志，可使用Demo日志快速体验CLS，无需采集日志即可体验日志检索分析、仪表盘和告警功能，且不产生任何费用。

2.2 获取API密钥

无论您选择使用LogListener采集还是通过SDK/API上传日志，都需要准备API密钥。登录访问管理控制台，查看或创建密钥对，并确认密钥状态为启用。密钥信息包括SecretId和SecretKey两个部分，请妥善保管，不建议将云API密钥信息明文存储至工程代码中。

2.3 创建日志集与日志主题

日志服务区分地域，为了降低网络延迟，尽可能选择与服务邻近的服务地域创建日志资源。在左侧导航栏中单击"日志主题"，进入日志主题管理页面，选择地域后单击"创建日志主题"。创建时需要填写以下信息：

存储时间：支持有限保存（1-3600天）或永久保存，也可将部分历史日志自动沉降到低频存储以节约费用。
日志主题名称：例如 topic_nginx_access。
日志集操作：默认选择当前地域现有的日志集，如需新建日志集可选择"创建日志集"并输入名称。

三、LogListener采集方式

LogListener是CLS提供的专用日志采集客户端，通过LogListener可实现快速无侵入式地把日志数据采集到日志服务中来。LogListener支持部署在腾讯云CVM、轻量应用服务器、非腾讯云服务器、容器服务TKE以及自建K8s集群等多种环境。

3.1 检查网络连通性

安装LogListener要求日志源机器的网络与日志服务的可用地域网络互通（腾讯云服务器默认内网访问日志服务）。可以执行以下命令检查网络连通性，其中<region>为日志服务所在地域简称：

ping <region简称>.cls.tencentyun.com

3.2 安装LogListener（Linux环境）

首先下载loglistener_operator脚本：

# 内网下载（腾讯云CVM推荐）
wget https://mirrors.tencentyun.com/install/cls/script/loglistener/loglistener_operator && chmod u+x loglistener_operator

# 外网下载
wget https://mirrors.tencent.com/install/cls/script/loglistener/loglistener_operator && chmod u+x loglistener_operator

使用root用户执行安装命令：

# 内网访问安装
./loglistener_operator install -s ${secret_id} -k ${secret_key} -r ${region}

# 外网访问安装
./loglistener_operator install -s ${secret_id} -k ${secret_key} -r ${region} -n internet

其中${secret_id}和${secret_key}为步骤2.2中获取的API密钥，${region}为日志服务所在地域（如ap-guangzhou）。LogListener支持在x64和ARM架构下的TencentOS、CentOS、Ubuntu、Debian、openSUSE等多种Linux操作系统上运行。

3.3 创建机器组

日志服务使用机器组来统一管理一组日志源机器。登录日志服务控制台后，在左侧导航栏单击"机器组管理"，在页面顶部选择合适的地域，单击"新建机器组"开始创建。一个机器组可以填入多个机器IP地址（每行一个IP地址），若是腾讯云服务器CVM，直接填写内网IP地址即可。CLS还支持通过机器标识动态配置机器组，只需要在LogListener的配置信息中填入机器标识，CLS即可识别并自动将机器添加至机器组（需LogListener 2.3.0及以上版本）。

3.4 配置采集规则

创建好机器组后，需要为日志主题配置采集规则。进入日志主题管理页面，单击目标日志主题名称进入管理页面，选择"采集配置"页签，在LogListener采集配置中单击"新增"。配置内容包括：

采集路径：指定日志文件所在的路径，支持通配符，如/var/log/nginx/*.log。
提取模式：支持单行全文、多行全文、JSON、分隔符、完全正则等多种解析模式。
过滤器：可配置过滤条件，只采集符合条件的日志行。

配置完成后，LogListener会自动开始采集指定路径下的日志文件并上报到CLS。

四、SDK与API上传方式

除了使用LogListener采集，CLS还提供了丰富的SDK和API方式供开发者直接将日志上传到日志服务。SDK对日志服务的数据接入接口做了统一封装，降低了使用上传日志的难度。目前CLS官方提供了Python、Java、Node.js、浏览器JavaScript、小程序JavaScript、HarmonyOS等多种语言的SDK。

4.1 Python SDK上传日志

Python SDK支持PyPy 2、3和Python 2.7、3.3至3.13版本。首先安装SDK：

pip install tencentcloud-cls-sdk-python

验证安装：

pip show tencentcloud-cls-sdk-python

以下为完整的Python SDK上传日志示例代码：

import time
import os
from tencentcloud.log.logclient import LogClient
from tencentcloud.log.logexception import LogException
from tencentcloud.log.cls_pb2 import LogGroupList

def upload_logs():
    # 从环境变量获取密钥，不建议硬编码
    endpoint = "ap-guangzhou.cls.tencentyun.com"  # 内网接入点
    access_key_id = os.environ.get("TENCENTCLOUD_SECRET_ID")
    access_key = os.environ.get("TENCENTCLOUD_SECRET_KEY")
    topic_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    
    client = LogClient(endpoint, access_key_id, access_key)
    
    log_group_list = LogGroupList()
    log_group = log_group_list.logGroupList.add()
    log_group.topicId = topic_id
    
    # 添加日志内容
    log = log_group.logs.add()
    log.time = int(time.time())
    content = log.contents.add()
    content.key = "message"
    content.value = "Hello from Python SDK!"
    
    content2 = log.contents.add()
    content2.key = "level"
    content2.value = "INFO"
    
    try:
        response = client.put_logs(log_group_list)
        print("Upload success")
    except LogException as e:
        print(f"Upload failed: {e}")

if __name__ == "__main__":
    upload_logs()

代码中通过环境变量动态获取云API密钥信息，避免硬编码带来的安全风险。endpoint参数根据网络环境选择：腾讯云内网使用<region>.cls.tencentyun.com，公网使用<region>.cls.tencentcs.com。

4.2 Java SDK上传日志

Java SDK支持JRE 6.0及以上版本。在Maven项目的pom.xml中添加依赖：

<dependency>
    <groupId>com.tencentcloudapi.cls</groupId>
    <artifactId>tencentcloud-cls-sdk-java</artifactId>
    <version>1.0.15</version>
</dependency>

Java SDK上传示例代码：

import com.tencentcloudapi.cls.sdk.AsyncProducerClient;
import com.tencentcloudapi.cls.sdk.AsyncProducerConfig;
import com.tencentcloudapi.cls.sdk.LogItem;
import com.tencentcloudapi.cls.sdk.LogContent;
import java.util.ArrayList;
import java.util.List;

public class TencentClsDemo {
    public static void main(String[] args) {
        String endpoint = "ap-guangzhou.cls.tencentyun.com";
        String secretId = System.getenv("TENCENTCLOUD_SECRET_ID");
        String secretKey = System.getenv("TENCENTCLOUD_SECRET_KEY");
        String topicId = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";
        
        AsyncProducerConfig config = new AsyncProducerConfig(endpoint, secretId, secretKey, topicId);
        AsyncProducerClient client = new AsyncProducerClient(config);
        
        List<LogItem> logItems = new ArrayList<>();
        LogItem item = new LogItem();
        item.setTime(System.currentTimeMillis() / 1000);
        
        List<LogContent> contents = new ArrayList<>();
        contents.add(new LogContent("message", "Hello from Java SDK!"));
        contents.add(new LogContent("level", "INFO"));
        item.setContents(contents);
        logItems.add(item);
        
        client.send(logItems);
        client.close();
    }
}

4.3 Node.js SDK上传日志

Node.js SDK的安装与使用也非常简洁：

npm install tencentcloud-cls-sdk-js

const CLS = require('tencentcloud-cls-sdk-js');

const client = new CLS.Client({
    endpoint: 'ap-guangzhou.cls.tencentyun.com',
    accessKeyId: process.env.TENCENTCLOUD_SECRET_ID,
    accessKey: process.env.TENCENTCLOUD_SECRET_KEY,
    topicId: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
});

const log = {
    time: Math.floor(Date.now() / 1000),
    contents: [
        { key: 'message', value: 'Hello from Node.js SDK!' },
        { key: 'level', value: 'INFO' }
    ]
};

client.putLogs([log], (err, data) => {
    if (err) console.error('Upload failed:', err);
    else console.log('Upload success');
});

4.4 OpenTelemetry接入

CLS已兼容OpenTelemetry OTLP/HTTP协议，开发者只需使用标准OTLP Exporter，配置对应的Endpoint、Authorization和topic_id即可完成上报，无需引入CLS专属SDK。这为已经使用OpenTelemetry进行可观测性采集的团队提供了极大的便利，可以将Log、Trace、Metric三类可观测数据统一上报至CLS。

五、日志检索与分析

5.1 索引配置

索引配置是使用CLS进行检索分析的必要条件，只有开启索引才能对日志进行检索分析。索引配置的核心是对原始日志进行"分词"，以快速且便捷地根据特定的检索条件检索日志。同时还可以针对特定的字段"开启统计"，便于使用SQL对日志进行统计分析。

5.2 CQL检索语法

CLS提供了专用的CQL（CLS Query Language）检索语法，专为日志检索设计，使用容易，推荐使用。检索分析语句由检索条件和SQL语句组成，两者通过竖线|分割。只需要检索日志而不需要统计分析时，可省略管道符及SQL语句。

常用检索示例：

检索GET请求中失败（状态码大于400）的日志：method:GET AND status>400
检索包含特定关键词的日志："error"
检索特定时间范围的日志：结合CLS控制台的时间选择器使用

5.3 SQL统计分析

CLS兼容SQL 92标准，支持200+ SQL函数。例如按状态码统计请求数：

* | SELECT status, count(*) AS pv GROUP BY status ORDER BY pv DESC

统计分析能力使CLS不仅是一个日志存储和检索系统，更是一个强大的业务指标分析平台。用户可以通过SQL灵活统计日志内的系统及业务指标并通过图表进行展示。

六、告警配置

CLS支持为一个或多个日志主题设置告警策略。告警策略定期执行监控任务，当查询分析结果满足触发条件时发送告警通知。配置告警的步骤如下：

登录CLS控制台，选择目标日志主题。
点击"告警策略"→"新建策略"。
定义触发条件：支持字段过滤（如status_code == 500）和统计聚合（如count(1) > 100）。
配置告警通知渠道（短信、邮件、微信、企业微信等）。

告警策略还支持配置沉默时间，避免告警信息持续发送造成骚扰。

七、日志投递与消费

7.1 投递到COS

CLS支持将日志数据投递到对象存储COS，满足日志备份、长期归档等场景需求。配置投递任务的步骤如下：

登录日志服务控制台，选择左侧导航栏中的"投递消费"→"投递到COS"。
单击"添加投递配置"，配置投递目标（COS存储桶、路径格式等）。
支持跨账号投递，通过CAM角色授权实现。

投递到COS后，用户可以通过腾讯云DLC（数据湖计算）、EMR（大数据平台）等服务从COS加载日志数据进行离线分析。

7.2 自定义消费

CLS还支持通过SDK进行自定义日志消费，开发者可以编写消费程序实时消费CLS中的日志数据，用于实时流计算、日志转发等场景。

八、日志数据加工

CLS提供数据加工能力，包括日志过滤、清洗、脱敏、富化、分发、结构化等操作。例如，可以按照双竖线||分隔符对日志进行结构化，或按照ERROR、WARNING、INFO三个级别将日志分发到三个不同的目标日志主题。数据加工还支持从腾讯云MySQL数据库中实时拉取数据，与日志数据进行动态关联。

九、成本优化与安全最佳实践

9.1 成本优化策略

合理设置存储周期：根据业务需求设置日志保留天数，避免永久保存带来的存储费用增长。
使用低频存储：将历史日志自动沉降到低频存储，有效节约费用。
利用内网接入：部署在同地域腾讯云VPC/CVM中的服务使用内网接入点，免公网流量费用、低延迟。
购买资源包：对于用量稳定的场景，购买资源包可以获得更优惠的价格。

9.2 安全最佳实践

密钥管理：不建议把SecretId和SecretKey硬编码在代码中或提交到代码仓库，建议通过环境变量或密钥管理服务注入。
权限控制：使用子账号并分配最小权限，避免使用主账号密钥。
数据加密：CLS对日志数据进行多冗余备份存储，保障数据安全。
匿名上传控制：如需使用浏览器端JavaScript SDK，必须对日志主题开通"匿名上传"功能，请谨慎评估安全风险。

十、常见问题解答

问1：LogListener和SDK上传方式有什么区别？分别适用于什么场景？

LogListener是CLS提供的专用采集客户端，适合采集服务器上已有的日志文件（如Nginx访问日志、应用日志文件等），部署后自动采集无需修改代码。SDK上传方式适合在应用程序代码中直接上报日志，适合需要实时上报的结构化日志、自定义业务日志等场景。两者可以结合使用，满足不同的日志采集需求。

问2：CLS的检索分析为什么需要开启索引？索引如何配置？

索引是CLS进行检索分析的必要条件，只有开启索引才能对日志进行检索分析。索引配置的核心是对原始日志进行"分词"。配置索引时需要在日志主题的"索引配置"中开启索引开关，并针对需要检索的字段设置数据类型（text、long、double等），对于需要SQL统计的字段还需开启"统计"开关。

问3：如何控制CLS的费用？主要有哪些计费项？

CLS默认按量计费，主要计费项包括：日志存储量（按GB/天）、外网下行流量、读写请求次数等。控制费用的方法包括：合理设置日志保留周期、使用低频存储归档历史数据、使用内网接入点避免外网流量费用、购买资源包享受优惠。

问4：CLS支持采集哪些来源的日志？

CLS支持多种数据源场景下的日志采集，包括：服务器日志文件（通过LogListener）、容器日志（TKE及自建K8s集群）、云产品日志（如云防火墙等）、应用程序直接上报（通过SDK/API）、OpenTelemetry可观测数据等。

问5：日志上传到CLS后，可以投递到哪些下游服务？

CLS支持将日志投递到多种下游服务，包括：对象存储COS（用于长期归档和备份）、Splunk（用于日志分析）、自定义消费（通过SDK实时消费）等。投递前可以使用预过滤函数对日志进行处理。

问6：CLS的检索语法CQL和Lucene有什么区别？

CQL是CLS专用的检索语法，专为日志检索设计，使用容易，推荐使用。Lucene是开源语法，由于并非专为日志检索设计，对特殊符号、大小写、通配符等有较多限制，使用较为繁琐，容易出现语法错误，不推荐使用。在CLS控制台的检索语法规则中，默认值为1（CQL语法）。