Rust SDK 快速入门

更新时间:
复制 MD 格式

本文通过两个完整示例,介绍如何使用 Client 向已有 LogStore 写入日志,并查询最近 15 分钟的日志。本文的直接写入方式是快速入门的默认路径;当需要升级写入能力时,可改用 Rust Producer,完整判据参见后续步骤。本文示例使用已有资源,不会创建或修改 Project、LogStore 和索引配置。

开始前准备

前提条件

  • 已按照“安装 Rust SDK”添加 SDK 依赖,并执行 cargo add aliyun-log-sdk-protobuf 添加写入示例所需的 Log、LogGroup 数据类型依赖。

  • 已按照“初始化 Rust SDK”配置访问凭证。

  • 目标 Project 和 LogStore 已存在,凭证具备写入和查询权限。

配置运行环境

写入和查询示例均通过 environment_credentials_provider() 读取访问凭证。运行前,在同一终端设置以下环境变量(Linux/macOS):

export ALIBABA_CLOUD_ACCESS_KEY_ID="<your-access-key-id>"
export ALIBABA_CLOUD_ACCESS_KEY_SECRET="<your-access-key-secret>"

将占位内容替换为有权访问目标 LogStore 的 RAM 用户 AccessKey,不要将真实密钥提交到代码仓库。Windows 用户可设置同名的系统环境变量,然后重新打开终端。

本文的写入和查询示例使用 #[tokio::main] 运行异步代码。运行前,在项目目录添加 Tokio 依赖:

cargo add tokio --features macros,rt-multi-thread
重要

写入前必须在目标 LogStore 开启全文索引。写入本身不要求开启索引,但本文的查询示例需要索引;索引配置通常只对后续写入的数据生效,请先开启索引再执行写入示例。

步骤一:写入日志

执行写入示例前,确认目标 LogStore 已开启全文索引(索引配置通常只对后续写入的数据生效)。将以下代码保存为 src/main.rs:

use aliyun_log_rust_sdk::{environment_credentials_provider, Client, Config, FromConfig};
use aliyun_log_sdk_protobuf::{Log, LogGroup};
use std::time::{SystemTime, UNIX_EPOCH};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = Config::builder()
        // 替换为 Project 所在地域的 Endpoint。
        .endpoint("https://cn-hangzhou.log.aliyuncs.com")
        .credentials_provider(environment_credentials_provider()?)
        .build()?;
    let client = Client::from_config(config)?;
    // 替换为已有的 Project 和 Logstore 名称。
    let project = "my-project";
    let logstore = "my-logstore";

    let seconds = SystemTime::now().duration_since(UNIX_EPOCH)?.as_secs();
    let mut log = Log::from_unixtime(u32::try_from(seconds)?);
    log.add_content_kv("level", "INFO")
        .add_content_kv("message", "Hello from Rust SDK");

    let mut group = LogGroup::new();
    group.set_topic("rust-demo")
        .set_source("rust-app")
        .add_log(log);

    let response = client.put_logs(project, logstore)
        .log_group(group)
        .send()
        .await?;

    println!("日志写入成功,request_id={:?}", response.get_request_id());
    Ok(())
}

在项目目录执行:

cargo run

当程序输出“日志写入成功”时,表示服务端已确认本次请求成功。request_id 是请求标识,可用于排查问题。

写入代码说明

  • Log 表示一条日志;字段名和字段值均为字符串。数值字段可先调用 .to_string()。

  • Log::from_unixtime 接收秒级 Unix 时间戳,不能传入毫秒时间戳。

  • LogGroup 表示一组日志。可以多次调用 .add_log(),用一次请求写入多条日志。

  • topic(主题)和 source(来源)为可选项,分别用于区分业务和标记日志来源。

  • Client 会自动压缩并发送这组日志,但不会将不同 put_logs 调用自动合并为一批。

步骤二:查询日志

写入后,需要等待日志可被查询。将 src/main.rs 替换为以下代码,再执行 cargo run,无需再次运行写入示例。步骤一的写入代码仍保留在上文,需要重新写入时可再次复制使用。

use aliyun_log_rust_sdk::{environment_credentials_provider, Client, Config, FromConfig};
use std::time::{SystemTime, UNIX_EPOCH};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = Config::builder()
        // 替换为 Project 所在地域的 Endpoint。
        .endpoint("https://cn-hangzhou.log.aliyuncs.com")
        .credentials_provider(environment_credentials_provider()?)
        .build()?;
    let client = Client::from_config(config)?;
    // 替换为已有的 Project 和 Logstore 名称。
    let project = "my-project";
    let logstore = "my-logstore";
    let now = i64::try_from(SystemTime::now().duration_since(UNIX_EPOCH)?.as_secs())?;

    let response = client.get_logs(project, logstore)
        .from(now - 15 * 60)
        .to(now + 1)
        .topic("rust-demo")
        .query("*")
        .offset(0)
        .line(100)
        .send()
        .await?;

    let body = response.get_body();
    if !body.is_complete() {
        return Err(std::io::Error::other("查询尚未完成,请稍后用相同条件重试").into());
    }

    println!("本次返回 {} 条日志", body.logs_count());
    for log in body.logs() {
        println!("{log:?}");
    }
    Ok(())
}

示例查询主题为 rust-demo 的日志,最多返回 100 条。当程序输出“本次返回 {} 条日志”并逐条打印日志明细时,表示查询已成功返回;查询结果中应包含 message 为 Hello from Rust SDK 的记录。如果返回 0 条,参见下文 is_complete() 说明与“常见问题”排查。

查询参数说明

参数

说明

from、to

查询开始、结束时间,单位为 Unix 秒。时间范围为左闭右开 [from, to),示例将结束时间设为当前秒加 1,以包含当前秒的日志。

topic

限定日志主题。查询所有主题时,移除此项。

query

查询语句。* 表示匹配范围内的所有日志。

offset

非 SQL 查询从第几条结果开始返回,0 表示从第一条开始。

line

非 SQL 查询本次最多返回的日志条数,不代表匹配日志总数。

使用字段条件,例如 level:INFO,需要提前配置对应字段的索引。使用 SQL 分析时,通过 SQL 的 LIMIT 子句控制返回行数,不使用 line 和 offset 分页。

说明

is_complete() 为 true 表示此次查询已完成,不表示已经获取全部分页数据,也不表示刚写入的日志一定已可查询。如果返回 0 条,请先检查 Project、LogStore、主题、时间范围和索引配置,再稍后重新查询。

常见问题

现象

排查建议

提示环境变量不存在

确认运行程序的终端或部署环境已设置该变量;SDK 不会自动读取项目内的 .env 文件。

鉴权失败或无访问权限

检查 AccessKey 是否有效、STS Token 是否配套且未过期,以及目标资源的 RAM 权限。

提示 Project 或 LogStore 不存在

检查名称及 Endpoint 所在地域。

连接失败或超时

检查网络、DNS 和 Endpoint,确认内网地址是否适用于当前环境。

写入成功但查询不到

确认索引在写入前已开启,查询范围包含日志时间,并等待日志可查询。不要仅因暂时查不到而重复写入。

错误处理与重试注意事项

Client 请求返回错误时,示例会退出并输出错误信息。服务端错误通常包含错误码、说明和 request_id,请保留这些信息用于排查,不要记录访问密钥。

网络超时不一定意味着服务端未写入;自动重试或应用再次发送可能导致重复日志。对重复敏感的业务,日志应携带业务唯一标识。

后续步骤

需要自动批量发送、后台重试和发送结果回调,或持续、大量写入日志时,参见“使用 Rust Producer 写入日志”。