feat: add readme for metrics module

Author: fengjiachun

ingester-example/src/main/java/io/greptime/bench/BatchingWriteBenchmark.java

@@ -21,6 +21,7 @@
 import io.greptime.common.util.MetricsUtil;
 import io.greptime.common.util.ServiceLoader;
 import io.greptime.common.util.SystemPropertyUtil;
+import io.greptime.metrics.ExporterOptions;
 import io.greptime.metrics.MetricsExporter;
 import io.greptime.models.Err;
 import io.greptime.models.Result;
@@ -61,8 +62,8 @@ public static void main(String[] args) throws Exception {
         LOG.info("Max points per second: {}", maxPointsPerSecond);
 
         // Start a metrics exporter
-        MetricsExporter metricsExporter = new MetricsExporter(8080, MetricsUtil.metricRegistry());
-        metricsExporter.init(null);
+        MetricsExporter metricsExporter = new MetricsExporter(MetricsUtil.metricRegistry());
+        metricsExporter.init(ExporterOptions.newDefault());
 
         GreptimeDB greptimeDB = DBConnector.connectTo(new String[] {endpoint}, dbName);
 

ingester-example/src/main/java/io/greptime/bench/BulkWriteBenchmark.java

@@ -22,6 +22,7 @@
 import io.greptime.common.util.MetricsUtil;
 import io.greptime.common.util.ServiceLoader;
 import io.greptime.common.util.SystemPropertyUtil;
+import io.greptime.metrics.ExporterOptions;
 import io.greptime.metrics.MetricsExporter;
 import io.greptime.models.Table;
 import io.greptime.models.TableSchema;
@@ -55,8 +56,8 @@ public static void main(String[] args) throws Exception {
         LOG.info("Batch size: {}", batchSize);
 
         // Start a metrics exporter
-        MetricsExporter metricsExporter = new MetricsExporter(8080, MetricsUtil.metricRegistry());
-        metricsExporter.init(null);
+        MetricsExporter metricsExporter = new MetricsExporter(MetricsUtil.metricRegistry());
+        metricsExporter.init(ExporterOptions.newDefault());
 
         GreptimeDB greptimeDB = DBConnector.connectTo(new String[] {endpoint}, dbName);
 

ingester-example/src/main/java/io/greptime/bench/StreamingWriteBenchmark.java

@@ -21,6 +21,7 @@
 import io.greptime.common.util.MetricsUtil;
 import io.greptime.common.util.ServiceLoader;
 import io.greptime.common.util.SystemPropertyUtil;
+import io.greptime.metrics.ExporterOptions;
 import io.greptime.metrics.MetricsExporter;
 import io.greptime.models.Table;
 import io.greptime.models.TableSchema;
@@ -58,8 +59,8 @@ public static void main(String[] args) throws Exception {
         LOG.info("Max points per second: {}", maxPointsPerSecond);
 
         // Start a metrics exporter
-        MetricsExporter metricsExporter = new MetricsExporter(8080, MetricsUtil.metricRegistry());
-        metricsExporter.init(null);
+        MetricsExporter metricsExporter = new MetricsExporter(MetricsUtil.metricRegistry());
+        metricsExporter.init(ExporterOptions.newDefault());
 
         GreptimeDB greptimeDB = DBConnector.connectTo(new String[] {endpoint}, dbName);
 

ingester-prometheus-metrics/README.md

@@ -0,0 +1,52 @@
+# Export Metrics
+
+Monitoring metrics is essential for maintaining a healthy ingester deployment. It enables you to:
+
+- Assess the current state of your ingester
+- Proactively maintain your deployment
+- Quickly diagnose and resolve issues when they arise
+
+For a comprehensive list of available metrics and their descriptions, please refer to our [detailed metrics documentation](../docs/metrics-display.md#list-of-metrics-constantly-updated).
+
+## Start Metrics Exporter
+
+To start an HTTP server that serves Prometheus metrics, initialize the metrics exporter before starting the GreptimeDB ingester:
+
+```java
+    MetricsExporter metricsExporter = new MetricsExporter(MetricsUtil.metricRegistry());
+    metricsExporter.init(ExporterOptions.newDefault());
+    // Start GreptimeDB ingester
+    // ...
+```
+
+## Get Metrics
+
+You can check the output of `curl http://<host>:<port>/metrics` by getting the latest metrics of Ingester.
+
+## Export metrics to Prometheus
+
+Ingester supports exporting metrics to Prometheus. Before configuring export of metrics, you need to setup Prometheus by following their official [documentation](https://prometheus.io/docs/prometheus/latest/installation/).
+
+To scrape metrics from Ingester, write a Prometheus configuration file and save it as `prometheus.yml`:
+
+```yaml
+global:
+  scrape_interval: 15s
+
+scrape_configs:
+  - job_name: 'greptimedb ingester'
+    static_configs:
+      # Assuming that Ingester is running locally.
+      # The default HTTP port of 8090.
+      - targets: ['localhost:8090']
+```
+
+Start Prometheus using the configuration file:
+
+```yaml
+./prometheus --config.file=prometheus.yml
+```
+
+## Grafana Dashboard
+
+You can import dashboard via JSON model: [`greptimedb-ingester-dashboard.json`](../grafana/greptimedb-ingester-dashboard.json)

ingester-prometheus-metrics/src/main/java/io/greptime/metrics/ExporterOptions.java

@@ -0,0 +1,63 @@
+/*
+ * Copyright 2023 Greptime Team
+ *
+ * Licensed 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.
+ */
+
+package io.greptime.metrics;
+
+import io.greptime.common.Copiable;
+
+/**
+ * Exporter options.
+ */
+public class ExporterOptions implements Copiable<ExporterOptions> {
+    private int port;
+    private boolean deamon;
+
+    public static ExporterOptions newDefault() {
+        ExporterOptions opts = new ExporterOptions();
+        opts.port = 8090;
+        opts.deamon = true;
+        return opts;
+    }
+
+    public int getPort() {
+        return port;
+    }
+
+    public void setPort(int port) {
+        this.port = port;
+    }
+
+    public boolean isDeamon() {
+        return deamon;
+    }
+
+    public void setDeamon(boolean deamon) {
+        this.deamon = deamon;
+    }
+
+    @Override
+    public ExporterOptions copy() {
+        ExporterOptions opts = new ExporterOptions();
+        opts.port = this.port;
+        opts.deamon = this.deamon;
+        return opts;
+    }
+
+    @Override
+    public String toString() {
+        return "ExporterOptions{" + "port=" + port + ", deamon=" + deamon + '}';
+    }
+}

ingester-prometheus-metrics/src/main/java/io/greptime/metrics/MetricsExporter.java

@@ -27,29 +27,30 @@
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
-public class MetricsExporter implements Lifecycle<Void> {
+public class MetricsExporter implements Lifecycle<ExporterOptions> {
 
     private static final Logger LOG = LoggerFactory.getLogger(MetricsExporter.class);
 
     private final CollectorRegistry prometheusMetricRegistry;
 
-    private final int port;
     private HTTPServer server;
+    private ExporterOptions opts;
 
     private final AtomicBoolean started = new AtomicBoolean(false);
 
-    public MetricsExporter(int port, MetricRegistry dropwizardMetricRegistry) {
-        this.port = port;
+    public MetricsExporter(MetricRegistry dropwizardMetricRegistry) {
         this.prometheusMetricRegistry = new CollectorRegistry();
         this.prometheusMetricRegistry.register(new DropwizardExports(dropwizardMetricRegistry));
     }
 
     @Override
-    public boolean init(Void opts) {
+    public boolean init(ExporterOptions opts) {
         if (this.started.compareAndSet(false, true)) {
+            this.opts = opts;
             try {
-                this.server = new HTTPServer(new InetSocketAddress(this.port), this.prometheusMetricRegistry, true);
-                LOG.info("Metrics exporter started at `http://localhost:{}/metrics`", this.port);
+                this.server = new HTTPServer(
+                        new InetSocketAddress(opts.getPort()), this.prometheusMetricRegistry, opts.isDeamon());
+                LOG.info("Metrics exporter started at `http://localhost:{}/metrics`", opts.getPort());
                 return true;
             } catch (IOException e) {
                 this.started.set(false);
@@ -69,4 +70,9 @@ public void shutdownGracefully() {
             }
         }
     }
+
+    @Override
+    public String toString() {
+        return "MetricsExporter{" + "opts=" + opts + '}';
+    }
 }