Aviator 表达式指南

概述

Aviator 是一个高性能的 Java 表达式引擎，1Duty 使用它来对告警 JSON 数据进行动态匹配、计算和修改。通过 Aviator 表达式，您可以编写灵活的规则来控制告警的降噪、聚合、分派和数据预处理流程。

Aviator 表达式在 1Duty 中的核心特性：

• 安全沙箱 - 禁止访问 Java 类，循环上限 100 次，执行超时 5 秒
• 字段直接引用 - 直接使用字段名引用告警 JSON 中的数据
• JSON 原地修改 - 通过 json.xxx = yyy 语法可以直接修改告警 JSON，修改会传递到外部
• 丰富的内置函数 - 正则匹配/提取/替换、字符串操作、HTML 清理等

在 1Duty 中的使用场景

Aviator 表达式在以下功能中使用，每个场景对表达式的返回值要求不同：

基本语法

引用字段

系统接收到告警后，会将 JSON 数据的所有字段展开到表达式上下文中。你可以直接使用字段名来引用告警中的任意字段，嵌套字段用点号访问。

{
  "title": "CPU 使用率过高",
  "severity": "CRITICAL",
  "source": "prometheus",
  "host": "web-server-01",
  "description": "CPU usage is 95%, threshold 80%",
  "labels": {
    "env": "production",
    "region": "cn-east-1",
    "team": "infra"
  },
  "value": 95.2,
  "status": "firing"
}

比较运算符

逻辑运算符

字符串函数

正则表达式函数

1Duty 提供了三个自定义正则函数，底层使用 RE2/J 引擎确保安全（不会因正则回溯导致性能问题）：

其他内置函数

nil 安全判断

当引用的字段可能不存在时，建议先做 nil 判断，避免执行错误：

## 安全判断字段是否存在
labels != nil && labels.env == 'production'

## 结合默认值（三元表达式）
severity != nil ? severity : 'UNKNOWN'

JSON 原地修改（核心特性）

这是 1Duty 中 Aviator 表达式最强大的特性之一。在数据预处理场景中，Aviator 脚本可以通过 json.xxx = yyy 语法直接修改告警的 JSON 数据，修改会传递到外部，后续的告警处理流程将使用修改后的数据。

工作原理

• 读取字段 - 直接使用字段名，如 title、severity、labels.env
• 修改字段 - 使用 json.字段名 = 新值，如 json.title = '[P0] ' + title
• 返回结果 - 脚本最后需要 return json; 返回修改后的 JSON 对象

这意味着你可以在 Webhook 接收到告警后、系统处理之前，对告警数据进行任意修改和增强。

数据预处理示例

示例 1：给标题添加前缀

json.title = '[P0] ' + title;
return json;

示例 2：从描述中提取错误码并添加为新字段

let code = regex_extract(description, 'code: (\d+)');
if code != nil {
  json.error_code = code;
}
return json;

示例 3：根据标题关键词自动设置严重级别

if string.contains(title, 'OOM') || string.contains(title, '宕机') {
  json.severity = 'CRITICAL';
} elsif string.contains(title, '超时') {
  json.severity = 'WARNING';
}
return json;

示例 4：清理 HTML 描述并提取关键信息

json.description = html2text(description);
let ip = regex_extract(description, '(\d+\.\d+\.\d+\.\d+)');
if ip != nil {
  json.source_ip = ip;
}
return json;

示例 5：修改嵌套字段

if labels != nil && labels.env == 'staging' {
  json.title = '[Staging] ' + title;
}
return json;

各场景完整示例

场景一：排除规则 / 静默策略 / 自动关闭（返回 true/false）

这些场景中，表达式返回 true 表示命中规则，返回 false 表示不命中。

## 排除 INFO 级别的告警
severity == 'INFO'

## 排除测试环境的告警
labels != nil && labels.env == 'test'

## 静默包含特定关键词的告警
string.contains(title, '健康检查') || string.contains(title, 'heartbeat')

## 自动关闭已恢复的告警
status == 'resolved' || status == 'ok'

## 组合条件：排除低级别 + 特定来源
severity == 'INFO' && source == 'prometheus' && value < 50

## 使用正则匹配
regex_match(title, '(?i).*test.*|.*debug.*')

场景二：聚合规则（返回字符串作为聚合 Key）

表达式返回字符串，系统对结果取 MD5 后作为聚合 Key。相同 Key 的告警会被合并到同一事件。

## 按标题聚合（等效于智能聚合）
title

## 按标题 + 主机名聚合
title + '_' + host

## 按来源 + 级别聚合
source + '_' + severity

## 使用正则提取关键信息聚合
regex_extract(title, '(\S+)\s+') + '_' + severity

场景三：分派策略条件（返回 true/false）

在分派策略中，Aviator 条件用于判断告警是否匹配该策略。

## 按严重级别分派
severity == 'CRITICAL'

## 按来源 + 标签分派
source == 'prometheus' && labels != nil && labels.team == 'infra'

## 按标题关键词分派到不同团队
string.contains(title, '数据库') || string.contains(title, 'MySQL')

场景四：主动探测条件（返回 true/false）

在主动探测中，可用变量包括 status_code、response_time、body_size、body_text 等。

## 状态码不是 200 或响应时间超过 3 秒
status_code != 200 || response_time > 3000

## 响应体包含错误关键词
string.contains(body_text, 'error') || string.contains(body_text, 'failed')

## 状态码正常但响应时间过长
status_code == 200 && response_time > 5000

安全限制

为了保障系统安全和稳定，1Duty 对 Aviator 表达式施加了以下限制：

常见错误