除了在SLS控制台创建告警监控以外,SLS的SDK也提供了对告警的管理功能,其中主要包括了初始化告警资源,告警监控规则的增删改查,告警资源的增删改查等功能。
文中的介绍需要使用到两个SDK,分别为:
告警资源初始化SDK: github.com/aliyun/alibaba-cloud-sdk-go/sdk
告警规则/策略管理SDK: github.com/aliyun/aliyun-log-go-sdk
SLS告警SDK主要包括三部分内容:
- 告警资源初始化
- 告警监控规则的管理
- 告警策略的管理,包括用户/用户组/通知渠道等
告警资源初始化
告警资源主要包括两部分:
- 用户级别下的告警中心资源
- Project下的告警历史资源
用户级别的告警中心资源
- 中心Project:名称为sls-alert-{uid}-{region},其中uid为阿里云主账号,region为用户指定的中心Project地域
- 中心Logstore:名称为internal-alert-center-log,该logstore挂载在中心Project下,为免费Logstore,主要用来存储告警在执行过程中的执行历史和诊断信息。
- 内置告警仪表盘:包括全局告警排障中心,全局告警链路中心,全局告警规则中心,开放告警中心。
- 每个阿里云主账号只需要初始化一次即可,会同时生成中心Project,中心Logstore和告警仪表盘。
Project下告警历史资源
- 告警监控规则必须挂载在SLS的某个Project下,在某个Project下创建告警规则之前,需要先初始化Project下的告警资源
- 告警历史统计Logstore:名称为internal-alert-history,该Logstore为免费Logstore,存储了当前Project下所有告警规则的评估历史记录,包括每次评估的状态和告警触发状态。
- 内置告警历史统计仪表盘:名称为internal-alert-analysis,仪表盘为内置仪表盘,展示了告警监控规则的执行历史成功率等。
- 每个Project只需要初始化一次即可。
告警资源初始化SDK
安装SDK,以Go为例
使用 go get 下载安装 SDK
$ go get -u github.com/aliyun/alibaba-cloud-sdk-go/sdk
创建客户端
package main import sls_sdk "github.com/aliyun/alibaba-cloud-sdk-go/services/sls" func main() { client, err := sls_sdk.NewClientWithAccessKey("REGION_ID", "ACCESS_KEY_ID", "ACCESS_KEY_SECRET") if err != nil { // Handle exceptions panic(err) } ... }
初始化中心告警资源
request := sls_sdk.CreateInitUserAlertResourceRequest() request.Domain = "sls.aliyuncs.com" request.Region = "cn-huhehaote" request.App = "none" request.Language = "cn" response, err := client.InitUserAlertResource(request) if err != nil { log.Println(fmt.Sprintf("set alert %s", err.Error())) panic(fmt.Errorf("set alert center resource err %v", err)) } responseBytes, err := json.Marshal(response) log.Println(string(responseBytes), err) ...
其中App参数固定为"none",Region为指定的SLS地域列表,具体可以参考服务入口。Language为cn或者en,会创建相应语言版本的仪表盘。
调用InitUserAlertResource接口需要有相应的权限,如果是子账号调用可以参考权限配置。
该接口调用成功后,会在阿里云主账号下创建相应的中心Project,中心Logstore和仪表盘。参数说明参考链接。
初始化Project告警资源
request := sls_sdk.CreateInitProjectAlertResourceRequest() request.Domain = "sls.aliyuncs.com" request.Region = "cn-beijing" request.ProjectName = "test-my-project-xxx" response, err := client.InitProjectAlertResource(request) if err != nil { log.Println(fmt.Sprintf("set alert %s", err.Error())) panic(fmt.Errorf("set alert project resource err %v", err)) } responseBytes, err := json.Marshal(response) log.Println(string(responseBytes), err)
其中ProjectName为告警监控规则归属的Project,Region为告警Project所属地域,具体可以参考服务入口。
接口调用成功后,会在Project下创建出internal-alert-history和告警历史统计仪表盘。参数说明参考链接。
告警监控规则管理
以Go SDK为例,详情可以查看Go SDK 概述。
安装SDK
注意,这里的sdk与告警资源初始化SDK不同
$ go get -u github.com/aliyun/aliyun-log-go-sdk
初始化client
package main import ( "fmt" sls "github.com/aliyun/aliyun-log-go-sdk" "github.com/gogo/protobuf/proto" "math/rand" "time" ) func main() { // 日志服务的服务入口。更多信息,请参见服务入口。 // 此处以杭州为例,其它地域请根据实际情况填写。 Endpoint := "cn-hangzhou.log.aliyuncs.com" // 配置AccessKey、服务入口、Project名称、Logstore名称等相关信息。 // 阿里云访问密钥AccessKey。更多信息,请参见访问密钥。阿里云账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM用户进行API访问或日常运维。 AccessKeyId := "your_access_key_id" AccessKeySecret := "your_access_key_secret" // RAM用户角色的临时安全令牌。此处取值为空,表示不使用临时安全令牌。更多信息,请参见授权用户角色。 SecurityToken := "" // 创建日志服务Client。 client := sls.CreateNormalInterface(Endpoint, AccessKeyId, AccessKeySecret, SecurityToken) .... }
告警监控规则相关
创建告警监控规则
告警监控规则主要包括查询语句,触发条件,告警策略配置等,具体字段说明见后文告警监控规则字段说明。
projectName := "test-my-project" alert := &sls.Alert{ Name: "test-alert-by-sdk", State: "Enabled", DisplayName: "AlertTest By GO SDK ", Description: "Description for alert by go sdk", Schedule: &sls.Schedule{ Type: sls.ScheduleTypeFixedRate, Interval: "1m", }, Configuration: &sls.AlertConfiguration{ Version: "2.0", Type: "default", GroupConfiguration: sls.GroupConfiguration{ Type: sls.GroupTypeNoGroup, }, QueryList: []*sls.AlertQuery{ { Query: "* | select count(1) as count", Start: "-120s", End: "now", TimeSpanType: "Custom", StoreType: sls.StoreTypeLog, Store: "test-alert", Region: "cn-hangzhou", Project: projectName, }, }, Dashboard: "test-dashboard", MuteUntil: time.Now().Unix(), Threshold: 1, NoDataFire: true, NoDataSeverity: sls.Medium, SendResolved: true, Annotations: []*sls.Tag{ &sls.Tag{ Key: "title", Value: "this is title", }, &sls.Tag{ Key: "desc", Value: "this is desc, count is ${count}", }, }, Labels: []*sls.Tag{ &sls.Tag{ Key: "env", Value: "test", }, }, SeverityConfigurations: []*sls.SeverityConfiguration{ &sls.SeverityConfiguration{ Severity: sls.Critical, EvalCondition: sls.ConditionConfiguration{ Condition: "count > 99", }, }, &sls.SeverityConfiguration{ Severity: sls.High, EvalCondition: sls.ConditionConfiguration{ Condition: "count > 80", }, }, &sls.SeverityConfiguration{ Severity: sls.Medium, EvalCondition: sls.ConditionConfiguration{ Condition: "count > 20", }, }, &sls.SeverityConfiguration{ Severity: sls.Report, EvalCondition: sls.ConditionConfiguration{ }, }, }, PolicyConfiguration: sls.PolicyConfiguration{ AlertPolicyId: "sls.builtin.dynamic", ActionPolicyId: "xxxx.test", RepeatInterval: "5m", }, }, } err := client.CreateAlert(projectName, alert) if err != nil { panic(err) }
其中Alert结构说明可以参考文章末尾的结构说明,PolicyConfiguration中包括告警策略id,行动策略id和重复等待时间,告警策略说明参考链接,行动策略说明参考链接,这里的告警策略和行动策略需要事先创建好,也可以使用控制台创建好的告警策略和行动策略。
列举Project下告警监控规则
alerts, _, _, err := client.ListAlert(projectName, "", "", 0, 100)
获取某个告警监控规则
alert, err := client.GetAlert(projectName, "test-alert-by-sdk")
禁用某个告警监控规则
err := client.DisableAlert(projectName, "test-alert-by-sdk")
启用某个告警监控规则
err := client.EnableAlert(projectName, "test-alert-by-sdk")
告警策略相关
SLS支持您通过动态行动策略为同一个告警策略动态绑定不同的行动策略。动态行动策略机制是指通过告警监控规则配置指定行动策略,而不是通过告警策略配置指定行动策略。关于动态行动策略机制说明可以参考链接。
SLS默认会默认创建一个id为sls.builtin.dynamic的告警策略,用于支持动态行动策略,也就是上文中创建告警监控规则中的指定的AlertPolicyId。
如果需要创建手动的告警策略,可以参考:
创建告警策略
resourceAlertPolicy := new(sls.ResourceAlertPolicy) resourceAlertPolicy.PolicyId = "my-alert-policy" resourceAlertPolicy.PolicyName = "测试告警策略" resourceAlertPolicy.GroupPolicy = `"fire(action_policy="my-test-action-policy", group={"alert.region": alert.region}, group_wait="30s", group_interval="10m", repeat_interval="4h")"` resourceAlertPolicy.SilencePolicy = "" resourceAlertPolicy.InhibitPolicy = "" policyVal, _ := json.Marshal(resourceAlertPolicy) myAlertPolicyRecord := new(sls.ResourceRecord) myAlertPolicyRecord.Id = resourceAlertPolicy.PolicyId myAlertPolicyRecord.Tag = resourceAlertPolicy.PolicyName myAlertPolicyRecord.Value = string(policyVal) err := client.CreateResourceRecord(sls.ResourceNameActionPolicy, myAlertPolicyRecord)
其中告警策略包括合并,静默,抑制等,这里会用到DSL,由于DSL可能会有版本升级,强烈建议您在控制台创建告警策略或者直接使用内置的sls.builtin.dynamic告警策略。以SDK创建的告警策略暂时不支持在控制台的图形化编辑。
创建行动策略
resourceActionPolicy := new(sls.ResourceActionPolicy) resourceActionPolicy.ActionPolicyId= "my-action-policy" resourceActionPolicy.ActionPolicyName= "测试行动策略" resourceActionPolicy.PrimaryPolicyScript = `if alert.labels.a == ("x" or "y"): fire(type="voice", users=["test-user-1"], groups=[], oncall_groups=[], template_id="sls.builtin.cn", check_quota="true", period="any") stop() fire(type="dingtalk", url="https://oapi.dingtalk.com/robot/send?access_token=xxxx", template_id="sls.builtin.cn", users=["test-user-1"], groups=[], oncall_groups=[], check_quota="none", period="any") fire(type="webhook", url="http://test.xxxx.com", method="POST", headers={}, template_id="sls.builtin.cn", check_quota="none", period="any")` alertPolicyVal, _ := json.Marshal(resourceActionPolicy) myActionPolicyRecord := new(sls.ResourceRecord) myActionPolicyRecord.Id = resourceAlertPolicy.PolicyId myActionPolicyRecord.Tag = resourceAlertPolicy.PolicyName myActionPolicyRecord.Value = string(alertPolicyVal) err := client.CreateResourceRecord(sls.ResourceNameActionPolicy, myActionPolicyRecord)
其中行动策略的执行逻辑包括了SLS DSL,由于DSL可能会有版本升级,强烈建议您在控制台创建行动策略,然后在告警规则中直接引用行动策略ID。
在行动策略的DSL会引用用户/用户组/内容模板等资源,在文章后续会有资源的介绍。
告警资源相关
创建用户
customUser := new(sls.ResourceRecord) user := new(sls.ResourceUser) user.UserId = "test-user-1" user.UserName = "test user name" user.Phone = "13888888888" user.CountryCode = "86" user.Enabled = true user.VoiceEnabled = true user.SmsEnabled = true userVal, _ := json.Marshal(user) customUser.Id = user.UserId customUser.Tag = user.UserName customUser.Value = string(userVal) err := client.CreateResourceRecord(sls.ResourceNameUser, customUser)
更新用户
user.UserName = "new name" userVal, _ = json.Marshal(user) customUser.Value = string(userVal) err = client.UpdateResourceRecord(sls.ResourceNameUser, customUser)
删除用户
err := client.DeleteResourceRecord(sls.ResourceNameUser, "test-user-1")
获取用户
resourceRecord, err := client.GetResourceRecord(sls.ResourceNameUser, "test-user-1") if err != nil { panic(err) } user := new(sls.ResourceUser) err = json.Unmarshal([]byte(resourceRecord.Value), user)
获取用户列表
resourceRecords, total, count, err := client.ListResourceRecord(sls.ResourceNameUser, 0, 100) if err != nil { panic(err) } resourceUsers := []*sls.ResourceUser{} for _, resourceRecord := range resourceRecords { user := new(sls.ResourceUser) err = json.Unmarshal([]byte(resourceRecord.Value), user) if err == nil { resourceUsers = append(resourceUsers, user) } }
其他告警资源
上述例子列举了用户的增删改查,SDK还支持用户组、Webhook集成等告警资源的增删改成,对应的资源名称列表如下:
const ( // 告警策略 ResourceNameAlertPolicy = "sls.alert.alert_policy" // 行动策略 ResourceNameActionPolicy = "sls.alert.action_policy" // 用户 ResourceNameUser = "sls.common.user" // 用户组 ResourceNameUserGroup = "sls.common.user_group" // 内容模板 ResourceNameContentTemplate = "sls.alert.content_template" // Webhook集成 ResourceNameWebhookIntegration = "sls.alert.webhook_application" // 全局配置 ResourceNameGlobalConfig = "sls.alert.global_config" )
虽然SDK支持对告警资源的管理,但是还是建议您在SLS控制台去管理告警资源,SLS控制台支持完整的用户管理/用户组管理/内容模板管理/Webhook集成管理,并且具有批量添加功能。
告警监控规则字段说明
Alert
结构
Field |
Type |
Required |
Comment |
Name |
string |
Y |
|
DisplayName |
string |
Y |
|
Description |
string |
N |
|
State |
string |
N |
Enabled,Disabled,默认Enabled |
Configuration |
AlertConfiguration |
Y |
|
Schedule |
Schedule |
Y |
|
CreateTime |
int |
N |
|
LastModifiedTime |
int |
N |
Schedule
结构
Field |
Type |
Required |
Comment |
type |
string |
Y |
类型,FixedRate,Cron,Weekly,Daily,Hourly |
interval |
string |
N |
定时间隔,FIXED_RATE下用 |
cronExpression |
string |
N |
cron表达式,Cron下用 |
dayOfWeek |
int32 |
N |
每周几,Weekly |
hour |
int32 |
N |
每小时,Weekly,Daily |
AlertConfiguration
结构
Field |
Type |
Required |
Comment |
version |
string |
Y |
2.0 |
type |
string |
Y |
default |
queryList |
[]AlertQuery |
Y |
查询列表,非模版必须 |
threshold |
int32 |
Y |
触发阈值,非模版必须 |
labels |
[]Tag |
N |
标签列表 |
annotations |
[]Tag |
N |
annotations列表 |
severityConfigurations |
[]SeverityConfiguration |
Y |
告警级别优先级,暂定任意一条结果数据先满足哪个条件,就设定为某个告警级别,最后一条为默认级别,至少有一条 |
noDataFire |
bool |
N |
无数据是否触发告警,默认false |
noDataSeverity |
int |
N |
无数据触发告警时,告警等级int,固定的枚举值,有大小关系,2,4,6,8.10,report, low,medium,high, critical |
sendResolved |
bool |
N |
告警恢复时是否通知,默认false |
joinConfigurations |
[]JoinConfiguration |
N |
多表Join时,Join条件列表,比如3个表Join,传入两个joinConfiguration |
groupConfiguration |
GroupConfiguration |
Y |
分组评估规则,类型,及分组字段 |
policyConfiguration |
PolicyConfiguration |
Y |
策略选择 |
Tag
结构
Field |
Type |
Required |
Comment |
key |
string |
Y |
键 |
value |
string |
Y |
值 |
PolicyConfiguration
结构
Field |
Type |
Required |
Comment |
alertPolicyId |
string |
N |
具体的告警策ID |
actionPolicyId |
string |
N |
在告警策略引用动态行动策略时有用,非必须。 |
repeatInterval |
string |
N |
在告警策略引用动态行动策略时有用,非必须。 ,重复间隔:数字s/m/h |
JoinConfiguration
结构
Field |
Type |
Required |
Comment |
type |
JoinType |
Y |
集合操作链接的类型, |
condition |
string |
N |
集合操作的条件,笛卡尔积时非必须 |
JoinType
枚举类型
Value |
Type |
Comment |
cross_join |
string |
笛卡尔积 |
inner_join |
string |
内联 |
left_join |
string |
左联 |
right_join |
string |
右联 |
full_join |
string |
全联 |
left_exclude |
string |
左斥 |
right_exclude |
string |
右斥 |
concat |
string |
拼接,直接顺序遍历每张表的数据 |
no_join |
string |
不合并,只取第一个表的数据 |
GroupConfiguration
结构
Field |
Type |
Required |
Comment |
type |
string |
Y |
分组类型,不分组:no_group,自动:labels_auto,自定义: custom |
fields |
[]string |
N |
分组的字段列表,不分组空数组,自动时不填,自定义必填 |
ConditionConfiguration
结构
Field |
Type |
Required |
Comment |
condition |
string |
Y |
目前是判断笛卡尔积的结果中任意一条数据满足Condition,即触发;分组后表示针对每个分组的数据触发条件,空字符串表示任意数据行都满足 |
countCondition |
string |
Y |
告警表达式,表示多少数据满足告警条件,任意数据填空字符串,CountCondition 传入 |
AlertQuery
结构
Field |
Type |
Required |
Comment |
storeType |
string |
Y |
查询类型, log: sls查询分析语句, metric: sls时序数据, meta:查询metastore |
project |
string |
N |
查询关联的Project |
store |
string |
N |
log或者metric查询的LogStore, |
query |
string |
N |
查询分析语句,对于 log或者metric查询LogStore |
timeSpanType |
string |
N |
时间类型,用于LogStore或者metric的LogStore |
start |
string |
N |
开始时间,用于LogStore或者metric的LogStore |
end |
string |
N |
结束时间,用于LogStore或者metric的LogStore |
region |
string |
N |
区域 |
roleArn |
string |
N |
角色访问使用的ARN(注意可能是当前主账号的角色授权) |
dashboardId |
string |
N |
关联的仪表盘 |
SeverityConfiguration
结构
Field |
Type |
Required |
Comment |
severity |
int |
Y |
告警等级int,固定的枚举值,有大小关系,2,4,6,8.10,report, low,medium,high, critical |
evalCondition |
ConditionConfiguration |
N |
告警表达式,数据存在用空字符串,数量表达式,任意使用空字符串,必须存在一项,且最后一项evalCondition为空。 |
TimeSpanType说明
start,end中的时间单位支持d/h/m/s 对应天/时/分/秒,最大跨度24小时
TimeSpanType |
Start |
End |
含义 |
Custom |
-15m |
absolute |
表示整点时间,15m以前到现在,按分钟取整 |
Custom |
-100s |
-20s |
表示相当时间,100s前到20s前的时间 |
Custom |
-60s |
now |
相对时间,60s前到现在 |
Custom |
-120m |
空字符串 |
同上,相对时间,120m前到现在 |
Relative |
-100s |
-20s |
表示相当时间,100s前到20s前的时间 |
Relative |
-60s |
now |
相对时间,60s前到现在 |
Relative |
-120m |
空字符串 |
同上,相对时间,120m前到现在 |
Truncated |
-15m |
任意 |
表示整点时间,15m以前到现在,按分钟取整,同Custom,absolute |
Today |
任意 |
任意 |
表示今天0点到现在 |
Yesterday |
任意 |
任意 |
表示昨天0点到今天0点 |
TheDayBeforeYesterday |
任意 |
任意 |
表示前天0点到昨天0点 |
Range |
开始时间戳(秒) |
结束时间戳(秒) |
指定开始和结束时间戳,字符串 |
参考
- 什么是日志服务【链接】
- 什么是日志服务告警【链接】
- 创建日志告警监控规则【链接】
- 创建告警策略【链接】
- 创建用户和用户组【链接】
- 创建行动策略【链接】
- SLS告警-学习路径【链接】
- 通知内容定制【链接】
- Java SDK概述【链接】
- Go SDK概述【链接】
进一步参考
- SLS(日志服务)云原生观测分析平台:https://www.aliyun.com/product/sls
- SLS新版告警文档首页:https://help.aliyun.com/document_detail/207609.html
- 欢迎扫群加入阿里云-日志服务(SLS)技术交流(集团同学请直接搜索群号11702236加入), 获得第一手资料与支持
- 后续系列直播与培训视频会同步到B站,敬请留意