日志 API - 通过 HTTP 查询和分析 SigNoz 日志
SigNoz Logs API 是一个功能强大的接口,帮助开发者高效地管理和分析日志数据。它支持多种操作:
-
搜索日志:根据特定条件检索日志数据,例如查找所有错误码为 500 的日志。
-
分页日志:以可控的方式浏览大量日志数据,例如每次获取 100 条日志,方便查看。
-
聚合日志:对日志数据进行汇总以提取有价值的信息,例如按天统计错误数量。
API Endpoint
Logs API 的端点为:
POST https://<your-instance-url>/api/v5/query_range
请将 <your-instance-url> 替换为你的 SigNoz 实例地址,例如 example.us.signoz.cloud。
前提条件
API key:访问该 API 需要一个 API key。在 SigNoz 中进入 Settings → Service Accounts,创建一个 service account,并在其 Keys 标签页中生成 API key。详细步骤请参考 Service Accounts。

只有拥有 Admin 角色的用户才能创建和管理 API key。如果你没有 Admin 角色,请联系组织的管理员为你创建。
service account 需要具备读取日志的角色,例如 signoz-viewer。详见 Service Accounts。
SigNoz 版本:本页内容适用于 SigNoz Cloud 以及 v0.114.0 及以上版本的自托管 SigNoz(v0.114.0 是首个引入 service accounts 的版本)。
认证
使用 API key:将 API key 添加到请求头中,如下所示:
CopySIGNOZ-API-KEY: <your-api-key>
Tip请妥善保管和处理你的 API key,防止被未授权访问。
发送请求
此示例返回过去 15 分钟内最新的 10 条错误日志。
-
设置您的 SigNoz 实例 URL 和 API 密钥:
Copyexport SIGNOZ_URL="https://<your-instance-url>" export SIGNOZ_API_KEY="<your-api-key>"请确认以下信息:
<your-instance-url>:用于访问 SigNoz 的 URL。例如,SigNoz Cloud 用户通常为example.us.signoz.cloud,自建用户则为signoz.example.com。如果您的自建实例未配置 TLS,请将https://改为http://。<your-api-key>:即先决条件中提到的 API 密钥。
-
构造请求负载。
Copystart和end为毫秒级 Unix 时间戳:END_MS=$(( $(date +%s) * 1000 )) START_MS=$(( END_MS - 15 * 60 * 1000 )) cat > query.json <<EOF { "start": $START_MS, "end": $END_MS, "requestType": "raw", "compositeQuery": { "queries": [ { "type": "builder_query", "spec": { "name": "A", "signal": "logs", "filter": { "expression": "severity_text = 'ERROR'" }, "order": [{ "key": { "name": "timestamp" }, "direction": "desc" }], "limit": 10 } } ] } } EOF -
发送请求:
Copycurl -s -X POST "$SIGNOZ_URL/api/v5/query_range" \ -H "SIGNOZ-API-KEY: $SIGNOZ_API_KEY" \ -H "Content-Type: application/json" \ -d @query.json
响应数据中,每条日志位于 data.data.results[0].rows 下,日志字段存放在每行的 data 属性中。下方为响应数据的缩略示例:
{
"status": "success",
"data": {
"type": "raw",
"data": {
"results": [
{
"queryName": "A",
"rows": [
{
"timestamp": "2026-11-06T05:52:01.605786Z",
"data": {
"body": "payment gateway timeout for order 42",
"severity_text": "ERROR",
"resources_string": { "service.name": "checkout" },
"attributes_string": { "http.route": "/api/checkout" },
"trace_id": "",
"id": "0mMZCp9dqBWc0v0QJnO2BRUhgst",
"timestamp": 1793944321605786000
}
}
]
}
]
}
}
}
如果只想返回部分字段(比如日志正文),请参考 Return only some fields。
如果响应中出现了 authz_forbidden 错误码,说明该 API key 对应的服务账号没有被赋予可读取日志的角色。请给它分配一个角色,例如 signoz-viewer。
操作
- Search Logs — 按属性、日志内容、严重级别或 trace ID 过滤日志,并支持分页。
- Aggregate Logs — 对过滤后的日志数据进行计数、求平均值和分组统计。
- Logs URL for Explorer — 生成一个指向 Logs Explorer 的直链 URL,并预置好过滤条件和时间范围。
- Payload Model — 请求和响应的数据结构参考。