doc/admin-guide/plugins/tcpinfo.en.rst

.. 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.

.. _admin-plugins-tcpinfo:

TCPInfo Plugin
**************

This global plugin logs TCP metrics at various points in the HTTP
processing pipeline. The TCP information is retrieved by the
:manpage:`getsockopt(2)` function using the ``TCP_INFO`` option.
This is only supported on systems that support the ``TCP_INFO``
option, currently Linux and BSD.

Plugin Options
--------------

The following options may be specified in :file:`plugin.config`:

.. NOTE: if the option name is not long enough, docutils will not
   add the colspan attribute and the options table formatting will
   be all messed up. Just a trap for young players.

--hooks=NAMELIST
  This option specifies when TCP information should be logged. The
  argument is a comma-separated list of the event names listed
  below. TCP information will be sampled and logged each time the
  specified set of events occurs.

  ==============  ===============================================
   Event Name     Triggered when
  ==============  ===============================================
  send_resp_hdr   The server begins sending an HTTP response.
  ssn_start       A new TCP connection is accepted.
  txn_close       A HTTP transaction is completed.
  txn_start       A HTTP transaction is initiated.
  ==============  ===============================================

--log-file=NAME
  This specifies the base name of the file where TCP information
  should be logged. If this option is not specified, the name
  ``tcpinfo`` is used. Traffic Server will automatically append
  the ``.log`` suffix.

--log-level=LEVEL
  The log level can be either ``1`` to log only the round trip
  time estimate, or ``2`` to log the complete set of TCP information.

  The following fields are logged when the log level is ``1``:

  ==========    ==================================================
  Field Name    Description
  ==========    ==================================================
  timestamp     Event timestamp
  event         Event name (one of the names listed above)
  client        Client IP address
  server        Server IP address
  rtt           Estimated round trip time in microseconds
  ==========    ==================================================

  The following fields are logged when the log level is ``2``:

  ==============    ==================================================
  Field Name        Description
  ==============    ==================================================
  timestamp         Event timestamp
  event             Event name (one of the names listed above)
  client            Client IP address
  server            Server IP address
  rtt               Estimated round trip time in microseconds
  rttvar
  last_sent
  last_recv
  snd_cwnd
  snd_ssthresh
  rcv_ssthresh
  unacked
  sacked
  lost
  retrans
  fackets
  all_retrans
  ==============    ==================================================

  In addition, on newer Linux system, the following two fields are appended
  in log level 2:

  ==============    ==================================================
  Field Name        Description
  ==============    ==================================================
  data_segs_in      Number of incoming data segments
  data_segs_out     Number of outgoing data segments
  ==============    ==================================================

  Note: Features such as TSO (TCP Segment Offload) might skew the numbers
  here. That's true as well for e.g. the retransmit metrics, i.e. anything
  that deals with segments.

--sample-rate=COUNT
  This is the number of times per 1000 requests that the data will
  be logged.  A pseudo-random number generator is used to determine if a
  request will be logged.  The default value is 1000 and this option is
  not required to be in the configuration file.  To achieve a log rate
  of 1% you would set this value to 10.

--rolling-enabled=VALUE
  This logfile option allows you to set logfile rolling behaviour of
  the output log file  without making any changes to the global
  logging configurations.  This option overrides the
  :ts:cv:`proxy.config.output.logfile.rolling_enabled` setting in :file:`records.yaml`
  for the ``tcpinfo`` plugin.  The setting may range from ``0`` to ``3``.
  ``0`` disables logfile rolling.  ``1`` is the ``default`` and enables logfile
  rolling at specific intervals set by ``--rolling-interval-sec`` discussed
  below.  ``2`` enables logfile rolling by logfile size, see
  ``--rolling-size-mb`` below.  Finally a value of ``3`` enables logfile rolling
  at specific intervals or size, whichever occurs first using the interval or size
  settings discussed below.

--rolling-offset-hr=VALUE
  Set the hour ``0`` to ``23`` at which the output log file will roll when
  using interval rolling. Default value is ``0``.

--rolling-interval-sec=VALUE
  Set the rolling interval in seconds for the output log file. May be set
  from ``60`` to ``86400`` seconds, Defaults to ``86400``.

--rolling-size=VALUE
  Set the size in MB at which the output log file  will roll when using log size
  rolling.  Minimum value is ``10``, defaults to ``1024``. In your config file,
  you may use the K, M, or G suffix as in::

  --rolling-size=10M

Examples:
---------

This example logs the simple TCP information to ``tcp-metrics.log``
at the start of a TCP connection and once for each HTTP
transaction thereafter::

  tcpinfo.so --log-file=tcp-metrics --log-level=1 --hooks=ssn_start,txn_start

The file ``tcp-metrics.log`` will contain the following log format (with client and server both on 127.0.0.1)::

  timestamp event client server rtt
  20140414.17h40m14s ssn_start 127.0.0.1 127.0.0.1 153859
  20140414.17h40m14s txn_start 127.0.0.1 127.0.0.1 181018
  20140414.17h40m16s ssn_start 127.0.0.1 127.0.0.1 86869
  20140414.17h40m16s txn_start 127.0.0.1 127.0.0.1 19088
  20140414.17h40m16s ssn_start 127.0.0.1 127.0.0.1 85718
  20140414.17h40m16s txn_start 127.0.0.1 127.0.0.1 38059