Simple Log Service:Integrate SLS SDK with agent skill

node -v
npx -v

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

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.

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

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) {}
}));

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>