You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@trafficserver.apache.org by James Peach <jp...@apache.org> on 2014/06/06 06:11:17 UTC
Re: git commit: Doc: Plugin identity and related logging tags.
On Jun 5, 2014, at 6:52 PM, amc@apache.org wrote:
> Repository: trafficserver
> Updated Branches:
> refs/heads/master caf514b25 -> 13843023a
>
>
> Doc: Plugin identity and related logging tags.
>
>
> Project: http://git-wip-us.apache.org/repos/asf/trafficserver/repo
> Commit: http://git-wip-us.apache.org/repos/asf/trafficserver/commit/13843023
> Tree: http://git-wip-us.apache.org/repos/asf/trafficserver/tree/13843023
> Diff: http://git-wip-us.apache.org/repos/asf/trafficserver/diff/13843023
>
> Branch: refs/heads/master
> Commit: 13843023a1eb45f9ee85b5df24a350eafc92db11
> Parents: caf514b
> Author: Alan M. Carroll <am...@network-geographics.com>
> Authored: Thu Jun 5 16:30:10 2014 -0700
> Committer: Alan M. Carroll <am...@network-geographics.com>
> Committed: Thu Jun 5 18:51:49 2014 -0700
>
> ----------------------------------------------------------------------
> doc/admin/event-logging-formats.en.rst | 10 ++++
> .../api/TSHttpConnectWithPluginId.en.rst | 56 ++++++++++++++++++++
> 2 files changed, 66 insertions(+)
> ----------------------------------------------------------------------
>
>
> http://git-wip-us.apache.org/repos/asf/trafficserver/blob/13843023/doc/admin/event-logging-formats.en.rst
> ----------------------------------------------------------------------
> diff --git a/doc/admin/event-logging-formats.en.rst b/doc/admin/event-logging-formats.en.rst
> index 751ec35..81557f3 100644
> --- a/doc/admin/event-logging-formats.en.rst
> +++ b/doc/admin/event-logging-formats.en.rst
> @@ -220,6 +220,16 @@ The following list describes Traffic Server custom logging fields.
> ``phr``
> The proxy hierarchy route; the route Traffic Server used to retrieve
> the object.
> +
> +.. _piid:
> +
> +``piid``
> + The plugin ID for the transaction. This is set for plugin driven transactions via :c:func:`TSHttpConnectWithPluginId`.
> +
> +.. _pitag:
> +
> +``pitag``
> + The plugin tag for the transaction. This is set for plugin driven transactions via :c:func:`TSHttpConnectWithPluginId`.
Nice!
>
> ``pqbl``
> The proxy request transfer length; the body length in Traffic
>
> http://git-wip-us.apache.org/repos/asf/trafficserver/blob/13843023/doc/reference/api/TSHttpConnectWithPluginId.en.rst
> ----------------------------------------------------------------------
> diff --git a/doc/reference/api/TSHttpConnectWithPluginId.en.rst b/doc/reference/api/TSHttpConnectWithPluginId.en.rst
> new file mode 100644
> index 0000000..2ddc7aa
> --- /dev/null
> +++ b/doc/reference/api/TSHttpConnectWithPluginId.en.rst
> @@ -0,0 +1,56 @@
> +.. 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.
> +
> +
> +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>`
> +
> +.. c:function:: 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 :c:func:`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 :c:type:`sockaddr` structure.
The correct syntax for referring to function arguments is :c:arg:`foo`
> +
> +*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 :ref:`pitag <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``.
:data:`NULL`
> +
> +*id*
> + This is a numeric identifier that is passed through to the HTTP state machine. It is accessible via the log field :ref:`piid <piid>`. This is intended as a connection identifier and should be distinct for every call to ``TSHttpConnectWithPluginID``.
:c:func:`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 ``TSCVonn``
:type:`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.
> +
> +This should also be useful for debugging by tagging not just the HTTP state machine but also the plugin's virtual connections (which are of type ``PluginVC``)
PluginVC is an internal type not visible in the API. I think it's better to omit any mention of it here.
> with data that be correlated with the source plugin.
> +
> +.. topic:: Example
Examples
========
> +
> + The SPDY plugin uses this to correlate client sessions with SPDY streams. Each client connection is assigned a distinct numeric identifier. This is passed as the *id* to ``TSHttpConnectWithPluginId``.
Well, there is not SPDY plugin, and there is no code that actually uses TSHttpConnectWithPluginId, so maybe this is not the best example. The "literalinclude" directive is useful for pasting actual code example in here, see TSHttpIsInternalRequest for an example.
> The *tag* is selected to be the NPN string for the client session protocol, e.g. "spdy/3" or "spdy/3.1". Log post processing can then count the number of connections for the various supported protocols and the number of SPDY virtual streams for each real client connection to Traffic Server.
We invariably close with a See also section, which should at least refer to :manpage:`TSAPI(3ts)`
J
Re: git commit: Doc: Plugin identity and related logging tags.
Posted by "Alan M. Carroll" <am...@network-geographics.com>.
James,
Monday, June 9, 2014, 10:44:15 AM, you wrote:
>>> :data:`NULL`
>> WARNING: py:data reference target not found: NULL
> Weird, that's used in other places. Does :c:data:`NULL` generate an error too?
Yes, I get dozens of messages from that every time I build the docs.
> SPDY never makes the call directly; it happens implicitly since SpdyClientSession is both a continuation and a PluginIdentity. That trick is not available to plugins.
Yes, that would seem to be a problem. Let met ponder that.
Re: git commit: Doc: Plugin identity and related logging tags.
Posted by James Peach <jp...@apache.org>.
On Jun 9, 2014, at 5:35 AM, Alan M. Carroll <am...@network-geographics.com> wrote:
> James,
>
>
>> The correct syntax for referring to function arguments is :c:arg:`foo`
>
> Except sockaddr in this case is not a functiona argument, it is a type. The argument is "addr".
Ah, good point.
>
>> :data:`NULL`
>
> WARNING: py:data reference target not found: NULL
Weird, that's used in other places. Does :c:data:`NULL` generate an error too?
>
> I would argue against using constructs that generate errors. We could use :literal:`NULL` but that's synonymous with ``NULL``.
>
> The real problem here is the lack of :c:const: and support for enums. We'll have to fix that someday.
>
>
>> Well, there is not SPDY plugin, and there is no code that actually uses TSHttpConnectWithPluginId,
>
> It is used in proxy/FetchSM.cc.
Well, that's not a plugin ;)
SPDY never makes the call directly; it happens implicitly since SpdyClientSession is both a continuation and a PluginIdentity. That trick is not available to plugins.
>> We invariably close with a See also section, which should at least refer to :manpage:`TSAPI(3ts)`
>
> Not quite invariably - see TSHttpConnect. I'll fix it anyway.
thanks!
Re: git commit: Doc: Plugin identity and related logging tags.
Posted by James Peach <jp...@apache.org>.
On Jun 9, 2014, at 5:35 AM, Alan M. Carroll <am...@network-geographics.com> wrote:
> James,
>
>
>> The correct syntax for referring to function arguments is :c:arg:`foo`
>
> Except sockaddr in this case is not a functiona argument, it is a type. The argument is "addr".
Ah, good point.
>
>> :data:`NULL`
>
> WARNING: py:data reference target not found: NULL
Weird, that's used in other places. Does :c:data:`NULL` generate an error too?
>
> I would argue against using constructs that generate errors. We could use :literal:`NULL` but that's synonymous with ``NULL``.
>
> The real problem here is the lack of :c:const: and support for enums. We'll have to fix that someday.
>
>
>> Well, there is not SPDY plugin, and there is no code that actually uses TSHttpConnectWithPluginId,
>
> It is used in proxy/FetchSM.cc.
Well, that's not a plugin ;)
SPDY never makes the call directly; it happens implicitly since SpdyClientSession is both a continuation and a PluginIdentity. That trick is not available to plugins.
>> We invariably close with a See also section, which should at least refer to :manpage:`TSAPI(3ts)`
>
> Not quite invariably - see TSHttpConnect. I'll fix it anyway.
thanks!
Re: git commit: Doc: Plugin identity and related logging tags.
Posted by "Alan M. Carroll" <am...@network-geographics.com>.
James,
> The correct syntax for referring to function arguments is :c:arg:`foo`
Except sockaddr in this case is not a functiona argument, it is a type. The argument is "addr".
> :data:`NULL`
WARNING: py:data reference target not found: NULL
I would argue against using constructs that generate errors. We could use :literal:`NULL` but that's synonymous with ``NULL``.
The real problem here is the lack of :c:const: and support for enums. We'll have to fix that someday.
> Well, there is not SPDY plugin, and there is no code that actually uses TSHttpConnectWithPluginId,
It is used in proxy/FetchSM.cc.
> We invariably close with a See also section, which should at least refer to :manpage:`TSAPI(3ts)`
Not quite invariably - see TSHttpConnect. I'll fix it anyway.