OpenAPI 规范

Telemetry 为记录的 HTTP API 发布了机器可读的 OpenAPI 3.1 规范。使用它来检查端点合同、生成类型化客户端作为起点、配置 API 浏览器或验证 CI 中的示例请求。

该规范涵盖：

• 使用 POST /log 进行结构化事件摄取；
• 同步SQL与POST /query；
• 异步 JSON 和 Parquet 与 POST /query/async 和 GET /query/async/{job_id} 导出；
• 表列表、模式检查、保留、分区列和删除；
• 仪表板列表、创建、替换更新和删除；
• 告警列表、创建、部分更新和删除；
• 旧的行删除端点，标记为已弃用。

下载规格书

curl -fsS https://telemetry.sh/openapi.json -o telemetry-openapi.json

该文档使用 https://api.telemetry.sh 作为其服务器，并描述了两种支持的授权标头形式：

Authorization: YOUR_API_KEY

Authorization: Bearer YOUR_API_KEY

不要将真正的 API 密钥放入提交到存储库的规范、源代码控制、生成的文档、示例、日志或客户端配置中。

验证文件

使用与 OpenAPI 3.1 兼容的验证器。例如，使用本地安装的 Redocly CLI：

npx @redocly/cli lint telemetry-openapi.json

在 CI 中固定验证器版本，以便工具升级不会意外更改发布行为。将有关不明确模式的警告视为审查项目，而不是自动抑制它们。

仔细生成客户

生成的客户端是脚手架，不能替代端点指南。生产使用前：

1. 验证身份验证和 API 密钥范围；
2. 配置连接和响应超时；
3. 仅重试具有有限指数退避和抖动的临时故障；
4. 重试摄取时保留事件标识符；
5. 对异步查询作业施加总轮询截止时间；
6. 避免遥测失败导致应用程序工作人员精疲力竭；
7. 分别查看破坏性表和行删除方法。

OpenAPI 架构有意将灵活的事件负载和查询结果行保留为开放式，因为它们的字段取决于您的事件契约和 SQL 投影。为应用程序中的这些有效负载生成域类型，而不是假设一种全局事件形状。

真实来源边界

该规范反映了此存储库中的公共 API 文档。人类可读的页面仍然是操作指南、规范化行为、示例和故障模式的来源：

• 日志API
• 查询API
• 表格 API
• 仪表板API
• 告警 API
• 删除API
• 速率限制和错误

特定于计划的配额可能会发生变化，并且不会在规范中编码为全局数字费率。检查产品和计费设置的当前帐户限制。如果 OpenAPI 文档和实时 API 响应不一致，请捕获最小安全复制并将其报告给 [email protected]；不要通过记录凭据或私有负载来解决不匹配问题。