Traffic Server Specific Markup

This section covers markup used specific to the Traffic Server documentation and custom domains provided by local extensions.

Types

Data types are documented using the standard :c:type: markup provided by Sphinx. Types provided by the C API should be documented in doc/developer-guide/api/types/

Constants

Functions

Custom Domains

The Traffic Server documentation provides a Sphinx extension, located at doc/ext/traffic-server.py which defines custom domains for various purposes. Those domains and their usage are documented here.

Configuration Variables

Configuration variables are documented with the :ts:cv: domain, which takes three required arguments (the scope, which is the literal string CONFIG, the variable name, and the data type) and a fourth optional argument (the default value).

:ts:cv: <scope> <variable name> <data type> <value>

This corresponds exactly to the line in records.config.

Definition

Scope

The scope of the variable. For configuration variables, this will always be the literal string CONFIG.

Variable Name

The full and exact configuration variable name.

Data Type

Indicates the data type of the variable and must be one of the following literal strings:

INT

Any integer value. Values may optionally be expressed with a binary order of magnitude suffix; e.g. K for value * 1024, M for value * 1024^2, G for value * 1024^3, or T for value * 1024^4.

FLOAT

Any floating point value.

STRING

Any alphanumeric string.

Value

The default value of the configuration variable. It is preferable to not use any order of magnitude suffix, as Traffic Server will rewrite its configuration files under varioua circumstances, and when doing so it does not maintain those suffixes.

Options

The domain for configuration variables takes serveral options.

reloadable

If marked the effect of the variable can be changed by reloading the Traffic Server configuration.

overridable

A flag option that should be set if the variable is overridable per transaction.

units

This takes a string option which is a description of the units for the variable. The most common case is to distinguish time values with units such as “seconds”, “minutes”, “milliseconds”, etc.

deprecated

A simple flag option which, when attached to a configuration variable, is used to indicate that the variable has been deprecated and should no longer be used or relied upon, as it may be removed at any time by future releases.

References

References to configuration variables from elsewhere in the documentation should be made using the standard domain reference markup:

:ts:cv:`full.variable.name`

Statistics

Traffic Server statistics are documented using the domain :ts:stat:. The domain takes three required arguments (collection, name, data type) and an option fourth (an example value).

:ts:stat: <collection> <statistic name> <data type> <example-value>

Definition

Collection

The key name of the collection in the returned JSON data from the Stats Over HTTP Plugin plugin. For most statistics, this is the literal sting global. Required

Statistic Name

The exact and full name of the statistic. Required

Data Type

One of the following literal string values: integer, float, boolean, or string. Required

Example Value

A valid example of the value which may be exported by the statistic. In cases where the description of the statistic makes note of particular features of the values, such as the case of string statistics which may be formatted in specific ways, providing the optional example is strongly recommended. Optional

The statistics domain also supports several options which can provide even more metadata about the statistic. These are currently:

Options

type

Defines the type of metric exposed by the statistic. Valid values are:

counter

Numeric values which only increment based on the accumulation or occurrence of underlying events. Examples include the total number of incoming connections, or the total number of bytes transferred.

gauge

Used for moment-in-time metrics, such as the current number of Traffic Server processes running, or the current number of connections open to origin servers.

flag

Indicates that values for this statistic will be an integer with each value indicating a particular state. Most statistics of this type are booleans, where 1 indicates a truth or an on state, and 0 the opposite.

derivative

Statistics of this type presents values that are calculated, or derived, from other staistics. They do not expose a number or state gathered directly. Typical statistics of this type are representations of a statistic over a given period (e.g. average origin connections per second), ratio or percentage of a statistic as part of a set (e.g. the percentage of total dns lookups which have failed), or any other statistic whose computation depends on the value(s) of one or more other statistics.

unit

Indicates the units of measurement that should be assumed for the given statistic’s value.

introduced

May be used to indicate the version of Traffic Server in which the statistic was first available. The value of this option should be a valid, human-readable version number string, e.g. 5.3.0.

deprecated

Used to indicate that the statistic is no longer supported and may be removed in later versions. This option may be used as a simple flag without any given value, or may have a value associated in which case it should be a valid, human-readable version number string for the Traffic Server release which was first to deprecate the statistic.

ungathered

A simple flag option, without any associated values, indicating that while the statistic is included in the output of plugins like Stats Over HTTP Plugin there is no underlying data gathered for the statistic. If a statistic is thus marked, it should be assumed to be invalid or simply unimplemented.

References

To reference a statistic from elsewhere in the documentation, the standard domain reference markup should be used:

:ts:stat:`full.statistic.name`

References should not include the collection name, data type, or any other components aside from the statistic name.

Referencing source code

To reference source code from the documentation, use the following markup:

:ts:git:`path/to/source/file`

This creates a link to Github. Sphinx does its best to pin the reference to the current release version of Apache Traffic Server™.

Avoid using hard links to Github as Github may be replaced with another host in the future.

Note

Although adding the ability to point to a specific line number would not be difficult, code shifts around too much and this feature would only cause confusion to a downstream reader. This feature was deliberately omitted.