add "Plugin Helper: Metrics" page and API specification change

Signed-off-by: Shizuo Fujita <[email protected]>

Author: Watson1978

.gitbook.yaml

@@ -204,6 +204,7 @@ redirects:
   v1.0/articles/api-plugin-helper-storage: developer/api-plugin-helper-storage.md
   v1.0/articles/api-plugin-helper-socket: developer/api-plugin-helper-socket.md
   v1.0/articles/api-plugin-helper-http_server: developer/api-plugin-helper-http_server.md
+  v1.0/articles/api-plugin-helper-metrics: developer/api-plugin-helper-metrics.md
 
   # Obsolete Pages
   v1.0/categories/data-analytics: README.md

SUMMARY.md

@@ -190,6 +190,7 @@
   * [Plugin Helper: Event Loop](plugin-helper-overview/api-plugin-helper-event_loop.md)
   * [Plugin Helper: Extract](plugin-helper-overview/api-plugin-helper-extract.md)
   * [Plugin Helper: Formatter](plugin-helper-overview/api-plugin-helper-formatter.md)
+  * [Plugin Helper: Metrics](plugin-helper-overview/api-plugin-helper-metrics.md)
   * [Plugin Helper: Inject](plugin-helper-overview/api-plugin-helper-inject.md)
   * [Plugin Helper: Parser](plugin-helper-overview/api-plugin-helper-parser.md)
   * [Plugin Helper: Record Accessor](plugin-helper-overview/api-plugin-helper-record_accessor.md)

plugin-helper-overview/README.md

@@ -23,6 +23,7 @@ It will include `Timer`, `Storage`. and `CompatParameters` plugin helpers.
 * [`extract`](api-plugin-helper-extract.md)
 * [`formatter`](api-plugin-helper-formatter.md)
 * [`inject`](api-plugin-helper-inject.md)
+* [`metrics`](api-plugin-helper-metrics.md)
 * [`parser`](api-plugin-helper-parser.md)
 * [`record_accessor`](api-plugin-helper-record_accessor.md)
 * [`server`](api-plugin-helper-server.md)

plugin-helper-overview/api-plugin-helper-metrics.md

@@ -0,0 +1,71 @@
+# Plugin Helper: Metrics
+
+The `metrics` plugin helper manages the metrics values in plugins.
+
+Here is an example:
+
+```ruby
+require 'fluent/plugin/input'
+
+module Fluent::Plugin
+  class ExampleInput < Input
+    Fluent::Plugin.register_input('example', self)
+
+    # 1. Load metrics helper
+    helpers :metrics
+
+    def configure(conf)
+      super
+
+      # 2. Create parser plugin instance
+      @metrics = metrics_create(namespace: "fluentd", subsystem: "input", name: "example", help_text: "Example metrics")
+    end
+
+    def start
+      super
+
+      # 3. Increase metrics value
+      @metrics.inc
+
+    end
+
+    def statistics
+      stats = super
+
+      # 4. Retrieve metrics value
+      stats = {
+        'input' => stats["input"].merge({ 'example' => @metrics.get })
+      }
+      stats
+    end
+end
+```
+
+For more details, see the following articles:
+
+* [Metrics Plugins Overview](../metrics/)
+
+## Methods
+
+### `metrics_create(namespace: "fluentd", subsystem: "metrics", name:, help_text:, labels: {}, prefer_gauge: false)`
+
+This method creates a metrics instance.
+
+* `namespace`: The namespace for the metrics.
+* `subsystem`: The names that represent specific functions or components.
+* `name`: The metrics name.
+* `help_text`: The description for metrics.
+* `labels`: The key/value pair for metrics labels.
+* `prefer_gauge`: Use gauge instead of counter for the metrics if `true`.
+
+Since  1.19.0, `metrics_create` method generates a getter method with the specified `name` on the calling instance.
+
+## Plugins using `metrics`
+
+* [`buffer`](../buffer/)
+* [`filter`](../filter/)
+* [`input`](../input/)
+* [`output`](../output/)
+
+If this article is incorrect or outdated, or omits critical information, please [let us know](https://github.com/fluent/fluentd-docs-gitbook/issues?state=open). [Fluentd](http://www.fluentd.org/) is an open-source project under [Cloud Native Computing Foundation \(CNCF\)](https://cncf.io/). All components are available under the Apache 2 License.
+