Merge pull request #347 from cosmo0920/1.0-metrics-plugin

1.0: Add metrics plugin descriptions

Author: kenhys

SUMMARY.md

@@ -122,6 +122,8 @@
   * [static](service_discovery/static.md)
   * [file](service_discovery/file.md)
   * [srv](service_discovery/srv.md)
+* [Metrics Plugins](metrics/README.md)
+  * [local](metrics/local.md)
 * [How-to Guides](how-to-guides/README.md)
   * [Stream Analytics with Materialize](how-to-guides/stream-analytics-with-materialize.md)
   * [Send Apache Logs to S3](how-to-guides/apache-to-s3.md)

buffer/README.md

@@ -1,6 +1,6 @@
 # Buffer Plugins
 
-Fluentd has eight \(8\) types of plugins:
+Fluentd has nine \(9\) types of plugins:
 
 * [Input](../input/)
 * [Parser](../parser/)
@@ -10,6 +10,7 @@ Fluentd has eight \(8\) types of plugins:
 * [Storage](../storage/)
 * [Service Discovery](../service_discovery/)
 * [Buffer](./)
+* [Metrics](../metrics/)
 
 This article gives an overview of Buffer Plugin.
 

filter/README.md

@@ -1,6 +1,6 @@
 # Filter Plugins
 
-Fluentd has eight \(8\) types of plugins:
+Fluentd has nine \(9\) types of plugins:
 
 * [Input](../input/)
 * [Parser](../parser/)
@@ -10,6 +10,7 @@ Fluentd has eight \(8\) types of plugins:
 * [Storage](../storage/)
 * [Service Discovery](../service_discovery/)
 * [Buffer](../buffer/)
+* [Metrics](../metrics/)
 
 This article gives an overview of the Filter Plugin.
 

formatter/README.md

@@ -1,6 +1,6 @@
 # Formatter Plugins
 
-Fluentd has eight \(8\) types of plugins:
+Fluentd has nine \(9\) types of plugins:
 
 * [Input](../input/)
 * [Parser](../parser/)
@@ -10,6 +10,7 @@ Fluentd has eight \(8\) types of plugins:
 * [Storage](../storage/)
 * [Service Discovery](../service_discovery/)
 * [Buffer](../buffer/)
+* [Metrics](../metrics/)
 
 This article gives an overview of the Formatter Plugin.
 

input/README.md

@@ -1,6 +1,6 @@
 # Input Plugins
 
-Fluentd has eight \(8\) types of plugins:
+Fluentd has nine \(9\) types of plugins:
 
 * [Input](./)
 * [Parser](../parser/)
@@ -10,6 +10,7 @@ Fluentd has eight \(8\) types of plugins:
 * [Storage](../storage/)
 * [Service Discovery](../service_discovery/)
 * [Buffer](../buffer/)
+* [Metrics](../metrics/)
 
 This article gives an overview of the Input Plugin.
 

metrics/README.md

@@ -0,0 +1,58 @@
+# Metrics Plugins
+
+Fluentd has nine \(9\) types of plugins:
+
+* [Input](../input/)
+* [Parser](../parser/)
+* [Filter](../filter/)
+* [Output](../output/)
+* [Formatter](../formatter/)
+* [Storage](../storage)
+* [Service Discovery](../service_discovery/)
+* [Buffer](../buffer/)
+* [Metrics](./)
+
+This article gives an overview of Metrics Plugin.
+
+## Overview
+
+Sometimes, the input/filter/output plugin needs to save its internal metrics in memory, influxdb or prometheus format ready in instances. Fluentd has a pluggable system called Metrics that lets a plugin store and reuse its internal state as metrics instances.
+
+## How To Use
+
+On Fluentd core, metrics plugin will handled on `<metrics>` on `<system>` to set up easily.
+
+Here is an example with `metrics_local`:
+
+```text
+<system>
+  <metrics>
+    @type local
+  </metrics>
+</system>
+```
+
+`local` type plugin should provide equivalent behavior before Fluentd v1.13.
+This metrics type should provide single numeric value storing functionality.
+
+And this `local` type plugin should be used by default.
+
+## List of Built-in Metrics Plugins
+
+* [`local`](local.md)
+
+## List of Base Plugin classes with Metrics support
+
+* `Fluent::Plugin::Input` for Input plugin base class
+* `Fluent::Plugin::Output` for most of output plugin base class
+* `Fluent::Plugin::Filter` for Filter plugin base class
+* `Fluent::Plugin::MultiOutput` for [out_copy](../output/copy.md) plugin base class
+* `Fluent::Plugin::BareOutput` for fluent-plugin-forest output plugin base class
+
+## List of 3rd party metrics plugins
+
+NOTE: This 3rd party metrics plugin list does not fully covers all of them.
+
+* [fluent-plugin-metrics-cmetrics](https://github.com/calyptia/fluent-plugin-metrics-cmetrics)
+
+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.

metrics/local.md

@@ -0,0 +1,32 @@
+# local
+
+The `local` metrics plugin stores the values on memory.
+
+## Parameters
+
+### `default_labels`
+
+Specifies the default labels for the metrics. \(default: `{agent: "Fluentd", hostname: "#{Socket.gethostname}"}`\)
+
+### `labels`
+
+Specifies other custom labels for the metrics. \(default: `{}`\)
+
+## Example
+
+With this configuration:
+
+```text
+<system>
+  <metrics>
+    @type local
+  </metrics>
+</system>
+```
+
+The above configuration will save the internal metrics for plugins on memory. As a result, you can retrive metrics from memory and also you can replace with your custom metrics plugin.
+
+Actually, @type local metrics plugin has equivalent functionality for previous single value based Ruby instance variables.
+This behavior will be changed by other 3rd party plugins.
+
+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.

output/README.md

@@ -1,6 +1,6 @@
 # Output Plugins
 
-Fluentd has eight \(8\) types of plugins:
+Fluentd has nine \(9\) types of plugins:
 
 * [Input](../input/)
 * [Parser](../parser/)
@@ -10,6 +10,7 @@ Fluentd has eight \(8\) types of plugins:
 * [Storage](../storage/)
 * [Service Discovery](../service_discovery/)
 * [Buffer](../buffer/)
+* [Metrics](../metrics/)
 
 This article gives an overview of the Output Plugin.
 

parser/README.md

@@ -1,6 +1,6 @@
 # Parser Plugins
 
-Fluentd has eight \(8\) types of plugins:
+Fluentd has nine \(9\) types of plugins:
 
 * [Input](../input/)
 * [Parser](./)
@@ -10,6 +10,7 @@ Fluentd has eight \(8\) types of plugins:
 * [Storage](../storage/)
 * [Service Discovery](../service_discovery/)
 * [Buffer](../buffer/)
+* [Metrics](../metrics/)
 
 This article gives an overview of the Parser Plugin.
 

service_discovery/README.md

@@ -1,6 +1,6 @@
 # Service Discovery Plugins
 
-Fluentd has eight \(8\) types of plugins:
+Fluentd has nine \(9\) types of plugins:
 
 * [Input](../input/)
 * [Parser](../parser/)
@@ -10,6 +10,7 @@ Fluentd has eight \(8\) types of plugins:
 * [Storage](../storage/)
 * [Service Discovery](./)
 * [Buffer](../buffer/)
+* [Metrics](../metrics/)
 
 This article gives an overview of the Service Discovery Plugin.