アラート
アラート 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-writePOST /alert,PATCH /alert、そしてDELETE /alert必要とするwriteまたはread-and-write
アラートのリスト
GET /alert API キーのチームのアラートを、次の順序で返します。 updated_at DESC.
サポートされているクエリパラメータ:
| フィールド | タイプ | 必須 | 正確な契約 | デフォルト |
|---|---|---|---|---|
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 つ 1, 3, 5, 10, 20, 50、または 100. |
ignore_last_data_point |
ブール値 | はい | 不完全なタイム バケットを表す可能性がある最新の結果行をスキップするかどうか。 |
check_interval_minutes |
整数 | はい | の 1 つ 1, 60、または 1440. |
comparison |
文字列 | はい | greater_than, less_than, greater_than_or_equal、または less_than_or_equal. |
threshold |
数値 | はい | 有限比較しきい値。 JSON のような文字列 "10" 拒否されます。 |
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 1 つのアラートを作成して返します 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 オブジェクトには、以下に示すすべてのフィールドが含まれます。 アラートフィールド;短縮された例では、作成 ID と URL が強調表示されています。
クエリペイロード
| フィールド | タイプ | 必須 | 正確な契約 |
|---|---|---|---|
querySql |
文字列 | はい | 空ではない、読み取り専用の SQL。書き込みまたは DDL を含むステートメントは拒否されます。 |
timestampColumn |
文字列または null |
いいえ | 行を新しいものから順に並べるのに使用される結果列。省略した場合、または null, Telemetry は、共通のタイムスタンプ列を検索します。 |
queryId |
文字列または null |
いいえ | アトリビューション用のオプションの保存されたクエリ ID。 |
sourceUrl |
文字列または null |
いいえ | ソース クエリに戻るためのオプションの相対 Telemetry URL。 |
クエリは、行ごとに 1 つの数値を含む 1 つの順序付けされた時系列を返す必要があります。アラート エバリュエーターは、タイムスタンプ列によって行を順序付けし、オプションで最新の行をスキップし、要求されたポイント数を取得して集計します。 metric、および適用されます comparison に threshold.
エクスプローラーのペイロード
Explorer アラートは、テーブル名と Explorer の状態を保持します。
{
"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アラートは 1 つのシリーズを評価するため、空にする必要があります。aggregation最上位のアラート条件と同じ集計名を受け入れます。非countExplorer の集約には次のものが必要です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 保存する前に。 Explorer アラートは、Telemetry が時間バケットを生成し、不足しているバケットをゼロで埋めるため、標準的なカウントとパーセンタイルに役立ちます。
エージェントが必要とする情報
次の入力を行うか、エージェントに停止して入力を求めるよう伝えます。
- トリガーする条件とそのしきい値の単位
- 予想されるテーブル名またはイベント名 (わかっている場合)
- 監視する環境、サービス、ルート、アカウント、またはその他の人口
- ルックバック、バケット サイズ、および違反する必要がある完了したバケットの数
- 安定したアラート名とスラッグ
- 応答を所有する受信者
- エージェントが配信を有効にしてもよいか、それとも無効なドラフトのみを作成すべきか
実稼働ページング アドレスを推測したり、いくつかのサンプル行からしきい値を作成したりするようエージェントに依頼しないでください。
推奨されるリクエストシーケンス
- 電話をかける
GET /tables正規のテーブル名を見つけます。 - 電話をかける
GET /tables/<table>/schema互換性のある型で実際に存在するフィールドのみを使用します。 - 電話をかける
GET /alert?page=1&pageSize=100そして目的の安定したスラッグを探します。存在する場合は使用しますPATCH /alert;重複を作成しないでください。 - クエリ アラートの場合は、提案されたとおりの SQL を実行します。
POST /query。 1 つのタイムスタンプ列、1 つの数値メトリック列、予期される単位、および最新のものから順に返されることを確認します。 - 新しいアラートを作成するには
enabled: false。返されたアラート、クエリ、しきい値、ポイント ウィンドウ、および受信者を確認します。 - レビュー済みアラートを有効にする
PATCH /alert。アラートを有効にすると、状態遷移後に実際の電子メールが配信される可能性があるため、これは副作用のあるステップとして扱ってください。
アラートの更新/挿入エンドポイントはありません。繰り返し POST /alert 既存のスラッグが戻る場合 409 Conflict;行儀の良いエージェントは最初にリストを作成し、既存のアラートに意図的にパッチを当てます。
検出呼び出しは次のとおりです。
curl "https://api.telemetry.sh/tables?page=1&pageSize=100" \
-H "Authorization: $API_KEY"
curl https://api.telemetry.sh/tables/http_request_completed/schema \
-H "Authorization: $API_KEY"
curl "https://api.telemetry.sh/alert?page=1&pageSize=100" \
-H "Authorization: $API_KEY"
コーディングエージェントの入力を求めるプロンプト
このプロンプトをコピーし、括弧で囲まれた値を置き換えます。
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.
両方の集計を慎重に選択する
Explorer アラートには 2 つの集約レイヤーがあります。 explorerState.aggregation 各時間バケット内の値を計算します。トップレベルの aggregation によって選択された最近のバケット値を減らします。 last_n_data_points。クエリ アラートは、SQL の各行を計算し、最近の行にわたる最上位の集計のみを使用します。
| 運用目標 | バケットあたりの価値 | 最上位の状態 |
|---|---|---|
| 持続的なサーバーエラー率 | SQL の計算 server_error_rate_pct |
完了した直近3バケットの平均を取り、次の値と比較: 5 パーセント |
| 遅延の急増 | Explorer は p95 を計算します duration_ms |
最後に完了した 5 つのバケットの最大値が次を超えています 850 ミリ秒 |
| 心拍の欠落 | Explorer はイベントをカウントし、不足しているバケットをゼロで埋めます | 最後に完了した 5 つのバケットの合計が次の値未満です 1 イベント |
ignore_last_data_point: true 最新のバケットは不完全である可能性があるため、これらの時間バケットの例には適切です。に設定します false 完全に計算された行を 1 つだけ返すクエリの場合。それ以外の場合、エバリュエーターはその行のみを削除します。
例: 継続的なサーバーエラー率
このクエリは、5 分間のバケットごとに 1 つのエラー率パーセンテージを計算し、バケットあたり 100 リクエスト未満のレート アラートを抑制します。次に、アラートは、完了した最新の 3 つのバケットを平均し、その平均を次のバケットと比較します。 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 遅延スパイク
この Explorer アラートは、1 分ごとに p95 リクエストの継続時間を計算します。トップレベル max 最近完了した 5 分のうち 1 分が次の時間を超える必要があることを意味します 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 カウントを使用します。 Explorer の時系列クエリにはゼロ値の欠落バケットが含まれるため、このアラートは、完了した最後の 5 つの 1 分バケットの合計が 1 イベント未満になるとトリガーされます。
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"。正規化されたスラッグには少なくとも 1 つの文字または数字が含まれている必要があり、チーム内で一意である必要があります。重複が返される 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
}'
両方の識別子が指定された場合は、同じアラートに解決される必要があります。送信 payload 一緒に alert_type 間を切り替えるとき query そして explorer.
クエリ、条件、スケジュール、または受信者のクリアの更新 last_value そして last_evaluated_at、戻ります status に inactive、および増分 evaluation_version。名前の変更、説明またはスラッグの変更、および切り替え 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" }'
成功した応答:
{
"status": "success",
"deleted_alert": {
"id": "d7463946-8c6a-4a54-8a47-74cc98247c54",
"name": "API error rate",
"slug": "api-error-rate",
"description": "Notify the API on-call rotation",
"url": "/team/acme/alert/api-error-rate"
}
}
よくあるエラー
400 Bad Request無効な JSON、無効なアラート フィールド、互換性のないペイロード、サポートされていないページネーション、または突然変異に使用された読み取りスコープのキーの場合401 UnauthorizedAPI キーが見つからない、または無効な場合404 Not Found(アラート識別子がAPIキーのチームに属していない場合)409 Conflict(正規化されたスラッグがチーム内にすでに存在する場合)429 Too Many Requests(APIキーがゲートウェイのレート制限を超えた場合)500 Internal Server Error有効な永続化操作が失敗したとき
アラート定義により電子メールを生成できます。テスト中に一時受信者を使用し、合成データで条件を検証し、検証後にテスト アラートを無効化または削除します。参照 アラート 評価セマンティクスと アラートの配信とトラブルシューティング 配送のご案内のため。