← 文章 / 云原生与基础设施
signoz 15天前 · 2026-11-07 05:02:56 · 10 阅读

日志 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。

Creating an API key in SigNoz Service Accounts
在 SigNoz Service Accounts 中创建 API key

只有拥有 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 添加到请求头中,如下所示:

Copy
SIGNOZ-API-KEY: <your-api-key>
Tip

请妥善保管和处理你的 API key,防止被未授权访问。

发送请求

此示例返回过去 15 分钟内最新的 10 条错误日志。

  1. 设置您的 SigNoz 实例 URL 和 API 密钥:

    Copy
    export 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 密钥。
  2. 构造请求负载。start 和 end 为毫秒级 Unix 时间戳:

    Copy
    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
  3. 发送请求:

    Copy
    curl -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 — 请求和响应的数据结构参考。
原始来源: signoz

评论 (0)