update sphinx doc

.github/workflows/sphinx.yml

@@ -22,6 +22,7 @@ jobs:
           - g3proxy
           - g3tiles
           - g3keymess
+          - g3statsd
     steps:
       - uses: actions/checkout@v4
       - run: |

Cargo.lock

@@ -470,9 +470,9 @@ dependencies = [
 
 [[package]]
 name = "cc"
-version = "1.2.22"
+version = "1.2.23"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "32db95edf998450acc7881c932f94cd9b05c87b4b2599e8bab064753da4acfd1"
+checksum = "5f4ac86a9e5bc1e2b3449ab9d7d3a6a405e3d1bb28d7b9be8614f55846ae3766"
 dependencies = [
  "shlex",
 ]

g3statsd/src/config/mod.rs

@@ -68,6 +68,7 @@ fn load_doc(map: &yaml::Hash) -> anyhow::Result<()> {
     g3_yaml::foreach_kv(map, |k, v| match g3_yaml::key::normalize(k).as_str() {
         "runtime" => g3_daemon::runtime::config::load(v),
         "worker" => g3_daemon::runtime::config::load_worker(v),
+        "controller" => g3_daemon::control::config::load(v),
         "importer" => importer::load_all(v, conf_dir),
         "collector" => collector::load_all(v, conf_dir),
         "exporter" => exporter::load_all(v, conf_dir),

g3statsd/src/runtime/export/stream/config.rs

@@ -54,7 +54,7 @@ impl StreamExportConfig {
 
     pub(crate) fn set_by_yaml_kv(&mut self, k: &str, v: &Yaml) -> anyhow::Result<()> {
         match g3_yaml::key::normalize(k).as_str() {
-            "server" => {
+            "host" | "server" => {
                 self.server = g3_yaml::value::as_host(v)?;
                 Ok(())
             }

sphinx/conf.py

@@ -15,6 +15,9 @@ multiproject_projects = {
     "g3tiles": {
         "path": "g3tiles",
     },
+    "g3statsd": {
+        "path": "g3statsd",
+    },
     "g3keymess": {
         "path": "g3keymess",
     },

sphinx/g3keymess/configuration/server.rst

@@ -9,7 +9,7 @@ The following keys are supported in a single keyless server:
 name
 ----
 
-**required**, **type**: :ref:`metrics name <conf_value_metrics_name>`
+**required**, **type**: :ref:`metric node name <conf_value_metric_node_name>`
 
 Set the name of the server.
 

sphinx/g3keymess/configuration/stores/index.rst

@@ -28,7 +28,7 @@ This section describes the common keys, they may be used by many stores.
 
 .. _conf_store_common_name:
 
-**required**, **type**: :ref:`metrics name <conf_value_metrics_name>`
+**required**, **type**: :ref:`metric node name <conf_value_metric_node_name>`
 
 Set the name of the discover.
 

sphinx/g3keymess/configuration/values/metrics.rst

@@ -4,10 +4,10 @@
 Metrics
 *******
 
-.. _conf_value_metrics_value:
+.. _conf_value_metric_value:
 
-metrics value
-=============
+metric value
+============
 
 **yaml value**: limited str
 
@@ -19,6 +19,24 @@ The character range is the same as `OpenTSDB metrics-and-tags`_.
 
 .. _OpenTSDB metrics-and-tags: http://opentsdb.net/docs/build/html/user_guide/writing/index.html#metrics-and-tags
 
+.. _conf_value_metric_tag_name:
+
+metric tag name
+===============
+
+**yaml value**: :ref:`metric value <conf_value_metric_value>`
+
+Set a metric tag name, which should not be empty.
+
+.. _conf_value_metric_tag_value:
+
+metric tag value
+================
+
+**yaml value**: :ref:`metric value <conf_value_metric_value>`
+
+Set a metric tag value, which may be empty according to the context.
+
 .. _conf_value_static_metrics_tags:
 
 static metrics tags
@@ -26,16 +44,15 @@ static metrics tags
 
 **yaml value**: map
 
-This should be a map, each key will be the tag name, and it's value will be the tag value.
+The key should be :ref:`metric tag name <conf_value_metric_tag_name>`.
+The value should be :ref:`metric tag value <conf_value_metric_tag_value>`.
 
-The tag name and the tag value should be of type :ref:`metrics value <conf_value_metrics_value>`.
+.. _conf_value_metric_node_name:
 
-.. _conf_value_metrics_name:
+metric node name
+================
 
-metrics name
-============
-
-**yaml value**: :ref:`metrics value <conf_value_metrics_value>`
+**yaml value**: :ref:`metric value <conf_value_metric_value>`
 
 The metrics name
 
@@ -151,7 +168,7 @@ The key *unix* is just handled as *target_unix* as above.
 prefix
 ------
 
-**optional**, **type**: :ref:`metrics name <conf_value_metrics_name>`
+**optional**, **type**: :ref:`metric node name <conf_value_metric_node_name>`
 
 Set the global prefix for all metrics.
 

sphinx/g3keymess/configuration/values/network.rst

@@ -45,6 +45,15 @@ ip addr str
 
 The string should be in *<ip>* format.
 
+.. _conf_value_interface_name:
+
+interface name
+==============
+
+**yaml value**: str | u32
+
+The string should be a network interface name or index.
+
 .. _conf_value_host:
 
 host
@@ -71,6 +80,16 @@ It consists of the following fields:
 
   **default**: [::]:0, which has empty port
 
+* interface
+
+  **optional**: **type**: :ref:`interface name <conf_value_interface_name>`
+
+  Bind the outgoing socket to a particular device like “eth0”.
+
+  **default**: not set
+
+  .. versionadded:: 0.4.2
+
 * backlog
 
   **optional**, **type**: unsigned int

sphinx/g3proxy/configuration/auditors/index.rst

@@ -9,7 +9,7 @@ The type for each auditor config is *map*, the keys are as follows:
 name
 ----
 
-**required**, **type**: :ref:`metrics name <conf_value_metrics_name>`
+**required**, **type**: :ref:`metric node name <conf_value_metric_node_name>`
 
 Set the auditor name, which will can be referenced in :ref:`server config <conf_server_common_auditor>`.
 

sphinx/g3proxy/configuration/escapers/index.rst

@@ -47,7 +47,7 @@ This section describes the common keys, they may be used by many escapers.
 name
 ----
 
-**required**, **type**: :ref:`metrics name <conf_value_metrics_name>`
+**required**, **type**: :ref:`metric node name <conf_value_metric_node_name>`
 
 Set the name of the escaper.
 
@@ -76,7 +76,7 @@ Set the escaper to use a logger running on a shared thread.
 resolver
 --------
 
-**type**: str
+**type**: :ref:`metric node name <conf_value_metric_node_name>`
 
 Set the resolver to use for this escaper.
 
@@ -126,8 +126,6 @@ bind_interface
 
 Bind the outgoing socket to a particular device like “eth0”.
 
-.. note:: This is only supported on Linux based OS.
-
 **default**: not set
 
 .. versionadded:: 1.9.9

sphinx/g3proxy/configuration/escapers/route_client.rst

@@ -24,7 +24,7 @@ Each rule is in *map* format, with two keys:
 
 * next
 
-  **required**, **type**: str
+  **required**, **type**: :ref:`metric node name <conf_value_metric_node_name>`
 
   Set the next escaper.
 
@@ -47,7 +47,7 @@ Each rule is in *map* format, with two keys:
 
 * next
 
-  **required**, **type**: str
+  **required**, **type**: :ref:`metric node name <conf_value_metric_node_name>`
 
   Set the next escaper.
 

sphinx/g3proxy/configuration/escapers/route_failover.rst

@@ -19,14 +19,14 @@ No common keys are supported.
 primary_next
 ------------
 
-**required**, **type**: str
+**required**, **type**: :ref:`metric node name <conf_value_metric_node_name>`
 
 Set the primary next escaper to be used.
 
 standby_next
 ------------
 
-**required**, **type**: str
+**required**, **type**: :ref:`metric node name <conf_value_metric_node_name>`
 
 Set the standby next escaper to be used.
 

sphinx/g3proxy/configuration/escapers/route_geoip.rst

@@ -37,7 +37,7 @@ Each rule is in *map* format, with the following keys:
 
 * next
 
-  **required**, **type**: str
+  **required**, **type**: :ref:`metric node name <conf_value_metric_node_name>`
 
   Set the next escaper.
 

sphinx/g3proxy/configuration/escapers/route_mapping.rst

@@ -18,7 +18,7 @@ No common keys are supported.
 next
 ----
 
-**required**, **type**: seq
+**required**, **type**: :ref:`metric node name <conf_value_metric_node_name>`
 
 This set all the next escapers. Each element should be the name of the target float escaper.
 

sphinx/g3proxy/configuration/escapers/route_query.rst

@@ -14,14 +14,14 @@ No common keys are supported.
 fallback_node
 -------------
 
-**required**, **type**: string
+**required**, **type**: :ref:`metric node name <conf_value_metric_node_name>`
 
 Set the fallback escaper name.
 
 query_allowed_next
 ------------------
 
-**required**, **type**: seq
+**required**, **type**: :ref:`metric node name <conf_value_metric_node_name>`
 
 Set all the next escapers those are allowed to use in the query result. Each element should be the next escaper name.
 If the selected escaper name is not found in this list, the fallback escaper will be used.

sphinx/g3proxy/configuration/escapers/route_resolved.rst

@@ -26,7 +26,7 @@ Each rule is in *map* format, with two keys:
 
 * next
 
-  **required**, **type**: str
+  **required**, **type**: :ref:`metric node name <conf_value_metric_node_name>`
 
   Set the next escaper.
 

sphinx/g3proxy/configuration/escapers/route_select.rst

@@ -24,12 +24,10 @@ No common keys are supported.
 next_nodes
 ----------
 
-**required**, **type**: string | seq
+**required**, **type**: :ref:`weighted metric node name <conf_value_weighted_metric_node_name>` | seq
 
 Set the next escaper(s) those can be selected.
 
-For *seq* value, each of its element must be :ref:`weighted metrics name <conf_value_weighted_metrics_name>`.
-
 .. _conf_escaper_route_select_next_pick_policy:
 
 next_pick_policy

sphinx/g3proxy/configuration/escapers/route_upstream.rst

@@ -24,7 +24,7 @@ For seq format:
 
   * next
 
-    **required**, **type**: str
+    **required**, **type**: :ref:`metric node name <conf_value_metric_node_name>`
 
     Set the next escaper.
 
@@ -75,7 +75,7 @@ For seq format:
 
   * next
 
-    **required**, **type**: str
+    **required**, **type**: :ref:`metric node name <conf_value_metric_node_name>`
 
     Set the next escaper.
 
@@ -126,7 +126,7 @@ For seq format:
 
   * next
 
-    **required**, **type**: str
+    **required**, **type**: :ref:`metric node name <conf_value_metric_node_name>`
 
     Set the next escaper.
 
@@ -178,7 +178,7 @@ For seq format:
 
   * next
 
-    **required**, **type**: str
+    **required**, **type**: :ref:`metric node name <conf_value_metric_node_name>`
 
     Set the next escaper.
 
@@ -230,7 +230,7 @@ For seq format:
 
   * next
 
-    **required**, **type**: str
+    **required**, **type**: :ref:`metric node name <conf_value_metric_node_name>`
 
     Set the next escaper.
 

sphinx/g3proxy/configuration/escapers/trick_float.rst

@@ -10,7 +10,7 @@ No common keys are supported.
 next
 ----
 
-**required**, **type**: seq
+**required**, **type**: :ref:`metric node name <conf_value_metric_node_name>` | seq
 
 This set all the next escapers. Each element should be the name of the target float escaper.
 

sphinx/g3proxy/configuration/resolvers/index.rst

@@ -34,7 +34,7 @@ Most of them are the runtime (of the standalone resolver thread) config.
 name
 ----
 
-**required**, **type**: :ref:`metrics name <conf_value_metrics_name>`
+**required**, **type**: :ref:`metric node name <conf_value_metric_node_name>`
 
 Set the name of the resolver.
 

sphinx/g3proxy/configuration/servers/index.rst

@@ -41,7 +41,7 @@ This section describes the common keys, they may be used by many servers.
 name
 ----
 
-**required**, **type**: :ref:`metrics name <conf_value_metrics_name>`
+**required**, **type**: :ref:`metric node name <conf_value_metric_node_name>`
 
 Set the name of the server.
 
@@ -59,7 +59,7 @@ Set the type of the server.
 escaper
 -------
 
-**required**, **type**: str
+**required**, **type**: :ref:`metric node name <conf_value_metric_node_name>`
 
 Set the escaper to use with this server.
 
@@ -70,7 +70,7 @@ If the specified escaper doesn't exist in configure, a default DummyDeny escaper
 auditor
 -------
 
-**optional**, **type**: str
+**optional**, **type**: :ref:`metric node name <conf_value_metric_node_name>`
 
 Set the auditor to use with this server.
 
@@ -83,7 +83,7 @@ If the specified auditor doesn't exist in configure, a default auditor will be u
 user_group
 ----------
 
-**optional**, **type**: str
+**optional**, **type**: :ref:`metric node name <conf_value_metric_node_name>`
 
 Set the user group for auth.
 

sphinx/g3proxy/configuration/user_group/index.rst

@@ -6,8 +6,17 @@ User Group
 
 The type for each user group config is *map*, with two always required keys:
 
-* *name*, which specify the name of the user group.
-* *type*, which specify the real type of the user group, decides how to parse other keys.
+* name
+
+  **type**: :ref:`metric node name <conf_value_metric_node_name>`
+
+  The name of the user group.
+
+* type
+
+  **type**: str
+
+  The real type of the user group, decides how to parse other keys.
 
 For now, we only support *hashed_user* type of user group. We may add a *gss_api* type after sometime.
 

sphinx/g3proxy/configuration/user_group/site.rst

@@ -14,7 +14,7 @@ site level config.
 id
 --
 
-**required**, **type**: :ref:`metrics name <conf_value_metrics_name>`
+**required**, **type**: :ref:`metric node name <conf_value_metric_node_name>`
 
 Each site should have an ID, and it will be used in metrics name if enabled.
 

sphinx/g3proxy/configuration/values/metrics.rst

@@ -5,10 +5,10 @@
 Metrics
 *******
 
-.. _conf_value_metrics_value:
+.. _conf_value_metric_value:
 
-metrics value
-=============
+metric value
+============
 
 **yaml value**: limited str
 
@@ -20,6 +20,24 @@ The character range is the same as `OpenTSDB metrics-and-tags`_.
 
 .. _OpenTSDB metrics-and-tags: http://opentsdb.net/docs/build/html/user_guide/writing/index.html#metrics-and-tags
 
+.. _conf_value_metric_tag_name:
+
+metric tag name
+===============
+
+**yaml value**: :ref:`metric value <conf_value_metric_value>`
+
+Set a metric tag name, which should not be empty.
+
+.. _conf_value_metric_tag_value:
+
+metric tag value
+================
+
+**yaml value**: :ref:`metric value <conf_value_metric_value>`
+
+Set a metric tag value, which may be empty according to the context.
+
 .. _conf_value_static_metrics_tags:
 
 static metrics tags
@@ -27,25 +45,24 @@ static metrics tags
 
 **yaml value**: map
 
-This should be a map, each key will be the tag name, and it's value will be the tag value.
+The key should be :ref:`metric tag name <conf_value_metric_tag_name>`.
+The value should be :ref:`metric tag value <conf_value_metric_tag_value>`.
 
-The tag name and the tag value should be of type :ref:`metrics value <conf_value_metrics_value>`.
+.. _conf_value_metric_node_name:
 
-.. _conf_value_metrics_name:
+metric node name
+================
 
-metrics name
-============
-
-**yaml value**: :ref:`metrics value <conf_value_metrics_value>`
+**yaml value**: :ref:`metrics value <conf_value_metric_value>`
 
 The metrics name
 
-.. _conf_value_weighted_metrics_name:
+.. _conf_value_weighted_metric_node_name:
 
-weighted metrics name
-=====================
+weighted metric node name
+=========================
 
-**yaml value**: map | :ref:`metrics name <conf_value_metrics_name>`
+**yaml value**: map | :ref:`metric node name <conf_value_metric_node_name>`
 
 A metrics name with weight set, which make can be grouped into selective vector.
 
@@ -53,7 +70,7 @@ The map consists 2 fields:
 
 * name
 
-  **required**, **type**: :ref:`metrics name <conf_value_metrics_name>`
+  **required**, **type**: :ref:`metric node name <conf_value_metric_node_name>`
 
   The name. The meaning of the name is depending on the config context.
 
@@ -184,7 +201,7 @@ The key *unix* is just handled as *target_unix* as above.
 prefix
 ------
 
-**optional**, **type**: :ref:`metrics name <conf_value_metrics_name>`
+**optional**, **type**: :ref:`metric node name <conf_value_metric_node_name>`
 
 Set the global prefix for all metrics.
 

sphinx/g3proxy/configuration/values/network.rst

@@ -280,6 +280,16 @@ It consists of the following fields:
 
   **default**: [::]:0, which has empty port
 
+* interface
+
+  **optional**: **type**: :ref:`interface name <conf_value_interface_name>`
+
+  Bind the outgoing socket to a particular device like “eth0”.
+
+  **default**: not set
+
+  .. versionadded:: 1.11.6
+
 * backlog
 
   **optional**, **type**: unsigned int
@@ -422,6 +432,16 @@ It consists of the following fields:
 
   **default**: [::]:0, which has empty port
 
+* interface
+
+  **optional**: **type**: :ref:`interface name <conf_value_interface_name>`
+
+  Bind the outgoing socket to a particular device like “eth0”.
+
+  **default**: not set
+
+  .. versionadded:: 1.11.6
+
 * ipv6_only
 
   **optional**, **type**: bool

sphinx/g3proxy/protocol/helper/route_query.rst

@@ -64,7 +64,7 @@ nodes
 
 Set the next escaper(s) those can be selected.
 
-For *seq* value, each of its element must be :ref:`weighted metrics name <conf_value_weighted_metrics_name>`.
+For *seq* value, each of its element must be :ref:`weighted metric node name <conf_value_weighted_metric_node_name>`.
 
 If empty, the :ref:`fallback node <configuration_escaper_route_query_fallback_node>` escaper config will take effect.
 

sphinx/g3statsd/.gitignore

@@ -0,0 +1 @@
+_build

sphinx/g3statsd/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

sphinx/g3statsd/conf.py

@@ -0,0 +1,33 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'g3statsd'
+copyright = '2025, Zhang Jingqiang'
+author = 'Zhang Jingqiang'
+release = '0.1.0'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = []
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'sphinx_rtd_theme'
+html_static_path = ['_static']
+
+# -- Custom Options ----------------------------------------------------------
+
+# Set the master document, which contains the root toctree directive.
+# The default changed from 'contents' to 'index' from sphinx version 2.0,
+# so we need to explicitly set it in order to be compatible with old versions.
+master_doc = 'index'

sphinx/g3statsd/configuration/collector/aggregate.rst

@@ -0,0 +1,27 @@
+.. _configuration_collector_aggregate:
+
+aggregate
+=========
+
+A collector to aggregate metrics.
+
+The following common keys are supported:
+
+* :ref:`next <conf_collector_common_next>`
+* :ref:`exporter <conf_collector_common_exporter>`
+
+emit_interval
+-------------
+
+**optional**, **type**: :ref:`humanize duration <conf_value_humanize_duration>`
+
+Set the time interval to emit internal metrics.
+
+**default**: 1s
+
+join_tags
+---------
+
+**optional**, **type**: :ref:`metric tag name <conf_value_metric_tag_name>` | seq
+
+Set the tag(s) used to join metrics after aggregated together.

sphinx/g3statsd/configuration/collector/discard.rst

@@ -0,0 +1,8 @@
+.. _configuration_collector_discard:
+
+discard
+=======
+
+This is the discard collector designed to discard all received metrics from importer.
+
+There are no extra config keys for this kind of collector.

sphinx/g3statsd/configuration/collector/index.rst

@@ -0,0 +1,68 @@
+.. _configuration_collector:
+
+*********
+Collector
+*********
+
+The type for each collector config is *map*, with two always required keys:
+
+* :ref:`name <conf_collector_common_name>`, which specify the name of the collector.
+* :ref:`type <conf_collector_common_type>`, which specify the real type of the collector, decides how to parse other keys.
+
+There are many types of collector, each with a section below.
+
+Collectors
+==========
+
+.. toctree::
+   :maxdepth: 1
+
+   aggregate
+   discard
+   internal
+   regulate
+
+Common Keys
+===========
+
+This section describes the common keys, they may be used by many collectors.
+
+.. _conf_collector_common_name:
+
+name
+----
+
+**required**, **type**: :ref:`metric node name <conf_value_metric_node_name>`
+
+Set the name of the collector.
+
+.. _conf_collector_common_type:
+
+type
+----
+
+**required**, **type**: str
+
+Set the type of the collector.
+
+.. _conf_collector_common_next:
+
+next
+----
+
+**type**: :ref:`metric node name <conf_value_metric_node_name>`
+
+Set the next collector to use.
+
+If the specified collector doesn't exist in configure, a default Discard collector will be used.
+
+.. _conf_collector_common_exporter:
+
+exporter
+--------
+
+**type**: :ref:`metric node name <conf_value_metric_node_name>` | seq
+
+Set the exporter(s) to use.
+
+If the specified exporter doesn't exist in configure, a default Discard exporter will be used.

sphinx/g3statsd/configuration/collector/internal.rst

@@ -0,0 +1,20 @@
+.. _configuration_collector_internal:
+
+internal
+========
+
+A collector to collect internal metrics.
+
+The following common keys are supported:
+
+* :ref:`next <conf_collector_common_next>`
+* :ref:`exporter <conf_collector_common_exporter>`
+
+emit_interval
+-------------
+
+**optional**, **type**: :ref:`humanize duration <conf_value_humanize_duration>`
+
+Set the time interval to emit internal metrics.
+
+**default**: 1s

sphinx/g3statsd/configuration/collector/regulate.rst

@@ -0,0 +1,25 @@
+.. _configuration_collector_regulate:
+
+regulate
+========
+
+A collector to regulate metrics.
+
+The following common keys are supported:
+
+* :ref:`next <conf_collector_common_next>`
+* :ref:`exporter <conf_collector_common_exporter>`
+
+prefix
+------
+
+**optional**, **type**: :ref:`metric name prefix <conf_value_metric_name_prefix>`
+
+Set the prefix to add to all metric names.
+
+drop_tags
+---------
+
+**optional**, **type**: :ref:`metric tag name <conf_value_metric_tag_name>` | seq
+
+Set the tag(s) to drop.

sphinx/g3statsd/configuration/exporter/console.rst

@@ -0,0 +1,8 @@
+.. _configuration_exporter_console:
+
+console
+=======
+
+This is the console exporter designed to log all received metrics from collector to stdout.
+
+There are no extra config keys for this kind of exporter.

sphinx/g3statsd/configuration/exporter/discard.rst

@@ -0,0 +1,8 @@
+.. _configuration_exporter_discard:
+
+discard
+=======
+
+This is the discard exporter designed to discard all received metrics from collector.
+
+There are no extra config keys for this kind of exporter.

sphinx/g3statsd/configuration/exporter/graphite.rst

@@ -0,0 +1,25 @@
+.. _configuration_exporter_graphite:
+
+graphite
+========
+
+Emit all metrics from collector to graphite by using the plaintext protocol.
+
+The following common keys are supported:
+
+* :ref:`prefix <conf_exporter_common_prefix>`
+* :ref:`global_tags <conf_exporter_common_global_tags>`
+
+The :ref:`Stream Export Runtime <configuration_exporter_runtime_stream>` is used:
+
+- default port 2003
+- all config keys supported
+
+emit_interval
+-------------
+
+**optional**, **type**: :ref:`humanize duration <conf_value_humanize_duration>`
+
+Set the time interval to emit internal metrics.
+
+**default**: 10s

sphinx/g3statsd/configuration/exporter/index.rst

@@ -0,0 +1,166 @@
+********
+Exporter
+********
+
+The type for each exporter config is *map*, with two always required keys:
+
+* :ref:`name <conf_exporter_common_name>`, which specify the name of the exporter.
+* :ref:`type <conf_exporter_common_type>`, which specify the real type of the exporter, decides how to parse other keys.
+
+There are many types of exporter, each with a section below.
+
+Exporters
+=========
+
+.. toctree::
+   :maxdepth: 1
+
+   console
+   discard
+   graphite
+   influxdb_v2
+   influxdb_v3
+   memory
+   opentsdb
+
+Common Keys
+===========
+
+This section describes the common keys, they may be used by many exporters.
+
+.. _conf_exporter_common_name:
+
+name
+----
+
+**required**, **type**: :ref:`metric node name <conf_value_metric_node_name>`
+
+Set the name of the exporter.
+
+.. _conf_exporter_common_type:
+
+type
+----
+
+**required**, **type**: str
+
+Set the type of the exporter.
+
+.. _conf_exporter_common_prefix:
+
+prefix
+------
+
+**optional**, **type**: :ref:`metric name prefix <conf_value_metric_name_prefix>`
+
+Set the prefix to add to all metric names.
+
+.. _conf_exporter_common_global_tags:
+
+global_tags
+-----------
+
+**optional**, **type**: :ref:`static metrics tags <conf_value_static_metrics_tags>`
+
+Set the tags to add to all metrics.
+
+Export Runtimes
+===============
+
+Export runtime is the loop runtime to emit metrics at the given `emit_interval`.
+
+.. _configuration_exporter_runtime_stream:
+
+Stream Export Runtime
+---------------------
+
+host
+^^^^
+
+**required**, **type**: :ref:`host <conf_value_host>`
+
+Set the peer host name.
+
+port
+^^^^
+
+**required**, **type**: u16
+
+Set the port of the peer server.
+
+**default**: each exporter will set a default port value
+
+resolve_retry_wait
+^^^^^^^^^^^^^^^^^^
+
+**optional**, **type**: :ref:`humanize duration <conf_value_humanize_duration>`
+
+Set how many time to wait before next connect after resolve error.
+
+**default**: 30s
+
+connect_retry_wait
+^^^^^^^^^^^^^^^^^^
+
+**optional**, **type**: :ref:`humanize duration <conf_value_humanize_duration>`
+
+Set how many time to wait before next connect after connect error.
+
+**default**: 10s
+
+.. _configuration_exporter_runtime_http:
+
+HTTP Export Runtime
+-------------------
+
+host
+^^^^
+
+**required**, **type**: :ref:`host <conf_value_host>`
+
+Set the peer host name.
+
+port
+^^^^
+
+**required**, **type**: u16
+
+Set the port of the peer server.
+
+**default**: each exporter will set a default port value
+
+resolve_retry_wait
+^^^^^^^^^^^^^^^^^^
+
+**optional**, **type**: :ref:`humanize duration <conf_value_humanize_duration>`
+
+Set how many time to wait before next connect after resolve error.
+
+**default**: 30s
+
+connect_retry_wait
+^^^^^^^^^^^^^^^^^^
+
+**optional**, **type**: :ref:`humanize duration <conf_value_humanize_duration>`
+
+Set how many time to wait before next connect after connect error.
+
+**default**: 10s
+
+rsp_header_max_size
+^^^^^^^^^^^^^^^^^^^
+
+**optional**, **type**: usize
+
+Set the max response header size.
+
+**default**: 8192
+
+body_line_max_length
+^^^^^^^^^^^^^^^^^^^^
+
+**optional**, **type**: usize
+
+Set the max line size in the response body.
+
+**default**: 512

sphinx/g3statsd/configuration/exporter/influxdb_v2.rst

@@ -0,0 +1,70 @@
+.. _configuration_exporter_influxdb_v2:
+
+influxdb_v2
+===========
+
+Emit all metrics from collector to influxdb by using the `v2 write API`_.
+
+.. _v2 write API: https://docs.influxdata.com/influxdb/v2/write-data/developer-tools/api/
+
+The following common keys are supported:
+
+* :ref:`prefix <conf_exporter_common_prefix>`
+* :ref:`global_tags <conf_exporter_common_global_tags>`
+
+The :ref:`HTTP Export Runtime <configuration_exporter_runtime_http>` is used:
+
+- default port 8181
+- all config keys supported
+
+emit_interval
+-------------
+
+**optional**, **type**: :ref:`humanize duration <conf_value_humanize_duration>`
+
+Set the time interval to emit internal metrics.
+
+**default**: 10s
+
+bucket
+------
+
+**required**, **type**: :ref:`http header value <conf_value_http_header_value>`
+
+Set the bucket name.
+
+token
+-----
+
+**optional**, **type**: :ref:`http header value <conf_value_http_header_value>`
+
+Set the auth token.
+
+If not set, the value in environment variable `INFLUX_TOKEN` will be used.
+
+**default**: not set
+
+precision
+---------
+
+**optional**, **type**: string
+
+Set the precision query parameter.
+
+Allowed values are:
+
+- s
+- ms
+- us
+- ns
+
+**default**: s
+
+max_body_lines
+--------------
+
+**optional**, **type**: usize
+
+Set the max body lines in a single request.
+
+**default**: 10000

sphinx/g3statsd/configuration/exporter/influxdb_v3.rst

@@ -0,0 +1,79 @@
+.. _configuration_exporter_influxdb_v3:
+
+influxdb_v3
+===========
+
+Emit all metrics from collector to influxdb by using the `v3 write_lp API`_.
+
+.. _v3 write_lp API: https://docs.influxdata.com/influxdb3/enterprise/write-data/api-client-libraries/
+
+The following common keys are supported:
+
+* :ref:`prefix <conf_exporter_common_prefix>`
+* :ref:`global_tags <conf_exporter_common_global_tags>`
+
+The :ref:`HTTP Export Runtime <configuration_exporter_runtime_http>` is used:
+
+- default port 8181
+- all config keys supported
+
+emit_interval
+-------------
+
+**optional**, **type**: :ref:`humanize duration <conf_value_humanize_duration>`
+
+Set the time interval to emit internal metrics.
+
+**default**: 10s
+
+database
+--------
+
+**required**, **type**: :ref:`http header value <conf_value_http_header_value>`
+
+Set the database name.
+
+token
+-----
+
+**optional**, **type**: :ref:`http header value <conf_value_http_header_value>`
+
+Set the auth token.
+
+If not set, the value in environment variable `INFLUXDB3_AUTH_TOKEN` will be used.
+
+**default**: not set
+
+precision
+---------
+
+**optional**, **type**: string
+
+Set the precision query parameter.
+
+Allowed values are:
+
+- second
+- millisecond
+- microsecond
+- nanosecond
+
+**default**: second
+
+no_sync
+-------
+
+**optional**, **type**: bool
+
+Set no_sync in the query parameter.
+
+**default**: false
+
+max_body_lines
+--------------
+
+**optional**, **type**: usize
+
+Set the max body lines in a single request.
+
+**default**: 10000

sphinx/g3statsd/configuration/exporter/memory.rst

@@ -0,0 +1,15 @@
+.. _configuration_exporter_memory:
+
+memory
+======
+
+This is the memory exporter designed to store all received metrics from collector to local memory.
+
+store_count
+-----------
+
+**optional**, **type**: usize
+
+Set how many values should be stored for each metric.
+
+**default**: 3600

sphinx/g3statsd/configuration/exporter/opentsdb.rst

@@ -0,0 +1,45 @@
+.. _configuration_exporter_opentsdb:
+
+opentsdb
+========
+
+Emit all metrics from collector to opentsdb by using the json `PUT API`_.
+
+.. _PUT API: https://opentsdb.net/docs/build/html/api_http/put.html
+
+The following common keys are supported:
+
+* :ref:`prefix <conf_exporter_common_prefix>`
+* :ref:`global_tags <conf_exporter_common_global_tags>`
+
+The :ref:`HTTP Export Runtime <configuration_exporter_runtime_http>` is used:
+
+- default port 4242
+- all config keys supported
+
+emit_interval
+-------------
+
+**optional**, **type**: :ref:`humanize duration <conf_value_humanize_duration>`
+
+Set the time interval to emit internal metrics.
+
+**default**: 10s
+
+sync_timeout
+------------
+
+**optional**, **type**: :ref:`humanize duration <conf_value_humanize_duration>`
+
+Set sync and sync_timeout query parameter.
+
+**default**: not set
+
+max_data_points
+---------------
+
+**optional**, **type**: usize
+
+Set the max data points that should be sent in a single HTTP request.
+
+**default**: 50

sphinx/g3statsd/configuration/importer/dummy.rst

@@ -0,0 +1,8 @@
+.. _configuration_importer_dummy:
+
+dummy
+=====
+
+This is the dummy importer designed to do nothing.
+
+There are no extra config keys for this kind of importer.

sphinx/g3statsd/configuration/importer/index.rst

@@ -0,0 +1,81 @@
+********
+Importer
+********
+
+The type for each importer config is *map*, with two always required keys:
+
+* :ref:`name <conf_importer_common_name>`, which specify the name of the importer.
+* :ref:`type <conf_importer_common_type>`, which specify the real type of the importer, decides how to parse other keys.
+
+There are many types of importer, each with a section below.
+
+Importers
+=========
+
+.. toctree::
+   :maxdepth: 1
+
+   dummy
+   statsd
+
+Common Keys
+===========
+
+This section describes the common keys, they may be used by many importers.
+
+.. _conf_importer_common_name:
+
+name
+----
+
+**required**, **type**: :ref:`metric node name <conf_value_metric_node_name>`
+
+Set the name of the importer.
+
+.. _conf_importer_common_type:
+
+type
+----
+
+**required**, **type**: str
+
+Set the type of the importer.
+
+.. _conf_importer_common_collector:
+
+collector
+---------
+
+**type**: :ref:`metric node name <conf_value_metric_node_name>`
+
+Set the collector to use for this importer.
+
+If the specified collector doesn't exist in configure, a default Discard collector will be used.
+
+.. _conf_importer_common_listen_in_worker:
+
+listen_in_worker
+----------------
+
+**optional**, **type**: bool
+
+Set if we should listen in each worker runtime if you have worker enabled.
+
+The listen instance count will be the same with the worker number count.
+
+**default**: false
+
+.. _conf_importer_common_ingress_network_filter:
+
+ingress_network_filter
+----------------------
+
+**optional**, **type**: :ref:`ingress network acl rule <conf_value_ingress_network_acl_rule>`
+
+Set the network filter for clients.
+
+The used client address will always be the interpreted client address, which means it will be the raw socket peer addr
+for servers that listen directly, and it will be the address set in the PROXY Protocol message for serverw chained after
+the server that support PROXY Protocol.
+
+**default**: not set

sphinx/g3statsd/configuration/importer/statsd.rst

@@ -0,0 +1,23 @@
+.. _configuration_importer_statsd:
+
+statsd
+======
+
+StatsD importer.
+
+The following common keys are supported:
+
+* :ref:`collector <conf_importer_common_collector>`
+* :ref:`listen_in_worker <conf_importer_common_listen_in_worker>`
+* :ref:`ingress_network_filter <conf_importer_common_ingress_network_filter>`
+
+listen
+------
+
+**optional**, **type**: :ref:`udp listen <conf_value_udp_listen>`
+
+Set the listen config for this importer.
+
+The instance count setting will be ignored if *listen_in_worker* is correctly enabled.
+
+**default**: not set

sphinx/g3statsd/configuration/index.rst

@@ -0,0 +1,39 @@
+.. _configuration:
+
+#############
+Configuration
+#############
+
+YAML is used as the configuration file format. The main conf file,
+which should be specified with the command line option *-c*,
+is make up of the following entries:
+
++-------------+----------+-------+------------------------------------------------+
+|Key          |Type      |Reload |Description                                     |
++=============+==========+=======+================================================+
+|runtime      |Map       |no     |Runtime config, see :doc:`runtime`              |
++-------------+----------+-------+------------------------------------------------+
+|worker       |Map [#w]_ |no     |An unaided runtime will be started if present.  |
++-------------+----------+-------+------------------------------------------------+
+|controller   |Seq       |no     |Controller config                               |
++-------------+----------+-------+------------------------------------------------+
+|importer     |Mix [#m]_ |yes    |Importer config                                 |
++-------------+----------+-------+------------------------------------------------+
+|collector    |Mix [#m]_ |yes    |Collector config                                |
++-------------+----------+-------+------------------------------------------------+
+|exporter     |Mix [#m]_ |yes    |Exporter config                                 |
++-------------+----------+-------+------------------------------------------------+
+
+.. rubric:: Footnotes
+
+.. [#m] See :ref:`hybrid map <conf_value_hybrid_map>` for the real format.
+.. [#w] See :ref:`unaided runtime config <conf_value_unaided_runtime_config>`.
+
+.. toctree::
+   :hidden:
+
+   runtime
+   importer/index
+   collector/index
+   exporter/index
+   values/index

sphinx/g3statsd/configuration/runtime.rst

@@ -0,0 +1,109 @@
+.. _configure_runtime_value_types:
+
+*******
+Runtime
+*******
+
+.. _conf_value_cpu_id_list_str:
+
+cpu id list str
+===============
+
+A string the represent a list of CPU IDs.
+
+It could be:
+
+ - A single CPU ID
+ - CPU ID range in the form `<start>-<end>`, where `start` should be less than `end`.
+ - A list of CPU ID / CPU ID range delimited by ','
+
+.. _conf_value_cpu_set:
+
+cpu set
+=======
+
+**yaml value** seq | str | usize
+
+A `CPU_SET(3)`_ for use with `sched_setaffinity(2)`_.
+
+The value should be one or a sequence of CPU IDs.
+
+The CPU ID valid can be:
+
+ - usize: a single CPU ID
+ - string: :ref:`cpu id list str <conf_value_cpu_id_list_str>`
+
+.. _CPU_SET(3): https://man7.org/linux/man-pages/man3/CPU_SET.3.html
+.. _sched_setaffinity(2): https://man7.org/linux/man-pages/man2/sched_setaffinity.2.html
+
+.. _conf_value_unaided_runtime_config:
+
+unaided runtime config
+======================
+
+**yaml value**: map
+
+This is the config for unaided runtime.
+
+The keys are:
+
+thread_number
+-------------
+
+**optional**, **type**: non-zero usize
+
+Set the total thread number.
+
+**default**: the number of logic CPU cores **alias**: threads_total, thread_number_total
+
+thread_number_per_runtime
+-------------------------
+
+**optional**, **type**: non-zero usize
+
+Set the thread number that each tokio runtime should use.
+
+**default**: 1, **alias**: threads_per_runtime
+
+thread_stack_size
+-----------------
+
+**optional**, **type**: :ref:`humanize usize <conf_value_humanize_usize>`
+
+Set the stack size for worker threads. For *<int>* value, the unit is bytes.
+
+**default**: system default
+
+sched_affinity
+--------------
+
+**optional**, **type**: map | bool
+
+Set the sched affinity for each threads.
+
+For map value, the key should be the thread id starting from 0, and the value should be :ref:`cpu set <conf_value_cpu_set>`.
+
+For bool value:
+
+* if true
+
+  - if found any `WORKER_<N>_CPU_LIST` environment variables
+
+    it will set the CPU affinity for that corresponding runtime `<N>`, the value should be :ref:`cpu id list str <conf_value_cpu_id_list_str>`.
+
+  - otherwise if thread_number_per_runtime is set to 1
+
+    a default CPU SET will be set for each thread, the CPU ID in the set will match the thread ID.
+
+* if false, no sched affinity will be set, just as if this config option is not present.
+
+**default**: no sched affinity set
+
+max_io_events_per_tick
+----------------------
+
+**optional**, **type**: usize
+
+Configures the max number of events to be processed per tick.
+
+**default**: 1024, tokio default value

sphinx/g3statsd/configuration/values/acl.rst

@@ -0,0 +1,89 @@
+
+.. _configure_acl_value_types:
+
+***
+ACL
+***
+
+All acl value types are described here.
+
+Basic Type
+==========
+
+.. _conf_value_acl_action:
+
+acl action
+----------
+
+**yaml value**: str
+
+There are 4 types of acl actions:
+
+* forbid_log
+
+  Forbid if match the rule and log. Alternatives: deny_log, reject_log.
+
+* forbid
+
+  Forbid if match the rule. Alternatives: deny, reject.
+
+* permit_log
+
+  Permit if match the rule and log. Alternatives: allow_log, accept_log.
+
+* permit
+
+  Permit if match the rule. Alternatives: allow, accept.
+
+The match order is the same as the list order above.
+
+.. _conf_value_acl_rule:
+
+acl rule
+--------
+
+**yaml value**: mix
+
+All the rules share the same config format described in this section.
+
+An acl rule is consisted of many records, each of them has an associated :ref:`acl action <conf_value_acl_action>`.
+A default missed action can be set in the rule, it set the default action if no record matches.
+
+The value in map format is consisted of the following fields:
+
+* default
+
+  Set the default acl action if no rule match.
+
+  Default action if rule is set but with *default* omitted: forbid if not specified in the rule's doc.
+
+* any of the acl actions as the key str
+
+  The value should be a valid record or a list of them, with the key string as the acl action.
+  See detail types for the format of each record type.
+
+The value could also be a single record or a list of them, which means only them are permitted with no log.
+
+The default missed action is **forbid** and the default found action is **permit**,
+if they are not specified in the detail types.
+
+Detail Type
+===========
+
+.. _conf_value_network_acl_rule:
+
+network acl rule
+----------------
+
+**yaml value**: :ref:`acl rule <conf_value_acl_rule>`
+
+The record type should be :ref:`ip network str <conf_value_ip_network_str>`.
+
+.. _conf_value_ingress_network_acl_rule:
+
+ingress network acl rule
+------------------------
+
+**yaml value**: :ref:`network acl rule <conf_value_network_acl_rule>`
+
+The same type as network acl rule. Default added: permit 127.0.0.1 and ::1.

sphinx/g3statsd/configuration/values/base.rst

@@ -0,0 +1,60 @@
+.. _configure_base_value_types:
+
+****
+Base
+****
+
+.. _conf_value_env_var:
+
+env var
+=======
+
+**yaml value**: str
+
+Set a environment variable, in the form '$' + variable name, E.g. $TCP_LISTEN_ADDR.
+
+The value of the environment variable will be parsed just as you write this value as *yaml string* directly there.
+
+.. _conf_value_humanize_usize:
+
+humanize usize
+==============
+
+**yaml value**: int | str
+
+For *str* value, it support units of 2^10 like "KiB", "MiB", or units of 1000 like "KB", "MB".
+
+For *int* value or *str* value without unit, the unit will be bytes.
+
+.. seealso::
+
+   `humanize_rs bytes <https://docs.rs/humanize-rs/0.1.5/humanize_rs/bytes/index.html>`_
+
+.. _conf_value_humanize_duration:
+
+humanize duration
+=================
+
+**yaml value**: int | str
+
+For *str* value, at least one unit is required. Multiple units string like "1h 30m 71s" is also supported.
+See `duration units`_ for all supported units.
+
+For *int* and *real* value, the unit will be seconds.
+
+.. seealso::
+
+   `humanize_rs duration <https://docs.rs/humanize-rs/0.1.5/humanize_rs/duration/index.html>`_
+
+.. _duration units: https://docs.rs/humanize-rs/0.1.5/src/humanize_rs/duration/mod.rs.html#115
+
+.. _conf_value_upstream_str:
+
+upstream str
+============
+
+**yaml value**: str
+
+The string should be in *<ip>[:<port>]* or *<domain>[:<port>]* format.
+
+If omitted, the *port* will be set to *0*.

sphinx/g3statsd/configuration/values/fs.rst

@@ -0,0 +1,23 @@
+.. _configure_fs_value_types:
+
+**********
+Filesystem
+**********
+
+.. _conf_value_hybrid_map:
+
+hybrid map
+==========
+
+**yaml value**: seq | str
+
+This is a hybrid container for a sequence of maps which may reside in other files.
+
+For *seq* value, all of it's values should be the final map, or a valid *str* value as described below.
+
+For *str* value, it should be a valid path, which may be absolute or relative to the directory of the main conf file.
+
+The path may be a file or directory:
+
+* If the path is a directory, the non-symbolic files in it with extension *.conf* will be parsed as described below.
+* If the path is a file, it should contains one or many yaml docs, each doc will be the final map.

sphinx/g3statsd/configuration/values/index.rst

@@ -0,0 +1,14 @@
+******************
+Common Value Types
+******************
+
+There are many common values used across this document.
+The meanings and formats of them are described as follows:
+
+.. toctree::
+
+   acl
+   base
+   fs
+   metrics
+   network

sphinx/g3statsd/configuration/values/metrics.rst

@@ -0,0 +1,68 @@
+.. _configure_metrics_value_types:
+
+*******
+Metrics
+*******
+
+.. _conf_value_metric_value:
+
+metric value
+============
+
+**yaml value**: limited str
+
+Only the following characters are allowed:
+
+a to z, A to Z, 0 to 9, -, _, ., / or Unicode letters (as per the specification)
+
+The character range is the same as `OpenTSDB metrics-and-tags`_.
+
+.. _OpenTSDB metrics-and-tags: http://opentsdb.net/docs/build/html/user_guide/writing/index.html#metrics-and-tags
+
+.. _conf_value_metric_tag_name:
+
+metric tag name
+===============
+
+**yaml value**: :ref:`metric value <conf_value_metric_value>`
+
+Set a metric tag name, which should not be empty.
+
+.. _conf_value_metric_tag_value:
+
+metric tag value
+================
+
+**yaml value**: :ref:`metric value <conf_value_metric_value>`
+
+Set a metric tag value, which may be empty according to the context.
+
+.. _conf_value_static_metrics_tags:
+
+static metrics tags
+===================
+
+**yaml value**: map
+
+The key should be :ref:`metric tag name <conf_value_metric_tag_name>`.
+The value should be :ref:`metric tag value <conf_value_metric_tag_value>`.
+
+.. _conf_value_metric_node_name:
+
+metric node name
+================
+
+**yaml value**: :ref:`metric value <conf_value_metric_value>`
+
+A single node in the metric name.
+
+.. _conf_value_metric_name_prefix:
+
+metric name prefix
+==================
+
+**yaml value**: seq of :ref:`metric node name <conf_value_metric_node_name>` | str
+
+Set prefix for metric name.
+
+This could be an array of metric node name, or a string value delimited by '.'.

sphinx/g3statsd/configuration/values/network.rst

@@ -0,0 +1,234 @@
+.. _configure_network_value_types:
+
+*******
+Network
+*******
+
+.. _conf_value_sockaddr_str:
+
+sockaddr str
+============
+
+**yaml value**: str
+
+The string should be in *<ip>[:<port>]* format, in which the port may be omitted if a default value is available.
+
+.. _conf_value_static_sockaddr_str:
+
+static sockaddr str
+===================
+
+**yaml value**: str
+
+The string should be in *@<domain>:<port>* or *@<ip>:<port>* format.
+
+It is different from :ref:`upstream str <conf_value_upstream_str>` as:
+
+- It will be resolved when we load the config files
+- The domain is only allowed to be resolved to just 1 IP address
+
+.. _conf_value_env_sockaddr_str:
+
+env sockaddr str
+================
+
+**yaml value**: :ref:`sockaddr str <conf_value_sockaddr_str>` or :ref:`static sockaddr str <conf_value_static_sockaddr_str>` or :ref:`env var <conf_value_env_var>`
+
+The string should be in *<ip>[:<port>]* format, in which the port may be omitted if a default value is available.
+
+.. _conf_value_ip_network_str:
+
+ip network str
+==============
+
+**yaml value**: str
+
+The string should be a network address in CIDR format, or just an ip address.
+
+.. _conf_value_interface_name:
+
+interface name
+==============
+
+**yaml value**: str | u32
+
+The string should be a network interface name or index.
+
+.. _conf_value_host:
+
+host
+====
+
+**yaml value**: str
+
+A host value. Which should be either a valid domain, or a valid IP address.
+
+.. _conf_value_socket_buffer_config:
+
+socket buffer config
+====================
+
+**yaml value**: mix
+
+It consists of 2 fields:
+
+* recv
+
+  **optional**, **type**: :ref:`humanize usize <conf_value_humanize_usize>`
+
+  Set the recv buf size.
+
+  **default**: not set
+
+* send
+
+  **optional**, **type**: :ref:`humanize usize <conf_value_humanize_usize>`
+
+  Set the send buf size.
+
+  **default**: not set
+
+The yaml value for *socket buffer config* can be in the following formats:
+
+* int | string
+
+  The value will be set for both **recv** and **send** fields above.
+
+* map
+
+  The keys of this map are the fields as described above.
+
+.. _conf_value_udp_listen:
+
+udp listen
+==========
+
+**yaml value**: mix
+
+It consists of the following fields:
+
+* address
+
+  **required**, **type**: :ref:`env sockaddr str <conf_value_env_sockaddr_str>`
+
+  Set the listen socket address.
+
+  **default**: [::]:0, which has empty port
+
+* interface
+
+  **optional**: **type**: :ref:`interface name <conf_value_interface_name>`
+
+  Bind the outgoing socket to a particular device like “eth0”.
+
+  **default**: not set
+
+* socket_buffer
+
+  **optional**, **type**: :ref:`socket buffer config <conf_value_socket_buffer_config>`
+
+  Set an explicit socket buffer config.
+
+  **default**: not set
+
+* socket_misc_opts
+
+  **optional**, **type**: :ref:`udp misc sock opts <conf_value_udp_misc_sock_opts>`
+
+  Set misc UDP socket options.
+
+  **default**: not set
+
+* ipv6_only
+
+  **optional**, **type**: bool
+
+  Listen only to ipv6 address only if address is set to [::].
+
+  **default**: false
+
+* instance
+
+  **optional**, **type**: int
+
+  Set how many listen instances. If *scale* is set, this will be the least value.
+
+  **default**: 1
+
+* scale
+
+  **optional**, **type**: float | string
+
+  Set the listen instance count scaled according to available parallelism.
+
+  For string value, it could be in percentage (n%) or fractional (n/d) format.
+
+  Example:
+
+  .. code-block:: yaml
+
+    scale: 1/2
+    # or
+    scale: 0.5
+    # or
+    scale: 50%
+
+  **default**: 0
+
+The yaml value for *listen* can be in the following formats:
+
+* int
+
+  Set the port only.
+
+* :ref:`sockaddr str <conf_value_sockaddr_str>`
+
+  Set ip and port. The port field is required.
+
+* map
+
+  The keys of this map are the fields as described above.
+
+.. _conf_value_udp_misc_sock_opts:
+
+udp misc sock opts
+==================
+
+**yaml value**: map
+
+This set misc udp socket options.
+
+Keys:
+
+* ttl
+
+  **optional**, **type**: u32, **alias**: time_to_live
+
+  Set value for ip level socket option IP_TTL, the time-to-live field in each sent packet.
+
+  **default**: not set
+
+* tos
+
+  **optional**, **type**: u8, **alias**: type_of_service
+
+  Set value for ip level socket option IP_TOS, the type-of-service field in each sent packet.
+
+  **default**: not set
+
+* mark
+
+  **optional**, **type**: u32, **alias**: netfilter_mark
+
+  Set value for socket level socket option SO_MARK, the netfilter mark value for our tcp sockets.
+
+  **default**: not set
+
+.. _conf_value_http_header_value:
+
+http header value
+=================
+
+**yaml value**: str
+
+This string should be a valid HTTP header value.

sphinx/g3statsd/index.rst

@@ -0,0 +1,7 @@
+Welcome to g3statsd's documentation!
+====================================
+
+.. toctree::
+   :maxdepth: 1
+
+   Configuration Reference <configuration/index>

sphinx/g3statsd/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

sphinx/g3statsd/requirements.txt

@@ -0,0 +1,2 @@
+sphinx
+sphinx-rtd-theme

sphinx/g3tiles/configuration/backends/index.rst

@@ -32,7 +32,7 @@ This section describes the common keys, they may be used by many backends.
 name
 ----
 
-**required**, **type**: :ref:`metrics name <conf_value_metrics_name>`
+**required**, **type**: :ref:`metric node name <conf_value_metric_node_name>`
 
 Set the name of the backend.
 
@@ -50,7 +50,7 @@ Set the type of the backend.
 discover
 --------
 
-**required**, **type**: :ref:`metrics name <conf_value_metrics_name>`
+**required**, **type**: :ref:`metric node name <conf_value_metric_node_name>`
 
 Set the discover that this backend should use.
 

sphinx/g3tiles/configuration/discovers/index.rst

@@ -30,7 +30,7 @@ This section describes the common keys, they may be used by many discovers.
 name
 ----
 
-**required**, **type**: :ref:`metrics name <conf_value_metrics_name>`
+**required**, **type**: :ref:`metric node name <conf_value_metric_node_name>`
 
 Set the name of the discover.
 

sphinx/g3tiles/configuration/servers/index.rst

@@ -34,7 +34,7 @@ This section describes the common keys, they may be used by many servers.
 name
 ----
 
-**required**, **type**: :ref:`metrics name <conf_value_metrics_name>`
+**required**, **type**: :ref:`metric node name <conf_value_metric_node_name>`
 
 Set the name of the server.
 

sphinx/g3tiles/configuration/servers/keyless_proxy.rst

@@ -16,7 +16,7 @@ The following common keys are supported:
 backend
 -------
 
-**required**, **type**: :ref:`metrics name <conf_value_metrics_name>`
+**required**, **type**: :ref:`metric node name <conf_value_metric_node_name>`
 
 Set the backend name.
 

sphinx/g3tiles/configuration/servers/openssl_proxy.rst

@@ -125,7 +125,7 @@ This set the config for a OpenSSl virtual host.
 name
 """"
 
-**required**, **type**: :ref:`metrics name <conf_value_metrics_name>`
+**required**, **type**: :ref:`metric node name <conf_value_metric_node_name>`
 
 Set the name of this virtual host.
 
@@ -242,5 +242,58 @@ This will overwrite the server level :ref:`task_idle_max_count <conf_server_comm
 
 **default**: not set
 
+.. _conf_server_openssl_proxy_host_backend:
+
 backends
 """"""""
+
+**required**, **type**: :ref:`alpn matched object <conf_value_alpn_matched_object>` <:ref:`backend <configuration_server_openssl_proxy_backend>`>
+
+Set the list of backends we should handle based on ALPN match rules.
+
+Example:
+
+- A single ALPN value:
+
+  .. code-block:: yaml
+
+    backends:
+      protocol: HTTP/1.1
+      backend: foo
+
+- Two single ALPN values:
+
+  .. code-block:: yaml
+
+    backends:
+      - protocol: HTTP/1.1
+        backend: foo
+      - protocol: H2
+        backend: bar
+
+- No ALPN value:
+
+  .. code-block:: yaml
+
+    backends:
+      - foo
+
+**default**: not set
+
+.. _configuration_server_openssl_proxy_backend:
+
+Backend
+^^^^^^^
+
+This is the backend config to be used in :ref:`host backends <conf_server_openssl_proxy_host_backend>`.
+
+It can be a map value, the keys are:
+
+backend
+"""""""
+
+**required**, **type**: :ref:`metric node name <conf_value_metric_node_name>`
+
+Set the name of the backend to use.
+
+It can also be written as a :ref:`metric node name <conf_value_metric_node_name>` value when needed.

sphinx/g3tiles/configuration/servers/rustls_proxy.rst

@@ -85,7 +85,7 @@ This set the config for a OpenSSl virtual host.
 name
 """"
 
-**required**, **type**: :ref:`metrics name <conf_value_metrics_name>`
+**required**, **type**: :ref:`metric node name <conf_value_metric_node_name>`
 
 Set the name of this virtual host.
 
@@ -193,5 +193,58 @@ This will overwrite the server level :ref:`task_idle_max_count <conf_server_comm
 
 **default**: not set
 
+.. _conf_server_rustls_proxy_host_backend:
+
 backends
 """"""""
+
+**required**, **type**: :ref:`alpn matched object <conf_value_alpn_matched_object>` <:ref:`backend <configuration_server_rustls_proxy_backend>`>
+
+Set the list of backends we should handle based on ALPN match rules.
+
+Example:
+
+- A single ALPN value:
+
+  .. code-block:: yaml
+
+    backends:
+      protocol: HTTP/1.1
+      backend: foo
+
+- Two single ALPN values:
+
+  .. code-block:: yaml
+
+    backends:
+      - protocol: HTTP/1.1
+        backend: foo
+      - protocol: H2
+        backend: bar
+
+- No ALPN value:
+
+  .. code-block:: yaml
+
+    backends:
+      - foo
+
+**default**: not set
+
+.. _configuration_server_rustls_proxy_backend:
+
+Backend
+^^^^^^^
+
+This is the backend config to be used in :ref:`host backends <conf_server_rustls_proxy_host_backend>`.
+
+It can be a map value, the keys are:
+
+backend
+"""""""
+
+**required**, **type**: :ref:`metric node name <conf_value_metric_node_name>`
+
+Set the name of the backend to use.
+
+It can also be written as a :ref:`metric node name <conf_value_metric_node_name>` value when needed.

sphinx/g3tiles/configuration/values/metrics.rst

@@ -5,10 +5,10 @@
 Metrics
 *******
 
-.. _conf_value_metrics_value:
+.. _conf_value_metric_value:
 
-metrics value
-=============
+metric value
+============
 
 **yaml value**: limited str
 
@@ -20,6 +20,24 @@ The character range is the same as `OpenTSDB metrics-and-tags`_.
 
 .. _OpenTSDB metrics-and-tags: http://opentsdb.net/docs/build/html/user_guide/writing/index.html#metrics-and-tags
 
+.. _conf_value_metric_tag_name:
+
+metric tag name
+===============
+
+**yaml value**: :ref:`metric value <conf_value_metric_value>`
+
+Set a metric tag name, which should not be empty.
+
+.. _conf_value_metric_tag_value:
+
+metric tag value
+================
+
+**yaml value**: :ref:`metric value <conf_value_metric_value>`
+
+Set a metric tag value, which may be empty according to the context.
+
 .. _conf_value_static_metrics_tags:
 
 static metrics tags
@@ -27,25 +45,24 @@ static metrics tags
 
 **yaml value**: map
 
-This should be a map, each key will be the tag name, and it's value will be the tag value.
+The key should be :ref:`metric tag name <conf_value_metric_tag_name>`.
+The value should be :ref:`metric tag value <conf_value_metric_tag_value>`.
 
-The tag name and the tag value should be of type :ref:`metrics value <conf_value_metrics_value>`.
+.. _conf_value_metric_node_name:
 
-.. _conf_value_metrics_name:
+metric node name
+================
 
-metrics name
-============
-
-**yaml value**: :ref:`metrics value <conf_value_metrics_value>`
+**yaml value**: :ref:`metric value <conf_value_metric_value>`
 
 The metrics name
 
-.. _conf_value_weighted_metrics_name:
+.. _conf_value_weighted_metric_node_name:
 
-weighted metrics name
-=====================
+weighted metric node name
+=========================
 
-**yaml value**: map | :ref:`metrics name <conf_value_metrics_name>`
+**yaml value**: map | :ref:`metric node name <conf_value_metric_node_name>`
 
 A metrics name with weight set, which make can be grouped into selective vector.
 
@@ -53,7 +70,7 @@ The map consists 2 fields:
 
 * name
 
-  **required**, **type**: :ref:`metrics name <conf_value_metrics_name>`
+  **required**, **type**: :ref:`metric node name <conf_value_metric_node_name>`
 
   The name. The meaning of the name is depending on the config context.
 
@@ -180,7 +197,7 @@ The key *unix* is just handled as *target_unix* as above.
 prefix
 ------
 
-**optional**, **type**: :ref:`metrics name <conf_value_metrics_name>`
+**optional**, **type**: :ref:`metric node name <conf_value_metric_node_name>`
 
 Set the global prefix for all metrics.
 

sphinx/g3tiles/configuration/values/network.rst

@@ -74,6 +74,15 @@ ip network str
 
 The string should be a network address in CIDR format, or just an ip address.
 
+.. _conf_value_interface_name:
+
+interface name
+==============
+
+**yaml value**: str | u32
+
+The string should be a network interface name or index.
+
 .. _conf_value_host:
 
 host
@@ -220,6 +229,16 @@ It consists of the following fields:
 
   **default**: [::]:0, which has empty port
 
+* interface
+
+  **optional**: **type**: :ref:`interface name <conf_value_interface_name>`
+
+  Bind the outgoing socket to a particular device like “eth0”.
+
+  **default**: not set
+
+  .. versionadded:: 0.3.9
+
 * backlog
 
   **optional**, **type**: unsigned int

sphinx/g3tiles/configuration/values/route.rst

@@ -41,3 +41,35 @@ A match object can contains one or more T(s), which means the yaml type for this
 or a sequence of T.
 
 Only a single T is allowed for each match rules, including the default one.
+
+.. _conf_value_alpn_matched_object:
+
+ALPN Matched Object
+===================
+
+**yaml value**: map | seq of map
+
+This set a ALPN based match object for generic type T, which will be specified in the real config options.
+
+The yaml value for T will be a map, but with the following keys as reserved as they are used by the match rules:
+
+* protocol
+
+  **optional**, **type**: ALPN protocol str
+
+  Match if this is the exact ALPN protocol.
+
+* set_default
+
+  **optional**, **type**: bool
+
+  If true, also set this T as default value
+
+  **default**: false
+
+If none of the above keys found, the parsed T value will also be used as the default value.
+
+A match object can contains one or more T(s), which means the yaml type for this object could be a single T,
+or a sequence of T.
+
+Only a single T is allowed for each match rules, including the default one.