feature: support monitoring pop3 metrics and add help doc

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
+ * @author a-little-fool
+ */
+@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://)                                                                                |
 | 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://)                                                                                |
+| 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  |
+
+