本文通过两个完整示例,介绍如何使用 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() 说明与“常见问题”排查。
查询参数说明
参数 | 说明 |
| 查询开始、结束时间,单位为 Unix 秒。时间范围为左闭右开 |
| 限定日志主题。查询所有主题时,移除此项。 |
| 查询语句。 |
| 非 SQL 查询从第几条结果开始返回,0 表示从第一条开始。 |
| 非 SQL 查询本次最多返回的日志条数,不代表匹配日志总数。 |
使用字段条件,例如 level:INFO,需要提前配置对应字段的索引。使用 SQL 分析时,通过 SQL 的 LIMIT 子句控制返回行数,不使用 line 和 offset 分页。
is_complete() 为 true 表示此次查询已完成,不表示已经获取全部分页数据,也不表示刚写入的日志一定已可查询。如果返回 0 条,请先检查 Project、LogStore、主题、时间范围和索引配置,再稍后重新查询。
常见问题
现象 | 排查建议 |
提示环境变量不存在 | 确认运行程序的终端或部署环境已设置该变量;SDK 不会自动读取项目内的 |
鉴权失败或无访问权限 | 检查 AccessKey 是否有效、STS Token 是否配套且未过期,以及目标资源的 RAM 权限。 |
提示 Project 或 LogStore 不存在 | 检查名称及 Endpoint 所在地域。 |
连接失败或超时 | 检查网络、DNS 和 Endpoint,确认内网地址是否适用于当前环境。 |
写入成功但查询不到 | 确认索引在写入前已开启,查询范围包含日志时间,并等待日志可查询。不要仅因暂时查不到而重复写入。 |
错误处理与重试注意事项
Client 请求返回错误时,示例会退出并输出错误信息。服务端错误通常包含错误码、说明和 request_id,请保留这些信息用于排查,不要记录访问密钥。
网络超时不一定意味着服务端未写入;自动重试或应用再次发送可能导致重复日志。对重复敏感的业务,日志应携带业务唯一标识。
后续步骤
需要自动批量发送、后台重试和发送结果回调,或持续、大量写入日志时,参见“使用 Rust Producer 写入日志”。