trafficserver-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From bc...@apache.org
Subject [trafficserver] 04/04: doc: Updates for the logging.config and ssl_server_name.config yaml conversion
Date Fri, 15 Jun 2018 00:25:32 GMT
This is an automated email from the ASF dual-hosted git repository.

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

commit 2e8724d535e37e60bd04030c7ae161cff925a74a
Author: Randall Meyer <randallmeyer@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
    
    (cherry picked from commit 1c189cdfb0b41130e78cf5ef18438db2fc5e18c3)
---
 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.

Mime
View raw message