使用Agent Skill快速集成SLS SDK

方式一（推荐）：通过 npx 命令安装

npx 命令随 Node.js 安装一起提供。安装前可先在终端执行以下命令确认环境是否可用：

node -v
npx -v

如果终端提示 node 或 npx 不存在，请先前往 Node.js 官网下载并安装：Node.js 下载地址。

执行以下命令安装 alibabacloud-sls-sdk-guidance 技能：

npx skills add aliyun/alibabacloud-aiops-skills --skill alibabacloud-sls-sdk-guidance --full-depth

方式二：手动下载技能安装包

从 GitHub Release 下载 alibabacloud-sls-sdk-guidance 安装包，并解压复制到 skills 安装目录中。请确保复制后 skills 目录下存在 alibabacloud-sls-sdk-guidance 目录，并重新启动 Agent 来加载该 Skill。

常见 Agent 的 skills 安装目录：

提示词编写建议

为了让 Agent 更准确地推荐 SDK 和生成代码，建议在提示词中包含以下信息：

• 编程语言和版本。例如 "Java 17"、"Go 1.21"。

• 业务场景。例如 "高吞吐写入日志"、"Consumer Group 消费日志"、"查询日志"、"创建索引配置"。

• 已有的技术栈。例如 "Spring Boot 项目"、"项目已经在用 Log4j2"。

以下示例场景中的 Project、Logstore 和代码为示例。实际使用时，请替换为您的资源名称。

场景一：根据业务场景选择合适的 SDK

提示词

我们 Java 项目需要高吞吐写日志到阿里云 SLS，同时需要用 Consumer Group 消费日志做实时处理。应该用哪些 SDK？分别给出 Maven 依赖。

Agent 输出示例

根据你的需求，建议使用以下两个 SDK 分别处理写入和消费：

### 写入：aliyun-log-java-producer

Java 高吞吐写入场景推荐使用 Producer SDK，而不是基础 Java SDK 的 PutLogs API。
Producer 提供异步非阻塞发送、自动攒批、自动重试、内存限流，适合 Flink / Spark 等大数据场景。

Maven 依赖：
<dependency>
  <groupId>com.aliyun.openservices</groupId>
  <artifactId>aliyun-log-producer</artifactId>
  <version>0.3.25</version>
</dependency>

### 消费：loghub-client-lib（aliyun-log-consumer-java）

Consumer Group 场景推荐使用 Consumer Library，它自动处理分片分配、心跳、
checkpoint 持久化和多实例负载均衡，你只需实现单分片的处理逻辑。

Maven 依赖：
<dependency>
  <groupId>com.aliyun.openservices</groupId>
  <artifactId>loghub-client-lib</artifactId>
  <version>0.6.50</version>
</dependency>
<dependency>
  <groupId>com.google.protobuf</groupId>
  <artifactId>protobuf-java</artifactId>
  <version>2.5.0</version>
</dependency>

### 为什么不用基础 Java SDK？

aliyun-log-java-sdk 可以写入和查询，但写入走的是同步 PutLogs 接口，没有攒批和重试，
高吞吐场景下性能不足。消费需要单独的 Consumer Library。

如果你还需要查询日志或管理 SLS 资源（创建 Project / Logstore / 索引等），
可以额外引入 alibabacloud-sls-java-sdk（OpenAPI SDK）。

场景二：使用 Java Producer SDK 写入日志

提示词

Java Spring Boot 项目需要用 Producer SDK 异步写入业务日志到 SLS， Project 是 prod-web，Logstore 是 app-logs，地域杭州。给出完整代码示例。

Agent 输出示例

推荐使用 aliyun-log-java-producer，它提供异步发送、自动攒批和自动重试，
适合服务端高吞吐写入。

### Maven 依赖

<dependency>
  <groupId>com.aliyun.openservices</groupId>
  <artifactId>aliyun-log-producer</artifactId>
  <version>0.3.25</version>
</dependency>

### 代码示例

import com.aliyun.openservices.aliyun.log.producer.LogProducer;
import com.aliyun.openservices.aliyun.log.producer.ProducerConfig;
import com.aliyun.openservices.aliyun.log.producer.ProjectConfig;
import com.aliyun.openservices.log.common.LogItem;

// 1. 创建 Producer（全局单例，线程安全）
ProducerConfig producerConfig = new ProducerConfig();
LogProducer producer = new LogProducer(producerConfig);

producer.putProjectConfig(new ProjectConfig(
    "prod-web", "cn-hangzhou.log.aliyuncs.com",
    System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"),
    System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET")));

// 2. 构造日志并发送（异步，立即返回）
LogItem item = new LogItem();
item.PushBack("level", "INFO");
item.PushBack("service", "order-service");
item.PushBack("message", "Order created successfully");
item.PushBack("orderId", "202604240001");

producer.send("prod-web", "app-logs", "", "", item);

// 3. 进程退出前必须调用 close()，否则缓冲区中的日志会丢失
producer.close();

### 注意事项

- send() 是异步的，调用后立即返回，日志在后台线程攒批发送。
- 进程退出前必须调用 producer.close()，它会阻塞直到缓冲区中的日志全部发送完毕。
- topic 和 source 是攒批维度，避免传入高基数值（如请求 ID），否则会破坏攒批效果。
- 如果遇到 protobuf 版本冲突，可使用 jar-with-dependencies 分类器。

场景三：使用 Java Consumer Group 消费日志

提示词

Java 项目需要从 SLS Logstore 实时消费日志，要求自动 checkpoint、多实例负载均衡。 Project 是 prod-web，Logstore 是 app-logs。给出 Consumer Group 的完整代码。

Agent 输出示例

推荐使用 aliyun-log-consumer-java（loghub-client-lib），它自动处理分片分配、
心跳、checkpoint 持久化和多实例负载均衡，你只需实现 ILogHubProcessor 接口。

### Maven 依赖

<dependency>
  <groupId>com.aliyun.openservices</groupId>
  <artifactId>loghub-client-lib</artifactId>
  <version>0.6.50</version>
</dependency>
<dependency>
  <groupId>com.google.protobuf</groupId>
  <artifactId>protobuf-java</artifactId>
  <version>2.5.0</version>
</dependency>

### 启动 Consumer Worker

LogHubConfig config = new LogHubConfig(
    "my-consumer-group",
    "consumer-1",          // 同一 consumer group 内必须唯一
    "cn-hangzhou.log.aliyuncs.com",
    "prod-web", "app-logs",
    System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"),
    System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"),
    LogHubConfig.ConsumePosition.BEGIN_CURSOR);

ClientWorker worker = new ClientWorker(new SampleProcessorFactory(), config);
Thread thread = new Thread(worker);
thread.start();

// 进程退出时优雅关闭
Runtime.getRuntime().addShutdownHook(new Thread(() -> {
    worker.shutdown();
    try { Thread.sleep(30_000); } catch (InterruptedException ignored) {}
}));

### Processor 实现

class SampleProcessor implements ILogHubProcessor {
    private int shardId;

    @Override
    public void initialize(int shardId) {
        this.shardId = shardId;
    }

    @Override
    public String process(List<LogGroupData> logGroups,
                          ILogHubCheckPointTracker tracker) {
        for (LogGroupData data : logGroups) {
            // 处理日志
            System.out.println("Shard " + shardId + ": "
                + data.GetAllLogs().size() + " logs");
        }
        tracker.saveCheckPoint(false); // 保存到本地，框架每 ~60s 自动刷盘到服务端
        return null;
    }

    @Override
    public void shutdown(ILogHubCheckPointTracker tracker) {
        tracker.saveCheckPoint(true); // 关闭时立即持久化到服务端
    }
}

class SampleProcessorFactory implements ILogHubProcessorFactory {
    @Override
    public ILogHubProcessor generatorProcessor() {
        return new SampleProcessor();
    }
}

### 注意事项

- ConsumePosition.BEGIN_CURSOR 仅在首次创建 Consumer Group 时生效，
  后续重启从上次保存的 checkpoint 恢复。
- checkpoint 默认每 ~60s 自动提交到服务端，崩溃可能导致少量重复消费（at-least-once）。
- 消费者名称在同一 Consumer Group 内必须唯一，建议使用 IP + PID。
- 一个 Logstore 最多允许 30 个 Consumer Group。

场景四：通过 Log4j2 Appender 零代码接入 SLS

提示词

我们 Java 项目已经在用 Log4j2 打日志，想把日志直接投递到阿里云 SLS，不改业务代码。 怎么配置？

Agent 输出示例

推荐使用 aliyun-log-log4j2-appender，只需要添加 Maven 依赖并修改 log4j2.xml 配置，
不需要改动任何业务代码。Appender 底层使用 Java Producer，日志异步攒批发送。

### Maven 依赖

<dependency>
  <groupId>com.aliyun.openservices</groupId>
  <artifactId>aliyun-log-log4j2-appender</artifactId>
  <version>0.1.15</version>
</dependency>
<dependency>
  <groupId>com.google.protobuf</groupId>
  <artifactId>protobuf-java</artifactId>
  <version>2.5.0</version>
</dependency>

### log4j2.xml 配置

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="WARN">
  <Appenders>
    <Loghub name="Loghub"
            project="your_project"
            logStore="your_logstore"
            endpoint="cn-hangzhou.log.aliyuncs.com"
            accessKeyId="${env:ALIBABA_CLOUD_ACCESS_KEY_ID}"
            accessKeySecret="${env:ALIBABA_CLOUD_ACCESS_KEY_SECRET}"
            totalSizeInBytes="104857600"
            maxBlockMs="0"
            ioThreadCount="8"
            batchSizeThresholdInBytes="524288"
            batchCountThreshold="4096"
            lingerMs="2000"
            retries="10"
            baseRetryBackoffMs="100"
            maxRetryBackoffMs="50000"
            topic=""
            source=""
            ignoreExceptions="true">
      <PatternLayout pattern="%d %-5level [%thread] %logger{0}: %msg"/>
    </Loghub>
  </Appenders>
  <Loggers>
    <Root level="WARN">
      <AppenderRef ref="Loghub"/>
    </Root>
  </Loggers>
</Configuration>

### 使用方式

配置完成后，使用标准 Log4j2 API 打印的日志会自动发送到 SLS，无需额外代码：

import org.apache.logging.log4j.LogManager;
import org.apache.logging.log4j.Logger;

Logger logger = LogManager.getLogger(MyClass.class);
logger.info("Application started");
logger.error("Order creation failed", exception);

每条日志在 SLS 中会包含以下字段：level、location、message、throwable（如有异常）、
thread、time、log。

### 注意事项

- 设置 maxBlockMs="0"（推荐）可防止缓冲区满时阻塞业务线程。
- 不要在配置文件中硬编码 AccessKey，使用 ${env:...} 读取环境变量。
- 如果项目同时使用 Log4j 或 Logback，SLS 也提供对应的 Appender：
  aliyun-log-log4j-appender 和 aliyun-log-logback-appender。

支持哪些 SDK 和编程语言？

该 Skill 覆盖 Java、Go、Python、Node.js、PHP、.NET、Rust、C/C++、iOS、Android 共 10 种语言平台，支持 20 余个 SDK，包括语言 SDK、Producer SDK、Consumer Library、Log4j / Log4j2 / Logback Appender，以及 alibabacloud OpenAPI SDK。

什么时候不推荐使用此技能？

1. 临时的、简单的、运维脚本中的日志查询需求，可无需编写 SDK 代码，推荐使用技能 alibabacloud-sls-query。该技能使用 cli 查询日志，更加轻量快捷。

2. Agent 工作流中需要动态生成查询语句时，推荐使用技能 alibabacloud-sls-query，agent 生成 cli 命令、查询语句更加灵活，可配合命令行工具灵活处理日志输出。