告警

告警 API 允许您配置和管理 Telemetry UI 中提供的相同单系列阈值告警。

如果您要求编码代理配置告警，请从使用编码代理创建告警开始。它为代理提供了安全的发现和验证序列、代理就绪提示以及常见用例的完整请求。

支持的操作：

列表. GET https://api.telemetry.sh/alert
创建. POST https://api.telemetry.sh/alert
编辑. PATCH https://api.telemetry.sh/alert
删除. DELETE https://api.telemetry.sh/alert

标题

名称	类型	描述
`Content-Type`	字符串	对于创建、编辑和删除请求，必须是 `application/json`。
`Authorization`	字符串	您的 API 密钥，作为原始密钥或 `Bearer <key>`。

范围规则：

GET /alert 接受 read、write 或 read-and-write
POST /alert、PATCH /alert 和 DELETE /alert 需要 write 或 read-and-write

列出告警

GET /alert 返回由 updated_at DESC 订购的 API 密钥团队的告警。

支持的查询参数：

领域	类型	必填	精确合约	默认
`page`	整数	否	从 1 开始的正页码。	`1`
`pageSize`	整数	否	正页面大小。高于 `100` 的值被钳位至 `100`。旧别名 `page_size` 也被接受。	`50`

curl "https://api.telemetry.sh/alert?page=1&pageSize=25" \
  -H "Authorization: $API_KEY"

响应包括标准分页元数据和完整的告警记录：

{
  "status": "success",
  "pagination": {
    "page": 1,
    "pageSize": 25,
    "total": 1,
    "totalPages": 1,
    "hasNextPage": false,
    "hasPreviousPage": false
  },
  "alerts": [
    {
      "id": "d7463946-8c6a-4a54-8a47-74cc98247c54",
      "team_id": "a7d4...",
      "name": "API error rate",
      "slug": "api-error-rate",
      "description": "Notify the API on-call rotation",
      "alert_type": "query",
      "payload": {
        "querySql": "SELECT time_bucket, error_rate FROM api_health",
        "timestampColumn": "time_bucket"
      },
      "aggregation": "avg",
      "metric": "error_rate",
      "last_n_data_points": 3,
      "ignore_last_data_point": true,
      "check_interval_minutes": 60,
      "comparison": "greater_than",
      "threshold": 0.05,
      "recipients": [
        { "type": "email", "recipient": "[email protected]" }
      ],
      "status": "inactive",
      "enabled": true,
      "last_evaluated_at": null,
      "last_value": null,
      "evaluation_version": 0,
      "created_by": null,
      "created_by_api_key_id": "key_123",
      "created_at": "2026-09-02T17:05:00.000Z",
      "updated_at": "2026-09-02T17:05:00.000Z",
      "url": "/team/acme/alert/api-error-rate"
    }
  ]
}

当团队没有告警时，pagination.totalPages 是 0。请求超出最后一页的页面将返回空的 alerts 数组。

告警字段

领域	类型	可写	精确合约
`id`	字符串	否	告警 ID。
`team_id`	字符串	否	拥有团队 ID。
`name`	字符串	是的	修剪后的非空显示名称，最多 200 个字符。
`slug`	字符串	是的	独特的团队范围的子弹。参见段塞归一化。
`description`	字符串或 `null`	是的	可选描述。空字符串存储为 `null`。
`alert_type`	字符串	是的	`query` 或 `explorer`。有效负载必须与所选类型匹配。
`payload`	对象	是的	已保存的查询定义。请参见查询负载和资源管理器有效负载。
`aggregation`	字符串	是的	`count`、`sum`、`avg`、`min`、`max`、`p50`、`p90`、`p95` 或`p99`。
`metric`	字符串或 `null`	是的	要聚合的数字结果列。如果 `null`，则求值程序使用第一个数字非时间戳列。建议使用明确的值。
`last_n_data_points`	整数	是的	`1`、`3`、`5`、`10`、`20`、`50` 或 `100` 之一。
`ignore_last_data_point`	布尔值	是的	是否跳过最新的结果行，这可以表示一个不完整的时间段。
`check_interval_minutes`	整数	是的	`1`、`60` 或 `1440` 之一。
`comparison`	字符串	是的	`greater_than`、`less_than`、`greater_than_or_equal` 或 `less_than_or_equal`。
`threshold`	数值	是的	用于比较的有限数值阈值。不接受 `"10"` 这样的 JSON 字符串。
`recipients`	数组	是的	1 到 25 个唯一的电子邮件收件人对象。地址被修剪并小写。
`status`	字符串	否	当前评估状态：满足条件时为`active`，否则为`inactive`。
`enabled`	布尔值	是的	评估者是否应该运行告警。
`last_evaluated_at`	字符串或 `null`	否	最近完成的评估的时间戳。
`last_value`	编号或`null`	否	最新聚合值。
`evaluation_version`	整数	否	内部乐观并发版本。
`created_by`	字符串或 `null`	否	UI 创建告警的用户 ID； `null` 用于 API 创建的告警。
`created_by_api_key_id`	字符串或 `null`	否	API 用于 API 创建的告警的密钥 ID； `null` 用于 UI 创建的告警。
`created_at`	字符串	否	创建时间戳。
`updated_at`	字符串	否	最新更新时间戳。
`url`	字符串	否	Telemetry UI 中的相对告警 URL。

创建告警

POST /alert 创建一个告警并返回 201 Created。

领域	必填	默认
`name`	是的	无
`slug`	否	从 `name` 归一化
`description`	否	`null`
`alert_type`	是的	无
`payload`	是的	无
`aggregation`	否	`avg`
`metric`	否	`null`
`last_n_data_points`	否	`3`
`ignore_last_data_point`	否	`true`
`check_interval_minutes`	否	`60`
`comparison`	否	`greater_than`
`threshold`	是的	无
`recipients`	是的	无
`enabled`	否	`true`

创建查询告警

curl -X POST https://api.telemetry.sh/alert \
  -H "Authorization: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "API error rate",
    "description": "Notify the API on-call rotation",
    "alert_type": "query",
    "payload": {
      "querySql": "SELECT timestamp_utc AS time_bucket, error_rate FROM api_health ORDER BY timestamp_utc DESC",
      "timestampColumn": "time_bucket",
      "sourceUrl": "/team/acme/default/error-rate/1"
    },
    "aggregation": "avg",
    "metric": "error_rate",
    "last_n_data_points": 3,
    "ignore_last_data_point": true,
    "check_interval_minutes": 60,
    "comparison": "greater_than",
    "threshold": 0.05,
    "recipients": [
      { "type": "email", "recipient": "[email protected]" }
    ]
  }'

成功响应：

{
  "status": "success",
  "alert": {
    "id": "d7463946-8c6a-4a54-8a47-74cc98247c54",
    "name": "API error rate",
    "slug": "api-error-rate",
    "created_by": null,
    "created_by_api_key_id": "key_123",
    "url": "/team/acme/alert/api-error-rate"
  }
}

返回的alert对象包含告警字段中显示的每个字段；缩短的示例突出显示了创建身份和 URL。

查询负载

领域	类型	必填	精确合约
`querySql`	字符串	是的	非空、只读 SQL。包含写入或 DDL 的语句将被拒绝。
`timestampColumn`	字符串或 `null`	否	结果列用于将最新的行排在最前面。当省略或 `null` 时，Telemetry 查找公共时间戳列。
`queryId`	字符串或 `null`	否	用于归因的可选保存查询 ID。
`sourceUrl`	字符串或 `null`	否	用于返回源查询的可选相对 Telemetry URL。

该查询应返回一个有序时间序列，每行一个数值。告警评估器按时间戳列对行进行排序，可以选择跳过最新行，获取请求的点数，聚合 metric，并将 comparison 应用于 threshold。

资源管理器有效负载

资源管理器告警保留表名称和资源管理器状态：

{
  "name": "Checkout failures",
  "alert_type": "explorer",
  "payload": {
    "tableName": "checkout_events",
    "explorerState": {
      "graphType": "line",
      "aggregation": "count",
      "metric": null,
      "timeZone": "UTC",
      "timePreset": "24h",
      "granularity": "hour",
      "splitBy": [],
      "filters": [
        {
          "logic": "AND",
          "conditions": [
            { "field": "outcome", "operator": "=", "value": "failed" }
          ]
        }
      ],
      "selectedColumns": [],
      "orderBy": null,
      "orderDirection": "DESC",
      "limit": 200
    },
    "fields": [
      { "name": "outcome", "type": "Utf8" }
    ]
  },
  "metric": "count",
  "threshold": 10,
  "recipients": [
    { "type": "email", "recipient": "[email protected]" }
  ]
}

浏览器告警规则：

payload.tableName 必须是非空字符串。
payload.explorerState 必须是一个对象，并且指定时其 graphType 必须是 line。
splitBy 必须为空，因为告警评估一个系列。
aggregation 接受与顶级告警条件相同的聚合名称。非 count Explorer 聚合需要 explorerState.metric。
timePreset 接受 1h、6h、24h、7d、30d、90d 或 custom。
granularity 接受 auto、minute、hour、day、week 或 month。
fields 是可选的。当过滤器或数字字段选择取决于架构类型时，包括 { "name", "type" } 记录。
过滤器运算符为 =、!=、>、>=、<、<=、LIKE、NOT LIKE、 IS NULL 和 IS NOT NULL。

使用编码代理创建告警

代理可以创建语法上有效的告警，但仍然会监视错误的表、使用错误的单位或向错误的人员发送电子邮件。给它一个操作目标，并要求它在调用 POST /alert 之前检查和验证数据。

查询告警通常是代理构建的最简单的类型，因为它可以在保存之前运行确切的 SQL 到 POST /query。资源管理器告警对于标准计数和百分位数非常有用，因为 Telemetry 生成时间段并用零填充缺失的段。

代理人需要的信息

提供这些输入或告诉代理停止并询问它们：

应触发的条件及其阈值的单位
预期的表或事件名称（如果已知）
要监控的环境、服务、路线、帐户或其他人群
回溯、存储桶大小以及必须突破多少个已完成的存储桶
稳定的告警名称和别名
拥有响应的接收者
代理是否可以启用交付或仅应创建禁用的草稿

不要要求代理推断生产分页地址或从几个示例行中发明阈值。

提示编码代理

复制此提示并替换括号中的值：

Create a Telemetry alert for [operational condition] using https://api.telemetry.sh.

Use the API key already available as API_KEY. The expected event or table is
[table, or "unknown"]. Monitor [population] over [window and bucket size]. The
threshold is [value and unit], and the owner is [recipient]. Use the stable slug
[slug].

Before changing anything:
1. List tables and inspect the selected table's schema.
2. List existing alerts and look for the stable slug.
3. Build a single-series query and run the exact SQL through POST /query.
4. Show me the returned columns and representative rows, the proposed alert
   request, and how its bucket aggregation differs from its top-level aggregation.

Do not guess field names, units, thresholds, or recipients. Do not create a
duplicate or delete an alert. If the slug does not exist, create the alert with
enabled set to false. If it exists, propose a PATCH instead. Do not enable the
alert until I confirm the query, threshold, and recipient.

慎重选择两个聚合

资源管理器告警有两个聚合层。 explorerState.aggregation 计算每个时间桶内的值；顶层aggregation减少了last_n_data_points选择的最近的桶值。查询告警计算 SQL 中的每一行，并仅使用最近行的顶级聚合。

运营目标	每桶价值	顶级条件
服务器持续错误率	SQL 计算 `server_error_rate_pct`	对最后三个完成的桶进行平均并与 `5` 百分比进行比较
任何延迟峰值	资源管理器计算p95 `duration_ms`	最后五个完成的桶中的最大值超过 `850` 毫秒
心跳缺失	资源管理器对事件进行计数并用零填充缺失的存储桶	最后五个完成的桶的总和小于 `1` 事件

ignore_last_data_point: true 适用于这些时间段示例，因为最新的时间段可能不完整。对于仅返回一个完全计算行的查询，将其设置为 false；否则评估器将仅删除该行。

示例：持续的服务器错误率

此查询计算每个五分钟存储桶的一个错误率百分比，并将比率告警抑制在每个存储桶 100 个请求以下。然后，告警对三个最新完成的存储桶进行平均，并将该平均值与 5 百分比进行比较。

首先运行精确的 SQL 并检查结果：

ALERT_QUERY=$(cat <<'SQL'
SELECT
  date_bin(
    INTERVAL '5 minutes',
    timestamp_utc,
    TIMESTAMP '1970-01-01'
  ) AS time_bucket,
  CASE
    WHEN COUNT(*) >= 100 THEN
      100.0 * SUM(CASE WHEN status_code >= 500 THEN 1 ELSE 0 END)
        / NULLIF(COUNT(*), 0)
    ELSE 0.0
  END AS server_error_rate_pct
FROM http_request_completed
WHERE
  timestamp_utc >= now() - INTERVAL '35 minutes'
  AND environment = 'production'
GROUP BY time_bucket
ORDER BY time_bucket DESC;
SQL
)

curl -X POST https://api.telemetry.sh/query \
  -H "Authorization: $API_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg query "$ALERT_QUERY" \
    '{query: $query, realtime: true, json: true}')"

验证 time_bucket 是时间戳且 server_error_rate_pct 是数字后，创建禁用草稿：

curl -X POST https://api.telemetry.sh/alert \
  -H "Authorization: $API_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg query "$ALERT_QUERY" '{
    name: "Production API error rate",
    slug: "production-api-error-rate",
    description: "Investigate recent deploys and affected routes before escalating.",
    alert_type: "query",
    payload: {
      querySql: $query,
      timestampColumn: "time_bucket"
    },
    aggregation: "avg",
    metric: "server_error_rate_pct",
    last_n_data_points: 3,
    ignore_last_data_point: true,
    check_interval_minutes: 1,
    comparison: "greater_than",
    threshold: 5,
    recipients: [
      {type: "email", recipient: "[email protected]"}
    ],
    enabled: false
  }')"

在启用告警之前，将示例收件人替换为已审核的所有者。

示例：p95 延迟尖峰

此资源管理器告警计算每分钟内的 p95 请求持续时间。顶级 max 表示最近完成的五分钟之一必须超过 850 毫秒。

curl -X POST https://api.telemetry.sh/alert \
  -H "Authorization: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production API p95 latency",
    "slug": "production-api-p95-latency",
    "description": "Inspect slow routes, dependencies, and the latest deploy.",
    "alert_type": "explorer",
    "payload": {
      "tableName": "http_request_completed",
      "explorerState": {
        "graphType": "line",
        "aggregation": "p95",
        "metric": "duration_ms",
        "timeZone": "UTC",
        "timePreset": "1h",
        "granularity": "minute",
        "splitBy": [],
        "filters": [
          {
            "logic": "AND",
            "conditions": [
              {
                "field": "environment",
                "operator": "=",
                "value": "production"
              }
            ]
          }
        ],
        "selectedColumns": ["duration_ms"],
        "orderBy": null,
        "orderDirection": "DESC",
        "limit": 200
      },
      "fields": [
        { "name": "duration_ms", "type": "Float64" },
        { "name": "environment", "type": "Utf8" }
      ]
    },
    "aggregation": "max",
    "metric": "duration_ms",
    "last_n_data_points": 5,
    "ignore_last_data_point": true,
    "check_interval_minutes": 1,
    "comparison": "greater_than",
    "threshold": 850,
    "recipients": [
      { "type": "email", "recipient": "[email protected]" }
    ],
    "enabled": false
  }'

fields 类型必须来自架构响应。它们让 Explorer SQL 生成器正确序列化过滤器值并识别数字度量。

示例：心跳缺失

当缺席信号时，使用探索者计数。 Explorer 时间序列查询包含零值缺失存储桶，因此当最近五个已完成的一分钟存储桶的总和小于一个事件时，会触发此告警。

curl -X POST https://api.telemetry.sh/alert \
  -H "Authorization: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production worker heartbeat missing",
    "slug": "production-worker-heartbeat-missing",
    "description": "Check the worker process, queue, and ingestion path.",
    "alert_type": "explorer",
    "payload": {
      "tableName": "worker_heartbeat",
      "explorerState": {
        "graphType": "line",
        "aggregation": "count",
        "metric": null,
        "timeZone": "UTC",
        "timePreset": "1h",
        "granularity": "minute",
        "splitBy": [],
        "filters": [
          {
            "logic": "AND",
            "conditions": [
              {
                "field": "environment",
                "operator": "=",
                "value": "production"
              }
            ]
          }
        ],
        "selectedColumns": [],
        "orderBy": null,
        "orderDirection": "DESC",
        "limit": 200
      },
      "fields": [
        { "name": "environment", "type": "Utf8" }
      ]
    },
    "aggregation": "sum",
    "metric": "count",
    "last_n_data_points": 5,
    "ignore_last_data_point": true,
    "check_interval_minutes": 1,
    "comparison": "less_than",
    "threshold": 1,
    "recipients": [
      { "type": "email", "recipient": "[email protected]" }
    ],
    "enabled": false
  }'

不要使用仅对现有检测信号事件进行分组的查询：如果没有事件到达，该查询可能不会针对缺失的时间间隔返回任何行。 Explorer 时间序列形式在这里很有用，因为它生成条件所需的零值存储桶。

示例：审核并启用草稿

再次列出告警并检查保存的稳定段头记录。然后仅启用该告警：

curl "https://api.telemetry.sh/alert?page=1&pageSize=100" \
  -H "Authorization: $API_KEY"

curl -X PATCH https://api.telemetry.sh/alert \
  -H "Authorization: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "alertSlug": "production-api-error-rate",
    "enabled": true
  }'

如果稳定段已存在，请使用相同的 PATCH /alert 形状仅更改已审核的字段。如果通知传送应保持暂停，请在查询或收件人更改期间保留 enabled: false。

段塞归一化

对于创建和编辑请求，Telemetry 修剪并小写 slug，删除 ASCII 字母、数字、空格和 - 以外的字符，将空格转换为 -，折叠重复的 -，并修剪前导或尾随-。

如果 create 省略 slug，则 API 标准化 name。例如，"API Errors!!!" 变为 "api-errors"。标准化的 slug 必须至少包含一个字母或数字，并且在团队中必须是唯一的。重复返回 409 Conflict。

编辑告警

PATCH /alert 是部分更新。用 alertId 或 alertSlug 标识告警；所有其他省略的字段保持不变。

curl -X PATCH https://api.telemetry.sh/alert \
  -H "Authorization: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "alertSlug": "api-error-rate",
    "threshold": 0.08,
    "last_n_data_points": 5
  }'

当提供两个标识符时，它们必须解析为相同的告警。在 query 和 explorer 之间切换时，将 payload 与 alert_type 一起发送。

更新查询、条件、计划或收件人会清除 last_value 和 last_evaluated_at，将 status 返回到 inactive，并递增 evaluation_version。重命名、更改描述或 slug 以及切换 enabled 不会清除评估状态。

响应为 200 OK，其形状与创建的 { "status": "success", "alert": { ... } } 相同。

删除告警

DELETE /alert 接受 alertId、alertSlug 或两者。删除告警也会删除其评估历史记录。

curl -X DELETE https://api.telemetry.sh/alert \
  -H "Authorization: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "alertSlug": "api-error-rate" }'