Provided by: trafficserver_8.1.1+ds-1.1_amd64 bug

NAME

       traffic_top - Display Traffic Server statistics

DESCRIPTION

       The  traffic_top  program  provides  a  simple CLI view of your Traffic Server statistics,
       reminiscent of programs like top(1) and nmon(1) for system processes and statistics.

OPTIONS

       -s COUNT
              Number of seconds in between each polling of the Traffic Server statistics API. The
              default is 5 seconds.

       URL|hostname|hostname:port
              Location at which the JSON output of Traffic Server statistics are accessible.

REQUIREMENTS

       The traffic_top program requires that your Traffic Server nodes are running the Stats Over
       HTTP plugin and that the machine from which you run traffic_top  is  able  to  access  the
       HTTP(S) end point for the plugin.

       If, for example, you have the following entry in your plugin.config to enable the plugin:

          stats_over_http.so statistics

       And  your  Traffic Server node is accessible using the hostname ats.example.tld (listening
       on port 80), then you would run traffic_top as follows:

          traffic_top http://ats.example.tld/statistics

       The hostname, port, and path to the Stats Over HTTP plugin JSON output should be  adjusted
       as necessary to match your environment.

       IMPORTANT:
          The    statistics    provided    by    Traffic    Server   (through   traffic_ctl   and
          admin-plugins-stats-over-http) expose quite a bit about  the  inner  workings  of  your
          Traffic  Server cache. While consumers of the JSON statistics endpoint won't be able to
          see or modify the raw contents of your cache, it is  still  very  strongly  advised  to
          limit access to this URL.

INTERFACE

       Upon  startup  (and  successful connection to the admin-plugins-stats-over-http endpoint),
       you will be presented with a curses interface that looks like:
         [image: Main  interface  for  the  traffic_top  command  line  program.]   [image]  Main
         interface for the traffic_top command line program..UNINDENT

         Each area of the main interface is explained in the following sections.

   Cache Information
   Disk Used
       The  amount  of  disk space currently in use by the Traffic Server cache. This number will
       never exceed Disk Total.

       Statistic: proxy.process.cache.bytes_used.

   Disk Total
       Total disk space allocated for Traffic Server cache.

       Statistic: proxy.process.cache.bytes_total.

   Ram Used
       Current amount of RAM Cache occupied by objects.  Objects  located  and  served  from  the
       Traffic  Server  RAM Cache avoid the much slower disk I/O necessary to serve from spinning
       rust.

       Statistic: proxy.process.cache.ram_cache.bytes_used

   Ram Total
       Total space allocated for used by the Traffic Server RAM Cache.

       Statistic: proxy.process.cache.ram_cache.total_bytes

   Lookups
       Total cache object lookups performed, including disk and RAM caches.

       Statistic: proxy.process.http.cache_lookups

   Writes
       Total number of object writes to the Traffic Server cache.

       Statistic: proxy.process.http.cache_writes.

   Updates
       Total number of existing cache objects which have been updated with new content  from  the
       origin server (i.e. existing cache object was stale, so Traffic Server revalidated against
       the origin and received a new object).

       Statistic: proxy.process.http.cache_updates.

   Deletes
       Total number of Traffic Server cache objects which have been deleted (generally through  a
       PURGE request).

       Statistic: proxy.process.http.cache_deletes.

   Read Activ
       Current number of active cache reads.

       Statistic: proxy.process.cache.read.active.

   Writes Act
       Current number of active cache writes.

       Statistic: proxy.process.cache.write.active.

   Update Act
       Current number of active cache updates.

       Statistic: proxy.process.cache.update.active.

   Entries
       The current number of cache directory entries in use.

       Statistic: proxy.process.cache.direntries.used.

   Avg Size
       The average size of current in the cache directory. This is calculated by dividing Entries
       into Disk Used.

       Statistics: proxy.process.cache.bytes_used, proxy.process.cache.direntries.used.

   DNS Lookup
       Total number of DNS lookups performed by Traffic Server, regardless of whether  they  were
       full  DNS  queries  or  were  satisfied  by  entries  in  the HostDB cache. If you are not
       operating a forward proxy and if none of your origin servers are mapped by hostnames, then
       it is normal for your HostDB cache to be empty.

       Statistic: proxy.process.hostdb.total_lookups.

   DNS Hits
       Total number of DNS lookups which were successfully served from the HostDB cache.

       Statistic: proxy.process.hostdb.total_hits.

   Ram Hit
       The  percentage  of  cache lookups which were served successfully from the RAM Cache (thus
       avoiding slower I/O from the disk cache, or even slower network I/O to the origin server).
       This is calculated as a ratio from the two RAM Cache statistics for hits and misses.

       Statistics: proxy.process.cache.ram_cache.hits, proxy.process.cache.ram_cache.misses.

   Fresh
       The  percentage of cache lookups which located a fresh cache object (i.e. an object not in
       need of any revalidation). These transactions are served directly from the  cache  to  the
       client  without  any  need  to contact origin servers or spend time updating the cache. An
       effective Traffic Server cache will have a very high Fresh percentage, as  these  are  the
       fastest responses to clients.

       Statistic: proxy.process.http.transaction_counts.hit_fresh.

   Revalidate
       The  percentage  of  cache  lookups  which located a stale cache object, but for which the
       origin server did not  return  new  data  when  Traffic  Server  revalidated  the  object.
       Revalidated  objects  don't incur cache update performance hits, but they do still lead to
       (what ends up being unnecessary) network traffic with origin servers.

       A high percentage of revalidated cache lookups may indicate that Traffic Server  is  being
       too aggressive with its object staleness heuristics.

       Statistic: proxy.process.http.transaction_counts.hit_revalidated.

   Cold
       The percentage of cache lookups which located an expired cache object. These were requests
       which located a matching object in the cache, but it had already been expired fully and  a
       new  copy  was  retrieved  from  the  origin server.  Unfortunately, the new copy from the
       origin server ended up being the unchanged from what had been marked expired in the cache.

       A high  percentage  of  cold  misses  indicates  that  your  origin  servers  are  setting
       expirations  on their responses which are too short, as compared to the actual lifetime of
       the content in those responses.

       Statistic: proxy.process.http.transaction_counts.miss_cold.

   Changed
       The percentage of cache lookups which located an expired cache object and  which  resulted
       in new data being retrieved from the origin server.

       Statistic: proxy.process.http.transaction_counts.miss_changed.

   Not Cache
       The  percentage of requests for which the requested object was marked not cacheable by the
       origin server. A high percentage of uncacheable objects  may  indicate  that  either  your
       origin  servers  simply  contain a large amount of dynamic, uncacheable data, or that they
       are not properly setting cache control headers in their responses.

       Statistic: proxy.process.http.transaction_counts.miss_not_cacheable.

   No Cache
       The percentage of requests for which the client indicated that the  cache  should  not  be
       used (e.g. a Cache-Control: no-cache request header was present).

       A high percentage of these requests may indicate possible client-side abuse of your proxy,
       in which a disproportionate number of client connections are attempting to force their way
       past your Traffic Server cache.

       Statistic: proxy.process.http.transaction_counts.miss_client_no_cache.

   Fresh (ms)
       The  average amount of time per lookup (in milliseconds) spent serving requests which were
       served by fresh cache lookups. Note that the underlying statistic is the total  amount  of
       time Traffic Server has spent serving these requests since startup, whereas traffic_top is
       displaying the number averaged by the total Fresh requests.

       Statistic: proxy.process.http.transaction_totaltime.hit_fresh.

   Reval (ms)
       The average amount of time per lookup  (in  milliseconds)  spent  serving  requests  which
       involved  revalidating a stale object for which the origin server did not return new data.
       Note that the underlying statistic is the total amount of time Traffic  Server  has  spent
       serving  these  requests  since  startup,  whereas  traffic_top  is  displaying the number
       averaged by the total Revalidate requests.

       Statistic: proxy.process.http.transaction_totaltime.hit_revalidated.

   Cold (ms)
       The average amount of time per lookup  (in  milliseconds)  spent  serving  requests  which
       involved  expired cache objects. Note that the underlying statistic is the total amount of
       time Traffic Server has spent serving these requests since startup, whereas traffic_top is
       displaying the number averaged by the total Cold requests.

       Statistic: proxy.process.http.transaction_totaltime.miss_cold.

   Chang (ms)
       The  average amount of time per lookup (in milliseconds) spent serving requests which were
       served by Traffic Server with new data obtained from  an  origin  server.  Note  that  the
       underlying  statistic  is  the total amount of time Traffic Server has spent serving these
       requests since startup, whereas traffic_top is displaying the number averaged by the total
       Changed requests.

       Statistic: proxy.process.http.transaction_totaltime.miss_changed.

   Not (ms)
       The  average amount of time per lookup (in milliseconds) spent serving requests which were
       served from the origin server because it had marked the object as uncacheable.  Note  that
       the  underlying  statistic  is  the  total amount of time Traffic Server has spent serving
       these requests since startup, whereas traffic_top is displaying the number averaged by the
       total Not Cache requests.

       Statistic: proxy.process.http.transaction_totaltime.miss_not_cacheable.

   No (ms)
       The  average amount of time per lookup (in milliseconds) spent serving requests which were
       served by the origin server because the client had requested that the Traffic Server cache
       be bypassed. Note that the underlying statistic is the total amount of time Traffic Server
       has spent serving these requests since startup,  whereas  traffic_top  is  displaying  the
       number averaged by the total No Cache requests.

       Statistic: proxy.process.http.transaction_totaltime.miss_client_no_cache.

   DNS Hit
       The  percentage  of  DNS  lookups  which  were  served  from the HostDB cache, rather than
       requiring full DNS queries.

       Statistics: proxy.process.hostdb.total_hits, proxy.process.hostdb.total_lookups.

   DNS Entry
       The total number of entries in the HostDB lookup cache. If you are not operating a forward
       proxy  and  if  none of your origin servers are mapped by hostnames, then it is normal for
       your HostDB cache to be empty.

       Statistic: proxy.process.hostdb.cache.current_items.

   Client Request & Response
   GET, HEAD, POST
       Each of these display the percentage of total requests by clients to Traffic Server  which
       used the given HTTP method.

       Statistics:       proxy.process.http.get_requests,       proxy.process.http.head_requests,
       proxy.process.http.post_requests.

   2xx
       Percentage of all requests made to Traffic Server which resulted in an HTTP response  code
       between  200  and  299  (inclusive)  being sent back to the client. 2xx response codes all
       indicate some form of successful transaction with content delivered.

       Statistic: proxy.process.http.2xx_responses.

   3xx
       Percentage of all requests made to Traffic Server which resulted in an HTTP response  code
       between 300 and 399 (inclusive) being sent back to the client. 3xx response codes indicate
       non-error conditions; most commonly redirects or IMS not-modified responses that  did  not
       deliver content (because they did not need to).

       Statistic: proxy.process.http.3xx_responses.

   4xx
       Percentage  of all requests made to Traffic Server which resulted in an HTTP response code
       between 400 and 499 (inclusive) being sent back to the client. 4xx response codes are used
       for  requests  which included a client-side error. Most frequently these responses are for
       invalid URLs (e.g. 404 Not Found), but also  include  authentication  failures  (e.g.  403
       Forbidden).  In  short,  Traffic  Server refused to fulfill the request because the client
       sent invalid or incorrect information.

       Statistic: proxy.process.http.4xx_responses.

   5xx
       Percentage of all requests made to Traffic Server which resulted in an HTTP response  code
       between  500 and 599 (inclusive) being sent back to the client. 5xx response code indicate
       a server-side error. For a caching proxy like Traffic Server, these are likely to be  most
       often  returned  for  gateway  errors; e.g. 502 Bad Gateway (the origin server address was
       invalid or a connection could not be established at all due to system or network failures)
       and  504  Gateway Timeout (the origin server was contacted, but did not return data in the
       time allowed).

       Statistic: proxy.process.http.5xx_responses.

   Conn Fail
       The total number of connections to Traffic Server which failed to connect properly.

       Statistic: proxy.process.http.transaction_counts.errors.connect_failed.

   Other Err
       The total number of Traffic Server transactions which experienced an error not covered  by
       Conn Fail and Abort.

       Statistic: proxy.process.http.transaction_counts.errors.other.

   Abort
       The  total  number of Traffic Server transactions which were prematurely ended (connection
       was closed before all data had been received and/or sent).

       Statistic: proxy.process.http.transaction_counts.errors.aborts.

   200, 206, 301, 302, 304, 404, 502
       The percentage of total Traffic Server transactions which resulted in the  specified  HTTP
       response  code.  For  details  on  the meaning of individual status codes, please refer to
       appendix-http-status-codes.

       Statistics:      proxy.process.http.200_responses,       proxy.process.http.206_responses,
       proxy.process.http.301_responses,                        proxy.process.http.302_responses,
       proxy.process.http.304_responses,                        proxy.process.http.404_responses,
       proxy.process.http.502_responses.

       NOTE:
          Traffic  Server  also  provides  statistics  for  every  other  response code. The keen
          observer will have hopefully already recognized the pattern in statistic names.

   100 B, 1 KB, 3 KB, 5 KB, 10 KB, 1 MB, > 1 MB
       Each of these fields indicates the percentage of responses from Traffic Server which  fell
       within  a particular size (document body size, excluding response headers). The individual
       fields are the upper bounds of exclusive buckets, meaning that a response with a  document
       body  of  4,500  bytes  will  be  counted in the 5 KB field, but not in any of the smaller
       sizes.

       Statistics:                                 proxy.process.http.response_document_size_100,
       proxy.process.http.response_document_size_1K,
       proxy.process.http.response_document_size_3K,
       proxy.process.http.response_document_size_5K,
       proxy.process.http.response_document_size_10K,
       proxy.process.http.response_document_size_1M,
       proxy.process.http.response_document_size_inf.

   Client
   Requests
       Total number of client requests serviced by Traffic Server. This includes both  successful
       content-bearing  responses  as  well as errors, redirects, and not-modified IMS responses.
       Additionally, this number includes requests which were serviced from  the  Traffic  Server
       cache as well as through proxied origin connections.

       Statistic: proxy.process.http.incoming_requests.

   Req/Conn
       The  average  number  of  requests  made per client connection. When Keep-Alive support is
       enabled in Traffic Server and clients make use of it, they are  able  to  submit  multiple
       document  requests  over a single connection in some situations. This number is calculated
       from the total number of client requests divided by the total number  of  new  connections
       that have been created.

       Statistics:                                          proxy.process.http.incoming_requests,
       proxy.process.http.total_client_connections.

   New Conn
       The total number of new HTTP connections from clients which have  been  created  over  the
       lifetime of the Traffic Server process.

       Statistic: proxy.process.http.total_client_connections.

   Curr Conn
       The number of currently-open HTTP connections from clients with Traffic Server.

       Statistic: proxy.process.http.current_client_connections.

   Active Con
       The number of currently active client connection threads (requests in the process of being
       fulfilled when the statistics snapshot was taken).

       Statistic: proxy.process.http.current_active_client_connections.

   Dynamic KA
       Statistics:                         proxy.process.net.dynamic_keep_alive_timeout_in_total,
       proxy.process.net.dynamic_keep_alive_timeout_in_count.

   Head Bytes
       The  total  bytes  consumed  by  outgoing  server  response headers from Traffic Server to
       clients.

       Statistic: proxy.process.http.user_agent_response_header_total_size.

   Body Bytes
       The total bytes consumed by outgoing document bodies in responses from Traffic  Server  to
       clients.

       Statistic: proxy.process.http.user_agent_response_document_total_size.

   Avg Size
       Average size in bytes of combined headers and document bodies for Traffic Server responses
       to clients.

       Statistics:                      proxy.process.http.user_agent_response_header_total_size,
       proxy.process.http.user_agent_response_document_total_size,
       proxy.process.http.incoming_requests.

   Net (bits)
       The summed bits (not bytes) of all Traffic Server responses  to  clients,  whether  served
       from the Traffic Server or through a proxied connection to an origin server.

       Statistics:                      proxy.process.http.user_agent_response_header_total_size,
       proxy.process.http.user_agent_response_document_total_size.

   Resp (ms)
       The average response time by Traffic Server across all client requests. Response  time  is
       measured  from  the  moment  a client connection is established, until the moment the last
       byte of the response is delivered. This field is simply the result of dividing  the  total
       time  spent  by  Traffic  Server  servicing  client  requests by the total number of those
       requests.

       Statistics:                                    proxy.process.http.total_transactions_time,
       proxy.process.http.incoming_requests.

   Origin Server
   Requests
       The  total  number  of  requests  made by Traffic Server to origin servers, because client
       requests could not be fulfilled by the Traffic Server cache (for any  reason,  whether  it
       was not present in the cache, was stale or expired, or not cacheable).

       Statistic: proxy.process.http.outgoing_requests.

   Req/Conn
       The  average  number  of requests made to origin servers by Traffic Server per connection.
       This field is simply the result of dividing the total number of requests made by the total
       number of connections that have ever been opened.

       Statistics:                                          proxy.process.http.outgoing_requests,
       proxy.process.http.total_server_connections.

   New Conn
       The total number of new HTTP connections from Traffic Server to origin servers  that  have
       been created during the lifetime of the Traffic Server process.

       Statistic: proxy.process.http.total_server_connections.

   Curr Conn
       The  number of HTTP connections currently open from Traffic Server to origin servers. Note
       that Traffic Server maintains a configurable number of origin server connections  open  at
       all  times,  whether there are requests being proxied or not, when configured as a reverse
       proxy to a known list  of  origin  servers.  This  is  not  the  case  for  forward  proxy
       configurations,  however,  as  Traffic Server has no foreknowledge of the servers to which
       clients may try to connect.

       Statistic: proxy.process.http.current_server_connections.

   Head Bytes
       The total bytes delivered as headers in responses from origin servers to Traffic Server.

       Statistic: proxy.process.http.origin_server_response_header_total_size.

   Body Bytes
       The total bytes delivered as document bodies in responses from origin servers  to  Traffic
       Server.

       Statistic: proxy.process.http.origin_server_response_document_total_size.

   Avg Size
       The average size of the combined header and document body responses from origin servers to
       Traffic Server.

       Statistics:                   proxy.process.http.origin_server_response_header_total_size,
       proxy.process.http.origin_server_response_document_total_size,
       proxy.process.http.outgoing_requests.

   Net (bits)
       The total bits (not bytes) transferred from origin servers to Traffic Server  for  proxied
       requests not fulfilled by the Traffic Server cache.

       Statistics:                   proxy.process.http.origin_server_response_header_total_size,
       proxy.process.http.origin_server_response_document_total_size.

COPYRIGHT

       2021, dev@trafficserver.apache.org