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

Co-authored-by: tomsun28 <[email protected]>

collector/src/main/java/org/dromara/hertzbeat/collector/collect/pop3/Pop3CollectImpl.java

@@ -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 failed，Timeout " + 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;
+ }
+}

collector/src/main/java/org/dromara/hertzbeat/collector/dispatch/DispatchConstants.java

@@ -107,6 +107,10 @@ public interface DispatchConstants {
  * protocol dns
  */
  String PROTOCOL_DNS = "dns";
+ /**
+ * protocol pop3
+ */
+ String PROTOCOL_POP3 = "pop3";
 
  // Protocol type related - end
  // 协议类型相关 - end //

collector/src/main/resources/META-INF/services/org.dromara.hertzbeat.collector.collect.AbstractCollect

@@ -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

common/src/main/java/org/dromara/hertzbeat/common/entity/job/Metrics.java

@@ -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

common/src/main/java/org/dromara/hertzbeat/common/entity/job/protocol/Pop3Protocol.java

@@ -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);
+ }
+}

home/docs/help/nginx.md

@@ -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:https://) |
 | 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 |

home/docs/help/pop3.md

@@ -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 Use：POP3**
+
+### 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:https://) |
+| 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 Set：email_status
+
+| Metric name | Metric unit | Metric help description |
+|--------------|-------------|------------------------------------------|
+| email_count | | Number of emails |
+| mailbox_size | kb | The total size of emails in the mailbox |
+
+