Setting Alarm
Last updated
Last updated
Application's status is periodically checked and alarm is triggered if certain pre-configured conditions (rules) are satisfied.
pinpoint-batch server checks every 3 minutes based on the last 5 minutes of data. And if the conditions are satisfied, it sends sms/email/webhook to the users listed in the user group.
If an email/sms/webhook is sent everytime when the threshold is exceeded, even after the recipients are aware of the event they might get the same alarms continuously which we thought might be unneccessary. Therefore we decided to gradually increase the transmission frequency for alarms. ex) If an alarm occurs continuously, transmission frequency is increased by a factor of two. 3 min -> 6min -> 12min -> 24min
NOTICE!
These logics were part of pinpoint-web server and ran in the background until v2.2.0 From v2.2.1 it is separated into pinpoint-batch server. Since the batch logic(code) in pinpoint-web will be deprecated in the future, we advise you to transfer the execution of batch to pinpoint-batch server.
Webhook function is newly added in v2.1.1, and has some changes in v2.3.1. In both versions, MYSQL table needs to be changed. Please check the notice on these changes in 2.1.1
1) Configuration menu
2) Register users
3) Create user groups
4) (Optional) Add webhooks
5) Set alarm rules
Alarm Rules
Alarms generated by Pinpoint can be configured to be sent over email, sms and webhook.
Sending alarms over email is simple - you will simply need to configure the property file. Sending alarms over sms requires some implementation. Read on to find out how to do this. The alarm using webhook requires a separate webhook receiver service. You should implement the webhook receiver service - which is not provided by Pinpoint, or You can use the sample project.
Few modifications are required in pinpoint-batch and pinpoint-web to use the alarm feature. Add some implementations and settings in pinpoint-batch. Configure Pinpoint-web for user to set an alarm settings.
A. Email alarm service
To use the mailing feature, you need to configure the SMTP server information and information to be included in the email in the batch-root.properties file.
The class that sends emails is already registered as Spring bean in applicationContext-batch-sender.xml.
If you would like to implement your own mail sender, simply replace the SpringSmtpMailSender
, JavaMailSenderImpl
beans above with your own implementation that implements com.navercorp.pinpoint.web.alarm.MailSender
interface.
B. Sms alarm service
To send alarms over sms, you will need to implement your own sms sender by implementing com.navercorp.pinpoint.batch.alarm.SmsSender
interface. If there is no SmsSender
implementation, then alarms will not be sent over sms.
C. Webhook alarm service
Webhook alarm service is a feature that can transmit Pinpoint's alarm message through Webhook API.
The webhook receiver service that receives the webhook message should be implemented by yourself, or use a sample project provided (in this case Slack).
The alarm messages(refer to as payloads) sent to webhook receiver have the different schema depending on the Alarm Checker type. You can see the payload schemas in 3.Others - The Specification of webhook payloads and the examples.
To enable the webhook alarm service, You need to configure webhook.enable in batch-root.properties file. Webhook receiver urls can be configured in web UI after configuring the web module to enable webhook as described in the following section.
NOTICE!
*** **MYSQL table ALTER for migrating to Pinpoint v2.1.1 *****
As the webhook alarm service is newly added in Pinpoint 2.1.1, you should add column
webhook_send
in tablealarm_rule
to your MYSQL server used for previous versions of Pinpoint.*** MYSQL table CREATE for migrating to Pinpoint v2.3.1 ***
Different webhook destinations can be specified to different alarms and new tables are added for this. Create table
webhook
andwebhook_send
as below in your MYSQL server used for previous versions of Pinpoint.Of course if you are migrating from versions lower than v2.1.1 to v2.3.1, all the changes above need to be applied.
WebhookSenderImpl class, which sends the webhook, is already implemented for you and is added as webhookSender bean in applicationContext-batch-sender.xml of Pinpoint-batch.
step 1
Prepare MYSQL Instance to persist the alarm service metadata.
step 2
Set up a MYSQL server and configure connection information in jdbc-root.properties file.
step 3
Create tables for the alarm service. Use below DDL files.
The pinpoint-batch project is based on spring boot and can be executed with the following command. When building is successfully finished, the executable file is placed under the target/deploy folder of the pinpoint-batch.
In order to persist user alarm settings, set the mysql connection information in jdbc-root.properties file in pinpoint-web.
Set webhook.enable in pinpoint-web-root.properties as true for user to configure the webhook alarm in Alarm menu.
As you enable the webhook alarm service, you can set the webhook as alarm type and specify the target webhook.
1) You may change the batch execution period by modifying the cron expression in applicationContext-batch-schedule.xml file
2) Ways to improve alarm batch performance
The alarm batch was designed to run concurrently. If there are a lot of applications using alarms, you may increase the size of the executor's thread pool by modifying pool-size
in applicationContext-alarmJob.xml file.
Note that increasing this value will result in higher resource usage.
If there are a lot of alarms registered to each application, you may set the alarmStep
registered in applicationContext-alarmJob.xml file to run concurrently.
3) Use quickstart's web
Pinpoint Web uses Mysql to persist users, user groups, and alarm configurations, but our Quickstart example uses MockDAO to reduce memory usage. If you want to use Mysql with Quickstart, please refer to Pinpoint Web's applicationContext-dao-config.xml and jdbc.properties.
Slack-Receiver is an example project for the webhook receiver. The project can receive alarms from Pinpoint through webhook and send the message to Slack. If you want more details, see the project repository.
The Schemas of webhook payloads
Key
Name | Type | Description | Nullable |
---|---|---|---|
pinpointUrl | String | Pinpoint-web server URL | O |
batchEnv | String | Batch server environment variable | X |
applicationId | String | Alarm target application Id | X |
serviceType | String | Alarm target application service type | X |
userGroup | UserGroup | The UserGroup in the user group page | X |
checker | Checker | The checker info in the alarm setting page | X |
unit | String | The unit of detected value by checker | O |
threshold | Integer | The threshold of value detected by checker during a set time | X |
notes | String | The notes in the alarm setting page | O |
sequenceCount | Integer | The number of alarm occurence | X |
UserGroup
Name | Type | Description | Nullable |
---|---|---|---|
userGroupId | String | The user group id in the user group page | X |
userGroupMembers | UserMember[] | Members Info of a specific user group | X |
Checker
Name | Type | Description | Nullable |
---|---|---|---|
name | String | The name of checker in the alarm setting page | X |
type | String | The type of checker abstracted by value detected by checker "LongValueAlarmChecker" type is the abstracted checker type of “Slow Count”, “Slow Rate”, “Error Count”, “Error Rate”, “Total Count”, “Slow Count To Callee”, “Slow Rate To Callee”, “Error Count To Callee”, “Error Rate To Callee”, “Total Count to Callee”. "LongValueAgentChecker" type is the abstracted checker type of "Heap Usage Rate", "Jvm Cpu Usage Rate", "System Cpu Usage Rate", "File Descriptor Count". "BooleanValueAgentChecker" type is the abstracted checker type of "Deadlock or not". "DataSourceAlarmListValueAgentChecker" type is the abstracted checker type of "DataSource Connection Usage Rate". | X |
detectedValue | Integer or DetectedAgent[] | The value detected by checker If “type” is “LongValueAlarmChecker”, “detectedValue” is Integer type. If "type" is not "LongValueAlarmChecker", "detectedValue" is DetectedAgents[] type. | X |
UserMember
Name | Type | Description | Nullable |
---|---|---|---|
id | String | Member id | X |
name | String | Member name | X |
String | Member email | O | |
department | String | Member department | O |
phoneNumber | String | Member phone number | O |
phoneCountryCode | String | Member phone country code | O |
DetectedAgent
Name | Type | Description | Nullable |
---|---|---|---|
agentId | String | Agent id detected by checker | X |
agentValue | Integer or Boolean or DataSourceAlarm[] | The value of Agent detected by checker If “type” is “LongValueAgentChecker”, “agentValue” is Integer type. If “type” is “BooleanValueAgentChecker”,“agentValue” is Boolean type. If “type” is “DataSourceAlarmListValueAgentChecker”, “agentValue” is DataSourceAlarm[] type | X |
DataSourceAlarm
Name | Type | Description | Nullable |
---|---|---|---|
databaseName | String | The database name connected to application | X |
connectionValue | Integer | The application's DataSource connection usage | X |
The Examples of the webhook Payload
LongValueAlarmChecker
LongValueAgentChecker
BooleanValueAgentChecker
DataSourceAlarmListValueAgentChecker
Pinpoint는 application 상태를 주기적으로 체크하여 application 상태의 수치가 임계치를 초과할 경우 사용자에게 알람을 전송하는 기능을 제공한다.
Application 상태 값이 사용자가 설정한 임계치를 초과하는지 판단하는 batch는 pinpoint-batch에서 동작 한다. Alarm batch는 기본적으로 3분에 한번씩 동작이 된다. 최근 5분동안의 데이터를 수집해서 alarm 조건을 만족하면 user group에 속한 user 들에게 sms/email/webhook message를 전송한다.
연속적으로 알람 조건이 임계치를 초과한 경우에 매번 sms/email/webhook를 전송하지 않는다. 알람 조건이 만족할때마다 매번 sms/email/webhook이 전송되는것은 오히려 방해가 된다고 생각하기 때문이다. 그래서 연속해서 알람이 발생할 경우 sms/email/webhook 전송 주기가 점증적으로 증가된다. 예) 알람이 연속해서 발생할 경우, 전송 주기는 3분 -> 6분 -> 12분 -> 24분 으로 증가한다.
알림
Batch는 pinpoint 2.2.0 버전까지는 pinpoint-web에서 동작되었지만, 2.2.1 버전 부터는 batch가 pinpoint-batch에서 동작되도록 로직을 분리했다.** **앞으로 pinpoint-web의 batch로직은 제거를 할 예정이므로, pinpoint-web에서 batch를 동작시키는 경우 pinpoint-batch에서 batch를 실행하도록 구성하는것을 추천한다.
웹훅 기능은 v2.1.1에 신규로 추가되었으며 v2.3.1에 기능이 개선되었다. 두 버전 모두에서 MYSQL 테이블 변경이 있으므로, 해당 버전 이전에서 업그레이드할 경우, 2.1.1 항목에서 관련 변경 사항을 확인 후 적용해야 한다.
1) 설정 화면으로 이동
2) user를 등록
3) userGroup을 생성
4) (선택사항) webhook 등
5) alarm rule을 등록
alarm rule에 대한 설명은 아래를 참고하시오.
알람을 전송하는 방법은 총 3가지로서, email, sms와 webhook으로 알람을 전송할 수 있다.
email 전송은 설정만 추가하면 기능을 사용할 수 있고, sms 전송을 하기 위해서는 직접 전송 로직을 구현해야 한다. webhook 전송은 webhook message를 받는 webhook receiver 서비스를 별도로 준비해야한다. webhook receiver 서비스는 샘플 프로젝트를 사용하거나 직접 구현해야 한다.
alarm 기능을 사용하려면 pinpoint-batch와 pinpoint-web를 수정해야한다. pinpoint-batch에는 alarm batch 동작을 위해서 설정 및 구현체를 추가해야 한다. pinpoint-web에는 사용자가 알람을 추가할 수 있도록 설정해야한다.
A. email 전송
email 전송 기능을 사용하기 위해서 batch-root.properties파일에 smtp 서버 정보와 email에 포함될 정보들을 설정해야 한다.
참고로 applicationContext-batch-sender.xml 파일에 email을 전송하는 class가 bean으로 등록 되어있다.
만약 email 전송 로직을 직접 구현하고 싶다면 위의 SpringSmtpMailSender, JavaMailSenderImpl bean 선언을 제거하고 com.navercorp.pinpoint.web.alarm.MailSender interface를 구현해서 bean을 등록하면 된다.
B. sms 전송
sms 전송 기능을 사용 하려면 com.navercorp.pinpoint.batch.alarm.SmsSender interface를 구현하고 bean으로 등록해야 한다. SmsSender 구현 class가 없는 경우 sms는 전송되지 않는다.
C. webhook 전송
Webhook 전송 기능은 Pinpoint의 Alarm message를 Webhook API로 전송 할 수 있는 기능이다.
webhook message를 전송받는 webhook receiver 서비스는 샘플 프로젝트를 사용하거나 직접 구현해야 한다. Webhook Receiver 서버에 전송되는 Alarm message(이하 payload)는 Alarm Checker 타입에 따라 스키마가 다르다. Checker 타입에 따른 payload 스키마는 3.기타 - webhook 페이로드 스키마 명세, 예시에서 설명한다.
webhook 기능을 활성화 하기위해서, batch-root.properties 파일에 Webhook 전송 여부(webhook.enable)를 설정한다. Receiver 서버 정보의 경우 2.2 pinpoint-web 설정 방법 같이 web 설정을 마친 후, UI를 통해 추가할 수 있다.
알림 *** Pinpoint v2.1.1로 업그레이드를 하기 위한 MYSQL 테이블 변경 ***
webhook 기능이 추가되면서 mysql 테이블 스키마가 수정되었기 때문에, Pinpoint 2.1.1 미만 버전에서 2.1.1 버전 이상으로 업그레이드한 경우 Mysql의 'alarm_rule' 테이블에 'webhook_send' 컬럼을 추가해야 다.
*** Pinpoint v2.3.1로 업그레이드를 하기 위한 MYSQL 테이블 추가 생성 ***
Pinpoint v2.1.1에서는 하나의 webhook receiver로만 알람을 보낼 수 있었는데, Pinpoint v2.3.1에서부터 각 알람마다 서로 다른 webhook destination을 설정할 수 있다. 이를 위해서 두 개의 새로운 MYSQL 테이블이 추가되었으며, 아래와 같이 ‘webhook’과 ‘webhook_send’테이블을 추가해야 한다.
물론 v2.3.1 이전 버전에서 바로 v2.3.1로 업그레이드하는 경우, 위의 모든 변경사항을 적용해야한다.
참고로 Webhook을 전송하는 클래스(WebhookSenderImpl)는 Pinpoint에서 이미 제공하고 있으며, webHookSender bean으 Pinpoint-batch의 applicationContext-batch-sender.xml 파일에 등록 되어있다.
step 1
알람에 관련된 데이터를 저장하기 위해 Mysql 서버를 준비한다.
step 2
mysql 접근을 위해서 pinpoint-batch의 jdbc-root.properties 파일에 접속 정보를 설정한다.
step 3
mysql에 Alarm 기능에 필요한 table을 생성한다. table 스키마는 아래 파일을 참조한다.
pinpoint-batch 프로젝트는 spring boot기반으로 되어있고 아래와 같은 명령어로 실행하면 된다. 빌드후 실행파일은 pinpoint-batch 모듈의 target/deploy 폴더 하위에서 확인할 수 있다.
사용자 알람 설정을 저장하기 위해서 pinpoint-web의 jdbc-root.properties 파일에 mysql 접속 정보를 설정한다.
사용자가 알람 설정에 webhook 기능을 적용할수 있도록 pinpoint-web-root.properties 파일에 webhook 기능을 활성화한다.
webhook 기능을 활성화하면, 아래 그림처럼 알람 설정 화면에서 webhook을 알람 타입으로 선택할 수 있다.
1) Batch의 동작 주기를 조정하고 싶다면 applicationContext-batch-schedule.xml 파일의 cron expression을 수정하면 된다.
2) Alarm batch 성능을 높이는 방법은 다음과 같다.
Alarm batch 성능 튜닝을 위해서 병렬로 동작이 가능하도록 구현을 해놨다. 그래서 아래에서 언급된 조건에 해당하는 경우 설정 값을 조정한다면 성능을 향상 시킬 수 있다. 단, 병렬성을 높이면 리소스 사용률이 높아지는 것은 감안해야 한다.
Alarm이 등록된 application의 개수가 많다면 applicationContext-alarmJob.xml 파일의 poolTaskExecutorForPartition의 pool size를 늘려주면 된다.
Application 각각마다 등록된 alarm의 개수가 많다면 applicationContext-alarmJob.xml 파일에 선언된 alarmStep이 병렬로 동작되도록 설정하면 된다.
3) Quickstart web을 사용한다면.
Quickstart pinpoint web은 mockDAO를 사용하기 때문에 추가한 알람 설정들이 저장되지 않는다. Mysql과 quickstart를 연동해서 사용하려면 다음의 설정들을 참고해서 수정 후 기능을 사용해야한다: applicationContext-dao-config.xml, jdbc.properties.
Slack-Receiver 는 Webhook Receiver의 예제 프로젝트이다. 이 프로젝트는 Pinpoint의 webhook의 알람을 받아서 Slack으로 메시지를 전송할 수 있는 스프링 부트로 구현된 서비스이다. 이 프로젝트의 자세한 사항은 해당 GitHub 저장소 를 참고하면 된다.
페이로드 스키마
Key
Name | Type | Description | Nullable |
---|---|---|---|
pinpointUrl | String | Pinpoint-web의 서버 URL 주소 | O |
batchEnv | String | Batch 서버의 환경 변수 | X |
applicationId | String | 타겟 애플리케이션 ID | X |
serviceType | String | 타겟 애플리케이션 서비스 타입 | X |
userGroup | UserGroup | 유저 그룹 페이지의 유저 그룹 | X |
checker | Checker | alarm 설정 페이지의 checker 정보 | X |
unit | String | checker가 감지한 값의 단위 | O |
threshold | Integer | 설정된 시간동안 체커가 감지한 값의 임계치 | X |
notes | String | 알람 설정 페이지의 notes | O |
sequenceCount | Integer | 알람 발생 횟수 | X |
UserGroup
Name | Type | Description | Nullable |
---|---|---|---|
userGroupId | String | 유저 그룹 페이지의 유저 그룹 ID | X |
userGroupMembers | UserMember[] | 특정 유저 그룹의 멤버 정보 | X |
Checker
Name | Type | Description | Nullable |
---|---|---|---|
name | String | 알람 설정 페이지의 checker 이름 | X |
type | String | 체커가 감지한 값의 추상 타입, 다음 중 하나에 해당됨 "LongValueAlarmChecker" 타입은 "Slow Count", “Slow Count”, “Slow Rate”, “Error Count”, “Error Rate”, “Total Count”, “Slow Count To Callee”, “Slow Rate To Callee”, “Error Count To Callee”, “Error Rate To Callee”, “Total Count to Callee”의 추상 타입에 속한다. "LongValueAgentChecker" 타입은 "Heap Usage Rate", "Jvm Cpu Usage Rate", "System Cpu Usage Rate", "File Descriptor Count"의 추상타입이다. "BooleanValueAgentChecker" 타입은 "Deadlock or not"의 추상 타입이다. "DataSourceAlarmListValueAgentChecker" 타입은 "DataSource Connection Usage Rate"의 추상타입이다. | X |
detectedValue | Integer or DetectedAgent[] | Checker가 감지한 값 “LongValueAlarmChecker”, “detectedValue” 타입은 Integer 타입이다. "LongValueAlarmChecker", "detectedValue"이 아닌 타입은 DetectedAgents[] 타입 이다. | X |
UserMember
Name | Type | Description | Nullable |
---|---|---|---|
id | String | 멤버의 id | X |
name | String | 멤버의 name | X |
String | 멤버의 email | O | |
department | String | 멤버의 department | O |
phoneNumber | String | 멤버의 phone number | O |
phoneCountryCode | String | 멤버의 phone country code | O |
DetectedAgent
Name | Type | Description | Nullable |
---|---|---|---|
agentId | String | Checker가 감지한 에이전트 ID | X |
agentValue | Integer or Boolean or DataSourceAlarm[] | 체커가 감지한 에이전트의 값 “LongValueAgentChecker”, “agentValue” 은 Integer 타입이다. “BooleanValueAgentChecker”,“agentValue” 은 Boolean 타입이다.. “DataSourceAlarmListValueAgentChecker”, “agentValue”은 DataSourceAlarm[] 타입이다. | X |
DataSourceAlarm
Name | Type | Description | Nullable |
---|---|---|---|
databaseName | String | 애플리케이션에 접속한 데이터베이스 이름 | X |
connectionValue | Integer | Applicaiton의 DataSource내의 Connection 사용률 | X |
webhook Payload 예제
LongValueAlarmChecker
LongValueAgentChecker
BooleanValueAgentChecker
DataSourceAlarmListValueAgentChecker