Updated Branches: refs/heads/master 1993bdf03 -> bb50292e0
Doc: Add transaction buffering control. Project: http://git-wip-us.apache.org/repos/asf/trafficserver/repo Commit: http://git-wip-us.apache.org/repos/asf/trafficserver/commit/bb50292e Tree: http://git-wip-us.apache.org/repos/asf/trafficserver/tree/bb50292e Diff: http://git-wip-us.apache.org/repos/asf/trafficserver/diff/bb50292e Branch: refs/heads/master Commit: bb50292e09f5a3b422b2aee20fb8401e64835c9b Parents: 1993bdf Author: Alan M. Carroll <a...@network-geographics.com> Authored: Fri Aug 30 15:27:56 2013 -0500 Committer: Alan M. Carroll <a...@network-geographics.com> Committed: Fri Aug 30 15:27:56 2013 -0500 ---------------------------------------------------------------------- doc/admin/http-proxy-caching.en.rst | 80 +++++++++++++++----- doc/glossary.en.rst | 5 ++ .../api/TSHttpOverridableConfig.en.rst | 70 +++++++++++++++++ doc/reference/api/TSLifecycleHookAdd.en.rst | 26 ++++--- doc/reference/api/TSTypes.en.rst | 16 +++- doc/reference/api/index.en.rst | 1 + .../configuration/records.config.en.rst | 42 +++++++--- doc/sdk/http-transformation-plugin.en.rst | 8 +- 8 files changed, 204 insertions(+), 44 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/trafficserver/blob/bb50292e/doc/admin/http-proxy-caching.en.rst ---------------------------------------------------------------------- diff --git a/doc/admin/http-proxy-caching.en.rst b/doc/admin/http-proxy-caching.en.rst index 2f5de11..1e60bb1 100644 --- a/doc/admin/http-proxy-caching.en.rst +++ b/doc/admin/http-proxy-caching.en.rst @@ -5,20 +5,20 @@ HTTP Proxy Caching .. Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file - distributed with this work for additional information - regarding copyright ownership. The ASF licenses this file - 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 - + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + 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 - KIND, either express or implied. See the License for the - specific language governing permissions and limitations - under the License. + + 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 + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. Web proxy caching enables you to store copies of frequently-accessed web objects (such as documents, images, and articles) and then serve this @@ -59,7 +59,7 @@ overview illustrates how Traffic Server serves a request. 4. If the data in the cache is stale, then Traffic Server connects to the origin server and checks if the object is still fresh (a - **revalidation**). If it is, then Traffic Server immediately sends + :term:`revalidation`). If it is, then Traffic Server immediately sends the cached copy to the client. 5. If the object is not in the cache (a **cache miss**) or if the server @@ -353,9 +353,9 @@ To configure the Force Immediate Update option .. important:: - When you enable the Force Immediate Update option, Traffic Server continually updates the URLs specified in :file:`update.config` - until you disable the option. To disable the Force Immediate Update option, set :ts:cv:`proxy.config.update.force` to ``0`` - (zero). + When you enable the Force Immediate Update option, Traffic Server continually updates the URLs specified in + :file:`update.config` until you disable the option. To disable the Force Immediate Update option, set + :ts:cv:`proxy.config.update.force` to ``0`` (zero). Pushing Content into the Cache ============================== @@ -402,7 +402,8 @@ place in the cache. The following is an example of a ``PUSH`` request:: .. important:: - Your header must include ``Content-length`` - ``Content-length`` must include both ``header`` and ``body byte count``. + Your header must include ``Content-length`` - ``Content-length`` must include both ``header`` and ``body byte + count``. Tools that will help manage pushing ----------------------------------- @@ -521,7 +522,7 @@ By default, Traffic Server strictly observes ``Cache-Control: no-cache`` directives. A response from an origin server with a ``no-cache`` header is not stored in the cache and any previous copy of the object in the cache is removed. If you configure Traffic Server to ignore ``no-cache`` -headers, then Traffic Server also ignores ``no-store`` headers. The +headers, then Traffic Server also ignores ``no-store`` headers. The efault behavior of observing ``no-cache`` directives is appropriate in most cases. @@ -731,3 +732,44 @@ tasks: #. Run the command :option:`traffic_line -x` to apply the configuration changes. +.. _transaction-buffering-control: + +Using Transaction Buffering Control +=================================== + +By default I/O operations are run at full speed, as fast as either Traffic Server, the network, or the cache can go. +This can be problematic for large objects if the client side connection is significantly slower. In such cases the +content will be buffered in ram while waiting to be sent to the client. This could potentially also happen for ``POST`` +requests if the client connection is fast and the origin server connection slow. If very large objects are being used +this can cause the memory usage of Traffic Server to become `very large +<https://issues.apache.org/jira/browse/TS-1496>`_. + +This problem can be ameloriated by controlling the amount of buffer space used by a transaction. A high water and low +water mark are set in terms of bytes used by the transaction. If the buffer space in use exceeds the high water mark, +the connection is throttled to prevent additional external data from arriving. Internal operations continue to proceed +at full speed until the buffer space in use drops below the low water mark and external data I/O is re-enabled. + +Although this is intended primarily to limit the memory usage of Traffic Server it can also serve as a crude rate +limiter by setting a buffer limit and then throttling the client side connection either externally or via a transform. +This will cause the connection to the origin server to be limited to roughly the client side connection speed. + +Traffic Server does network I/O in large chunks (32K or so) and therefore the granularity of transaction buffering +control is limited to a similar precision. + +The buffer size calculations include all elements in the transaction, including any buffers associated with :ref:`transform plugins <transform-plugin>`. + +Transaction buffering control can be enabled globally by using configuration variables or by :c:func:`TSHttpTxnConfigIntSet` in a plugin. + +================= ================================================== ======================================== +Value Variable `TSHttpTxnConfigIntSet` key +================= ================================================== ======================================== +Enable buffering :ts:cv:`proxy.config.http.flow_control.enabled` `TS_CONFIG_HTTP_FLOW_CONTROL_ENABLED` +Set high water :ts:cv:`proxy.config.http.flow_control.high_water` `TS_CONFIG_HTTP_FLOW_CONTROL_HIGH_WATER` +Set low water :ts:cv:`proxy.config.http.flow_control.low_water` `TS_CONFIG_HTTP_FLOW_CONTROL_LOW_WATER` +================= ================================================== ======================================== + +Be careful to always have the low water mark equal or less than the high water mark. If you set only one, the other will +be set to the same value. + +If using c:func:`TSHttpTxnConfigIntSet`, it must be called no later than `TS_HTTP_READ_RESPONSE_HDR_HOOK`. + http://git-wip-us.apache.org/repos/asf/trafficserver/blob/bb50292e/doc/glossary.en.rst ---------------------------------------------------------------------- diff --git a/doc/glossary.en.rst b/doc/glossary.en.rst index e477540..0970090 100644 --- a/doc/glossary.en.rst +++ b/doc/glossary.en.rst @@ -53,3 +53,8 @@ Glossary storage unit The physical storage described by a single line in :file:`storage.config`. + + revalidation + Verifying that a currently cached object is still valid. This is usually done using an `If-Modified-Since + <http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.25>`_ request which allows the origin server to + validate the content without resending the content. http://git-wip-us.apache.org/repos/asf/trafficserver/blob/bb50292e/doc/reference/api/TSHttpOverridableConfig.en.rst ---------------------------------------------------------------------- diff --git a/doc/reference/api/TSHttpOverridableConfig.en.rst b/doc/reference/api/TSHttpOverridableConfig.en.rst new file mode 100644 index 0000000..09c1774 --- /dev/null +++ b/doc/reference/api/TSHttpOverridableConfig.en.rst @@ -0,0 +1,70 @@ +.. Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + 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 + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + +.. default-domain:: c + +.. _ts-overridable-config: + +======================= +TSHttpOverridableConfig +======================= + +Synopsis +======== +`#include <ts/ts.h>` + +.. type:: TSOverridableConfigKey + +.. function:: TSReturnCode TSHttpTxnConfigIntSet(TSHttpTxn txnp, TSOverridableConfigKey key, TSMgmtInt value) +.. function:: TSReturnCode TSHttpTxnConfigIntGet(TSHttpTxn txnp, TSOverridableConfigKey key, TSMgmtInt* value) +.. function:: TSReturnCode TSHttpTxnConfigFloatSet(TSHttpTxn txnp, TSOverridableConfigKey key, TSMgmtFloat value) +.. function:: TSReturnCode TSHttpTxnConfigFloatGet(TSHttpTxn txnp, TSOverridableConfigKey key, TSMgmtFloat* value) +.. function:: TSReturnCode TSHttpTxnConfigStringSet(TSHttpTxn txnp, TSOverridableConfigKey key, const char* value, int length) +.. function:: TSReturnCode TSHttpTxnConfigStringGet(TSHttpTxn txnp, TSOverridableConfigKey key, const char** value, int* length) +.. function:: TSReturnCode TSHttpTxnConfigFind(const char* name, int length, TSOverridableConfigKey* key, TSRecordDataType* type) + +Description +=========== + +Some of the values that are set in :file:`records.config` can be changed for a specific transaction. It is important to +note that these functions change the configuration values stored for the transation, which is not quite the same as +changing the actual operating values of the transaction. The critical effect is the value must be changed before it is +used by the transaction - after that, changes will not have any effect. + +All of the ``...Get`` functions store the internal value in the storage indicated by the :arg:`value` argument. For strings :arg:`length*` will receive the length of the string. + +The values are identified by the enumeration :type:`TSOverridableConfigKey`. String values can be used indirectly by +first passing them to :func:`TSHttpTxnConfigFind` which, if the string matches an overridable value, return the key and data +type. + +Examples +======== + +Enable :ref:`transaction buffer control <transaction-buffering-control>` with a high water mark of 262144 and a low water mark of 65536. :: + + int callback(TSCont contp, TSEvent event, void* data) + { + TSHttpTxn txnp = static_cast<TSHttpTxn>(data); + TSHttpTxnConfigIntSet(txnp, TS_CONFIG_HTTP_FLOW_CONTROL_ENABLED, 1); + TSHttpTxnConfigIntSet(txnp, TS_CONFIG_HTTP_FLOW_CONTROL_HIGH_WATER_MARK, 262144); + TSHttpTxnConfigIntSet(txnp, TS_CONFIG_HTTP_FLOW_CONTROL_LOWER_WATER_MARK, 65536); + return 0; + } + +See also +======== +:manpage:`TSAPI(3ts)` http://git-wip-us.apache.org/repos/asf/trafficserver/blob/bb50292e/doc/reference/api/TSLifecycleHookAdd.en.rst ---------------------------------------------------------------------- diff --git a/doc/reference/api/TSLifecycleHookAdd.en.rst b/doc/reference/api/TSLifecycleHookAdd.en.rst index 31dc461..b546b77 100644 --- a/doc/reference/api/TSLifecycleHookAdd.en.rst +++ b/doc/reference/api/TSLifecycleHookAdd.en.rst @@ -36,11 +36,6 @@ Description based on the Traffic Server process, not on any specific transaction or session. These will typically be called only once during the execution of the Traffic Server process and therefore should be added in :func:`TSPluginInit` (which could itself be considered a lifecyle hook). Unlike other hooks, lifecycle hooks may not have a well defined ordering and use of them should not assume that one of the hooks is always called before another unless specifically mentioned. -These were introduced to solve process initialization ordering issues (TS-1487). Different API calls required different -modules of Traffic Server to be initialized and all of them had to be called from :func:`TSPluginInit`. The solution was -to move :func:`TSPluginInit` as early as possible in the process initialization and provide hooks for API calls that -needed to be invoked later. - `TS_LIFECYCLE_PORTS_INITIALIZED_HOOK` Called after the :ts:cv:`proxy server port <proxy.config.http.server_ports>` data structures have been initialized but before connections are accepted on those ports. The sockets corresponding to the ports may or may not be open @@ -70,12 +65,12 @@ Ordering Examples ======== -The following example demonstrates how to correctly use :func:`TSNetAcceptNamedProtocol`, which does not work if called -from :func:`TSPluginInit` directly. :: +The following example demonstrates how to correctly use :func:`TSNetAcceptNamedProtocol`, which requires the proxy ports +to be initialized and therefore does not work if called from :func:`TSPluginInit` directly. :: #include <ts/ts.h> - #define SSL_PROTOCOL_NAME "blah blah" + #define SSL_PROTOCOL_NAME "whatever" static int ssl_proto_handler(TSCont contp, TSEvent event, void* data) @@ -86,8 +81,11 @@ from :func:`TSPluginInit` directly. :: static int local_ssl_init(TSCont contp, TSEvent event, void *edata) { - if (TS_EVENT_LIFECYCLE_PORTS_INITIALIZED) { // just to be safe. - TSNetAcceptNamedProtocol(TSContCreate(ssl_proto_handler, NULL), SSL_PROTOCOL_NAME); + if (TS_EVENT_LIFECYCLE_PORTS_INITIALIZED == event) { // just to be safe. + TSNetAcceptNamedProtocol( + TSContCreate(ssl_proto_handler, TSMutexCreate()), + SSL_PROTOCOL_NAME + ); } return 0; } @@ -98,6 +96,14 @@ from :func:`TSPluginInit` directly. :: TSLifecycleHookAdd(TS_LIFECYCLE_PORTS_INITIALIZED_HOOK, TSContCreate(local_ssl_init, NULL)); } +History +======= + +Lifecycle hooks were introduced to solve process initialization ordering issues (TS-1487). Different API calls required +different modules of Traffic Server to be initialized for the call to work, but others did not work that late in initialization, which was problematic because all of them could effectively only be called from :func:`TSPluginInit` . The +solution was to move :func:`TSPluginInit` as early as possible in the process initialization and provide hooks for API +calls that needed to be invoked later which served essentially as additional pluging initialization points. + See also ======== :manpage:`TSAPI(3ts)`, :manpage:`TSContCreate(3ts)` http://git-wip-us.apache.org/repos/asf/trafficserver/blob/bb50292e/doc/reference/api/TSTypes.en.rst ---------------------------------------------------------------------- diff --git a/doc/reference/api/TSTypes.en.rst b/doc/reference/api/TSTypes.en.rst index e24d603..4c4641e 100644 --- a/doc/reference/api/TSTypes.en.rst +++ b/doc/reference/api/TSTypes.en.rst @@ -28,7 +28,8 @@ Synopsis Description =========== -The Apache Traffic Server API provides large number of types. +The Apache Traffic Server API provides large number of types. Many of them are specific to a particular API function or +function group, but others are used more widely. Those are described on this page. .. type:: TSCont @@ -61,3 +62,16 @@ The Apache Traffic Server API provides large number of types. An indicator of the results of an API call. A value of :const:`TS_SUCCESS` means the call was successful. Any other value indicates a failure and is specific to the API call. +.. type:: TSRecordDataType + + An enumeration that specifies the type of a value in an internal data structure that is accessible via the API. + +.. type:: TSMgmtInt + + The type used internally for an integer. This corresponds to the value :const:`TS_RECORDDATATYPE_INT` for + :type:`TSRecordDataType`. + +.. type:: TSMgmtFloat + + The type used internally for a floating point value. This corresponds to the value :const:`TS_RECORDDATATYPE_FLOAT` for + :type:`TSRecordDataType`. http://git-wip-us.apache.org/repos/asf/trafficserver/blob/bb50292e/doc/reference/api/index.en.rst ---------------------------------------------------------------------- diff --git a/doc/reference/api/index.en.rst b/doc/reference/api/index.en.rst index b1fa32f..3509312 100644 --- a/doc/reference/api/index.en.rst +++ b/doc/reference/api/index.en.rst @@ -34,5 +34,6 @@ API Reference TSTrafficServerVersionGet.en TSUrlCreate.en TSLifecycleHookAdd.en + TSHttpOverridableConfig.en TSmalloc.en TSTypes.en http://git-wip-us.apache.org/repos/asf/trafficserver/blob/bb50292e/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 4d81143..74867dd 100644 --- a/doc/reference/configuration/records.config.en.rst +++ b/doc/reference/configuration/records.config.en.rst @@ -703,14 +703,16 @@ Origin Server Connect Attempts .. ts:cv:: CONFIG proxy.config.http.origin_min_keep_alive_connections INT 0 :reloadable: - As connection to an origin server are opened, keep at least 'n' number of connections open to that origin, even if the connection - isn't used for a long time period. Useful when the origin supports keep-alive, removing the time needed to set up a new connection from + As connection to an origin server are opened, keep at least 'n' number of connections open to that origin, even if + the connection isn't used for a long time period. Useful when the origin supports keep-alive, removing the time + needed to set up a new connection from the next request at the expense of added (inactive) connections. To enable, set to one (``1``). .. ts:cv:: CONFIG proxy.config.http.connect_attempts_rr_retries INT 2 :reloadable: - The maximum number of failed connection attempts allowed before a round-robin entry is marked as 'down' if a server has round-robin DNS entries. + The maximum number of failed connection attempts allowed before a round-robin entry is marked as 'down' if a server + has round-robin DNS entries. .. ts:cv:: CONFIG proxy.config.http.connect_attempts_timeout INT 30 :reloadable: @@ -720,7 +722,8 @@ Origin Server Connect Attempts .. ts:cv:: CONFIG proxy.config.http.post_connect_attempts_timeout INT 1800 :reloadable: - The timeout value (in seconds) for an origin server connection when the client request is a ``POST`` or ``PUT`` request. + The timeout value (in seconds) for an origin server connection when the client request is a ``POST`` or ``PUT`` + request. .. ts:cv:: CONFIG proxy.config.http.down_server.cache_time INT 900 :reloadable: @@ -730,17 +733,33 @@ Origin Server Connect Attempts .. ts:cv:: CONFIG proxy.config.http.down_server.abort_threshold INT 10 :reloadable: - The number of seconds before Traffic Server marks an origin server as unavailable after a client abandons a request because the origin - server was too slow in sending the response header. + The number of seconds before Traffic Server marks an origin server as unavailable after a client abandons a request + because the origin server was too slow in sending the response header. Congestion Control ================== .. ts:cv:: CONFIG proxy.config.http.congestion_control.enabled INT 0 - Enables (``1``) or disables (``0``) the Congestion Control option, which configures Traffic Server to stop forwarding HTTP requests to - origin servers when they become congested. Traffic Server sends the client a message to retry the congested origin server later. Refer - to `Using Congestion Control <../http-proxy-caching#UsingCongestionControl>`_. + Enables (``1``) or disables (``0``) the Congestion Control option, which configures Traffic Server to stop forwarding + HTTP requests to origin servers when they become congested. Traffic Server sends the client a message to retry the + congested origin server later. Refer to `Using Congestion Control <../http-proxy-caching#UsingCongestionControl>`_. + +.. ts:cv:: CONFIG proxy.config.http.flow_control.enabled INT 0 + + Transaction buffering / flow control is enabled if this is set to a non-zero value. Otherwise no flow control is done. + +.. ts:cv:: CONFIG proxy.config.http.flow_control.high_water INT 65536 + :metric: bytes + + The high water mark for transaction buffer control. External source I/O is halted when the total buffer space in use + by the transaction exceeds this value. + +.. ts:cv:: CONFIG proxy.config.http.flow_control.low_water INT 65536 + :metric: bytes + + The low water mark for transaction buffer control. External source I/O is resumed when the total buffer space in use + by the transaction is no more than this value. Negative Response Caching ========================= @@ -748,8 +767,9 @@ Negative Response Caching .. ts:cv:: CONFIG proxy.config.http.negative_caching_enabled INT 0 :reloadable: - When enabled (``1``), Traffic Server caches negative responses (such as ``404 Not Found``) when a requested page does not exist. The next - time a client requests the same page, Traffic Server serves the negative response directly from cache. + When enabled (``1``), Traffic Server caches negative responses (such as ``404 Not Found``) when a requested page does + not exist. The next time a client requests the same page, Traffic Server serves the negative response directly from + cache. .. note:: http://git-wip-us.apache.org/repos/asf/trafficserver/blob/bb50292e/doc/sdk/http-transformation-plugin.en.rst ---------------------------------------------------------------------- diff --git a/doc/sdk/http-transformation-plugin.en.rst b/doc/sdk/http-transformation-plugin.en.rst index bc01e0e..b7acfe1 100644 --- a/doc/sdk/http-transformation-plugin.en.rst +++ b/doc/sdk/http-transformation-plugin.en.rst @@ -1,3 +1,5 @@ +.. _transform-plugin: + HTTP Transformation Plugins *************************** @@ -8,9 +10,9 @@ HTTP Transformation Plugins 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 @@ -84,7 +86,7 @@ relationship between the transformation ``VConnection`` and its :alt: A Transformation and its VIOs A Transformation and its VIOs - + Because the Traffic Server API places transformations directly in the response or request data stream, the transformation ``VConnection`` is responsible only for reading the data from the input buffer,
