Rust SDK
telemetry-sh crate 提供了一个用于事件摄取和交互式查询的小型阻塞客户端。每种方法都会构造一个阻塞 reqwest 客户端并发送一个 HTTP 请求。该包不公开异步客户端、可配置超时、重试策略、批处理队列或刷新方法。
安装并初始化
[dependencies]
telemetry-sh = "1.0.0"
serde_json = "1.0"
uuid = { version = "1", features = ["v4"] }
use std::env;
use telemetry_sh::Telemetry;
let mut telemetry = Telemetry::new();
telemetry.init(env::var("TELEMETRY_API_KEY")?);
将密钥保留在服务器端配置中。将写入范围的密钥用于仅摄取服务，将读取范围的密钥用于报告或查询自动化。
发送结构化事件
use serde_json::json;
use uuid::Uuid;
let event_id = Uuid::new_v4().to_string();
let event = json!({
"event_id": event_id,
"job_name": "invoice_sync",
"status": "success",
"duration_ms": 912,
"attempt": 1,
"release": env::var("APP_RELEASE").ok(),
});
match telemetry.log("job_completed", &event) {
Ok(response) => println!("telemetry response: {response}"),
Err(error) => eprintln!(
"telemetry delivery failed event_id={} error_type=transport_error: {}",
event_id,
error
),
}
避免使用凭据、标头、cookie、原始请求正文、提示、异常文本和私人客户内容。更喜欢受控的类别和稳定的内部标识符。
SDK 接受一个 serde_json::Value。数组值可以表示 Log API 批量有效负载，但在将批处理作为生产交付合同的一部分之前测试确切的箱子和 API 行为。
运行SQL
let query = r#"
SELECT
status,
COUNT(*) AS jobs
FROM job_completed
WHERE timestamp_utc >= now() - INTERVAL '24 hours'
GROUP BY status
ORDER BY jobs DESC
"#;
let result = telemetry.query(query)?;
let rows = result
.get("data")
.and_then(|value| value.as_array())
.cloned()
.unwrap_or_default();
println!("query rows: {}", rows.len());
结果是动态 JSON。在自动化中使用值之前验证类型、空值、API 状态和空结果。直接使用 异步查询API 进行长期运行的 JSON 或 Parquet 导出。
阻塞和超时行为
两种 crate 方法均使用 reqwest::blocking。在未隔离阻塞工作的情况下，请勿直接在异步执行程序线程或延迟敏感的请求路径上调用它们。
已发布的包不会公开其 HTTP 客户端或配置超时。如果服务需要上下文取消、连接重用、固定超时、特定于状态的重试或持久队列，请改为使用应用程序拥有的 reqwest::Client 来实现记录的 HTTP 请求。
保持传输策略有限，以便遥测中断不会耗尽工作线程。
重试和关闭策略
仅重试暂时性连接失败、429、502、503 和 504。使用带有抖动的指数退避，限制总时间，并保留相同的 event_id。不要重试未更改的无效请求。
SDK 没有要刷新的后台队列。成功返回 log 意味着立即请求产生了可解码的响应；它并不是一次性存储的承诺。在进程关闭之前，跟踪所需的调用或将持久事件保留在应用程序拥有的发件箱中。
对于普通分析，不要因为遥测不可用而将已完成的客户操作转变为失败。查看 事件传递和幂等性。
验证集成
发送已知成功和失败的灯具，然后查询：
SELECT timestamp_utc, event_id, job_name, status, duration_ms, error_type
FROM job_completed
ORDER BY timestamp_utc DESC
LIMIT 20;
检查表命名、字段类型、单位、空行为、重复事件 ID 和敏感数据边界。在依赖该事件发出告警之前，请先执行连接超时并正常关闭。
故障排除
- 缺少密钥错误：从非空服务器端环境值初始化客户端。
- 运行时停顿：将阻塞调用移出异步执行程序线程或使用应用程序拥有的异步 HTTP 客户端。
- 错误响应解码为JSON：检查返回的状态和消息；该板条箱不调用
error_for_status。 - 重复行：跨网络尝试保留
event_id并监控 重复的 ID。 - 大导出：使用HTTP异步查询启动、状态和下载流程。