tencentcloud-cls-alarm

Tencent Cloud CLS — アラーム管理

CLS アラームポリシー、通知グループ、ミュートシールド、アラーム実行ログの CRUD。

セットアップ： tencentcloud authentication を参照してください。環境変数の TENCENTCLOUD_REGION がデフォルトで使用されます。CLS アラームはリージョンごとに管理されます。

関連スキル： ログ内容の検索には tencentcloud-cls を使用します。

CLI（推奨）

このスキルには scripts/cls_alarm.py が含まれています。すべてのアラーム／通知／シールド操作をサブコマンドとして実行できます。

# $SKILL_DIR can point at another skill loaded this turn — anchor on our own
# script (re-run this at the top of every fresh-shell Bash block).
CLSA="$SKILL_DIR/scripts/cls_alarm.py"; [ -f "$CLSA" ] || CLSA=$(find /tmp -maxdepth 8 -path '*/skills/*/scripts/cls_alarm.py' 2>/dev/null | head -1)
[ -f "$CLSA" ] || { echo "tencentcloud-cls-alarm script not found (SKILL_DIR=$SKILL_DIR)" >&2; exit 1; }

python3 "$CLSA" alarms                          # list policies
python3 "$CLSA" alarm <alarm-id>                # full detail
python3 "$CLSA" alarm-disable <alarm-id>        # quick mute (Status=false)
python3 "$CLSA" alarm-enable  <alarm-id>
python3 "$CLSA" alarm-create --json /tmp/alarm.json --dry-run
python3 "$CLSA" alarm-modify <alarm-id> --condition '$1.cnt > 20'
python3 "$CLSA" alarm-delete <alarm-id> --yes   # destructive

python3 "$CLSA" notices                         # notice groups
python3 "$CLSA" notice <notice-id>

python3 "$CLSA" shields                         # mute rules
python3 "$CLSA" shield-create --notice-id <notice-id> --start $(date +%s) --end $(date -v+2H +%s) --type 1 --reason "deploy"

python3 "$CLSA" alarm-log --time 6h             # firing history

CLI で公開されていないスキーマフィールドが必要な場合は、以下の SDK の直接利用例を参照してください。

使用する場面

• 既存のアラームポリシーを確認する（名前や有効フラグで絞り込み）
• ログベースのアラームを新規作成する：CQL／SQL クエリ → トリガー条件 → 通知グループ
• しきい値、クエリ、期間、通知先を変更する
• インシデント中にすばやく有効化／無効化してミュートする
• 通知グループを管理する（通知先：ユーザー、グループ、Webhook、エスカレーション設定）
• デプロイ中にミュートする、時間制限付きのシールドルールを管理する
• アラーム実行ログを取得し、どのアラームがいつ発火したかを確認する

依存関係

pip install tencentcloud-sdk-python

クイックスタート

import os
import json
from tencentcloud.common import credential
from tencentcloud.cls.v20201016 import cls_client, models

cred = credential.EnvironmentVariableCredential().get_credential()
client = cls_client.ClsClient(cred, os.environ["TENCENTCLOUD_REGION"])

主な概念

オブジェクト	API メソッド	内容
アラームポリシー	DescribeAlarms / CreateAlarm / ModifyAlarm / DeleteAlarm	1 つ以上のトピックに対するクエリ＋条件＋通知グループ
通知グループ	DescribeAlarmNotices / CreateAlarmNotice / …	通知先（ユーザー／グループ／Webhook）＋エスカレーション
シールド	DescribeAlarmShields / CreateAlarmShield / …	通知グループを対象とした、時間制限付きのミュート
アラームログ	GetAlarmLog	発火履歴

ワークフロー

アラームポリシーの一覧表示

req = models.DescribeAlarmsRequest()
req.Limit = 100
# Optional filters: req.Filters = [{"Key": "name", "Values": ["DeepSeek"]}]
resp = client.DescribeAlarms(req)
for a in resp.Alarms:
    print(a.AlarmId, a.Name, "Enable=", a.Enable, "Status=", a.Status)

個別のアラームポリシーの詳細取得

req = models.DescribeAlarmsRequest()
req.Filters = [{"Key": "alarmId", "Values": ["<alarm-id>"]}]
resp = client.DescribeAlarms(req)
print(json.dumps(resp.Alarms[0]._serialize(), indent=2, ensure_ascii=False))

アラームの作成

req = models.CreateAlarmRequest()
req.Name = "OpenAI 5xx burst"
req.AlarmTargets = [{
    "TopicId": "<trace-topic-id>",
    "Query": "* | select count(*) as cnt where status_code >= 500",
    "Number": 1,
    "StartTimeOffset": -5,
    "EndTimeOffset": 0,
    "SyntaxRule": 1,             # 1 = CQL, 0 = Lucene
}]
req.MonitorTime = {"Type": "Period", "Time": 1}
req.Condition = "$1.cnt > 10"
req.AlarmPeriod = 5              # evaluate every 5 minutes
req.TriggerCount = 1             # fire after 1 consecutive match
req.AlarmLevel = 2               # 0=Notice, 1=Warning, 2=Critical
req.AlarmNoticeIds = ["<notice-id-a>", "<notice-id-b>"]
req.MonitorObjectType = 0
req.Enable = True

resp = client.CreateAlarm(req)
print("Created", resp.AlarmId)

すばやく有効化／無効化する

req = models.ModifyAlarmRequest()
req.AlarmId = "<alarm-id>"
req.Status = False               # mute (Status — runtime), keep Enable=True
client.ModifyAlarm(req)

Enable と Status は別のフィールドです。Enable=False はアラーム定義をアーカイブします。ミュートに使用する日常的なオン／オフ切り替えには Status=False を使います。

ペイロード全体を書き換えずにしきい値を変更する

req = models.ModifyAlarmRequest()
req.AlarmId = "<alarm-id>"
req.Condition = "$1.cnt > 20"
req.AlarmPeriod = 10
client.ModifyAlarm(req)

削除（破壊的操作）

# Confirm with the user first — there's no undo.
req = models.DeleteAlarmRequest()
req.AlarmId = "<alarm-id>"
client.DeleteAlarm(req)

通知グループの管理

# List
req = models.DescribeAlarmNoticesRequest()
req.Limit = 100
for n in client.DescribeAlarmNotices(req).AlarmNotices:
    print(n.AlarmNoticeId, n.Name, n.Type)

# Create
req = models.CreateAlarmNoticeRequest()
req.Name = "Ops on-call"
req.Type = "Trigger"             # Trigger | Recovery | All
req.NoticeReceivers = [{
    "ReceiverType": "Uin",
    "ReceiverIds": [123456],
    "ReceiverChannels": ["Email", "Sms"],
    "StartTime": "00:00:00",
    "EndTime": "23:59:59",
}]
req.WebCallbacks = [{
    "Url": "https://hooks.example.com/cls",
    "CallbackType": "WeCom",
    "Method": "POST",
}]
resp = client.CreateAlarmNotice(req)

時間制限付きシールド（デプロイ中のミュート）

import time
req = models.CreateAlarmShieldRequest()
req.AlarmNoticeId = "<notice-id>"
req.StartTime = int(time.time())
req.EndTime = int(time.time()) + 7200       # 2 hours
req.Type = 1                                # 1 = full shield, 2 = partial
req.Reason = "Deploy <git-sha>"
client.CreateAlarmShield(req)

アラームの発火履歴を確認する

req = models.GetAlarmLogRequest()
req.From = int((time.time() - 86400) * 1000)
req.To = int(time.time() * 1000)
req.Query = 'alarm_name:"OpenAI*"'
req.Limit = 100
resp = client.GetAlarmLog(req)
for line in resp.Results:
    print(line.Time, line.LogJson)

アラームの複製

類似したアラームを作成する最も手早い方法は、既存のアラームを読み取り、読み取り専用フィールドを削除して調整し、再作成することです。

import json
existing = client.DescribeAlarms(models.DescribeAlarmsRequest(Filters=[{"Key": "alarmId", "Values": ["<src-id>"]}])).Alarms[0]
payload = json.loads(json.dumps(existing._serialize()))      # deep clone
for k in ("AlarmId", "CreateTime", "UpdateTime"):
    payload.pop(k, None)
payload["Name"] = "OpenAI 5xx burst v2"
# ...edit other fields...
req = models.CreateAlarmRequest()
req.from_json_string(json.dumps(payload))
print(client.CreateAlarm(req).AlarmId)

重要な注意事項

• CreateAlarm／ModifyAlarm の前に、必ずペイロードをプレビューしてください（json.dumps(req._serialize(), indent=2)）。スキーマは厳密で、エラーメッセージも分かりにくいためです。
• 破壊的な操作（DeleteAlarm、DeleteAlarmNotice、DeleteAlarmShield）を実行する前に、チャットでユーザーの明示的な確認を得てください。
• Enable（アーカイブ済みかどうか）と Status（現在有効かどうか）は別のフィールドです。日常的なミュートには Status を使ってください。
• シールドルールは単一の AlarmNoticeId を対象とします。すべてのシールドを一括で一覧表示するには、すべての通知 ID を順に処理してください。
• デフォルトのリージョンは ap-hongkong です。必要に応じて cls_client.ClsClient(cred, "ap-singapore") で別のリージョンを指定してください。

コンソールへのリンク

• アラームコンソール：https://console.cloud.tencent.com/cls/alarm/list
• アラーム API リファレンス：https://www.tencentcloud.com/document/product/614/56473