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 <[email protected]> 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 [email protected].
