Apache Traffic Server recipes

Apache Traffc Server is a high performance, customizable HTTP proxy server. This is a collection of small "recipes", showing how to accomplish various tasks. This cookbook is work in progress, I haven't quite decided yet how I want to handle this "documentation". Perhaps it belongs in Apache official docs, but for now, I find it easier to use the tools I'm used to here on ogre.com to maintain this.


Cache configurations

Cache inspector and other server stat pages

Traffic Server has a set of built in stats pages, that can be used to monitor the server, inspecting the cache etc. In order to enable this feature, you must add a configuration to records.config (it's not there by default, to avoid accidentally exposing your server). The setting is

CONFIG proxy.config.http_ui_enabled INT 0

The possible values are

0 - Don't enable anything in the stats pages system (default)
1 - Enable only the cache inspector
2 - Enable only the various stats pages (see more below)
3 - Enable both cache inspector and stats pages


Once enabled, you also have to setup remap.config rules. This is how you will access the pages, with well specified (your choice) URLs. For example

map http://www.ogre.com/_stat_page_cache-internal/ http://{cache-internal}/
map http://www.ogre.com/_stat_page_cache/ http://{cache}/ @src_ip= @action=allow
map http://www.ogre.com/_stat_page_stat/ http://{stat}/
map http://www.ogre.com/_stat_page_test/ http://{test}/ @src_ip= @action=allow
map http://www.ogre.com/_stat_page_hostdb/ http://{hostdb}/
map http://www.ogre.com/_stat_page_net/ http://{net}/
map http://www.ogre.com/_stat_page_http/ http://{http}/

I'd strongly recommend using the src_ip filters, as shown in a couple of the examples. These filters supports individual IPs, or IP ranges (e.g.

Enabling read-while-writer

The following settings are required for the read-while-writer feature to function:

CONFIG proxy.config.cache.max_doc_size INT 0
CONFIG proxy.config.cache.enable_read_while_writer INT 1
CONFIG proxy.config.http.background_fill_completed_threshold FLOAT 0

With this enabled, the pressure on a single object that is uncacheable is heavily improved. See TS-505 for more details. In addition, this setting makes life quite nice again:

CONFIG proxy.config.http.cache.max_open_read_retries INT -1

I've made this the new default on Apache Traffic Server trunk, it makes things 10-20x faster under certain conditions, and 20x less latency.

Logging and stats

Logging configurations

This is a small list of some useful logging options that can be tuned.

Log rotation

By default, log rotation happens every 24 hours, and this can be configured via

CONFIG proxy.config.log.rolling_interval_sec INT 86400

You can also choose under what conditions log files should be rotated, this is configured via the "enabled" option.

CONFIG proxy.config.log.rolling_enabled INT 1

The possible values are as follows:

Value Description
0 Rolling of log files are completely disabled
1 Rolling only happens at certain intervals (times). Max is 24h.
2 Rolling only happens when the log files hits a certain size.
3 Rolling happens on either time or size (whichever comes first)
4 Rolling happens on both time and size (both have to be satisfied)

When configuring log rotation on size, you must also configure

CONFIG proxy.config.log.rolling_size_mb INT 10


Performance tuning

This section contains various configurations that can improve the performance, some might not be appropriate for your environment, but all these options are known to have an impact on performance.


This is probably the most important configuration for your system, particularly for benchmarking. The default configurations are good for most systems, but can obviously be improved. The relevant settings are:

CONFIG proxy.config.exec_thread.autoconfig INT 0
CONFIG proxy.config.exec_thread.autoconfig.scale FLOAT 2.0
CONFIG proxy.config.exec_thread.limit INT 5

CONFIG proxy.config.accept_threads INT 1

CONFIG proxy.config.cache.threads_per_disk INT 8

CONFIG proxy.config.task_threads INT 2

The first three control the number of network threads, which are the threads primarily responsible for handling and processing all requests.

The next configuration controls the accept thread configuration, 1 is almost always the best, but some times 0 (moves accept back to the net-threads), or 2-3 might be optimal. It's really application specific.

Cache threads are setup per disk, 8 is usually good, but on very active system, with lots of disk activity, 16 or more threads might be necessary. These threads are blocking on disk I/O, so having more of these generally won't make the system a lot slower (but don't go overboard). Going with too few threads obviously won't let you use the full capacity of the disk's I/O capacity.

Finally, there's a set of background task threads, threads meant to off load the normal net-threads with mundane tasks. This is currently only mildly used by the ATS core, but more and more tasks are moved over to these threads as we make progress. This allows the net-thread to both serve more requets, and do so at less latency in the responses. Additionally, plugins are encouraged to use this pool of threads for similar tasks. This means that the number of these threads depends on not only which version of ATS you are using (v3.0 only lightly uses these threads), but also what plugins you are using. You will simply have to watch these threads, and see if they are becoming bottlenecks, and then increase this as necessary.


Network related options


HTTP related options