通过 Prometheus Rule 代码化管理告警规则

最佳实践

上传规则

1. 验证规则文件：检查规则文件的有效性，包括 PromQL 表达式语法、规则配置完整性等。

   promtool ruleup --dir /path/to/rules --check

   输出示例（验证通过）：

   Found 1 rule file(s) in directory: /path/to/rules
   
   File: /path/to/rules/prometheus-rules.yml
   Type: prometheus
   Validation: OK

   输出示例（验证失败）：

   Found 1 rule file(s) in directory: /path/to/rules
   
   File: /path/to/rules/prometheus-rules.yml
   Type: prometheus
   Validation errors:
     - group "system_resources": rule "HighCPUUsage": invalid PromQL expression: syntax error
     - group "application_services": rule "HighHTTPErrorRate": missing 'for' duration

   如果验证失败，命令会以退出码 1 退出。

2. 上传规则：验证通过后再上传规则到阿里云 Prometheus。

   promtool ruleup --dir /path/to/rules --upload --access-key-id YOUR_ACCESS_KEY_ID --access-key-secret YOUR_ACCESS_KEY_SECRET --user-id YOUR_USER_ID

   交互式确认：命令会显示上传配置信息并要求确认：

   === Upload Configuration ===
   User ID: 123456789
   Rule groups to upload: 5
     [1] system_resources (4 rules)
     [2] application_services (4 rules)
     [3] database (3 rules)
     [4] kubernetes (3 rules)
     [5] business_metrics (2 rules)
   Total rules to upload: 16
   Datasources: 2
     [1] Region: cn-hangzhou, Instance: rw-dfaa8e87409285b4b422b3c862ee
     [2] Region: cn-beijing, Instance: rw-abc123456789
   Workspace: will be automatically retrieved from instance
   
   Do you want to proceed with the upload? (yes/no): 

   输入 yes 或 y 继续，其他任何输入将取消上传。

   上传结果示例：

   === Upload Result ===
   Total uploads: 10 (rule groups × datasources)
   Success: 10, Failed: 0
   
   Datasource [1]: Region=cn-hangzhou, Instance=rw-dfaa8e87409285b4b422b3c862ee
     Group: system_resources, Request ID: 12345678-1234-1234-1234-123456789abc
       Uploaded rules: 4
         - HighCPUUsage (ID: rule-001, Status: enabled, Level: warning)
         - HighMemoryUsage (ID: rule-002, Status: enabled, Level: warning)
         - HighDiskUsage (ID: rule-003, Status: enabled, Level: critical)
         - HighDiskIO (ID: rule-004, Status: enabled, Level: warning)
   
   Upload completed! 10 datasource(s) succeeded.

删除阿里云 Prometheus 中的规则

从阿里云 Prometheus 实例中删除指定的规则组。删除前会进行与上传相同的验证。

promtool ruleup \
  --dir /path/to/rules \
  --delete \
  --access-key-id YOUR_ACCESS_KEY_ID \
  --access-key-secret YOUR_ACCESS_KEY_SECRET \
  --user-id YOUR_USER_ID

交互式确认：命令会显示删除配置信息并要求确认。

=== Delete Configuration ===
User ID: 123456789
Rule groups to delete: 5
  [1] system_resources
  [2] application_services
  [3] database
  [4] kubernetes
  [5] business_metrics
Datasources: 2
  [1] Region: cn-hangzhou, Instance: rw-dfaa8e87409285b4b422b3c862ee
  [2] Region: cn-beijing, Instance: rw-abc123456789

WARNING: This will delete all rules in the specified groups from the datasources!
Do you want to proceed with the deletion? (yes/no): 

删除结果示例：

=== Delete Result ===
Total deletions: 10 (rule groups × datasources)
Success: 10, Failed: 0

Datasource [1]: Region=cn-hangzhou, Instance=rw-dfaa8e87409285b4b422b3c862ee
  Group: system_resources deleted, Request ID: 12345678-1234-1234-1234-123456789abc
  All rules in group deleted successfully

Deletion completed! 10 deletion(s) succeeded.

查看规则文件基本信息

显示指定目录中所有规则文件的基本信息，包括文件类型、规则组数量、数据源数量等。

promtool ruleup --dir /path/to/rules

输出示例：

Found 2 rule file(s) in directory: /path/to/rules

File: /path/to/rules/prometheus-rules.yml
Type: prometheus
  PrometheusRule: 5 group(s), 2 datasource(s)
  Total rules: 15

File: /path/to/rules/alertmanager.yml
Type: alertmanager
  AlertManagerRule: 3 receiver(s)
  Route configured: yes

完整工作流程示例

1. 先验证规则再上传。

2. 使用版本控制：

   • 将规则文件纳入版本控制系统（如 Git）。

   • 在修改规则前先备份现有配置。

3. 分环境管理：

   • 为不同环境（开发、测试、生产）使用不同的规则文件目录。

   • 使用不同的数据源配置区分环境。

4. 规则命名规范：

   • 使用有意义的规则组名称，如 system_resources、application_services。

   • 告警名称应清晰描述告警内容，如 HighCPUUsage、ServiceInstanceDown。

5. 数据源配置：

   • 确保数据源配置中的 instance 和 regionId 准确无误。

   • 验证实例 ID 是否存在且可访问。

6. 批量操作前确认：

   • 上传或删除操作会影响多个数据源，操作前仔细检查配置信息。

   • 在生产环境操作前，先在测试环境验证。

# 1. 查看规则文件基本信息
promtool ruleup --dir ./example/rule

# 2. 验证规则文件
promtool ruleup --dir ./example/rule --check

# 3. 上传规则到阿里云（需要交互确认）
promtool ruleup \
  --dir ./example/rule \
  --upload \
  --access-key-id $ALIYUN_ACCESS_KEY_ID \
  --access-key-secret $ALIYUN_ACCESS_KEY_SECRET \
  --user-id $ALIYUN_USER_ID

# 4. 删除规则（需要交互确认）
promtool ruleup \
  --dir ./example/rule \
  --delete \
  --access-key-id $ALIYUN_ACCESS_KEY_ID \
  --access-key-secret $ALIYUN_ACCESS_KEY_SECRET \
  --user-id $ALIYUN_USER_ID

export ALIYUN_ACCESS_KEY_ID="your-access-key-id"
export ALIYUN_ACCESS_KEY_SECRET="your-access-key-secret"
export ALIYUN_USER_ID="your-user-id"

No rule files found in directory

• 原因：指定目录中没有找到规则文件。

• 解决：检查目录路径是否正确，确保目录中包含有效的 YAML 规则文件。

No PrometheusRule file found

• 原因：目录中没有找到 PrometheusRule 类型的文件。

• 解决：确保至少有一个文件包含 PrometheusRule 配置。

No rule groups found in PrometheusRule

• 原因：PrometheusRule 文件中没有配置规则组。

• 解决：在规则文件中添加至少一个 groups 配置。

No datasources configured in PrometheusRule

• 原因：规则文件中没有配置数据源。

• 解决：在规则文件顶部添加 datasources 配置。

Datasource [N] missing 'instance' field

• 原因：数据源配置中缺少 instance 字段或值为空。

• 解决：为每个数据源配置有效的 instance 值。

Datasource [N] missing 'regionId' field

• 原因：数据源配置中缺少 regionId 字段或值为空。

• 解决：为每个数据源配置有效的 regionId 值。

Rule validation failed

• 原因：规则验证失败，可能是 PromQL 表达式语法错误、缺少必需字段等。

• 解决：使用 --check 参数查看详细的验证错误信息，修复后重试。

--access-key-id is required when --upload is set

• 原因：使用 --upload 时未提供 Access Key ID。

• 解决：添加 --access-key-id 参数。

--user-id is required when --upload is set

• 原因：使用 --upload 时未提供 User ID。

• 解决：添加 --user-id 参数。