You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficcontrol.apache.org by ma...@apache.org on 2020/04/23 20:35:11 UTC
[trafficcontrol] branch master updated: Tm plugin docs (#4627)
This is an automated email from the ASF dual-hosted git repository.
mattjackson pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/trafficcontrol.git
The following commit(s) were added to refs/heads/master by this push:
new bdfa3b7 Tm plugin docs (#4627)
bdfa3b7 is described below
commit bdfa3b74be2d98b08f8cac90c20b0c99f1cec15e
Author: ocket8888 <oc...@gmail.com>
AuthorDate: Thu Apr 23 14:34:59 2020 -0600
Tm plugin docs (#4627)
* Moved special param docs to the section specifically for those
* Added docs section for TM extensions
* Added health.polling.format docs
* Added explicit reference captions
* Fixed grammar error
---
docs/source/admin/traffic_monitor.rst | 41 +++++++++++-------------
docs/source/overview/profiles_and_parameters.rst | 39 ++++++++++++++++++++++
2 files changed, 57 insertions(+), 23 deletions(-)
diff --git a/docs/source/admin/traffic_monitor.rst b/docs/source/admin/traffic_monitor.rst
index ca07ae9..b7871a4 100644
--- a/docs/source/admin/traffic_monitor.rst
+++ b/docs/source/admin/traffic_monitor.rst
@@ -66,29 +66,6 @@ As mentioned in the :ref:`health-proto` section of the :ref:`tm-overview` overvi
To enable the optimistic quorum feature, the ``peer_optimistic_quorum_min`` property in ``traffic_monitor.cfg`` should be configured with a value greater than zero that specifies the minimum number of peers that must be available in order to participate in the optimistic health protocol. If at any time the number of available peers falls below this threshold, the local Traffic Monitor will serve 503s whenever the aggregated, optimistic health protocol enabled view of the CDN's health is [...]
-
-Cache Polling URL
------------------------------------
-
-The :term:`cache servers` are polled at the URL specified in the ``health.polling.url`` :term:`parameter`, on the :term:`cache server`'s :term:`profile`.
-
-This :term:`parameter` must have the config file ``rascal.properties``.
-
-The value is a template with the text ``${hostname}`` being replaced with the :term:`cache server`'s Network IP (IPv4, IPv6, or alternating between IPv4 and IPv6 depending on the cache polling protocol described in `Configuration Overview`_), and ``${interface_name}`` being replaced with the :term:`cache server`'s network Interface Name. For example, ``http://${hostname}/_astats?application=&inf.name=${interface_name}``.
-.. Note:: When an IPv6 address is used, it must be surrounded by square brackets ``[`` and ``]``. This is done when the text ``${hostname}`` is replaced and should not be done in the server configuration itself.
-
-If the template contains a port, that port will be used, and the :term:`cache server`'s HTTPS and TCP Ports will not be added.
-
-If the template does not contain a port, then if the template starts with ``https`` the :term:`cache server`'s HTTPS Port will be added, and if the template doesn't start with ``https`` the :term:`cache server`'s TCP Port will be added.
-
-Examples:
-
-Template ``http://${hostname}/_astats?application=&inf.name=${interface_name}`` Server IP ``192.0.2.42`` Server TCP Port ``8080`` HTTPS Port ``8443`` becomes ``http://192.0.2.42:8080/_astats?application=&inf.name=${interface_name}``.
-Template ``http://${hostname}/_astats?application=&inf.name=${interface_name}`` Server IP ``2001:DB8:0:0:1::1`` Server TCP Port ``8080`` HTTPS Port ``8443`` becomes ``http://[2001:DB8:0:0:1::1]/_astats?application=&inf.name=${interface_name}``.
-Template ``https://${hostname}/_astats?application=&inf.name=${interface_name}`` Server IP ``192.0.2.42`` Server TCP Port ``8080`` HTTPS Port ``8443`` becomes ``https://192.0.2.42:8443/_astats?application=&inf.name=${interface_name}``.
-Template ``http://${hostname}:1234/_astats?application=&inf.name=${interface_name}`` Server IP ``192.0.2.42`` Server TCP Port ``8080`` HTTPS Port ``8443`` becomes ``http://192.0.2.42:1234/_astats?application=&inf.name=${interface_name}``.
-Template ``https://${hostname}:1234/_astats?application=&inf.name=${interface_name}`` Server IP ``192.0.2.42`` Server TCP Port ``8080`` HTTPS Port ``8443`` becomes ``https://192.0.2.42:1234/_astats?application=&inf.name=${interface_name}``.
-
Stat and Health Flush Configuration
-----------------------------------
The Monitor has a health flush interval, a stat flush interval, and a stat buffer interval. Recall that the monitor polls both stats and health. The health poll is so small and fast, a buffer is largely unnecessary. However, in a large CDN, the stat poll may involve thousands of :term:`cache servers` with thousands of stats each, or more, and CPU may be a bottleneck.
@@ -104,3 +81,21 @@ It is not recommended to set either flush interval to 0, regardless of the stat
Troubleshooting and Log Files
=============================
Traffic Monitor log files are in :file:`/opt/traffic_monitor/var/log/`.
+
+.. _admin-tm-extensions:
+
+Extensions
+==========
+Traffic Monitor allows extensions to its parsers for the statistics returned by :term:`cache servers` and/or their plugins. The formats supported by Traffic Monitor by default are ``astats``, ``astats-dsnames`` (which is an odd variant of ``astats`` that probably shouldn't be used), and ``stats_over_http``. The format of a :term:`cache server`'s health and statistics reporting payloads must be declared on its :term:`Profile` as the :ref:`health.polling.format <param-health-polling-format [...]
+
+For instructions on how to develop a parsing extension, refer to the :atc-godoc:`traffic_monitor/cache` package's documentation.
+
+Importantly, though, a statistics provider *must* respond to HTTP GET requests over either plain HTTP or HTTPS (which is controlled by the :ref:`health.polling.url <param-health-polling-url>` :term:`Parameter`), and it *must* provide the following statistics, or enough information to calculate them:
+
+- System "loadavg" (only requires the one-minute value)
+
+ .. seealso:: For more information on what "loadavg" is, refer to the :manpage:`proc(5)` manual page.
+
+- Input bytes, output bytes, and speeds for all monitored network interfaces
+
+There are other optional and/or :term:`Delivery Service`-related statistics that may cause Traffic Stats to not have the right information if not provided, but the above are essential for implementing :ref:`health-proto`.
diff --git a/docs/source/overview/profiles_and_parameters.rst b/docs/source/overview/profiles_and_parameters.rst
index f9d5b57..6532d73 100644
--- a/docs/source/overview/profiles_and_parameters.rst
+++ b/docs/source/overview/profiles_and_parameters.rst
@@ -507,12 +507,51 @@ For each Parameter with this Config File value on the same :ref:`Profile <profil
.. seealso:: `The Apache Traffic server documentation on the plugin.config configuration file <https://docs.trafficserver.apache.org/en/7.1.x/admin-guide/files/plugin.config.en.html>`_ explains what Value_ and :ref:`parameter-name` a Parameter should have to be valid.
+.. _tm-related-cache-server-params:
+
rascal.properties
'''''''''''''''''
This Config File is meant to be on Parameters assigned to either Traffic Monitor Profiles_ or :term:`cache server` Profiles_. Its allowed :ref:`Parameter Names <parameter-name>` are all configuration options for Traffic Monitor. The :ref:`Names <parameter-name>` with meaning are as follows.
.. seealso:: :ref:`health-proto`
+.. _param-health-polling-format:
+
+health.polling.format
+ The Value_ of this Parameter should be the name of a parsing format supported by Traffic Monitor, used to decode statistics when polling for health and statistics. If this Parameter does not exist on a :term:`cache server`'s :ref:`Profile <Profiles>`, the default format (``astats``) will be used. The only supported values are
+
+ - ``astats`` parses the statistics output from the `astats_over_http plugin <https://github.com/apache/trafficcontrol/tree/master/traffic_server/plugins/astats_over_http/README.md>`_.
+ - ``stats_over_http`` parses the statistics output from the `stats_over_http plugin <https://docs.trafficserver.apache.org/en/latest/admin-guide/plugins/stats_over_http.en.html>`_.
+ - ``noop`` no statistics are parsed; the :term:`cache servers` using this Value_ will always be considered healthy, but statistics will never be gathered for them.
+
+ For more information on Traffic Monitor plug-ins that can expand the parsed formats, refer to :ref:`admin-tm-extensions`.
+
+.. _param-health-polling-url:
+
+health.polling.url
+ The Value_ of this Parameter sets the URL requested when Traffic Monitor polls cache servers that have this Parameter in their Profiles_. Specifically, the Value_ is interpreted as a template - in a format reminiscent of variable interpolation in double-quoted strings in Bash -, that offers the following substitutions:
+
+ - ``${hostname}`` Replaced by the *IP Address* of the :term:`cache server` being polled, and **not** its (short) hostname. The IP address used will be its IPv4 service address if it has one, otherwise its IPv6 service address. IPv6 addresses are properly formatted when inserted into the template, so the template need not include "square brackets" (:kbd:`[` and :kbd:`]`) around ``${hostname}``\ s even when they anticipate they will be IPv6 addresses.
+ - ``${interface_name}`` Replaced by the name of the network interface that contains the :term:`cache server`'s service address(es). For most cache servers (specifically those using the ``stats_over_http`` :abbr:`ATS (Apache Traffic Server)` plugin to report their health and statistics) using this in a template won't be necessary.
+
+ If the template doesn't include a specific port number, the :term:`cache server`'s TCP port will be inserted if the URL uses the HTTP scheme, or its HTTPS Port if the :term:`cache server` uses the the HTTPS scheme.
+
+ Table :ref:`tbl-health-polling-url-examples` gives some examples of templates, inputs, and outputs.
+
+ .. _tbl-health-polling-url-examples:
+
+ .. table:: health.polling.url Value Examples
+
+ +---------------------------------------------------------------+-------------------+----------+------------+----------------+--------------------------------------------------+
+ | Template | Chosen Service IP | TCP Port | HTTPS Port | Interface Name | Output |
+ +===============================================================+===================+==========+============+================+==================================================+
+ | ``http://${hostname}/_astats?inf.name=${interface_name}`` | 192.0.2.42 | 8080 | 8443 | eth0 | ``http://192.0.2.42:8080/_astats?inf.name=eth0`` |
+ +---------------------------------------------------------------+-------------------+----------+------------+----------------+--------------------------------------------------+
+ | ``https://${hostname}/_stats`` | 2001:DB8:0:0:1::1 | 8080 | 8443 | eth0 | ``https://[2001:DB8:0:0:1::1]/_stats`` |
+ +---------------------------------------------------------------+-------------------+----------+------------+----------------+--------------------------------------------------+
+ | ``http://${hostname}:80/custom/stats/path/${interface_name}`` | 192.0.2.42 | 8080 | 8443 | eth0 | ``http://192.0.2.42:80/custom/stats/path/eth0`` |
+ +---------------------------------------------------------------+-------------------+----------+------------+----------------+--------------------------------------------------+
+
health.threshold.loadavg
The Value_ of this Parameter sets the "load average" above which the associated :ref:`Profile <profiles>`'s :term:`cache server` will be considered "unhealthy".