Doc: Various minor fixes, update milestone API page.
Project: http://git-wip-us.apache.org/repos/asf/trafficserver/repo Commit: http://git-wip-us.apache.org/repos/asf/trafficserver/commit/14c9cf2c Tree: http://git-wip-us.apache.org/repos/asf/trafficserver/tree/14c9cf2c Diff: http://git-wip-us.apache.org/repos/asf/trafficserver/diff/14c9cf2c Branch: refs/heads/5.0.x Commit: 14c9cf2c8be26fe8ff121df44e00a18df634d488 Parents: c290ce0 Author: Alan M. Carroll <a...@network-geographics.com> Authored: Fri Aug 23 22:33:07 2013 -0500 Committer: Alan M. Carroll <a...@network-geographics.com> Committed: Fri Aug 23 22:33:07 2013 -0500 ---------------------------------------------------------------------- doc/ext/traffic-server.py | 3 +- doc/reference/api/TSHttpTxnMilestoneGet.en.rst | 70 +++++++++++--------- doc/reference/api/index.en.rst | 5 +- .../configuration/records.config.en.rst | 2 +- 4 files changed, 44 insertions(+), 36 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/trafficserver/blob/14c9cf2c/doc/ext/traffic-server.py ---------------------------------------------------------------------- diff --git a/doc/ext/traffic-server.py b/doc/ext/traffic-server.py index e6a4ef0..4adfb8f 100644 --- a/doc/ext/traffic-server.py +++ b/doc/ext/traffic-server.py @@ -209,7 +209,8 @@ def setup(app): objname='Configuration file', indextemplate='pair: %s; Configuration files') - rst.roles.register_generic_role('arg', nodes.emphasis); + rst.roles.register_generic_role('arg', nodes.emphasis) + rst.roles.register_generic_role('const', nodes.literal) app.add_domain(TrafficServerDomain) http://git-wip-us.apache.org/repos/asf/trafficserver/blob/14c9cf2c/doc/reference/api/TSHttpTxnMilestoneGet.en.rst ---------------------------------------------------------------------- diff --git a/doc/reference/api/TSHttpTxnMilestoneGet.en.rst b/doc/reference/api/TSHttpTxnMilestoneGet.en.rst index c7e6bb8..da1188b 100644 --- a/doc/reference/api/TSHttpTxnMilestoneGet.en.rst +++ b/doc/reference/api/TSHttpTxnMilestoneGet.en.rst @@ -26,51 +26,57 @@ Synopsis `#include <ts/ts.h>` -.. function:: TSReturnCode TSHttpTxnMilestoneGet(TSHttpTxn txnp, TSMilestonesType milestone, TSHRTime * time) +.. function:: TSReturnCode TSHttpTxnMilestoneGet(TSHttpTxn txnp, TSMilestonesType milestone, TSHRTime* time) Description =========== -:func:`TSHttpTxnMilestoneGet` will fetch a specific milestone timer -value for the current request. These timers are calculated during -the lifetime of a transaction, and are all in :type:`TSHRTime` units -(nanoseconds), measured from the beginning of the transaction. The -:data:`time` argument is a pointer to a valid :type:`TSHRtime` -storage, and is set upon success. +:func:`TSHttpTxnMilestoneGet` will fetch a specific :arg:`milestone` timer value for the transaction :arg:`txnp`. These timers are +calculated during the lifetime of a transaction and are measured in nanoseconds from the beginning of the transaction. +:arg:`time` is used a pointer to storage to update if the call is successful. -The supported :type:`TSMilestonesType` milestone types are: - -.. _txn-milestone-table: +.. type:: TSMilestonesType =============================================== ========== -Key Milestone +Value Milestone =============================================== ========== -:data:`TS_MILESTONE_UA_BEGIN` -:data:`TS_MILESTONE_UA_READ_HEADER_DONE` -:data:`TS_MILESTONE_UA_BEGIN_WRITE` -:data:`TS_MILESTONE_UA_CLOSE` -:data:`TS_MILESTONE_SERVER_FIRST_CONNECT` -:data:`TS_MILESTONE_SERVER_CONNECT` -:data:`TS_MILESTONE_SERVER_CONNECT_END` -:data:`TS_MILESTONE_SERVER_BEGIN_WRITE` -:data:`TS_MILESTONE_SERVER_FIRST_READ` -:data:`TS_MILESTONE_SERVER_READ_HEADER_DONE` -:data:`TS_MILESTONE_SERVER_CLOSE` -:data:`TS_MILESTONE_CACHE_OPEN_READ_BEGIN` -:data:`TS_MILESTONE_CACHE_OPEN_READ_END` -:data:`TS_MILESTONE_CACHE_OPEN_WRITE_BEGIN` -:data:`TS_MILESTONE_CACHE_OPEN_WRITE_END` -:data:`TS_MILESTONE_DNS_LOOKUP_BEGIN` -:data:`TS_MILESTONE_DNS_LOOKUP_END` -:data:`TS_MILESTONE_SM_START` -:data:`TS_MILESTONE_SM_FINISH` -:data:`TS_MILESTONE_LAST_ENTRY` +:const:`TS_MILESTONE_UA_BEGIN` The client connection is accepted. +:const:`TS_MILESTONE_UA_READ_HEADER_DONE` The request header from the client has been read and parsed. +:const:`TS_MILESTONE_UA_BEGIN_WRITE` The response header write to the client starts. +:const:`TS_MILESTONE_UA_CLOSE` Last I/O activity on the client socket, or connection abort. +:const:`TS_MILESTONE_SERVER_FIRST_CONNECT` First time origin server connect attempted or shared shared session attached. +:const:`TS_MILESTONE_SERVER_CONNECT` Most recent time origin server connect attempted or shared session attached. +:const:`TS_MILESTONE_SERVER_CONNECT_END` More recent time a connection attempt was resolved. +:const:`TS_MILESTONE_SERVER_BEGIN_WRITE` First byte is written to the origin server connection. +:const:`TS_MILESTONE_SERVER_FIRST_READ` First byte is read from connection to origin server. +:const:`TS_MILESTONE_SERVER_READ_HEADER_DONE` Origin server response has been read and parsed. +:const:`TS_MILESTONE_SERVER_CLOSE` Last I/O activity on origin server connection. +:const:`TS_MILESTONE_CACHE_OPEN_READ_BEGIN` Initiate read of the cache. +:const:`TS_MILESTONE_CACHE_OPEN_READ_END` Initial cache read has resolved. +:const:`TS_MILESTONE_CACHE_OPEN_WRITE_BEGIN` Start open for cache write. +:const:`TS_MILESTONE_CACHE_OPEN_WRITE_END` Cache has been opened for write. +:const:`TS_MILESTONE_DNS_LOOKUP_BEGIN` Initiate host resolution in HostDB +:const:`TS_MILESTONE_DNS_LOOKUP_END` Host resolution resolves. +:const:`TS_MILESTONE_SM_START` Transaction state machine is initialized. +:const:`TS_MILESTONE_SM_FINISH` Transaction has finished, state machine final logging has started. =============================================== ========== +* The server connect times predate the transmission of the ``SYN`` packet. That is, before a connection to the + origin server is completed. + +* A connection attempt is *resolved* when no more connection related activity remains to be done, and the connection is + either established or has failed. + +* :const:`TS_MILESTONE_UA_CLOSE` and :const:`TS_MILESTONE_SERVER_CLOSE` are updated continuously during the life of the + transaction, every time there is I/O activity. The updating stops when the corresponding connection is closed, + leaving the last I/O time as the final value. + +* The cache ``OPEN`` milestones time only the initial setup, the "open", not the full read or write. + Return values ============= -:data:`TS_SUCCESS` or :data:`TS_ERROR`. +:const:`TS_SUCCESS` if successful and :arg:`time` was updated, otherwise :const:`TS_ERROR`. See also ======== http://git-wip-us.apache.org/repos/asf/trafficserver/blob/14c9cf2c/doc/reference/api/index.en.rst ---------------------------------------------------------------------- diff --git a/doc/reference/api/index.en.rst b/doc/reference/api/index.en.rst index 3224697..77c02be 100644 --- a/doc/reference/api/index.en.rst +++ b/doc/reference/api/index.en.rst @@ -8,9 +8,9 @@ API Reference 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 @@ -34,3 +34,4 @@ API Reference TSTrafficServerVersionGet.en.rst TSUrlCreate.en.rst TSmalloc.en.rst + TSTypes.en.rst http://git-wip-us.apache.org/repos/asf/trafficserver/blob/14c9cf2c/doc/reference/configuration/records.config.en.rst ---------------------------------------------------------------------- diff --git a/doc/reference/configuration/records.config.en.rst b/doc/reference/configuration/records.config.en.rst index 9e17988..4d81143 100644 --- a/doc/reference/configuration/records.config.en.rst +++ b/doc/reference/configuration/records.config.en.rst @@ -1567,7 +1567,7 @@ server, refer to `logs_xml.config <logs_xml.config>`_. If set to a non-zero value :arg:`N` then any connection that takes longer than :arg:`N` milliseconds from accept to completion will cause its timing stats to be written to the :ts:cv:`debugging log file - <proxy.config.output.logfile>`. This is identifying data about the transaction and all of the :ref:`transaction milestones <txn-milestone-table>`. + <proxy.config.output.logfile>`. This is identifying data about the transaction and all of the :c:type:`transaction milestones <TSMilestonesType>`. Diagnostic Logging Configuration ================================
