警示

警示 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" }'