Integrate SLS SDK with Agent Skill

Method 1 (recommended): Install with npx

The npx command is included with Node.js. Before installation, run the following commands to verify that Node.js is available:

node -v
npx -v

If the terminal reports that node or npx is not found, download and install Node.js from the official Node.js website.

Run the following command to install the alibabacloud-sls-sdk-guidance skill:

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

Method 2: Manual installation

Download the alibabacloud-sls-sdk-guidance package from GitHub Releases. Extract the package and copy the contents to the skills installation directory of your agent. Make sure that the alibabacloud-sls-sdk-guidance directory exists in the skills directory, and then restart the agent to load the skill.

The following table lists the skills installation directories for common agents:

Prompt writing tips

To help the agent recommend SDKs and generate code more accurately, include the following information in your prompts:

• Programming language and version. For example, "Java 17" or "Go 1.21".

• Use case. For example, "high-throughput log ingestion", "Consumer Group-based log consumption", "query logs", or "create index configuration".

• Existing technology stack. For example, "Spring Boot project" or "the project already uses Log4j 2".

Scenario 1: Select the right SDK for your use case

Prompt

My Java project needs high-throughput log ingestion to Alibaba Cloud SLS and Consumer Group-based log consumption for real-time processing. Which SDKs should I use? Provide the Maven dependencies for each.

Sample agent output

Based on your requirements, I recommend the following two SDKs for ingestion and consumption respectively:

### Ingestion: aliyun-log-java-producer

For high-throughput log ingestion in Java, use the Producer SDK instead of the basic Java SDK's PutLogs API.
The Producer provides asynchronous non-blocking sending, automatic batching, automatic retries, and memory throttling. It is suitable for big data scenarios such as Flink and Spark.

Maven dependency:

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

### Consumption: loghub-client-lib (aliyun-log-consumer-java)

For Consumer Group scenarios, use the Consumer Library. It automatically handles shard assignment, heartbeat,
checkpoint persistence, and multi-instance load balancing. You only need to implement the processing logic for a single shard.

<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>

### Why not use the basic Java SDK?

aliyun-log-java-sdk supports ingestion and querying, but its ingestion uses the synchronous PutLogs API without
batching or retries. This is insufficient for high-throughput scenarios. Consumption requires a separate Consumer Library.

Scenario 2: Ingest logs with Java Producer SDK

Prompt

My Java Spring Boot project needs to use the Producer SDK to asynchronously write business logs to SLS. The project is prod-web, the Logstore is app-logs, and the region is China (Hangzhou). Provide a complete code sample.

Sample agent output

I recommend using aliyun-log-java-producer, which provides asynchronous sending, automatic batching, and automatic retries.
It is suitable for high-throughput server-side log ingestion.

### Maven dependency

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

### Code sample

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. Create a Producer (global singleton, thread-safe)
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. Build a log entry and send (asynchronous, returns immediately)
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);

Scenario 3: Consume logs with Java Consumer Group

Prompt

My Java project needs to consume logs from an SLS Logstore in real time, with automatic checkpointing and multi-instance load balancing. The project is prod-web, and the Logstore is app-logs. Provide the complete Consumer Group code.

Sample agent output

I recommend using aliyun-log-consumer-java (loghub-client-lib). It automatically handles shard assignment,
heartbeat, checkpoint persistence, and multi-instance load balancing. You only need to implement the ILogHubProcessor interface.

### Maven dependency

<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>

### Start the Consumer Worker

LogHubConfig config = new LogHubConfig(
    "my-consumer-group",
    "consumer-1",          // Must be unique within the same 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();

// Shut down gracefully when the process exits
Runtime.getRuntime().addShutdownHook(new Thread(() -> {
    worker.shutdown();
    try { Thread.sleep(30_000); } catch (InterruptedException ignored) {}
}));

Scenario 4: Integrate Log4j 2 Appender with zero code changes

Prompt

My Java project already uses Log4j 2 for logging. I want to send logs directly to Alibaba Cloud SLS without modifying any application code. How do I configure this?

Sample agent output

I recommend using aliyun-log-log4j2-appender. You only need to add a Maven dependency and update the log4j2.xml
configuration. No changes to your application code are required. The Appender uses the Java Producer under the hood
to send logs asynchronously in batches.

### Maven dependency

<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 configuration

<?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"
    />
  </Appenders>
</Configuration>

What SDKs and programming languages are supported?

This skill covers 10 language platforms: Java, Go, Python, Node.js, PHP, .NET, Rust, C/C++, iOS, and Android. It supports more than 20 SDKs, including language-specific SDKs, Producer SDK, consumer library, Log4j / Log4j 2 / Logback Appender, and alibabacloud OpenAPI SDKs.

When should I not use this skill?

1. For ad-hoc, simple, or operations-scripted log queries, you do not need to write SDK code. We recommend using the alibabacloud-sls-query skill instead, which queries logs through the CLI and is faster and more lightweight.

2. When your agent workflow requires dynamic query generation, we recommend using the alibabacloud-sls-query skill. The agent generates CLI commands and query statements more flexibly, and can process log output with command-line tools.