Simple Log Service:Integrate SLS SDK with agent skill

Método 1 (recomendado): Instale com o npx

O comando npx está incluído no Node.js. Antes da instalação, execute os seguintes comandos para verificar se o Node.js está disponível:

node -v
npx -v

Se o terminal informar que node ou npx não for encontrado, baixe e instale o Node.js no site oficial do Node.js.

Execute o seguinte comando para instalar a skill alibabacloud-sls-sdk-guidance:

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

Método 2: Instalação manual

Baixe o pacote alibabacloud-sls-sdk-guidance no GitHub Releases. Extraia o pacote e copie o conteúdo para o diretório de instalação de skills do seu agente. Certifique-se de que o diretório alibabacloud-sls-sdk-guidance exista no diretório de skills e reinicie o agente para carregar a skill.

A tabela a seguir lista os diretórios de instalação de skills para os agentes mais comuns:

Dicas para escrever prompts

Para ajudar o agente a recomendar SDKs e gerar código com mais precisão, inclua as seguintes informações nos seus prompts:

• Linguagem de programação e versão. Por exemplo, "Java 17" ou "Go 1.21".

• Caso de uso. Por exemplo, "ingestão de logs de alto throughput", "consumo de logs baseado em Consumer Group", "consultar logs" ou "criar configuração de índice".

• Stack de tecnologia existente. Por exemplo, "projeto Spring Boot" ou "o projeto já usa o Log4j 2".

Cenário 1: Selecione o SDK certo para o seu caso de uso

Prompt

Meu projeto Java precisa de ingestão de logs de alto throughput para o Alibaba Cloud SLS e consumo de logs baseado em Consumer Group para processamento em tempo real. Quais SDKs devo usar? Forneça as dependências do Maven para cada um.

Exemplo de resposta do agente

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.

Cenário 2: Ingerir logs com o Producer SDK do Java

Prompt

Meu projeto Java Spring Boot precisa usar o Producer SDK para gravar logs de negócios de forma assíncrona no SLS. O projeto é prod-web, o Logstore é app-logs e a região é China (Hangzhou). Forneça um exemplo de código completo.

Exemplo de resposta do agente

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

Cenário 3: Consumir logs com o Consumer Group do Java

Prompt

Meu projeto Java precisa consumir logs de um Logstore do SLS em tempo real, com checkpointing automático e balanceamento de carga de múltiplas instâncias. O projeto é prod-web e o Logstore é app-logs. Forneça o código completo do Consumer Group.

Exemplo de resposta do agente

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

Cenário 4: Integrar o Appender do Log4j 2 sem alterar o código

Prompt

Meu projeto Java já usa o Log4j 2 para log. Quero enviar logs diretamente para o Alibaba Cloud SLS sem modificar nenhum código da aplicação. Como configuro isso?

Exemplo de resposta do agente

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>

Quais SDKs e linguagens de programação são suportados?

Esta skill abrange 10 plataformas de linguagem: Java, Go, Python, Node.js, PHP, .NET, Rust, C/C++, iOS e Android. Ela suporta mais de 20 SDKs, incluindo SDKs específicos de linguagem, Producer SDK, biblioteca de consumo, Appenders para Log4j / Log4j 2 / Logback e SDKs OpenAPI do alibabacloud.

Quando não devo usar esta skill?

1. Para consultas de logs ad-hoc, simples ou automatizadas por scripts, não é necessário escrever código de SDK. Recomendamos o uso da skill alibabacloud-sls-query, que consulta logs por meio da CLI, sendo mais rápida e leve.

2. Quando o fluxo de trabalho do seu agente exige geração dinâmica de consultas, recomendamos o uso da skill alibabacloud-sls-query. O agente gera comandos da CLI e instruções de consulta de forma mais flexível e pode processar a saída de log com ferramentas de linha de comando.