使用SDK管理SLS告警-以Go为例

除了在SLS控制台创建告警监控以外,SLS的SDK也提供了对告警的管理功能,其中主要包括了初始化告警资源,告警监控规则的增删改查,告警资源的增删改查等功能。

文中的介绍需要使用到两个SDK,分别为:

告警资源初始化SDK: github.com/aliyun/alibaba-cloud-sdk-go/sdk

告警规则/策略管理SDK: github.com/aliyun/aliyun-log-go-sdk

SLS告警SDK主要包括三部分内容:

  • 告警资源初始化
  • 告警监控规则的管理
  • 告警策略的管理,包括用户/用户组/通知渠道等

使用SDK管理SLS告警-以Go为例

告警资源初始化

告警资源主要包括两部分:

  • 用户级别下的告警中心资源
  • 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 传入 __count__ >= 3


AlertQuery 结构

Field

Type

Required

Comment

storeType

string

Y

查询类型,

log: sls查询分析语句,

metric: sls时序数据,

meta:查询metastore

project

string

N

查询关联的Project

store

string

N

log或者metric查询的LogStore,
对于meta数据表示,要查的resourceName

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概述【链接

进一步参考

使用SDK管理SLS告警-以Go为例


上一篇:特殊权限set_uid、set_gid、stick_bit、软链接文件、硬链接文件


下一篇:SLS新版告警入门-告警严重度