快速入门
将 JSON 事件发送到 Telemetry，再用 SQL 查询。本快速入门将带你发送一个事件，检查 Telemetry 创建的表，并运行查询。
如果您有兴趣了解有关 Telemetry 内部工作原理的更多信息，请查看我们的 Telemetry架构文档 以获取详细概述。有关更深入的用例，例如通过检测 API 调用来跟踪 OpenAI 成本，请参阅我们的 跟踪 OpenAI 成本 指南。
想按更简短的任务逐步学习？请依次阅读：
获取 API 密钥
访问首页，从设置提示词中获取 anon_… 密钥。无需账户即可发送和查询事件。如果已有账户，请使用团队设置 → API 密钥中的 read-and-write 密钥。
匿名查询在首个事件后可用 24 小时。请在 7 天内创建账户，以保留事件和原密钥。注册会识别当前浏览器中的试用。在其他浏览器中，先选择已有匿名 API 密钥？，粘贴密钥并点击查找我的数据，再注册。已有账户的用户可在保留我的数据中恢复密钥，然后登录。未发送事件的试用在创建 7 天后到期。
安装Telemetry
本教程使用JavaScript。您还可以使用 Python、Go、Rust、Ruby、PHP 或 cURL。
npm install telemetry-sh
记录一些数据
Telemetry 在记录数据时自动创建表。在以下示例中，我们将合成骑行数据记录到名为 uber_rides 的表中。 Telemetry 使用 city 和 price 创建表及其架构；每行还收到 timestamp_utc。
import telemetry from "telemetry-sh";
telemetry.init("YOUR_API_KEY");
telemetry.log("uber_rides", {
city: "paris",
price: 42
});
使用我们的 UI 探索数据
先通过查询验证事件，无需注册：
const result = await telemetry.query("SELECT city, price FROM uber_rides LIMIT 10");
console.log(result);
要使用图表、仪表板和警报，请创建账户并保留数据。现有密钥仍然有效，注册后会打开存有事件的工作区。已有账户则可关联试用。
Telemetry 流程示意图：从表、SQL 查询和图表，到共享仪表板或告警。
探索视图
使用探索选项卡筛选事件、创建图表或表格，无需编写 SQL。
探索每次处理一个表。打开方式如下：
- 进入你的团队页面。
- 打开表。
- 选择一个表。
- 打开该表页面上的 探索 选项卡。
路由格式：
/team/{team}/table/{table}?tab=explore
- 选择图形类型（
Samples、Table、Line、Bar或Stacked Area）。 - 设置时间范围并添加一个或多个过滤器。
- 选择要包含的列（包括
data.toolName等嵌套字段）。 - 单击运行来执行并呈现结果。
提示：控件处于草稿状态。仅当您单击“运行”时，结果才会更新。
假设的示例数据集（虚构）
对于下面的探索示例，假设您使用如下结构记录了合成测试事件（没有真实的用户数据）：
{
"timestamp_utc": "2026-02-27T12:00:00.000Z",
"event": "tool_call",
"status": "success",
"data": {
"toolName": "smart_avantis_buy",
"args": {
"symbol": "BTC-USD",
"amountUsd": 2500
}
}
}
您可以将其记录到 agent_demo_events 等表中，并在“探索”中使用该表。
示例 1：过滤工具调用并检查原始行
使用上面的虚构模式，在“探索”中尝试以下操作：
- 将图表类型设置为
Samples. - 添加过滤器：
event = tool_call. - 添加过滤器：
data.toolName = smart_avantis_buy. - 点击 运行.
URL 模板（替换占位符）：
/team/{team}/table/agent_demo_events?tab=explore&graphType=samples&f=event:=:tool_call&f=data.toolName:=:smart_avantis_buy示例 2：比较图表视图与表格视图
使用相同的过滤器，然后：
- 选择
Line然后单击 运行. - 切换到
Table然后单击 运行 再次。
这为您提供了一种快速验证趋势和准确值的方法。
示例 3：“所有列”模式下的嵌套列
当你保留 All columns 在探索中选择，生成的 SQL 显式枚举列，因此包含嵌套字段。
生成的 SQL 形状示例：
SELECT "timestamp_utc", "event", "data.toolName", "data.args.symbol"
FROM "your_table"
WHERE timestamp_utc >= now() - INTERVAL '7 days'
ORDER BY timestamp_utc DESC
LIMIT 200仪表板
仪表板可让您将探索图表/表格和查询结果固定到一个共享视图中。
创建和使用仪表板：
- 打开探索中的任何表或打开已保存的查询结果。
- 单击“添加到仪表板”。
- 选择现有的仪表板，或先创建一个新的仪表板。
- 为小部件指定标题并确认。
仪表板路由格式：
/team/{team}/dashboard/{dashboardSlug}
使用仪表板将团队的关键信号（延迟、错误率、成本和转化指标）保存在一个位置。
创建提醒
获得图表或查询结果后，您可以将其转换为 Telemetry UI 中的告警。
- 在 探索中打开表或在结果/图表 视图中运行查询。
- 单击“创建告警”。
- 配置条件（聚合、最后 N 点、比较和阈值）。
- 设置检查间隔和一个或多个电子邮件收件人。
- 单击“创建告警”进行保存。您将被重定向到
/team/{team}/alert/{alertSlug}以监控状态和历史记录。
提示：为存储时间序列启用忽略最后一个数据点，因为最新的存储桶通常不完整。
有关完整演练，请参阅 告警指南。
交互式内嵌示例
示例 1：延迟尖峰检测器 (p95)
在“探索”表中尝试此操作 latency_ms:
- 将图表类型设置为
Line. - 将聚合设置为
p95带公制latency_ms. - 点击 运行，然后单击 创建告警.
- 条件：
p95 of last 5 data points is Greater than 850. - 间隔：
Every minute，然后添加收件人电子邮件。
URL 模板（替换占位符）：
/team/{team}/table/{table}?tab=explore&graphType=line&agg=p95&metric=latency_ms&time=7d示例 2：错误突发检测器（计数）
检测失败请求中的峰值：
- 在探索中，使用以下内容过滤行
status >= 500. - 使用带有聚合的折线图
count. - 点击 创建告警.
- 条件：
Average of last 3 data points is Greater than 20.
这可以捕获短暂的错误突发，同时避免来自单个坏桶的噪音。
示例 3：安静流量检测器（低于阈值）
将其用于 cron 作业、队列或摄取管道：
- 查询或绘制随时间变化的事件量图表。
- 创建比较告警
Less than. - 条件：
Sum of last 10 data points is Less than 50.
如果触发此情况，通常意味着数据在客户注意到之前停止流动。
与您的代码库集成
您可以通过查询 API 来使用 SQL 查询数据，从而将 Telemetry 集成到您的产品或内部仪表板中。
const results =
await telemetry.query(`
SELECT
city,
AVG(price)
FROM
uber_rides
GROUP BY
city
`);
当您准备好分析 API 错误、延迟百分位数、作业重试、LLM 成本、转换、保留或丢失心跳时，请浏览 SQL配方库。
对于这些秘诀背后的架构和分析模型，请继续 SQL 用于可观测性和事件分析。 要运行从摄取到 SQL 结果的完整合成工作流程，请使用 端到端 SaaS 可观测性演示。