feature: support monitoring pop3 metrics and add help doc (#1427)

Co-authored-by: tomsun28 <tomsun28@outlook.com>
This commit is contained in:
淞筱
2023-12-17 21:10:18 +08:00
committed by GitHub
co-authored by tomsun28
parent b576affc40
commit ad1dad69d4
8 changed files with 517 additions and 3 deletions
@@ -0,0 +1,183 @@
package org.dromara.hertzbeat.collector.collect.pop3;
import lombok.extern.slf4j.Slf4j;
import org.apache.commons.net.pop3.POP3MessageInfo;
import org.dromara.hertzbeat.collector.collect.AbstractCollect;
import org.dromara.hertzbeat.collector.dispatch.DispatchConstants;
import org.dromara.hertzbeat.common.constants.CollectorConstants;
import org.dromara.hertzbeat.common.constants.CommonConstants;
import org.dromara.hertzbeat.common.entity.job.Metrics;
import org.dromara.hertzbeat.common.entity.job.protocol.Pop3Protocol;
import org.dromara.hertzbeat.common.entity.message.CollectRep;
import org.apache.commons.net.pop3.POP3SClient;
import org.apache.commons.net.pop3.POP3Client;
import org.dromara.hertzbeat.common.util.CommonUtil;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
/**
* pop3 collect
*
*/
@Slf4j
public class Pop3CollectImpl extends AbstractCollect {
private final static String EMAIL_COUNT = "email_count";
private final static String MAILBOX_SIZE = "mailbox_size";
public Pop3CollectImpl() {
}
@Override
public void collect(CollectRep.MetricsData.Builder builder, long monitorId, String app, Metrics metrics) {
long startTime = System.currentTimeMillis();
try {
validateParams(metrics);
} catch (Exception e) {
builder.setCode(CollectRep.Code.FAIL);
builder.setMsg(e.getMessage());
return;
}
Pop3Protocol pop3Protocol = metrics.getPop3();
POP3Client pop3Client = null;
boolean ssl = Boolean.parseBoolean(pop3Protocol.getSsl());
try {
pop3Client = createPOP3Client(pop3Protocol, ssl);
if (pop3Client.isConnected()) {
long responseTime = System.currentTimeMillis() - startTime;
obtainPop3Metrics(builder, pop3Client, metrics.getAliasFields(),
responseTime);
} else {
builder.setCode(CollectRep.Code.UN_CONNECTABLE);
builder.setMsg("Peer connect failedTimeout " + pop3Protocol.getTimeout() + "ms");
}
} catch (IOException e1) {
String errorMsg = CommonUtil.getMessageFromThrowable(e1);
log.info(errorMsg);
builder.setCode(CollectRep.Code.FAIL);
builder.setMsg(errorMsg);
} catch (Exception e2) {
String errorMsg = CommonUtil.getMessageFromThrowable(e2);
log.info(errorMsg);
builder.setCode(CollectRep.Code.FAIL);
builder.setMsg(errorMsg);
} finally {
if (pop3Client != null) {
try {
pop3Client.logout();
pop3Client.disconnect();
} catch (IOException e) {
String errorMsg = CommonUtil.getMessageFromThrowable(e);
log.info(errorMsg);
builder.setCode(CollectRep.Code.FAIL);
builder.setMsg(errorMsg);
}
}
}
}
@Override
public String supportProtocol() {
return DispatchConstants.PROTOCOL_POP3;
}
/**
* 校验参数
* @param metrics
* @throws Exception
*/
private void validateParams(Metrics metrics) throws Exception {
Pop3Protocol pop3Protocol = metrics.getPop3();
if (metrics == null || pop3Protocol == null || pop3Protocol.isInvalid()) {
throw new Exception("Pop3 collect must has pop3 params");
}
}
/**
* 创建POP3连接【支持SSL加密】
* @param pop3Protocol
* @param ssl
* @return
* @throws IOException
*/
private POP3Client createPOP3Client(Pop3Protocol pop3Protocol, boolean ssl) throws Exception {
POP3Client pop3Client = null;
// 判断是否启用 SSL 加密连接
if (ssl) {
pop3Client = new POP3SClient(true);
} else {
pop3Client = new POP3Client();
}
// 设置超时时间
int timeout = Integer.parseInt(pop3Protocol.getTimeout());
if (timeout > 0) {
pop3Client.setConnectTimeout(timeout);
}
pop3Client.setCharset(StandardCharsets.UTF_8);
// 连接到POP3服务器
String host = pop3Protocol.getHost();
int port = Integer.parseInt(pop3Protocol.getPort());
pop3Client.connect(host, port);
// 验证凭据
String email = pop3Protocol.getEmail();
String authorize = pop3Protocol.getAuthorize();
boolean isAuthenticated = pop3Client.login(email, authorize);
if (!isAuthenticated) {
throw new Exception("Pop3 client authentication failed");
}
return pop3Client;
}
/**
* 获取Pop3指标信息
* @param builder
* @param pop3Client
* @param aliasFields
* @param responseTime
*/
private void obtainPop3Metrics(CollectRep.MetricsData.Builder builder, POP3Client pop3Client,
List<String> aliasFields, long responseTime) throws IOException {
Map<String,Object> pop3Metrics = parsePop3Metrics(pop3Client, aliasFields);
CollectRep.ValueRow.Builder valueRowBuilder = CollectRep.ValueRow.newBuilder();
for (String alias : aliasFields) {
Object value = pop3Metrics.get(alias);
if (value != null) {
valueRowBuilder.addColumns(String.valueOf(value));
} else {
if (CollectorConstants.RESPONSE_TIME.equalsIgnoreCase(alias)) {
valueRowBuilder.addColumns(String.valueOf(responseTime));
} else {
valueRowBuilder.addColumns(CommonConstants.NULL_VALUE);
}
}
}
builder.addValues(valueRowBuilder);
}
private Map<String,Object> parsePop3Metrics(POP3Client pop3Client, List<String> aliasFields) throws IOException {
Map<String,Object> pop3Metrics = new HashMap<>(aliasFields.size());
POP3MessageInfo status = pop3Client.status();
int emailCount = 0;
double mailboxSize = 0.0;
if (status != null) {
emailCount = status.number;
// byte -> kb
mailboxSize = (double)status.size / 1024.0;
pop3Metrics.put(EMAIL_COUNT, emailCount);
pop3Metrics.put(MAILBOX_SIZE, mailboxSize);
}
return pop3Metrics;
}
}
@@ -107,6 +107,10 @@ public interface DispatchConstants {
* protocol dns
*/
String PROTOCOL_DNS = "dns";
/**
* protocol pop3
*/
String PROTOCOL_POP3 = "pop3";
// Protocol type related - end
// 协议类型相关 - end //
@@ -18,3 +18,4 @@ org.dromara.hertzbeat.collector.collect.push.PushCollectImpl
org.dromara.hertzbeat.collector.collect.dns.DnsCollectImpl
org.dromara.hertzbeat.collector.collect.nginx.NginxCollectImpl
org.dromara.hertzbeat.collector.collect.memcached.MemcachedCollectImpl
org.dromara.hertzbeat.collector.collect.pop3.Pop3CollectImpl
@@ -192,9 +192,13 @@ public class Metrics {
*/
private DnsProtocol dns;
/**
* Monitoring configuration information using the public DNS protocol
* Monitoring configuration information using the public Nginx protocol
*/
private NginxProtocol nginx;
/**
* Monitoring configuration information using the public Nginx protocol
*/
private Pop3Protocol pop3;
/**
* collector use - Temporarily store subTask metrics response data
@@ -0,0 +1,47 @@
package org.dromara.hertzbeat.common.entity.job.protocol;
import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;
import org.apache.commons.lang3.StringUtils;
@Data
@Builder
@AllArgsConstructor
@NoArgsConstructor
public class Pop3Protocol {
/**
* 接收服务器地址
*/
private String host;
/**
* 接收服务器端口
*/
private String port;
/**
* 超时时间
*/
private String timeout;
/**
* 是否开启SSL加密【邮箱传输】
*/
private String ssl = "false";
/**
* pop邮箱地址
*/
private String email;
/**
* 授权码
*/
private String authorize;
public boolean isInvalid() {
return StringUtils.isAllBlank(host, port, timeout, ssl, email, authorize);
}
}
+2 -2
View File
@@ -2,7 +2,7 @@
id: nginx
title: Monitoring Nginx
sidebar_label: Nginx Monitor
keywords: [open source monitoring tool, open source java spark monitoring tool, monitoring nginx metrics]
keywords: [open source monitoring tool, open source java monitoring tool, monitoring nginx metrics]
---
> Collect and monitor the general performance Metrics of Nginx.
@@ -75,7 +75,7 @@ http {
|---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Monitoring Host | Monitored IPV4, IPV6 or domain name. Note⚠️Without protocol header (eg: https://, http://) |
| Monitoring name | Identify the name of this monitoring. The name needs to be unique |
| Port | Port provided by JMX |
| Port | Port provided by Nginx |
| Timeout | Allow collection response time |
| Collection interval | Interval time of monitor periodic data collection, unit: second, and the minimum interval that can be set is 30 seconds |
| Whether to detect | Whether to detect and check the availability of monitoring before adding monitoring. Adding and modifying operations will continue only after the detection is successful |
+50
View File
@@ -0,0 +1,50 @@
---
id: pop3
title: Monitoring POP3
sidebar_label: POP3 Monitor
keywords: [open source monitoring tool, open source java monitoring tool, monitoring POP3 metrics]
---
> Collect and monitor the general performance Metrics of POP3.
**Protocol UsePOP3**
### Enable POP3 Service
If you want to monitor information in 'POP3' with this monitoring type, you just need to open `POP3` service in your mail server.
**1、Open `POP3` Service:**
```text
以qq邮箱为例【其它邮箱类似】:
1. 点击`设置`选项
2. 选择`账号`
3. 找到开启SMTP/POP3/IMAP选项,并开启
4. 得到POP3服务器域名,端口号,以及授权码【开启SMTP/POP3/IMAP服务后,qq邮箱提供】
5. 通过POP3服务器域名,端口号,qq邮箱账号以及授权码连接POP3服务器,采集监控指标
```
### Configuration parameter
| Parameter name | Parameter help description |
|---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Monitoring Host | Monitored IPV4, IPV6 or domain name. Note⚠️Without protocol header (eg: https://, http://) |
| Monitoring name | Identify the name of this monitoring. The name needs to be unique |
| Port | Port provided by POP3 |
| SSL | POP3 If enabled SSL |
| Timeout | Allow collection response time |
| Collection interval | Interval time of monitor periodic data collection, unit: second, and the minimum interval that can be set is 30 seconds |
| Whether to detect | Whether to detect and check the availability of monitoring before adding monitoring. Adding and modifying operations will continue only after the detection is successful |
| Description remarks | For more information about identifying and describing this monitoring, users can note information here |
### Collection Metrics
#### Metrics Setemail_status
| Metric name | Metric unit | Metric help description |
|--------------|-------------|------------------------------------------|
| email_count | | Number of emails |
| mailbox_size | kb | The total size of emails in the mailbox |
@@ -0,0 +1,225 @@
# Licensed to the Apache Software Foundation (ASF) under one or more
# contributor license agreements. See the NOTICE file distributed with
# this work for additional information regarding copyright ownership.
# The ASF licenses this file to You under the Apache License, Version 2.0
# (the "License"); you may not use this file except in compliance with
# the License. You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
# 监控类型所属类别:service-应用服务 program-应用程序 db-数据库 custom-自定义 os-操作系统 bigdata-大数据 mid-中间件 webserver-web服务器 cache-缓存 cn-云原生 network-网络监控等等
category: service
# 监控应用类型名称(与文件名保持一致) eg: linux windows tomcat mysql aws...
app: pop3
# The app api i18n name
# app api国际化名称
name:
zh-CN: POP3
en-US: POP3
# 监控类型的帮助描述信息
help:
zh-CN: HertzBeat 使用 <a class='help_module_content' href='https://www.alibabacloud.com/help/zh/alibaba-mail/latest/how-to-turn-off-or-open-the-pop3-or-imap-protocol-for-accounts'> POP3 </a> 通过开启邮箱 pop3 服务 对 POP3服务器 的通用性能指标(email_count、mailbox_size)进行采集监控。<br>您可以点击“<i>新建 POP3</i>”并进行配置,或者选择“<i>更多操作</i>”,导入已有配置。
en-US: HertzBeat uses <a class='help_module_content' href='https://www.alibabacloud.com/help/zh/alibaba-mail/latest/how-to-turn-off-or-open-the-pop3-or-imap-protocol-for-accounts'> POP3 </a> to open pop3 service for collecting general metrics of POP3 Server (email_count, mailbox_size.). <br>You can click "<i>New POP3</i>" and configure it, or select "<i>More Operations</i>" to import the existing configuration.
zh-TW: HertzBeat 使用 <a class='help_module_content' href='https://www.alibabacloud.com/help/zh/alibaba-mail/latest/how-to-turn-off-or-open-the-pop3-or-imap-protocol-for-accounts'> POP3 </a> 通過开启邮箱 pop3 服务 對 POP3服务器 的通用性能指標(邮件数量、邮箱大小等)進行采集監控。<br>您可以點擊“<i>新建 POP3</i>”並進行配置,或者選擇“<i>更多操作</i>”,導入已有配置。
helpLink:
zh-CN: https://hertzbeat.com/zh-cn/docs/help/pop3
en-US: https://hertzbeat.com/docs/help/pop3
# app api所需输入参数定义(根据定义渲染页面UI)
# Input params define for app api(render web ui by the definition)
params:
# field-param field key
# field-字段名称标识符
- field: host
# name-param field display i18n name
# name-参数字段显示名称
name:
zh-CN: 目标Host
en-US: Target Host
# type-param field type(most mapping the html input type)
# type-字段类型,样式(大部分映射input标签type属性)
type: host
# required-true or false
# 是否是必输项 true-必填 false-可选
required: true
# field-param field key
# field-变量字段标识符
- field: port
# name-param field display i18n name
# name-参数字段显示名称
name:
zh-CN: 端口
en-US: Port
# type-param field type(most mapping the html input type)
# type-字段类型,样式(大部分映射input标签type属性)
type: number
# when type is number, range is required
# 当type为number时,用range表示范围
range: '[0,65535]'
# required-true or false
# required-是否是必输项 true-必填 false-可选
required: true
# default value
# 默认值
defaultValue: 110
# field-param field key
# field-变量字段标识符
- field: timeout
# name-param field display i18n name
# name-参数字段显示名称
name:
zh-CN: 连接超时时间(ms)
en-US: Connect Timeout(ms)
# type-param field type(most mapping the html input type)
# type-字段类型,样式(大部分映射input标签type属性)
type: number
# when type is number, range is required
# 当type为number时,用range表示范围
range: '[0,100000]'
# required-true or false
# 是否是必输项 true-必填 false-可选
required: true
# default value 6000
# 默认值 6000
defaultValue: 6000
- field: ssl
# name-param field display i18n name
# name-参数字段显示名称
name:
zh-CN: 启动SSL
en-US: SSL
# When the type is boolean, the frontend will display a switch for it.
# 当type为boolean时,前端用switch展示开关
type: boolean
# required-true or false
# required-是否是必输项 true-必填 false-可选
required: false
# field-param field key
# field-变量字段标识符
- field: email
# name-param field display i18n name
# name-参数字段显示名称
name:
zh-CN: POP邮箱地址
en-US: Email
# type-param field type(most mapping the html input type) The type "text" belongs to a text input field.
# type-字段类型,样式(大部分映射input标签type属性) text类型属于文本输入框
type: text
# required-true or false
# required-是否是必输项 true-必填 false-可选
required: true
# field-param field key
# field-变量字段标识符
- field: authorize
# name-param field display i18n name
# name-参数字段显示名称
name:
zh-CN: 授权码
en-US: Authorize Code
# type-param field type(most mapping the html input type) The type "text" belongs to a text input field.
# type-字段类型,样式(大部分映射input标签type属性) text类型属于文本输入框
type: text
# required-true or false
# required-是否是必输项 true-必填 false-可选
required: true
# collect metrics config list
# 采集指标配置列表
metrics:
# metrics - available
# 监控指标 - available
- name: available
i18n:
zh-CN: 通用指标
en-US: Available
# metrics scheduling priority(0->127)->(high->low), metrics with the same priority will be scheduled in parallel
# priority 0's metrics is availability metrics, it will be scheduled first, only availability metrics collect success will the scheduling continue
# 指标采集调度优先级(0->127)->(优先级高->低) 优先级低的指标会等优先级高的指标采集完成后才会被调度, 相同优先级的指标会并行调度采集
# 优先级为0的指标为可用性指标,即它会被首先调度,采集成功才会继续调度其它指标,采集失败则中断调度
priority: 0
# collect metrics content
# 具体监控指标列表
fields:
# field-metric name, type-metric type(0-number,1-string), instance-is instance primary key, unit-metric unit
# 指标信息 包括 field名称 type字段类型:0-number数字,1-string字符串 instance是否为实例主键 unit:指标单位
- field: responseTime
type: 0
unit: ms
i18n:
zh-CN: 响应时间
en-US: Response Time
# the protocol used for monitoring, eg: sql, ssh, http, telnet, wmi, snmp, sdk
# 采集协议,目前支持sql,ssh,http,telnet,wmi,snmp,sdk
protocol: pop3
# Specific collection configuration when protocol is http protocol
# 当protocol为http协议时具体的采集配置
pop3:
# http host: ipv4 ipv6 domain
# 主机host: ipv4 ipv6 域名
host: ^_^host^_^
# http port
# 端口
port: ^_^port^_^
# timeout
# 超时时间
timeout: ^_^timeout^_^
# enable SSL/TLS, that is, whether it is http or https, the default is false
# 是否启用ssl/tls,即是http还是https,默认false
ssl: ^_^ssl^_^
# email
# pop邮箱地址
email: ^_^email^_^
# password
# 授权码
authorize: ^_^authorize^_^
- name: email_status
i18n:
zh-CN: 邮箱 状态信息
en-US: Email Status
# metrics scheduling priority(0->127)->(high->low), metrics with the same priority will be scheduled in parallel
# priority 0's metrics is availability metrics, it will be scheduled first, only availability metrics collect success will the scheduling continue
# 指标采集调度优先级(0->127)->(优先级高->低) 优先级低的指标会等优先级高的指标采集完成后才会被调度, 相同优先级的指标会并行调度采集
# 优先级为0的指标为可用性指标,即它会被首先调度,采集成功才会继续调度其它指标,采集失败则中断调度
priority: 1
fields:
- field: email_count
type: 0
i18n:
zh-CN: 邮箱数量
en-US: Email Count
- field: mailbox_size
type: 0
unit: KB
i18n:
zh-CN: 邮箱大小
en-US: MailBox Size
# the protocol used for monitoring, eg: sql, ssh, http, telnet, wmi, snmp, sdk
# 采集协议,目前支持sql,ssh,http,telnet,wmi,snmp,sdk
protocol: pop3
# Specific collection configuration when protocol is http protocol
# 当protocol为http协议时具体的采集配置
pop3:
# http host: ipv4 ipv6 domain
# 主机host: ipv4 ipv6 域名
host: ^_^host^_^
# http port
# 端口
port: ^_^port^_^
# timeout
# 超时时间
timeout: ^_^timeout^_^
# enable SSL/TLS, that is, whether it is http or https, the default is false
# 是否启用ssl/tls,即是http还是https,默认false
ssl: ^_^ssl^_^
# email
# pop邮箱地址
email: ^_^email^_^
# password
# 授权码
authorize: ^_^authorize^_^