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. User Guide
1) Configuration menu
2) Register users
3) Create user groups
4) (Optional) Add webhooks
5) Set alarm rules
Alarm Rules
SLOW COUNT
Triggered when the number of slow requests sent to the application exceeds the configured threshold.
SLOW RATE
Triggered when the percentage(%) of slow requests sent to the application exceeds the configured threshold.
ERROR COUNT
Triggered when the number of failed requests sent to the application exceeds the configured threshold.
ERROR RATE
Triggered when the percentage(%) of failed requests sent to the application exceeds the configured threshold.
TOTAL COUNT
Triggered when the number of all requests sent to the application exceeds the configured threshold.
APDEX SCORE
Triggered when the Apdex score goes down below the configured threshold.
SLOW COUNT TO CALLEE
Triggered when the number of slow requests sent by the application exceeds the configured threshold.
You must specify the domain or the address(ip, port) in the configuration UI's "Note..." box
ex) www.naver.com, 127.0.0.1:8080
SLOW RATE TO CALLEE
Triggered when the percentage(%) of slow requests sent by the application exceeds the configured threshold.
You must specify the domain or the address(ip, port) in the configuration UI's "Note..." box
ex) www.naver.com, 127.0.0.1:8080
ERROR COUNT TO CALLEE
Triggered when the number of failed requests sent by the application exceeds the configured threshold.
You must specify the domain or the address(ip, port) in the configuration UI's "Note..." box
ex) www.naver.com, 127.0.0.1:8080
ERROR RATE TO CALLEE
Triggered when the percentage(%) of failed requests sent by the application exceeds the configured threshold.
You must specify the domain or the address(ip, port) in the configuration UI's "Note..." box
ex) www.naver.com, 127.0.0.1:8080
TOTAL COUNT TO CALLEE
Triggered when the number of all requests sent by the application exceeds the configured threshold.
You must specify the domain or the address(ip, port) in the configuration UI's "Note..." box
ex) www.naver.com, 127.0.0.1:8080
HEAP USAGE RATE
Triggered when the application's heap usage(%) exceeds the configured threshold.
JVM CPU USAGE RATE
Triggered when the application's CPU usage(%) detected by JVM exceeds the configured threshold.
SYSTEM CPU USAGE RATE
Triggered when the application's CPU usage(%) detected by system exceeds the configured threshold.
DATASOURCE CONNECTION USAGE RATE
Triggered when the application's DataSource connection usage(%) exceeds the configured threshold.
FILE DESCRIPTOR COUNT
Triggered when the number of open file descriptors exceeds the configured threshold.
2. Configuration & Implementation
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.
2.1 Configuration & Implementation in pinpoint-batch
2.1.1) Email configuration, sms and webhook implementation
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.
pinpoint.url= #pinpoint-web server url
alarm.mail.server.url= #smtp server address
alarm.mail.server.port= #smtp server port
alarm.mail.server.username= #username for smtp server authentication
alarm.mail.server.password= #password for smtp server authentication
alarm.mail.sender.address= #sender's email address
ex)
pinpoint.url=http://pinpoint.com
alarm.mail.server.url=stmp.server.com
alarm.mail.server.port=587
alarm.mail.server.username=pinpoint
alarm.mail.server.password=pinpoint
alarm.mail.sender.address=pinpoint_operator@pinpoint.com
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.
public interface MailSender {
void sendEmail(AlarmChecker checker, int sequenceCount);
}
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.
public interface SmsSender {
public void sendSms(AlarmChecker checker, int sequenceCount);
}
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).
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.
# webhook config
webhook.enable=true
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 table alarm_rule to your MYSQL server used for previous versions of Pinpoint.
ALTER TABLE alarm_rule ADD COLUMN webhook_send CHAR(1) DEFAULT NULL;
*** 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 and webhook_send as below in your MYSQL server used for previous versions of Pinpoint.
CREATE TABLE `webhook` (
`webhook_id` INT UNSIGNED NOT NULL AUTO_INCREMENT,
`alias` VARCHAR(45) NULL,
`url` VARCHAR(45) NOT NULL,
`application_id` VARCHAR(45) NULL,
`service_name` VARCHAR(45) NULL,
PRIMARY KEY (`webhook_id`)
);
CREATE TABLE `webhook_send` (
`webhook_send_info_id` INT UNSIGNED NOT NULL AUTO_INCREMENT,
`webhook_id` INT UNSIGNED NOT NULL,
`rule_id` INT UNSIGNED NOT NULL,
PRIMARY KEY (`webhook_send_info_id`)
);
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.
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.
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.
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.
3.2 Details on Webhook
3.2.1) webhook receiver sample project
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.
3.2.2) The Specification of webhook payloads and the examples
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
email
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
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. Alarm 기능 사용 방법
1) 설정 화면으로 이동
2) user를 등록
3) userGroup을 생성
4) (선택사항) webhook 등
5) alarm rule을 등록
alarm rule에 대한 설명은 아래를 참고하시오.
SLOW COUNT
외부에서 application을 호출한 요청 중에 외부서버로 응답을 늦게 준 요청의 개수가 임계치를 초과한 경우 알람이 전송된다.
SLOW RATE
외부에서 application을 호출한 요청 중에 외부서버로 응답을 늦게 준 요청의 비율(%)이 임계치를 초과한 경우 알람이 전송된다.
ERROR COUNT
외부에서 application을 호출한 요청 중에 에러가 발생한 요청의 개수가 임계치를 초과한 경우 알람이 전송된다.
ERROR RATE
외부에서 application을 호출한 요청 중에 에러가 발생한 요청의 비율(%)이 임계치를 초과한 경우 알람이 전송된다.
TOTAL COUNT
외부에서 application을 호출한 요청 개수가 임계치를 초과한 경우 알람이 전송된다.
APDEX SCORE
Apdex 점수가 임계치 이하로 내려간 경우 알람이 전송된다.
SLOW COUNT TO CALLEE
application 내에서 외부서버를 호출한 요청 중 slow 호출의 개수가 임계치를 초과한 경우 알람이 전송된다.
설정 화면의 Note 항목에 외부서버의 도메인 이나 주소(ip, port)를 입력해야 합니다. ex) naver.com, 127.0.0.1:8080
SLOW RATE TO CALLEE
application 내에서 외부서버를 호출한 요청 중 slow 호출의 비율(%)이 임계치를 초과한 경우 알람이 전송된다.
설정 화면의 Note 항목에 외부서버의 도메인 이나 주소(ip, port)를 입력해야 합니다. ex) naver.com, 127.0.0.1:8080
ERROR COUNT TO CALLEE
application 내에서 외부서버를 호출한 요청 중 error 가 발생한 호출의 개수가 임계치를 초과한 경우 알람이 전송된다.
설정 화면의 Note 항목에 외부서버의 도메인 이나 주소(ip, port)를 입력해야 합니다. ex) naver.com, 127.0.0.1:8080
ERROR RATE TO CALLEE
application 내에서 외부서버를 호출한 요청 중 error 가 발생한 호출의 비율이 임계치를 초과한 경우 알람이 전송된다.
설정 화면의 Note 항목에 외부서버의 도메인 이나 주소(ip, port)를 입력해야 합니다. ex) naver.com, 127.0.0.1:8080
TOTAL COUNT TO CALLEE
application 내에서 외부서버를 호출한 요청의 개수가 임계치를 초과한 경우 알람이 전송된다.
설정 화면의 Note 항목에 외부서버의 도메인 이나 주소(ip, port)를 입력해야 합니다. ex) naver.com, 127.0.0.1:8080
HEAP USAGE RATE
heap의 사용률이 임계치를 초과한 경우 알람이 전송된다.
JVM CPU USAGE RATE
applicaiton의 CPU 사용률이 임계치를 초과한 경우 알람이 전송된다.
SYSTEM CPU USAGE RATE
서버의 CPU 사용률이 임계치를 초과한 경우 알람이 전송된다.
DATASOURCE CONNECTION USAGE RATE
applicaiton의 DataSource내의 Connection 사용률이 임계치를 초과한 경우 알람이 전송된다.
FILE DESCRIPTOR COUNT
열려있는 File Descriptor 개수가 임계치를 초가한 경우 알람이 전송된다.
2. 설정 및 구현 방법
알람을 전송하는 방법은 총 3가지로서, email, sms와 webhook으로 알람을 전송할 수 있다.
email 전송은 설정만 추가하면 기능을 사용할 수 있고, sms 전송을 하기 위해서는 직접 전송 로직을 구현해야 한다.
webhook 전송은 webhook message를 받는 webhook receiver 서비스를 별도로 준비해야한다. webhook receiver 서비스는 샘플 프로젝트를 사용하거나 직접 구현해야 한다.
alarm 기능을 사용하려면 pinpoint-batch와 pinpoint-web를 수정해야한다. pinpoint-batch에는 alarm batch 동작을 위해서 설정 및 구현체를 추가해야 한다. pinpoint-web에는 사용자가 알람을 추가할 수 있도록 설정해야한다.
pinpoint.url= #pinpoint-web 서버의 url
alarm.mail.server.url= #smtp 서버 주소
alarm.mail.server.port= #smtp 서버 port
alarm.mail.server.username= #smtp 인증을 위한 userName
alarm.mail.server.password= #smtp 인증을 위한 password
alarm.mail.sender.address= # 송신자 email
ex)
pinpoint.url=http://pinpoint.com
alarm.mail.server.url=stmp.server.com
alarm.mail.server.port=587
alarm.mail.server.username=pinpoint
alarm.mail.server.password=pinpoint
alarm.mail.sender.address=pinpoint_operator@pinpoint.com
만약 email 전송 로직을 직접 구현하고 싶다면 위의 SpringSmtpMailSender, JavaMailSenderImpl bean 선언을 제거하고 com.navercorp.pinpoint.web.alarm.MailSender interface를 구현해서 bean을 등록하면 된다.
public interface MailSender {
void sendEmail(AlarmChecker checker, int sequenceCount);
}
B. sms 전송
sms 전송 기능을 사용 하려면 com.navercorp.pinpoint.batch.alarm.SmsSender interface를 구현하고 bean으로 등록해야 한다. SmsSender 구현 class가 없는 경우 sms는 전송되지 않는다.
public interface SmsSender {
public void sendSms(AlarmChecker checker, int sequenceCount);
}
C. webhook 전송
Webhook 전송 기능은 Pinpoint의 Alarm message를 Webhook API로 전송 할 수 있는 기능이다.
webhook message를 전송받는 webhook receiver 서비스는 샘플 프로젝트를 사용하거나 직접 구현해야 한다. Webhook Receiver 서버에 전송되는 Alarm message(이하 payload)는 Alarm Checker 타입에 따라 스키마가 다르다. Checker 타입에 따른 payload 스키마는 3.기타 - webhook 페이로드 스키마 명세, 예시에서 설명한다.
알림*** Pinpoint v2.1.1로 업그레이드를 하기 위한 MYSQL 테이블 변경 ***
webhook 기능이 추가되면서 mysql 테이블 스키마가 수정되었기 때문에, Pinpoint 2.1.1 미만 버전에서 2.1.1 버전 이상으로 업그레이드한 경우 Mysql의 'alarm_rule' 테이블에 'webhook_send' 컬럼을 추가해야 다.
ALTER TABLE alarm_rule ADD COLUMN webhook_send CHAR(1) DEFAULT NULL;
*** Pinpoint v2.3.1로 업그레이드를 하기 위한 MYSQL 테이블 추가 생성 ***
Pinpoint v2.1.1에서는 하나의 webhook receiver로만 알람을 보낼 수 있었는데, Pinpoint v2.3.1에서부터 각 알람마다 서로 다른 webhook destination을 설정할 수 있다. 이를 위해서 두 개의 새로운 MYSQL 테이블이 추가되었으며, 아래와 같이 ‘webhook’과 ‘webhook_send’테이블을 추가해야 한다.
CREATE TABLE `webhook` (
`webhook_id` INT UNSIGNED NOT NULL AUTO_INCREMENT,
`alias` VARCHAR(45) NULL,
`url` VARCHAR(45) NOT NULL,
`application_id` VARCHAR(45) NULL,
`service_name` VARCHAR(45) NULL,
PRIMARY KEY (`webhook_id`)
);
CREATE TABLE `webhook_send` (
`webhook_send_info_id` INT UNSIGNED NOT NULL AUTO_INCREMENT,
`webhook_id` INT UNSIGNED NOT NULL,
`rule_id` INT UNSIGNED NOT NULL,
PRIMARY KEY (`webhook_send_info_id`)
);
물론 v2.3.1 이전 버전에서 바로 v2.3.1로 업그레이드하는 경우, 위의 모든 변경사항을 적용해야한다.
참고로 Webhook을 전송하는 클래스(WebhookSenderImpl)는 Pinpoint에서 이미 제공하고 있으며, webHookSender bean으 Pinpoint-batch의 applicationContext-batch-sender.xml 파일에 등록 되어있다.
Slack-Receiver 는 Webhook Receiver의 예제 프로젝트이다. 이 프로젝트는 Pinpoint의 webhook의 알람을 받아서 Slack으로 메시지를 전송할 수 있는 스프링 부트로 구현된 서비스이다. 이 프로젝트의 자세한 사항은 해당 GitHub 저장소 를 참고하면 된다.
3.2.2 webhook 페이로드 스키마 및 예시
페이로드 스키마
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
email
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[] 타입이다.
