bionic (3) TSHttpConnectWithPluginId.3ts.gz

NAME

       TSHttpConnectWithPluginId  -  allows  the  plugin  to initiate an http connection. This will tag the HTTP
       state machine with extra data that can be accessed by the logging interface. The connection is treated as
       an HTTP transaction as if it came from a client

SYNOPSIS

       #include <ts/ts.h>

       TSVConn TSHttpConnectWithPluginId(sockaddr const * addr, char const * tag, int64_t id)

DESCRIPTION

       This  call  attempts to create an HTTP state machine and a virtual connection to that state machine. This
       is more efficient than using TSNetConnect() because it avoids using the operating system  stack  via  the
       loopback interface.

       addr   This  is the network address of the target of the connection.  This includes the port which should
              be stored in the sockaddr structure pointed at by addr.

       tag    This is a tag that is passed through to the HTTP state machine.  It must be  a  persistent  string
              that  has a lifetime longer than the connection. It is accessible via the log field pitag. This is
              intended as a class or type identifier that is consistent across all connections for this  plugin.
              In effect, the name of the plugin. This can be NULL.

       id     This  is  a  numeric identifier that is passed through to the HTTP state machine. It is accessible
              via the log field piid. This is intended as a connection identifier and  should  be  distinct  for
              every  call  to  TSHttpConnectWithPluginId().   The easiest mechanism is to define a plugin global
              value and increment it for each connection. The value 0 is reserved to mean "not set" and  can  be
              used as a default if this functionality is not needed.

       The  virtual connection returned as the TSVConn is API equivalent to a network virtual connection both to
       the plugin and to internal mechanisms. Data is read and written to the  connection  (and  thence  to  the
       target system) by reading and writing on this virtual connection.

       NOTE:
          This  function only opens the connection. To drive the transaction an actual HTTP request must be sent
          and the HTTP response handled. The transaction is handled as a standard HTTP transaction  and  all  of
          the standard configuration options and plugins will operate on it.

       The  combination  of  tag  and  id  is  intended  to  enable  correlation in log post processing. The tag
       identifies the connection as related to the plugin and the id can  be  used  in  conjuction  with  plugin
       generated logs to correlate the log records.

NOTES

       The  H2  implementation uses this to correlate client sessions with H2 streams. Each client connection is
       assigned a distinct numeric identifier. This is passed as the id to TSHttpConnectWithPluginId(). The  tag
       is  selected  to  be  the NPN string for the client session protocol, e.g.  "h2". Log post processing can
       then count the number of connections for the various supported protocols and the  number  of  H2  virtual
       streams for each real client connection to Traffic Server.

SEE ALSO

       TSHttpConnect(3ts), TSNetConnect(3ts), TSAPI(3ts)

COPYRIGHT

       2018, dev@trafficserver.apache.org