You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficserver.apache.org by bc...@apache.org on 2018/06/14 17:48:31 UTC
[trafficserver] 04/04: doc: Updates for the logging.config and
ssl_server_name.config yaml conversion
This is an automated email from the ASF dual-hosted git repository.
bcall pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/trafficserver.git
commit 1c189cdfb0b41130e78cf5ef18438db2fc5e18c3
Author: Randall Meyer <ra...@yahoo.com>
AuthorDate: Fri Jun 1 08:09:10 2018 -0700
doc: Updates for the logging.config and ssl_server_name.config yaml conversion
This is still a WIP
---
doc/admin-guide/files/logging.config.en.rst | 107 +++++++++----------
.../files/ssl_server_name.config.en.rst | 36 +++----
doc/admin-guide/logging/destinations.en.rst | 16 +--
doc/admin-guide/logging/examples.en.rst | 114 +++++++++++----------
doc/admin-guide/logging/formatting.en.rst | 17 +--
doc/admin-guide/logging/understanding.en.rst | 10 +-
6 files changed, 150 insertions(+), 150 deletions(-)
diff --git a/doc/admin-guide/files/logging.config.en.rst b/doc/admin-guide/files/logging.config.en.rst
index d368435..9ad9a21 100644
--- a/doc/admin-guide/files/logging.config.en.rst
+++ b/doc/admin-guide/files/logging.config.en.rst
@@ -68,20 +68,20 @@ variable. The function takes a table with two attributes: a mandatory string
optional number ``Interval`` defining the aggregation interval for summary
logs.
-.. code:: lua
+.. code:: yaml
- -- A one-line-per-event format that just prints event timestamps.
- myformat = format {
- Format = '%<cqtq>'
- }
+ # A one-line-per-event format that just prints event timestamps.
+ formats:
+ - name: myformat
+ format: '%<cqtq>'
- -- An aggregation/summary format that prints the last event timestamp from
- -- the interval along with the total count of events in the same interval.
- -- (Doing so every 30 seconds.)
- mysummaryformat = format {
- Format = '%<LAST(cqtq)> %<COUNT(*)>',
- Interval = 30
- }
+ # An aggregation/summary format that prints the last event timestamp from
+ # the interval along with the total count of events in the same interval.
+ # (Doing so every 30 seconds.)
+ formats:
+ - name: mysummaryformat
+ format: '%<LAST(cqtq)> %<COUNT(*)>'
+ interval: 30
You may define as many and as varied a collection of format objects as you
desire.
@@ -294,30 +294,29 @@ required.
=================== =========== ===============================================
Name Type Description
=================== =========== ===============================================
-Filename string The name of the logfile relative to the default
+filename string The name of the logfile relative to the default
logging directory (set with
:ts:cv:`proxy.config.log.logfile_dir`).
-Format string or Either a format object created earlier, or a
- format obj string with a valid format specification.
-Header string If present, emitted as the first line of each
+format string a string with a valid named format specification.
+header string If present, emitted as the first line of each
new log file.
-RollingEnabled *see below* Determines the type of log rolling to use (or
+rolling_enabled *see below* Determines the type of log rolling to use (or
whether to disable rolling). Overrides
:ts:cv:`proxy.config.log.rolling_enabled`.
-RollingIntervalSec number Interval in seconds between log file rolling.
+rolling_interval_sec number Interval in seconds between log file rolling.
Overrides
:ts:cv:`proxy.config.log.rolling_interval_sec`.
-RollingOffsetHr number Specifies an hour (from 0 to 23) at which log
+rolling_offset_hr number Specifies an hour (from 0 to 23) at which log
rolling is guaranteed to align. Only has an
effect if RollingIntervalSec is set to greater
than one hour. Overrides
:ts:cv:`proxy.config.log.rolling_offset_hr`.
-RollingSizeMb number Size, in megabytes, at which log files are
+rolling_size_mb number Size, in megabytes, at which log files are
rolled.
-Filters array of The optional list of filter objects which
+filters array of The optional list of filter objects which
filters restrict the individual events logged. The array
may only contain one accept filter.
-CollationHosts array of If present, one or more strings specifying the
+collation_hosts array of If present, one or more strings specifying the
strings log collation hosts to which logs should be
delivered, each in the form of "<ip>:<port>".
:ref:`admin-logging-collation` for more
@@ -325,7 +324,7 @@ CollationHosts array of If present, one or more strings specifying the
=================== =========== ===============================================
Enabling log rolling may be done globally in :file:`records.config`, or on a
-per-log basis by passing appropriate values for the ``RollingEnabled`` key. The
+per-log basis by passing appropriate values for the ``rolling_enabled`` key. The
latter method may also be used to effect different rolling settings for
individual logs. The numeric values that may be passed are the same as used by
:ts:cv:`proxy.config.log.rolling_enabled`. For convenience and readability,
@@ -355,64 +354,60 @@ Examples
The following is an example of a format that collects information using three
common fields:
-.. code:: lua
+.. code:: yaml
- minimalfmt = format {
- Format = '%<chi> : %<cqu> : %<pssc>'
- }
+ formats:
+ - name: minimalfmt
+ format: '%<chi> : %<cqu> : %<pssc>'
The following is an example of a format that uses aggregate operators to
produce a summary log:
-.. code:: lua
+.. code:: yaml
- summaryfmt = format {
- Format = '%<LAST(cqts)> : %<COUNT(*)> : %<SUM(psql)>',
- Interval = 10
- }
+ formats:
+ - name: summaryfmt
+ format: '%<LAST(cqts)> : %<COUNT(*)> : %<SUM(psql)>'
+ interval: 10
The following is an example of a filter that will cause only REFRESH_HIT events
to be logged:
-.. code:: lua
+.. code:: yaml
- refreshhitfilter = filter.accept('pssc MATCH REFRESH_HIT')
+ filters:
+ - name: refreshhitfilter
+ accept: pssc MATCH REFRESH_HIT
The following is an example of a filter that will cause the value of the first
query parameter named ``passwd`` to be wiped.
-.. code:: lua
+.. code:: yaml
- passwdfilter = filter.wipe('passwd')
+ filters:
+ - name: passwdfilter
+ wipe: passwd
The following is an example of a log specification that creates a local log
file for the minimal format defined earlier. The log filename will be
``minimal.log`` because we select the ASCII logging format.
-.. code:: lua
+.. code:: yaml
- log.ascii {
- Filename = 'minimal',
- Format = minimalfmt
- }
+ logs:
+ - mode: ascii
+ filename: minimal
+ format: minimalfmt
The following is an example of a log specification that creates a local log
file using the summary format from earlier, and only includes events that
matched the REFRESH_HIT filter we created.
-.. code:: lua
+.. code:: yaml
- log.ascii {
- Filename = 'refreshhit_summary',
- Format = summaryfmt,
- Filters = { refreshhitfilter }
- }
-
-Further Reading
-===============
-
-As the :file:`logging.config` configuration file is just a Lua script (with a
-handful of predefined functions and variables), general Lua references may be
-handy for those not already familiar with the language.
-
-* `Lua Documentation <https://www.lua.org/docs.html>`_
+ logs:
+ - mode: ascii
+ filename: refreshhit_summary
+ format: summaryfmt
+ filters:
+ - refreshhitfilter
diff --git a/doc/admin-guide/files/ssl_server_name.config.en.rst b/doc/admin-guide/files/ssl_server_name.config.en.rst
index 281edf7..7760ee0 100644
--- a/doc/admin-guide/files/ssl_server_name.config.en.rst
+++ b/doc/admin-guide/files/ssl_server_name.config.en.rst
@@ -37,11 +37,10 @@ By default this is named :file:`ssl_server_name.config`. The file can be changed
:ts:cv:`proxy.config.ssl.servername.filename`. This file is loaded on start up and by
:option:`traffic_ctl config reload` if the file has been modified since process start.
-The configuration file is Lua based. After parsing and executing the Lua code, the global Lua
-variable :code:`server_config` is examined. Its value should be a list of tables. Each table is a set
-of key / value pairs that create a configuration item. This configuration file accepts wildcard entries. To apply an SNI based
-setting on all the servernames with a common upper level domain name, the user needs to enter the fqdn in the configuration
-with a ``*.`` followed by the common domain name. (``*.yahoo.com`` for e.g.,).
+The configuration file is yaml-based. After parsing the configuration, a list of tables will be the result.
+Each table is a set of key / value pairs that create a configuration item. This configuration file accepts
+wildcard entries. To apply an SNI based setting on all the servernames with a common upper level domain name,
+the user needs to enter the fqdn in the configuration with a ``*.`` followed by the common domain name. (``*.yahoo.com`` for e.g.,).
======================= ==============================================================================
Key Meaning
@@ -108,31 +107,28 @@ Examples
Disable HTTP/2 for ``no-http2.example.com``.
-.. code-block:: lua
+.. code-block:: yaml
- server_config = {{ fqdn="no-http2.example.com", disable_h2=true }}
+ - fqdn: no-http2.example.com
+ disable_h2: true
Require client certificate verification for ``example.com`` and any server name ending with ``.yahoo.com``. Therefore, client request for a server name ending with yahoo.com (for e.g., def.yahoo.com, abc.yahoo.com etc.) will cause |TS| require and verify the client certificate. By contrast, |TS| will allow a client certficate to be provided for ``example.com`` and if it is, |TS| will require the certificate to be valid.
-.. code-block:: lua
+.. code-block:: yaml
- server_config = {
- { fqdn="example.com", verify_client='MODERATE' },
- { fqdn="*.yahoo.com", verify_client='STRICT' }
- }
+ - fqdn: example.com
+ verify_client: MODERATE
+ - fqdn: '*.yahoo.com'
+ verify_client: STRICT
Disable outbound server certificate verification for ``trusted.example.com`` and require a valid
client certificate.
-.. code-block:: lua
+.. code-block:: yaml
- server_config = {
- {
- fqdn="trusted.example.com",
- verify_origin_server='NONE',
- verify_client='STRICT'
- }
- }
+ - fqdn: trusted.example.com
+ verify_origin_server: NONE
+ verify_client: STRICT
See Also
========
diff --git a/doc/admin-guide/logging/destinations.en.rst b/doc/admin-guide/logging/destinations.en.rst
index 1cb2c44..354fb80 100644
--- a/doc/admin-guide/logging/destinations.en.rst
+++ b/doc/admin-guide/logging/destinations.en.rst
@@ -306,13 +306,15 @@ To collate custom event log files:
``CollationHosts`` attribute to the relevant logs. For example, adding two
collation hosts to an ASCII log that uses the Squid format would look like:
- .. code:: lua
-
- log.ascii {
- Format = squid,
- Filename = 'squid',
- CollationHosts = { '192.168.1.100:4567', '192.168.1.101:4567' }
- }
+ .. code:: yaml
+
+ logs:
+ - mode: ascii
+ format: squid
+ filename: squid
+ collationhosts:
+ - 192.168.1.100:4567
+ - 192.168.1.101:4567
#. Run the command :option:`traffic_ctl config reload` to restart |TS|.
diff --git a/doc/admin-guide/logging/examples.en.rst b/doc/admin-guide/logging/examples.en.rst
index 12a51bc..07474bf 100644
--- a/doc/admin-guide/logging/examples.en.rst
+++ b/doc/admin-guide/logging/examples.en.rst
@@ -68,11 +68,11 @@ No. Field Description
To recreate this as a log format in :file:`logging.config` you would define the
following format object:
-.. code:: lua
+.. code:: yaml
- common = format {
- Format = '%<chi> - %<caun> [%<cqtn>] "%<cqtx>" %<pssc> %<pscl>'
- }
+ formats:
+ - name: common
+ format: '%<chi> - %<caun> [%<cqtn>] "%<cqtx>" %<pssc> %<pscl>'
.. _admin-logging-examples-extended:
@@ -115,11 +115,11 @@ No. Field Description
To recreate this as a log format in :file:`logging.config` you would define the
following format object:
-.. code:: lua
+.. code:: yaml
- extended = format {
- Format = '%<chi> - %<caun> [%<cqtn>] "%<cqtx>" %<pssc> %<pscl> %<sssc> %<sscl> %<cqcl> %<pqcl> %<cqhl> %<pshl> %<pqhl> %<sshl> %<tts>'
- }
+ formats:
+ - name: extended
+ format: '%<chi> - %<caun> [%<cqtn>] "%<cqtx>" %<pssc> %<pscl> %<sssc> %<sscl> %<cqcl> %<pqcl> %<cqhl> %<pshl> %<pqhl> %<sshl> %<tts>'
.. _admin-logging-examples-extended2:
@@ -154,11 +154,11 @@ No. Field Description
To recreate this as a log format in :file:`logging.config` you would define the
following format object:
-.. code:: lua
+.. code:: yaml
- extended2 = format {
- Format = '%<chi> - %<caun> [%<cqtn>] "%<cqtx>" %<pssc> %<pscl> %<sssc> %<sscl> %<cqcl> %<pqcl> %<cqhl> %<pshl> %<pqhl> %<sshl> %<tts> %<phr> %<cfsc> %<pfsc> %<crc>'
- }
+ formats:
+ - name: extended2
+ format: '%<chi> - %<caun> [%<cqtn>] "%<cqtx>" %<pssc> %<pscl> %<sssc> %<sscl> %<cqcl> %<pqcl> %<cqhl> %<pshl> %<pqhl> %<sshl> %<tts> %<phr> %<cfsc> %<pfsc> %<crc>'
.. _admin-logging-examples-squid:
@@ -208,11 +208,11 @@ No. Field Description
To recreate this as a log format in :file:`logging.config` you would define the
following format object:
-.. code:: lua
+.. code:: yaml
- squid = format {
- Format = '%<cqtq> %<ttms> %<chi> %<crc>/%<pssc> %<psql> %<cqhm> %<cquc> %<caun> %<phr>/%<pqsn> %<psct>'
- }
+ formats:
+ - name: squid
+ format: '%<cqtq> %<ttms> %<chi> %<crc>/%<pssc> %<psql> %<cqhm> %<cquc> %<caun> %<phr>/%<pqsn> %<psct>'
Hourly Rotated Squid Proxy Logs
===============================
@@ -221,19 +221,19 @@ The following example demonstrates the creation of a Squid-compatible log
format, which is then applied to a log object containing an hourly rotation
policy.
-.. code:: lua
+.. code:: yaml
- squid = format {
- Format = '%<cqtq> %<ttms> %<chi> %<crc>/%<pssc> %<psql> %<cqhm> %<cquc> %<caun> %<phr>/%<pqsn> %<psct>'
- }
+ formats:
+ - name: squid
+ format: '%<cqtq> %<ttms> %<chi> %<crc>/%<pssc> %<psql> %<cqhm> %<cquc> %<caun> %<phr>/%<pqsn> %<psct>'
- log.ascii {
- Format = squid,
- Filename = 'squid',
- RollingEnabled = 1,
- RollingIntervalSec = 3600,
- RollingOffsetHr = 0
- }
+ logs:
+ - mode: ascii
+ format: squid
+ filename: squid
+ rolling_enabled: time
+ rolling_interval_sec: 3600
+ rolling_offset_hr: 0
Summarizing Number of Requests and Total Bytes Sent Every 10 Seconds
====================================================================
@@ -243,12 +243,12 @@ contains the timestamp of the last entry of the interval, a count of the number
of entries seen within that 10-second interval, and the sum of all bytes sent
to clients:
-.. code:: lua
+.. code:: yaml
- mysummary = format {
- Format = "%<LAST(cqts)> : %<COUNT(*)> : %<SUM(psql)>",
- Interval = "10"
- }
+ formats:
+ - name: mysummary
+ format: '%<LAST(cqts)> : %<COUNT(*)> : %<SUM(psql)>'
+ interval: 10
Dual Output to Compact Binary Logs and ASCII Pipes
==================================================
@@ -258,7 +258,7 @@ a hypothetical scenario where we may wish to keep a compact form of our logs
available for archival purposes, while performing live log analysis on a stream
of the event data.
-.. code:: lua
+.. code:: yaml
ourformat = format {
Format = '%<chi> - %<caun> [%<cqtn>] "%<cqtx>" %<pssc> %<pscl>'
@@ -282,19 +282,22 @@ off all sorts of alarms. To accomplish this, we demonstrate the use of a filter
object that matches events against these particular canaries and emits log data
for them to a UNIX pipe that the alerting software can constantly read from.
-.. code:: lua
+.. code:: yaml
- canaryformat = format {
- Format = '%<chi> - %<caun> [%<cqtn>] "%<cqtx>" %<pssc> %<pscl>'
- }
+ formats:
+ - name: canaryformat
+ format: '%<chi> - %<caun> [%<cqtn>] "%<cqtx>" %<pssc> %<pscl>'
- canaryfilter = filter.accept('cqup MATCH "/nightmare/scenario/dont/touch"')
+ filters:
+ - name: canaryfilter
+ accept: cqup MATCH "/nightmare/scenario/dont/touch"
- log.pipe {
- Format = canaryformat,
- Filters = [ canaryfilter ],
- Filename = 'alerting_canaries'
- }
+ logs:
+ - mode: pipe
+ format: canaryformat
+ filters:
+ - canaryfilter
+ filename: alerting_canaries
Summarizing Origin Responses by Hour
====================================
@@ -305,18 +308,21 @@ servers (where we assume that any cache result code without the string ``HIT``
in it signals origin access), as well as the average time it took to fulfill
the request to clients during that hour.
-.. code:: lua
+.. code:: yaml
- originrepformat = format {
- Format = '%<FIRST(cqtq)> %<COUNT(*)> %<AVERAGE(ttms)>',
- Interval = 3600
- }
+ formats:
+ - name: originrepformat
+ format: '%<FIRST(cqtq)> %<COUNT(*)> %<AVERAGE(ttms)>'
+ interval: 3600
- originfilter = filter.reject('crc CONTAINS "HIT"')
+ filters:
+ - name: originfilter
+ reject: crc CONTAINS "HIT"
- log.ascii {
- Format = originrepformat,
- Filters = [ originfilter ],
- Filename = 'origin_access_summary'
- }
+ logs:
+ - mode: ascii
+ format: originrepformat
+ filters:
+ - originfilter
+ filename: origin_access_summary
diff --git a/doc/admin-guide/logging/formatting.en.rst b/doc/admin-guide/logging/formatting.en.rst
index 6ac7b7f..d42640b 100644
--- a/doc/admin-guide/logging/formatting.en.rst
+++ b/doc/admin-guide/logging/formatting.en.rst
@@ -48,11 +48,12 @@ logging destinations.
A very simple exampe, which contains only the timestamp of when the event began
and the canonical URL of the request, would look like:
-.. code:: lua
+.. code:: yaml
+
+ formats:
+ - name: myformat
+ format: '%<cqtq> %<cauc>'
- myformat = format {
- Format = "%<cqtq> %<cauc>"
- }
You may include as many custom field codes as you wish. The full list of codes
available can be found in :ref:`admin-logging-fields`. You may also include
@@ -61,11 +62,11 @@ the timestamp and canonical URL in our customer format above with a slash
instead of a space, or even a slash surrounded by spaces, we could do so by
just adding the desired characters to the format string:
-.. code:: lua
+.. code:: yaml
- myformat = format {
- Format = "%<cqtq> / %<cauc>"
- }
+ formats:
+ - name: myformat
+ format: '%<cqtq> / %<cauc>'
You may define as many custom formats as you wish. To apply changes to custom
formats, you will need to run the command :option:`traffic_ctl config reload`
diff --git a/doc/admin-guide/logging/understanding.en.rst b/doc/admin-guide/logging/understanding.en.rst
index 2839ca2..0c9fcb9 100644
--- a/doc/admin-guide/logging/understanding.en.rst
+++ b/doc/admin-guide/logging/understanding.en.rst
@@ -147,12 +147,12 @@ Summary logs are defined in :file:`logging.config` just like regular event
logs, with the only two differences being the exclusive use of the
aforementioned aggregate functions and the specification of an interval, as so:
-.. code:: lua
+.. code:: yaml
- mysummary = format {
- Format = "%<operator(field)> : %<operator(field)>",
- Interval = "n"
- }
+ formats:
+ - name: mysummary
+ format: '%<operator(field)> : %<operator(field)>'
+ interval: n
The interval itself is given with *n* as the number of seconds for each period
of aggregation. There is no default value.
--
To stop receiving notification emails like this one, please contact
bcall@apache.org.