diff --git a/.github/workflows/sphinx.yml b/.github/workflows/sphinx.yml index 79f81ead..04a5d69e 100644 --- a/.github/workflows/sphinx.yml +++ b/.github/workflows/sphinx.yml @@ -22,6 +22,7 @@ jobs: - g3proxy - g3tiles - g3keymess + - g3statsd steps: - uses: actions/checkout@v4 - run: | diff --git a/Cargo.lock b/Cargo.lock index 34eae01f..48201353 100644 --- a/Cargo.lock +++ b/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", ] diff --git a/g3statsd/src/config/mod.rs b/g3statsd/src/config/mod.rs index 7f8b4197..2e7b67b2 100644 --- a/g3statsd/src/config/mod.rs +++ b/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), diff --git a/g3statsd/src/runtime/export/stream/config.rs b/g3statsd/src/runtime/export/stream/config.rs index 73d17dda..c78c25a7 100644 --- a/g3statsd/src/runtime/export/stream/config.rs +++ b/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(()) } diff --git a/sphinx/conf.py b/sphinx/conf.py index 1ac664e2..b3fd3abb 100644 --- a/sphinx/conf.py +++ b/sphinx/conf.py @@ -15,6 +15,9 @@ multiproject_projects = { "g3tiles": { "path": "g3tiles", }, + "g3statsd": { + "path": "g3statsd", + }, "g3keymess": { "path": "g3keymess", }, diff --git a/sphinx/g3keymess/_static/.place-holder b/sphinx/g3keymess/_static/.place-holder new file mode 100644 index 00000000..e69de29b diff --git a/sphinx/g3keymess/_templates/.place-holder b/sphinx/g3keymess/_templates/.place-holder new file mode 100644 index 00000000..e69de29b diff --git a/sphinx/g3keymess/configuration/server.rst b/sphinx/g3keymess/configuration/server.rst index 6dd6c271..e562ad1c 100644 --- a/sphinx/g3keymess/configuration/server.rst +++ b/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 ` +**required**, **type**: :ref:`metric node name ` Set the name of the server. diff --git a/sphinx/g3keymess/configuration/stores/index.rst b/sphinx/g3keymess/configuration/stores/index.rst index 8e94cad5..5ba503c7 100644 --- a/sphinx/g3keymess/configuration/stores/index.rst +++ b/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 ` +**required**, **type**: :ref:`metric node name ` Set the name of the discover. diff --git a/sphinx/g3keymess/configuration/values/metrics.rst b/sphinx/g3keymess/configuration/values/metrics.rst index d8142606..ef114323 100644 --- a/sphinx/g3keymess/configuration/values/metrics.rst +++ b/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 ` + +Set a metric tag name, which should not be empty. + +.. _conf_value_metric_tag_value: + +metric tag value +================ + +**yaml value**: :ref:`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 `. +The value should be :ref:`metric tag value `. -The tag name and the tag value should be of type :ref:`metrics value `. +.. _conf_value_metric_node_name: -.. _conf_value_metrics_name: +metric node name +================ -metrics name -============ - -**yaml value**: :ref:`metrics value ` +**yaml value**: :ref:`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 ` +**optional**, **type**: :ref:`metric node name ` Set the global prefix for all metrics. diff --git a/sphinx/g3keymess/configuration/values/network.rst b/sphinx/g3keymess/configuration/values/network.rst index e23f58f0..635e04fb 100644 --- a/sphinx/g3keymess/configuration/values/network.rst +++ b/sphinx/g3keymess/configuration/values/network.rst @@ -45,6 +45,15 @@ ip addr str The string should be in ** 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 ` + + Bind the outgoing socket to a particular device like “eth0”. + + **default**: not set + + .. versionadded:: 0.4.2 + * backlog **optional**, **type**: unsigned int diff --git a/sphinx/g3proxy/configuration/auditors/index.rst b/sphinx/g3proxy/configuration/auditors/index.rst index 245da843..d08aa637 100644 --- a/sphinx/g3proxy/configuration/auditors/index.rst +++ b/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 ` +**required**, **type**: :ref:`metric node name ` Set the auditor name, which will can be referenced in :ref:`server config `. diff --git a/sphinx/g3proxy/configuration/escapers/index.rst b/sphinx/g3proxy/configuration/escapers/index.rst index 4b66c3e0..a0c24f36 100644 --- a/sphinx/g3proxy/configuration/escapers/index.rst +++ b/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 ` +**required**, **type**: :ref:`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 ` 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 diff --git a/sphinx/g3proxy/configuration/escapers/route_client.rst b/sphinx/g3proxy/configuration/escapers/route_client.rst index 09912693..bdd5e2d7 100644 --- a/sphinx/g3proxy/configuration/escapers/route_client.rst +++ b/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 ` 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 ` Set the next escaper. diff --git a/sphinx/g3proxy/configuration/escapers/route_failover.rst b/sphinx/g3proxy/configuration/escapers/route_failover.rst index 738acf4a..3eca9003 100644 --- a/sphinx/g3proxy/configuration/escapers/route_failover.rst +++ b/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 ` Set the primary next escaper to be used. standby_next ------------ -**required**, **type**: str +**required**, **type**: :ref:`metric node name ` Set the standby next escaper to be used. diff --git a/sphinx/g3proxy/configuration/escapers/route_geoip.rst b/sphinx/g3proxy/configuration/escapers/route_geoip.rst index 160e31df..4cd80a8a 100644 --- a/sphinx/g3proxy/configuration/escapers/route_geoip.rst +++ b/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 ` Set the next escaper. diff --git a/sphinx/g3proxy/configuration/escapers/route_mapping.rst b/sphinx/g3proxy/configuration/escapers/route_mapping.rst index 21920353..c7a19596 100644 --- a/sphinx/g3proxy/configuration/escapers/route_mapping.rst +++ b/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 ` This set all the next escapers. Each element should be the name of the target float escaper. diff --git a/sphinx/g3proxy/configuration/escapers/route_query.rst b/sphinx/g3proxy/configuration/escapers/route_query.rst index e899da68..7b5df429 100644 --- a/sphinx/g3proxy/configuration/escapers/route_query.rst +++ b/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 ` Set the fallback escaper name. query_allowed_next ------------------ -**required**, **type**: seq +**required**, **type**: :ref:`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. diff --git a/sphinx/g3proxy/configuration/escapers/route_resolved.rst b/sphinx/g3proxy/configuration/escapers/route_resolved.rst index f00045ed..39e8b66a 100644 --- a/sphinx/g3proxy/configuration/escapers/route_resolved.rst +++ b/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 ` Set the next escaper. diff --git a/sphinx/g3proxy/configuration/escapers/route_select.rst b/sphinx/g3proxy/configuration/escapers/route_select.rst index 1e443b61..aa21151f 100644 --- a/sphinx/g3proxy/configuration/escapers/route_select.rst +++ b/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 ` | seq Set the next escaper(s) those can be selected. -For *seq* value, each of its element must be :ref:`weighted metrics name `. - .. _conf_escaper_route_select_next_pick_policy: next_pick_policy diff --git a/sphinx/g3proxy/configuration/escapers/route_upstream.rst b/sphinx/g3proxy/configuration/escapers/route_upstream.rst index c3a533a1..8a5fc3bd 100644 --- a/sphinx/g3proxy/configuration/escapers/route_upstream.rst +++ b/sphinx/g3proxy/configuration/escapers/route_upstream.rst @@ -24,7 +24,7 @@ For seq format: * next - **required**, **type**: str + **required**, **type**: :ref:`metric node name ` Set the next escaper. @@ -75,7 +75,7 @@ For seq format: * next - **required**, **type**: str + **required**, **type**: :ref:`metric node name ` Set the next escaper. @@ -126,7 +126,7 @@ For seq format: * next - **required**, **type**: str + **required**, **type**: :ref:`metric node name ` Set the next escaper. @@ -178,7 +178,7 @@ For seq format: * next - **required**, **type**: str + **required**, **type**: :ref:`metric node name ` Set the next escaper. @@ -230,7 +230,7 @@ For seq format: * next - **required**, **type**: str + **required**, **type**: :ref:`metric node name ` Set the next escaper. diff --git a/sphinx/g3proxy/configuration/escapers/trick_float.rst b/sphinx/g3proxy/configuration/escapers/trick_float.rst index e0c15d41..73f2d2e1 100644 --- a/sphinx/g3proxy/configuration/escapers/trick_float.rst +++ b/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 ` | seq This set all the next escapers. Each element should be the name of the target float escaper. diff --git a/sphinx/g3proxy/configuration/resolvers/index.rst b/sphinx/g3proxy/configuration/resolvers/index.rst index 45a1a4b1..02b16ff3 100644 --- a/sphinx/g3proxy/configuration/resolvers/index.rst +++ b/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 ` +**required**, **type**: :ref:`metric node name ` Set the name of the resolver. diff --git a/sphinx/g3proxy/configuration/servers/index.rst b/sphinx/g3proxy/configuration/servers/index.rst index eb6299b8..33b47ff9 100644 --- a/sphinx/g3proxy/configuration/servers/index.rst +++ b/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 ` +**required**, **type**: :ref:`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 ` 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 ` 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 ` Set the user group for auth. diff --git a/sphinx/g3proxy/configuration/user_group/index.rst b/sphinx/g3proxy/configuration/user_group/index.rst index 86eb1f3e..32cb9fd8 100644 --- a/sphinx/g3proxy/configuration/user_group/index.rst +++ b/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 ` + + 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. diff --git a/sphinx/g3proxy/configuration/user_group/site.rst b/sphinx/g3proxy/configuration/user_group/site.rst index 0e4a529d..2605857c 100644 --- a/sphinx/g3proxy/configuration/user_group/site.rst +++ b/sphinx/g3proxy/configuration/user_group/site.rst @@ -14,7 +14,7 @@ site level config. id -- -**required**, **type**: :ref:`metrics name ` +**required**, **type**: :ref:`metric node name ` Each site should have an ID, and it will be used in metrics name if enabled. diff --git a/sphinx/g3proxy/configuration/values/metrics.rst b/sphinx/g3proxy/configuration/values/metrics.rst index 506a6dbb..b5c02200 100644 --- a/sphinx/g3proxy/configuration/values/metrics.rst +++ b/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 ` + +Set a metric tag name, which should not be empty. + +.. _conf_value_metric_tag_value: + +metric tag value +================ + +**yaml value**: :ref:`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 `. +The value should be :ref:`metric tag value `. -The tag name and the tag value should be of type :ref:`metrics value `. +.. _conf_value_metric_node_name: -.. _conf_value_metrics_name: +metric node name +================ -metrics name -============ - -**yaml value**: :ref:`metrics value ` +**yaml value**: :ref:`metrics 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 ` +**yaml value**: map | :ref:`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 ` + **required**, **type**: :ref:`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 ` +**optional**, **type**: :ref:`metric node name ` Set the global prefix for all metrics. diff --git a/sphinx/g3proxy/configuration/values/network.rst b/sphinx/g3proxy/configuration/values/network.rst index 25c33ea0..c7408e80 100644 --- a/sphinx/g3proxy/configuration/values/network.rst +++ b/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 ` + + 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 ` + + Bind the outgoing socket to a particular device like “eth0”. + + **default**: not set + + .. versionadded:: 1.11.6 + * ipv6_only **optional**, **type**: bool diff --git a/sphinx/g3proxy/protocol/helper/route_query.rst b/sphinx/g3proxy/protocol/helper/route_query.rst index 3b689ba1..8d1ccb9a 100644 --- a/sphinx/g3proxy/protocol/helper/route_query.rst +++ b/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 `. +For *seq* value, each of its element must be :ref:`weighted metric node name `. If empty, the :ref:`fallback node ` escaper config will take effect. diff --git a/sphinx/g3statsd/.gitignore b/sphinx/g3statsd/.gitignore new file mode 100644 index 00000000..e35d8850 --- /dev/null +++ b/sphinx/g3statsd/.gitignore @@ -0,0 +1 @@ +_build diff --git a/sphinx/g3statsd/Makefile b/sphinx/g3statsd/Makefile new file mode 100644 index 00000000..d4bb2cbb --- /dev/null +++ b/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) diff --git a/sphinx/g3statsd/_static/.place-holder b/sphinx/g3statsd/_static/.place-holder new file mode 100644 index 00000000..e69de29b diff --git a/sphinx/g3statsd/_templates/.place-holder b/sphinx/g3statsd/_templates/.place-holder new file mode 100644 index 00000000..e69de29b diff --git a/sphinx/g3statsd/conf.py b/sphinx/g3statsd/conf.py new file mode 100644 index 00000000..78dbe4d1 --- /dev/null +++ b/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' diff --git a/sphinx/g3statsd/configuration/collector/aggregate.rst b/sphinx/g3statsd/configuration/collector/aggregate.rst new file mode 100644 index 00000000..074132ff --- /dev/null +++ b/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 ` +* :ref:`exporter ` + +emit_interval +------------- + +**optional**, **type**: :ref:`humanize duration ` + +Set the time interval to emit internal metrics. + +**default**: 1s + +join_tags +--------- + +**optional**, **type**: :ref:`metric tag name ` | seq + +Set the tag(s) used to join metrics after aggregated together. diff --git a/sphinx/g3statsd/configuration/collector/discard.rst b/sphinx/g3statsd/configuration/collector/discard.rst new file mode 100644 index 00000000..360142e8 --- /dev/null +++ b/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. diff --git a/sphinx/g3statsd/configuration/collector/index.rst b/sphinx/g3statsd/configuration/collector/index.rst new file mode 100644 index 00000000..1da26148 --- /dev/null +++ b/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 `, which specify the name of the collector. +* :ref:`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 ` + +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 ` + +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 ` | seq + +Set the exporter(s) to use. + +If the specified exporter doesn't exist in configure, a default Discard exporter will be used. diff --git a/sphinx/g3statsd/configuration/collector/internal.rst b/sphinx/g3statsd/configuration/collector/internal.rst new file mode 100644 index 00000000..7f80c6f3 --- /dev/null +++ b/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 ` +* :ref:`exporter ` + +emit_interval +------------- + +**optional**, **type**: :ref:`humanize duration ` + +Set the time interval to emit internal metrics. + +**default**: 1s diff --git a/sphinx/g3statsd/configuration/collector/regulate.rst b/sphinx/g3statsd/configuration/collector/regulate.rst new file mode 100644 index 00000000..e0cb9c57 --- /dev/null +++ b/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 ` +* :ref:`exporter ` + +prefix +------ + +**optional**, **type**: :ref:`metric name prefix ` + +Set the prefix to add to all metric names. + +drop_tags +--------- + +**optional**, **type**: :ref:`metric tag name ` | seq + +Set the tag(s) to drop. diff --git a/sphinx/g3statsd/configuration/exporter/console.rst b/sphinx/g3statsd/configuration/exporter/console.rst new file mode 100644 index 00000000..a0c2d3df --- /dev/null +++ b/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. diff --git a/sphinx/g3statsd/configuration/exporter/discard.rst b/sphinx/g3statsd/configuration/exporter/discard.rst new file mode 100644 index 00000000..35acb27c --- /dev/null +++ b/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. diff --git a/sphinx/g3statsd/configuration/exporter/graphite.rst b/sphinx/g3statsd/configuration/exporter/graphite.rst new file mode 100644 index 00000000..14b25323 --- /dev/null +++ b/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 ` +* :ref:`global_tags ` + +The :ref:`Stream Export Runtime ` is used: + +- default port 2003 +- all config keys supported + +emit_interval +------------- + +**optional**, **type**: :ref:`humanize duration ` + +Set the time interval to emit internal metrics. + +**default**: 10s diff --git a/sphinx/g3statsd/configuration/exporter/index.rst b/sphinx/g3statsd/configuration/exporter/index.rst new file mode 100644 index 00000000..6f424e73 --- /dev/null +++ b/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 `, which specify the name of the exporter. +* :ref:`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 ` + +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 ` + +Set the prefix to add to all metric names. + +.. _conf_exporter_common_global_tags: + +global_tags +----------- + +**optional**, **type**: :ref:`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 ` + +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 ` + +Set how many time to wait before next connect after resolve error. + +**default**: 30s + +connect_retry_wait +^^^^^^^^^^^^^^^^^^ + +**optional**, **type**: :ref:`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 ` + +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 ` + +Set how many time to wait before next connect after resolve error. + +**default**: 30s + +connect_retry_wait +^^^^^^^^^^^^^^^^^^ + +**optional**, **type**: :ref:`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 diff --git a/sphinx/g3statsd/configuration/exporter/influxdb_v2.rst b/sphinx/g3statsd/configuration/exporter/influxdb_v2.rst new file mode 100644 index 00000000..2e6cf394 --- /dev/null +++ b/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 ` +* :ref:`global_tags ` + +The :ref:`HTTP Export Runtime ` is used: + +- default port 8181 +- all config keys supported + +emit_interval +------------- + +**optional**, **type**: :ref:`humanize duration ` + +Set the time interval to emit internal metrics. + +**default**: 10s + +bucket +------ + +**required**, **type**: :ref:`http header value ` + +Set the bucket name. + +token +----- + +**optional**, **type**: :ref:`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 diff --git a/sphinx/g3statsd/configuration/exporter/influxdb_v3.rst b/sphinx/g3statsd/configuration/exporter/influxdb_v3.rst new file mode 100644 index 00000000..514aef30 --- /dev/null +++ b/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 ` +* :ref:`global_tags ` + +The :ref:`HTTP Export Runtime ` is used: + +- default port 8181 +- all config keys supported + +emit_interval +------------- + +**optional**, **type**: :ref:`humanize duration ` + +Set the time interval to emit internal metrics. + +**default**: 10s + +database +-------- + +**required**, **type**: :ref:`http header value ` + +Set the database name. + +token +----- + +**optional**, **type**: :ref:`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 diff --git a/sphinx/g3statsd/configuration/exporter/memory.rst b/sphinx/g3statsd/configuration/exporter/memory.rst new file mode 100644 index 00000000..7afe4adc --- /dev/null +++ b/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 diff --git a/sphinx/g3statsd/configuration/exporter/opentsdb.rst b/sphinx/g3statsd/configuration/exporter/opentsdb.rst new file mode 100644 index 00000000..9989caed --- /dev/null +++ b/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 ` +* :ref:`global_tags ` + +The :ref:`HTTP Export Runtime ` is used: + +- default port 4242 +- all config keys supported + +emit_interval +------------- + +**optional**, **type**: :ref:`humanize duration ` + +Set the time interval to emit internal metrics. + +**default**: 10s + +sync_timeout +------------ + +**optional**, **type**: :ref:`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 diff --git a/sphinx/g3statsd/configuration/importer/dummy.rst b/sphinx/g3statsd/configuration/importer/dummy.rst new file mode 100644 index 00000000..c28e3c11 --- /dev/null +++ b/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. diff --git a/sphinx/g3statsd/configuration/importer/index.rst b/sphinx/g3statsd/configuration/importer/index.rst new file mode 100644 index 00000000..2c7a7bcc --- /dev/null +++ b/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 `, which specify the name of the importer. +* :ref:`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 ` + +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 ` + +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 ` + +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 diff --git a/sphinx/g3statsd/configuration/importer/statsd.rst b/sphinx/g3statsd/configuration/importer/statsd.rst new file mode 100644 index 00000000..c6acb9bc --- /dev/null +++ b/sphinx/g3statsd/configuration/importer/statsd.rst @@ -0,0 +1,23 @@ +.. _configuration_importer_statsd: + +statsd +====== + +StatsD importer. + +The following common keys are supported: + +* :ref:`collector ` +* :ref:`listen_in_worker ` +* :ref:`ingress_network_filter ` + +listen +------ + +**optional**, **type**: :ref:`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 diff --git a/sphinx/g3statsd/configuration/index.rst b/sphinx/g3statsd/configuration/index.rst new file mode 100644 index 00000000..56b93d45 --- /dev/null +++ b/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 ` for the real format. +.. [#w] See :ref:`unaided runtime config `. + +.. toctree:: + :hidden: + + runtime + importer/index + collector/index + exporter/index + values/index diff --git a/sphinx/g3statsd/configuration/runtime.rst b/sphinx/g3statsd/configuration/runtime.rst new file mode 100644 index 00000000..6e3c831c --- /dev/null +++ b/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 `-`, 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 ` + +.. _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 ` + +Set the stack size for worker threads. For ** 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 `. + +For bool value: + +* if true + + - if found any `WORKER__CPU_LIST` environment variables + + it will set the CPU affinity for that corresponding runtime ``, the value should be :ref:`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 diff --git a/sphinx/g3statsd/configuration/values/acl.rst b/sphinx/g3statsd/configuration/values/acl.rst new file mode 100644 index 00000000..ea0d57ad --- /dev/null +++ b/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 `. +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 ` + +The record type should be :ref:`ip network str `. + +.. _conf_value_ingress_network_acl_rule: + +ingress network acl rule +------------------------ + +**yaml value**: :ref:`network acl rule ` + +The same type as network acl rule. Default added: permit 127.0.0.1 and ::1. diff --git a/sphinx/g3statsd/configuration/values/base.rst b/sphinx/g3statsd/configuration/values/base.rst new file mode 100644 index 00000000..61f99f44 --- /dev/null +++ b/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 `_ + +.. _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 `_ + +.. _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 *[:]* or *[:]* format. + +If omitted, the *port* will be set to *0*. diff --git a/sphinx/g3statsd/configuration/values/fs.rst b/sphinx/g3statsd/configuration/values/fs.rst new file mode 100644 index 00000000..1f86407c --- /dev/null +++ b/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. diff --git a/sphinx/g3statsd/configuration/values/index.rst b/sphinx/g3statsd/configuration/values/index.rst new file mode 100644 index 00000000..f41743e1 --- /dev/null +++ b/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 diff --git a/sphinx/g3statsd/configuration/values/metrics.rst b/sphinx/g3statsd/configuration/values/metrics.rst new file mode 100644 index 00000000..4bec6649 --- /dev/null +++ b/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 ` + +Set a metric tag name, which should not be empty. + +.. _conf_value_metric_tag_value: + +metric tag value +================ + +**yaml value**: :ref:`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 `. +The value should be :ref:`metric tag value `. + +.. _conf_value_metric_node_name: + +metric node name +================ + +**yaml value**: :ref:`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 ` | str + +Set prefix for metric name. + +This could be an array of metric node name, or a string value delimited by '.'. diff --git a/sphinx/g3statsd/configuration/values/network.rst b/sphinx/g3statsd/configuration/values/network.rst new file mode 100644 index 00000000..adcb1d78 --- /dev/null +++ b/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 *[:]* 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 *@:* or *@:* format. + +It is different from :ref:`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 ` or :ref:`static sockaddr str ` or :ref:`env var ` + +The string should be in *[:]* 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 ` + + Set the recv buf size. + + **default**: not set + +* send + + **optional**, **type**: :ref:`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 ` + + Set the listen socket address. + + **default**: [::]:0, which has empty port + +* interface + + **optional**: **type**: :ref:`interface name ` + + Bind the outgoing socket to a particular device like “eth0”. + + **default**: not set + +* socket_buffer + + **optional**, **type**: :ref:`socket buffer config ` + + Set an explicit socket buffer config. + + **default**: not set + +* socket_misc_opts + + **optional**, **type**: :ref:`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 ` + + 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. diff --git a/sphinx/g3statsd/index.rst b/sphinx/g3statsd/index.rst new file mode 100644 index 00000000..c2e04660 --- /dev/null +++ b/sphinx/g3statsd/index.rst @@ -0,0 +1,7 @@ +Welcome to g3statsd's documentation! +==================================== + +.. toctree:: + :maxdepth: 1 + + Configuration Reference diff --git a/sphinx/g3statsd/make.bat b/sphinx/g3statsd/make.bat new file mode 100644 index 00000000..32bb2452 --- /dev/null +++ b/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 diff --git a/sphinx/g3statsd/requirements.txt b/sphinx/g3statsd/requirements.txt new file mode 100644 index 00000000..cbf1e365 --- /dev/null +++ b/sphinx/g3statsd/requirements.txt @@ -0,0 +1,2 @@ +sphinx +sphinx-rtd-theme diff --git a/sphinx/g3tiles/configuration/backends/index.rst b/sphinx/g3tiles/configuration/backends/index.rst index e6f78ace..cc588561 100644 --- a/sphinx/g3tiles/configuration/backends/index.rst +++ b/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 ` +**required**, **type**: :ref:`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 ` +**required**, **type**: :ref:`metric node name ` Set the discover that this backend should use. diff --git a/sphinx/g3tiles/configuration/discovers/index.rst b/sphinx/g3tiles/configuration/discovers/index.rst index 432693b9..7ece1171 100644 --- a/sphinx/g3tiles/configuration/discovers/index.rst +++ b/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 ` +**required**, **type**: :ref:`metric node name ` Set the name of the discover. diff --git a/sphinx/g3tiles/configuration/servers/index.rst b/sphinx/g3tiles/configuration/servers/index.rst index 11862f22..5fa45ea0 100644 --- a/sphinx/g3tiles/configuration/servers/index.rst +++ b/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 ` +**required**, **type**: :ref:`metric node name ` Set the name of the server. diff --git a/sphinx/g3tiles/configuration/servers/keyless_proxy.rst b/sphinx/g3tiles/configuration/servers/keyless_proxy.rst index 03c0c9fb..0ea57c83 100644 --- a/sphinx/g3tiles/configuration/servers/keyless_proxy.rst +++ b/sphinx/g3tiles/configuration/servers/keyless_proxy.rst @@ -16,7 +16,7 @@ The following common keys are supported: backend ------- -**required**, **type**: :ref:`metrics name ` +**required**, **type**: :ref:`metric node name ` Set the backend name. diff --git a/sphinx/g3tiles/configuration/servers/openssl_proxy.rst b/sphinx/g3tiles/configuration/servers/openssl_proxy.rst index 4739df1a..1d5dd0ba 100644 --- a/sphinx/g3tiles/configuration/servers/openssl_proxy.rst +++ b/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 ` +**required**, **type**: :ref:`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 ` <:ref:`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 `. + +It can be a map value, the keys are: + +backend +""""""" + +**required**, **type**: :ref:`metric node name ` + +Set the name of the backend to use. + +It can also be written as a :ref:`metric node name ` value when needed. diff --git a/sphinx/g3tiles/configuration/servers/rustls_proxy.rst b/sphinx/g3tiles/configuration/servers/rustls_proxy.rst index 3b953310..87481dd7 100644 --- a/sphinx/g3tiles/configuration/servers/rustls_proxy.rst +++ b/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 ` +**required**, **type**: :ref:`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 ` <:ref:`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 `. + +It can be a map value, the keys are: + +backend +""""""" + +**required**, **type**: :ref:`metric node name ` + +Set the name of the backend to use. + +It can also be written as a :ref:`metric node name ` value when needed. diff --git a/sphinx/g3tiles/configuration/values/metrics.rst b/sphinx/g3tiles/configuration/values/metrics.rst index a418f71d..208c8e42 100644 --- a/sphinx/g3tiles/configuration/values/metrics.rst +++ b/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 ` + +Set a metric tag name, which should not be empty. + +.. _conf_value_metric_tag_value: + +metric tag value +================ + +**yaml value**: :ref:`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 `. +The value should be :ref:`metric tag value `. -The tag name and the tag value should be of type :ref:`metrics value `. +.. _conf_value_metric_node_name: -.. _conf_value_metrics_name: +metric node name +================ -metrics name -============ - -**yaml value**: :ref:`metrics value ` +**yaml value**: :ref:`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 ` +**yaml value**: map | :ref:`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 ` + **required**, **type**: :ref:`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 ` +**optional**, **type**: :ref:`metric node name ` Set the global prefix for all metrics. diff --git a/sphinx/g3tiles/configuration/values/network.rst b/sphinx/g3tiles/configuration/values/network.rst index f06c769f..c2a4004f 100644 --- a/sphinx/g3tiles/configuration/values/network.rst +++ b/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 ` + + Bind the outgoing socket to a particular device like “eth0”. + + **default**: not set + + .. versionadded:: 0.3.9 + * backlog **optional**, **type**: unsigned int diff --git a/sphinx/g3tiles/configuration/values/route.rst b/sphinx/g3tiles/configuration/values/route.rst index 1bb3672e..b55e2a27 100644 --- a/sphinx/g3tiles/configuration/values/route.rst +++ b/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.