[trafficserver] branch 9.2.x updated: Add docs for remap_stats plugin (#8927)

[zw...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

zwoop pushed a commit to branch 9.2.x
in repository https://gitbox.apache.org/repos/asf/trafficserver.git


The following commit(s) were added to refs/heads/9.2.x by this push:
     new d146db490 Add docs for remap_stats plugin (#8927)
d146db490 is described below

commit d146db49098d6c5dd47b3b6557b2b5c4c7e34762
Author: Robert O Butts <ro...@users.noreply.github.com>
AuthorDate: Mon Jun 27 08:56:50 2022 -0600

    Add docs for remap_stats plugin (#8927)
    
    (cherry picked from commit 5bbf7968acae304324e358309693e76e3149eb65)
---
 doc/admin-guide/plugins/index.en.rst       |  4 ++
 doc/admin-guide/plugins/remap_stats.en.rst | 71 ++++++++++++++++++++++++++++++
 2 files changed, 75 insertions(+)

diff --git a/doc/admin-guide/plugins/index.en.rst b/doc/admin-guide/plugins/index.en.rst
index 94e71e4a0..986a95691 100644
--- a/doc/admin-guide/plugins/index.en.rst
+++ b/doc/admin-guide/plugins/index.en.rst
@@ -172,6 +172,7 @@ directory of the |TS| source tree. Experimental plugins can be compiled by passi
    OpenTelemetry Tracer <otel_tracer.en>
    Parent Select <parent_select.en>
    Rate Limit <rate_limit.en>
+   Remap Stats <remap_stats.en>
    URI Signing <uri_signing.en>
    Legacy Signed URLs <url_sig.en>
    Slice <slice.en>
@@ -248,6 +249,9 @@ directory of the |TS| source tree. Experimental plugins can be compiled by passi
 :doc:`Rate Limit <rate_limit.en>`
    Simple transaction rate limiting.
 
+:doc:`Remap Stats <remap_stats.en>`
+   This global plugin adds remap stats to the stats.
+
 :doc:`Remap Purge <remap_purge.en>`
    This remap plugin allows the administrator to easily setup remotely
    controlled ``PURGE`` for the content of an entire remap rule.
diff --git a/doc/admin-guide/plugins/remap_stats.en.rst b/doc/admin-guide/plugins/remap_stats.en.rst
new file mode 100644
index 000000000..5bf767151
--- /dev/null
+++ b/doc/admin-guide/plugins/remap_stats.en.rst
@@ -0,0 +1,71 @@
+.. include:: ../../common.defs
+
+.. _admin-plugins-remap-stats:
+
+Remap Stats Plugin
+******************
+
+.. Licensed to the Apache Software Foundation (ASF) under one
+   or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied.  See the License for the
+  specific language governing permissions and limitations
+  under the License.
+
+
+This global plugin adds remap stats to the Traffic Server statistics.
+
+Installation
+============
+
+Add the following line to :file:`plugin.config`::
+
+    remap_stats.so
+
+In this case, the plugin will use the default behaviour:
+
+- Create stats for all remap stats
+- URLs will be the pristine URL from the client
+- Stats will not be persistent
+
+Options
+=======
+
+Flags and options are:
+
+``--post-remap-host``: Whether to use the post-remap host in the URL, instead of the pristine client URL.
+``-P``: shorthand for ``--post-remap-host``.
+``--persistent``: Whether to use persistent stats.
+``-p``: shorthand for ``--persistent``.
+
+Options in the code:
+``MAX_STAT_LENGTH`` The maximum length of any stat name. Since stat names include the remap FQDN, this affects the maximum FQDN length that can be included in the stat.
+
+Stats
+=====
+
+The following stats are added to the Traffic Server statistics, for every remap rule.
+
+    plugin.remap_stats.<fqdn>.in_bytes
+    plugin.remap_stats.<fqdn>.out_bytes
+    plugin.remap_stats.<fqdn>.status_2xx
+    plugin.remap_stats.<fqdn>.status_3xx
+    plugin.remap_stats.<fqdn>.status_4xx
+    plugin.remap_stats.<fqdn>.status_5xx
+    plugin.remap_stats.<fqdn>.status_unknown
+
+The ``<fqdn>`` will be either the pristine client URL or the remapped URL, depending on whether ``--post-remap-host`` is set.
+
+All stat values are integers.
+
+These stats are available anywhere Traffic Server statistics can be viewed, such as the ``stats_over_http`` plugin and ``traffic_ctl metric get``. See :ref:`admin-stats-accessing`.