mcpField
C
cx-alerts

cx-alerts

github.com/coralogix云与 DevOps2153.7k 次安装今天更新
代码仓库

关于 cx-alerts

cx-alerts 是通过 `cx alerts` 命令管理 Coralogix 告警定义和抑制规则的技能，涵盖告警创建、排查与维护，并强调优先级选择和创建后验证。

主要功能

  1. 01列出、查看、创建和删除告警
  2. 02启用或停用告警定义
  3. 03查询告警事件和统计数据
  4. 04管理告警抑制规则
  5. 05使用 JSON 或 TOON 输出
  6. 06同时面向多个配置文件

适用场景

  1. 01创建日志、指标或链路追踪告警
  2. 02查找并检查触发中的告警
  3. 03在维护期间静默告警
  4. 04查看告警事件统计

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/coralogix/cx-cli --skill cx-alerts

安装后在 Claude Code 中输入/cx-alerts确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
alert-schemas.md
dataprime-reference.md
logs-querying.md
promql-guidelines.md
spans-querying.md

详细介绍

告警管理技能

使用此技能通过 cx alerts CLI 命令列出、检查、创建、删除、启用和停用 Coralogix 告警定义。

CLI 命令

命令用途关键标志
cx alerts list列出所有告警定义--name <filter>
cx alerts get <id>按 ID 获取单个告警定义-
cx alerts create根据 JSON 定义创建告警--from-file <path>（默认：标准输入）
cx alerts delete <id>删除告警-
cx alerts enable <id>启用告警-
cx alerts disable <id>停用告警-
cx alerts events列出事件；筛选时使用限定告警版本的端点--alert-version-id、--start、--end
cx alerts event-stats获取告警事件统计信息-
cx alerts suppression-rules list列出抑制规则-
cx alerts suppression-rules get <id>获取抑制规则-
cx alerts suppression-rules create创建抑制规则--from-file <path>
cx alerts suppression-rules update更新抑制规则--from-file <path>
cx alerts suppression-rules delete <id>删除抑制规则-

**输出格式：**在 list、get 和 create 命令后附加 -o json 或 -o toon，以输出机器可读格式。

**多配置文件：**使用 -p <profile>（可重复指定）同时针对多个配置文件执行操作。

告警类型参考

Coralogix 支持 12 种告警类型：

类型枚举名称描述
ALERT_DEF_TYPE_LOGS_IMMEDIATE日志即时告警每当日志条目匹配时触发
ALERT_DEF_TYPE_LOGS_THRESHOLD日志阈值告警在某个时间窗口内日志数量超过阈值时触发
ALERT_DEF_TYPE_LOGS_ANOMALY日志异常告警基于 ML 的日志量异常检测
ALERT_DEF_TYPE_LOGS_RATIO_THRESHOLD日志比率阈值告警根据两个日志查询之间的比率触发
ALERT_DEF_TYPE_LOGS_NEW_VALUE日志新值告警字段中出现新值时触发
ALERT_DEF_TYPE_LOGS_UNIQUE_COUNT日志唯一值计数告警达到唯一值计数阈值时触发
ALERT_DEF_TYPE_LOGS_TIME_RELATIVE_THRESHOLD日志时间相对阈值告警比较当前时间窗口与过去的时间窗口
ALERT_DEF_TYPE_METRIC_THRESHOLD指标阈值告警PromQL 表达式越过阈值时触发
ALERT_DEF_TYPE_METRIC_ANOMALY指标异常告警基于 ML 的指标异常检测
ALERT_DEF_TYPE_TRACING_IMMEDIATE追踪即时告警每当 Span 匹配时触发
ALERT_DEF_TYPE_TRACING_THRESHOLD追踪阈值告警Span 数量超过阈值时触发
ALERT_DEF_TYPE_FLOW流程告警基于序列的告警，可组合多个条件

优先级

创建告警时，务必询问用户要使用何种优先级：

优先级使用场景
P1严重——立即通知值班人员
P2高——需要在一小时内处理
P3中——在工作时间内调查
P4低——信息提示，方便时查看
P5信息——仅用于日志记录或跟踪

创建工作流

  1. 询问用户要针对什么内容设置告警（日志、指标或追踪）
  2. 询问优先级（P1–P5）
  3. 使用 alertDefProperties 构建 JSON 负载——采用 API 线格式（所有枚举值请参见 references/alert-schemas.md）
  4. **提示：**使用 cx alerts get <existing-id> -o json 获取可用模板，修改后通过管道传入 create 命令
  5. 使用以下命令创建：echo '<json>' | cx alerts create 或 cx alerts create --from-file alert.json
  6. 使用 cx alerts list --name "<alert name>" 验证

重要结构说明：type 字段是一个字符串枚举（例如 "ALERT_DEF_TYPE_LOGS_THRESHOLD"），告警类型配置（例如 "logsThreshold": {...}）是同级字段，而不是嵌套在 type 内。

示例：日志阈值告警
{
  "alertDefProperties": {
    "name": "High Error Rate",
    "description": "Alert when error logs exceed threshold",
    "priority": "ALERT_DEF_PRIORITY_P2",
    "type": "ALERT_DEF_TYPE_LOGS_THRESHOLD",
    "enabled": true,
    "logsThreshold": {
      "logsFilter": {
        "simpleFilter": {
          "luceneQuery": "severity:ERROR",
          "labelFilters": {
            "applicationName": [
              { "operation": "LOG_FILTER_OPERATION_TYPE_IS_OR_UNSPECIFIED", "value": "my-app" }
            ]
          }
        }
      },
      "rules": [{
        "condition": {
          "conditionType": "LOGS_THRESHOLD_CONDITION_TYPE_MORE_THAN_OR_UNSPECIFIED",
          "threshold": 100,
          "timeWindow": {
            "logsTimeWindowSpecificValue": "LOGS_TIME_WINDOW_VALUE_MINUTES_5_OR_UNSPECIFIED"
          }
        }
      }]
    }
  }
}
示例：指标阈值告警
{
  "alertDefProperties": {
    "name": "CPU Usage Critical",
    "priority": "ALERT_DEF_PRIORITY_P1",
    "type": "ALERT_DEF_TYPE_METRIC_THRESHOLD",
    "enabled": true,
    "metricThreshold": {
      "metricFilter": { "promql": "avg(cpu_usage_percent)" },
      "rules": [{
        "condition": {
          "conditionType": "METRIC_THRESHOLD_CONDITION_TYPE_MORE_THAN_OR_UNSPECIFIED",
          "threshold": 90,
          "ofTheLast": { "dynamicDuration": "5m" },
          "forOverPct": 100
        }
      }]
    }
  }
}
示例：日志即时告警
{
  "alertDefProperties": {
    "name": "OOM Killer Detected",
    "description": "Alert immediately when OOM killer runs",
    "priority": "ALERT_DEF_PRIORITY_P1",
    "type": "ALERT_DEF_TYPE_LOGS_IMMEDIATE_OR_UNSPECIFIED",
    "enabled": true,
    "logsImmediate": {
      "logsFilter": {
        "simpleFilter": {
          "luceneQuery": "\"Out of memory\" OR \"OOM\"",
          "labelFilters": {}
        }
      }
    }
  }
}

调查工作流

查找触发中的告警
# List all alerts and look for ALERTING status
cx alerts list -o json | jq '.[] | select(.status == "ALERTING")'

# Filter by name
cx alerts list --name "error"
检查特定告警
cx alerts get <alert-id>
cx alerts get <alert-id> -o json
禁用嘈杂的告警（临时静音）
cx alerts disable <alert-id>
# Later, re-enable:
cx alerts enable <alert-id>

抑制规则

管理告警抑制规则，在维护时段或已知的嘈杂时段静音告警。

命令用途
cx alerts suppression-rules list列出所有抑制规则
cx alerts suppression-rules get <id>按 ID 获取抑制规则
cx alerts suppression-rules create --from-file创建抑制规则
cx alerts suppression-rules update --from-file更新抑制规则
cx alerts suppression-rules delete <id>删除抑制规则

一条规则有两个 ID：unique_identifier 是稳定且可寻址的 ID（用于 get/update/delete），而 id 是规则版本 ID，每次更新都会变化。

请求正文结构

create 和 update 接收封装在 alertSchedulerRule 对象中的规则。

{
  "alertSchedulerRule": {
    "uniqueIdentifier": "<rule-id>",
    "name": "maintenance-window",
    "filter": { "whatExpression": "source logs | filter true", "alertUniqueIds": { "value": [] } },
    "schedule": {
      "scheduleOperation": "SCHEDULE_OPERATION_MUTE",
      "oneTime": { "timeframe": { "startTime": "2026-08-10T19:30:00", "endTime": "2026-08-10T20:30:00", "timezone": "UTC" } }
    }
  }
}

# List suppression rules - the ID column is the unique_identifier
cx alerts suppression-rules list -o json

# Inspect one rule
cx alerts suppression-rules get <unique-identifier> -o json

# Create from a definition file (must use the alertSchedulerRule wrapper)
cx alerts suppression-rules create --from-file suppression-rule.json

# Delete
cx alerts suppression-rules delete <unique-identifier> --yes

关键原则

  • 始终询问优先级（P1–P5）再创建告警——绝不要自行假设
  • 对告警数量较多的大型账户使用 --name 筛选条件
  • 使用 -o json 和 jq 进行筛选和转换
  • 以编程方式构造告警时，使用 --from-file - 从标准输入传入 JSON
  • 创建后进行验证——创建后始终列出或获取告警以确认
  • 禁用而非删除——为便于审计，应优先禁用告警，而不是删除
  • 链接到特定告警——cx alerts list 只会打印一个“View in Coralogix”链接，指向告警概览页面，而非单个告警的链接。若要将用户链接到某一条特定告警，请构造 <base>/alerts/<alert_id>；其中 <base> 是本次会话中任意 cx alerts 命令打印的 View in Coralogix: <base>/... 行里出现的控制台 URL——切勿自行编造 <base>。

更多资源

参考文件
  • references/alert-schemas.md - 全部 12 种告警类型的完整 JSON schema 参考：字段名称、枚举值（条件类型、时间窗口、筛选操作）、常见子对象（日志筛选器、追踪筛选器、通知组、活动计划）以及重要注意事项
  • references/dataprime-reference.md - 基于日志和基于跨度的告警条件所用 DataPrime 查询语言参考（筛选语法、运算符、严重性值）
  • references/logs-querying.md - 日志数据模型、字段发现以及用于构建日志告警条件的查询模式
  • references/promql-guidelines.md - 基于指标的告警条件所用 PromQL 参考（计数器、仪表、直方图、阈值模式）
  • references/spans-querying.md - 跨度数据模型、持续时间单位以及用于构建追踪告警条件的查询模式
相关技能
  • cx-cases - 对将告警事件归类为调查的案例进行分流
  • cx-slos - 错误预算消耗会触发告警的 SLO 定义
  • cx-observability-setup - 设置告警的通知路由和 webhook 集成
  • cx-telemetry-querying - 调查触发中告警背后的遥测数据

评论

支持 Markdown