当前位置：首页 > news >正文

Java 中使用阿里云日志服务（SLS）完整指南

news 2025/8/16 15:31:10

阿里云日志服务（SLS）是一款针对日志数据的一站式服务，支持日志的采集、存储、查询与分析等功能。在 Java 开发中，借助阿里云提供的官方 SDK，能便捷地将应用日志接入 SLS。本文将从准备工作到核心操作，详细介绍 Java 中使用 SLS 的全过程。

一、准备工作：搭建 SLS 使用基础环境

在编写代码前，需完成 SLS 的前期配置与依赖引入，为后续开发做好铺垫。

1. 配置 SLS 基础资源

创建 SLS 项目与日志库：登录阿里云控制台，进入 “日志服务 SLS” 页面。先创建一个 “项目”（Project），项目需关联具体地域；再在项目下创建 “日志库”（LogStore），日志库将用于存储实际的日志数据。
获取关键访问信息：
- AccessKey：进入阿里云 “访问控制 RAM” 控制台，创建或使用已有的 AccessKey（包含 AccessKey ID 和 AccessKey Secret），需确保该 AccessKey 拥有 SLS 的操作权限（如日志写入、查询等）。
- Endpoint：在 SLS 项目详情页中获取 Endpoint，格式通常为 “地域标识.log.aliyuncs.com”（例如：cn-beijing.log.aliyuncs.com，地域需与项目所在地域一致）。

2. 引入 SLS Java SDK 依赖

SLS 提供了 Java 语言的官方 SDK，通过 Maven 或 Gradle 可快速引入项目。以 Maven 为例，在pom.xml中添加如下依赖（建议使用最新版本，可通过阿里云官方仓库查询最新版本号）：

<dependency><groupId>com.aliyun.openservices</groupId><artifactId>aliyun-log</artifactId><version>0.6.69</version> <!-- 替换为最新版本 -->
</dependency>

二、核心操作：Java 中 SLS 的常用功能实现

完成基础准备后，通过 SDK 可实现日志发送、日志查询等核心操作，以下为具体实现步骤与示例。

1. 初始化 SLS 客户端

所有 SLS 操作都需通过Client对象完成，初始化时需传入 Endpoint、AccessKey ID 和 AccessKey Secret，代码如下：

import com.aliyun.openservices.log.Client;public class SLSClientInit {// 替换为实际配置private static final String ENDPOINT = "your_endpoint"; // 如：cn-beijing.log.aliyuncs.comprivate static final String ACCESS_KEY_ID = "your_access_key_id";private static final String ACCESS_KEY_SECRET = "your_access_key_secret";private static final String PROJECT = "your_project_name"; // 项目名称private static final String LOG_STORE = "your_log_store_name"; // 日志库名称// 初始化客户端public static Client getSLSClient() {return new Client(ENDPOINT, ACCESS_KEY_ID, ACCESS_KEY_SECRET);}
}

Client对象是与 SLS 服务交互的入口，后续的日志发送、查询等操作均需基于此对象。

2. 发送日志到 SLS

应用运行中产生的日志，可通过 SDK 封装为LogItem对象，再批量发送到 SLS 日志库。每条LogItem包含日志时间戳和若干键值对（日志字段与内容）。

实现步骤：

创建LogItem列表，用于存放多条日志；
为每条LogItem设置时间戳（单位：秒），并通过PushBack方法添加日志字段（如日志级别、消息内容等）；
构建PutLogsRequest请求，指定项目、日志库及日志列表；
调用Client的PutLogs方法发送日志。

示例代码：

import com.aliyun.openservices.log.Client;
import com.aliyun.openservices.log.common.LogItem;
import com.aliyun.openservices.log.exception.LogException;
import com.aliyun.openservices.log.request.PutLogsRequest;
import com.aliyun.openservices.log.response.PutLogsResponse;import java.util.ArrayList;
import java.util.List;public class SLSLogSender {public static void main(String[] args) {// 获取SLS客户端Client client = SLSClientInit.getSLSClient();try {// 发送日志sendLogsToSLS(client);} catch (LogException e) {System.err.println("日志发送失败：" + e.getMessage());e.printStackTrace();}}/*** 向SLS发送日志*/private static void sendLogsToSLS(Client client) throws LogException {// 1. 创建日志条目列表List<LogItem> logItems = new ArrayList<>();// 2. 添加普通INFO级别日志LogItem infoLog = new LogItem((int)(System.currentTimeMillis() / 1000)); // 时间戳（秒）infoLog.PushBack("level", "INFO");infoLog.PushBack("message", "用户登录成功");infoLog.PushBack("user_id", "user_123");infoLog.PushBack("action", "login");logItems.add(infoLog);// 3. 添加ERROR级别日志（示例多条日志）LogItem errorLog = new LogItem((int)(System.currentTimeMillis() / 1000));errorLog.PushBack("level", "ERROR");errorLog.PushBack("message", "数据库连接超时");errorLog.PushBack("error_code", "DB_TIMEOUT_001");errorLog.PushBack("service", "order_service");logItems.add(errorLog);// 4. 构建发送请求PutLogsRequest request = new PutLogsRequest(SLSClientInit.PROJECT,  // 项目名称SLSClientInit.LOG_STORE, // 日志库名称"", // 日志主题（可选，无主题则留空）"", // 日志来源（可选，如应用服务器IP）logItems // 日志列表);// 5. 发送日志并获取响应PutLogsResponse response = client.PutLogs(request);System.out.println("日志发送成功！请求ID：" + response.GetRequestId());}
}

注意事项：

日志时间戳需精确到秒（LogItem构造函数接收秒级时间戳）；
单条日志的字段数量建议控制在合理范围（避免过多字段影响查询效率）；
若需高频发送日志，可考虑批量攒批发送（减少请求次数）。

3. 从 SLS 查询日志

除了发送日志，SLS SDK 还支持从日志库中查询日志，可根据时间范围、关键词等条件筛选所需日志。

实现步骤：

构建GetLogsRequest请求，指定查询的项目、日志库、时间范围、查询条件等；
调用Client的GetLogs方法执行查询，获取GetLogsResponse响应；
从响应中解析日志数据（如日志时间、字段内容等）。

示例代码：

import com.aliyun.openservices.log.Client;
import com.aliyun.openservices.log.common.LogContent;
import com.aliyun.openservices.log.common.LogItem;
import com.aliyun.openservices.log.exception.LogException;
import com.aliyun.openservices.log.request.GetLogsRequest;
import com.aliyun.openservices.log.response.GetLogsResponse;import java.util.List;public class SLSLogQuery {public static void main(String[] args) {Client client = SLSClientInit.getSLSClient();try {// 查询最近15分钟的ERROR级别日志queryLogsFromSLS(client);} catch (LogException e) {System.err.println("日志查询失败：" + e.getMessage());e.printStackTrace();}}/*** 从SLS查询日志*/private static void queryLogsFromSLS(Client client) throws LogException {// 1. 计算查询时间范围（最近15分钟）long currentTime = System.currentTimeMillis() / 1000; // 当前时间（秒）int fromTime = (int)(currentTime - 15 * 60); // 开始时间（15分钟前）int toTime = (int)currentTime; // 结束时间（当前）// 2. 构建查询请求GetLogsRequest request = new GetLogsRequest(SLSClientInit.PROJECT,SLSClientInit.LOG_STORE,fromTime, // 开始时间戳（秒）toTime,   // 结束时间戳（秒）"", // 日志主题（无则留空）"level:ERROR", // 查询条件（SLS查询语法，如“level:ERROR AND service:order_service”）100, // 最大返回日志条数0, // 偏移量（从第0条开始）false // 是否返回日志上下文（false则仅返回匹配日志）);// 3. 执行查询GetLogsResponse response = client.GetLogs(request);// 4. 解析并打印查询结果System.out.println("查询到" + response.GetCount() + "条日志：");List<LogItem> logItems = response.GetLogs();for (LogItem logItem : logItems) {System.out.println("\n日志时间：" + logItem.GetTime()); // 时间戳（秒）List<LogContent> contents = logItem.GetLogContents();for (LogContent content : contents) {System.out.println(content.GetKey() + "：" + content.GetValue());}}}
}

说明：

查询条件语法：支持类似 SQL 的查询语法，例如level:ERROR AND error_code:DB_TIMEOUT_001（查询级别为 ERROR 且错误码为 DB_TIMEOUT_001 的日志），更多语法可参考阿里云 SLS 查询语法文档；
分页查询：若日志量较大，可通过调整offset参数实现分页（如offset=100表示从第 100 条开始查询）。

4. 其他常用操作（扩展）

除了日志发送与查询，SLS SDK 还支持创建日志库、删除日志等管理类操作，以下为部分示例：

创建日志库

import com.aliyun.openservices.log.request.CreateLogStoreRequest;
import com.aliyun.openservices.log.exception.LogException;// 在指定项目下创建日志库
public static void createLogStore(Client client) throws LogException {// 参数：项目名称、日志库名称、数据保存时间（天）、分片数CreateLogStoreRequest request = new CreateLogStoreRequest(SLSClientInit.PROJECT, "new_log_store", 30, 2);client.CreateLogStore(request);System.out.println("日志库创建成功");
}

删除日志库

import com.aliyun.openservices.log.request.DeleteLogStoreRequest;
import com.aliyun.openservices.log.exception.LogException;public static void deleteLogStore(Client client) throws LogException {DeleteLogStoreRequest request = new DeleteLogStoreRequest(SLSClientInit.PROJECT, "log_store_to_delete");client.DeleteLogStore(request);System.out.println("日志库删除成功");
}