doc/admin-guide/plugins/stats_over_http.en.rst

.. 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.

.. include:: ../../common.defs

.. _admin-plugins-stats-over-http:

Stats Over HTTP Plugin
**********************

This plugin implements an HTTP interface to all Traffic Server statistics. The
metrics returned are in a JSON format by default, for easy processing. You can
also output the stats in CSV format as well. This plugin is now part of the
standard ATS build process, and should be available after install.

Enabling Stats Over HTTP
========================

To enable this plugin, add to the :file:`plugin.config` file::

    stats_over_http.so

After starting Traffic Server, the JSON metrics are now available on the
default URL::

    http://host:port/_stats

where host and port is the hostname/IP and port number of the server.



Plugin Options
==============


.. option:: --integer-counters

This option causes the plugin to emit floating point and integral
metric values as JSON numbers, rather then JSON strings. This can
cause interoperability problems since integer metrics have a 64-bit
unsigned range.

.. option:: --wrap-counters

This option wraps 64-bit unsigned values to the 64-bit signed range.
This aids interoperability with Java, since prior to the Java SE 8
release, Java did not have a 64-bit unsigned type.

You can optionally modify the path to use, and this is highly
recommended in a public facing server. For example::

    stats_over_http.so 81c075bc0cca1435ea899ba4ad72766b

and the URL would then be e.g.::

    https://host:port/81c075bc0cca1435ea899ba4ad72766b

This is weak security at best, since the secret could possibly leak if you are
careless and send it over clear text.

Config File Usage
=================

stats_over_http.so also accepts a configuration file taken as a parameter

The plugin first checks if the parameter that was passed in is a file that exists, if so
it uses that as a config file, otherwise if a parameter exists it assumes that it is meant
to be used a path value (as if you were not using a config file)

You can add comments to the config file, starting with a `#` value

Other options you can specify:

.. option:: path=

This sets the path value for stats

.. option:: allow_ip=

A comma separated list of IPv4 addresses allowed to access the endpoint

.. option:: allow_ip6=

A comma separated list of IPv6 addresses allowed to access the endpoint

Output Format
=============

By default stats_over_http.so will output all the stats in JSON format. However
if you wish to have it in CSV format you can do so by passing an ``Accept`` header:

.. option:: Accept: text/csv

Prometheus formatted output is also supported via the ``Accept`` header. Version 0.0.4
(flat metric names) and version 2.0.0 (labeled metrics for better aggregation)
are supported:

.. option:: Accept: text/plain; version=0.0.4
.. option:: Accept: text/plain; version=2.0.0

Alternatively, the output format can be specified as a suffix to the configured
path in the HTTP request target.  The supported suffixes are ``/json``,
``/csv``, ``/prometheus``, and ``/prometheus_v2``.  For example, if the path
is set to ``/_stats`` (the default), you can access the stats in CSV format by
using the URL::

    http://host:port/_stats/csv

The Prometheus version 0.0.4 format (flat) can be requested by using the URL::

    http://host:port/_stats/prometheus

The Prometheus v2 labeled format can be requested by using the URL::

    http://host:port/_stats/prometheus_v2

The JSON format is the default, but you can also access it explicitly by using the URL::

    http://host:port/_stats/json

Note that using a path suffix overrides any ``Accept`` header. Thus if you
specify a path suffix, the plugin will return the data in that format regardless of
the ``Accept`` header.

In either case the ``Content-Type`` header returned by ``stats_over_http.so`` will
reflect the content that has been returned: ``text/json``, ``text/csv``,
``text/plain; version=0.0.4; charset=utf-8``, or
``text/plain; version=2.0.0; charset=utf-8`` for JSON, CSV, Prometheus v1, and
Prometheus v2 formats respectively.


Stats over http also accepts returning data in gzip or br compressed format per the
``Accept-encoding`` header. If the header is present, the plugin will return the
data in the specified encoding, for example:

.. option:: Accept-encoding: gzip, br