trafficserver-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From a..@apache.org
Subject [trafficserver] branch master updated: Doc: Update plugin stats documentation.
Date Fri, 07 Apr 2017 15:26:13 GMT
This is an automated email from the ASF dual-hosted git repository.

amc pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/trafficserver.git

The following commit(s) were added to refs/heads/master by this push:
       new  bb47c96   Doc: Update plugin stats documentation.
bb47c96 is described below

commit bb47c966a0f369f7543ae99d6a07a85c88c95e5e
Author: Alan M. Carroll <amc@apache.org>
AuthorDate: Tue Mar 28 12:32:32 2017 -0500

    Doc: Update plugin stats documentation.
---
 doc/developer-guide/api/functions/TSRecords.en.rst |  3 -
 doc/developer-guide/api/functions/TSStat.en.rst    | 71 ++++++++++++++++++++++
 .../api/types/TSRecordDataType.en.rst              | 39 ++++++------
 doc/developer-guide/api/types/TSRecordType.en.rst  | 29 +++++----
 .../plugins/adding-statistics.en.rst               | 31 +++++-----
 5 files changed, 120 insertions(+), 53 deletions(-)

diff --git a/doc/developer-guide/api/functions/TSRecords.en.rst b/doc/developer-guide/api/functions/TSRecords.en.rst
index 339c3dd..3744139 100644
--- a/doc/developer-guide/api/functions/TSRecords.en.rst
+++ b/doc/developer-guide/api/functions/TSRecords.en.rst
@@ -39,8 +39,6 @@ Synopsis
                                            TSRecordCheckType check_type, \
                                            const char* check_regex, TSRecordAccessType access_type)
 
-.. function:: int TSStatCreate(const char* name, TSRecordDataType type, TSStatPersistence
persistence, TSStatSync sync_style)
-
 Description
 ===========
 
@@ -53,7 +51,6 @@ Return Values
 
 :func:`TSMgmtStringCreate` and :func:`TSMgmtIntCreate` return :const:`TS_SUCCESS` if the
management value was created and :const:`TS_ERROR` if not.
 
-
 See Also
 ========
 
diff --git a/doc/developer-guide/api/functions/TSStat.en.rst b/doc/developer-guide/api/functions/TSStat.en.rst
new file mode 100644
index 0000000..f8ebd69
--- /dev/null
+++ b/doc/developer-guide/api/functions/TSStat.en.rst
@@ -0,0 +1,71 @@
+.. 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.
+
+.. include:: ../../../common.defs
+
+.. default-domain:: c
+
+Plugin Statistics
+**********************
+
+A plugin can create statistics (metrics) that are accessible in the same way as |TS| core
+statistics. In general monitoring the behavior of plugins in production is easier to do in
this way
+in contrast to processing log files.
+
+Synopsis
+========
+
+`#include <ts/ts.h>`
+
+.. function:: int TSStatCreate(const char * name, TSRecordDataType type, TSStatPersistence
persistence, TSStatSync sync_style)
+.. function:: TSReturnCode TSStatFindName(const char * name, int * idx_ptr)
+
+.. function:: TSMgmtInt TSStatIntGet(int idx)
+.. function:: void TSStatIntSet(int idx, TSMgmtInt value)
+.. function:: void TSStatIntIncrement(int idx, TSMgmtInt value)
+.. function:: void TSStatIntDecrement(int idx, TSMgmtInt value)
+
+Description
+===========
+
+A plugin statistic is created by :func:`TSStatCreate`. The :arg:`name` must be globally unique
and
+should follow the standard dotted tag form. To avoid collisions and for easy of use the first
tag
+should be the plugin name or something easily derived from it. Currently only integers are
suppored
+therefore :arg:`type` must be :macro:`TS_RECORDTYPE_INT`. The return value is the index of
the
+statistic. In general thsi should work but if it doesn't it will :code:`assert`. In particular,
+creating the same statistic twice will fail in this way, which can happen if statistics are
created
+as part of or based on configuration files and |TS| is reloaded.
+
+:func:`TSStatFindName` locates a statistic by :arg:`name`. If found the function returns
+:const:`TS_SUCCESS` and the value pointed at by :arg:`idx_ptr` is updated to be the index
of the
+statistic. Otherwise it returns ``TS_ERROR``.
+
+The values in statistics are manipulated by :func:`TSStatIntSet` to set the statistic directly,
+:func:`TSStatIntIncrement` to increase it by :arg:`value`, and :func:`TSStatIntDecrement`
to
+decrease it by :arg:`value`.
+
+Return Values
+=============
+
+:func:`TSMgmtStringCreate` and :func:`TSMgmtIntCreate` return :const:`TS_SUCCESS` if the
management
+value was created and :const:`TS_ERROR` if not.
+
+
+See Also
+========
+
+:ref:`developer-plugins-add-statistics`
+:manpage:`TSAPI(3ts)`
diff --git a/doc/developer-guide/api/types/TSRecordDataType.en.rst b/doc/developer-guide/api/types/TSRecordDataType.en.rst
index 6be0026..7a9d434 100644
--- a/doc/developer-guide/api/types/TSRecordDataType.en.rst
+++ b/doc/developer-guide/api/types/TSRecordDataType.en.rst
@@ -16,8 +16,8 @@
 
 .. include:: ../../../common.defs
 
-TSRecordType
-************
+TSRecordDataType
+****************
 
 Synopsis
 ========
@@ -26,40 +26,37 @@ Synopsis
 
 .. c:type:: TSRecordDataType
 
-Enum typedef.
+   The underlying data type of a data record (configuration variable or statistic).
 
-Enumeration Members
-===================
+   .. c:macro:: TS_RECORDDATATYPE_NULL
 
-.. c:member:: TSRecordType TS_RECORDDATATYPE_NULL
+      No data type. Used as an invalid initialization value.
 
-   No data type. Used to as an invalid initialization value.
+   .. c:macro:: TS_RECORDDATATYPE_INT
 
-.. c:member:: TSRecordType TS_RECORDDATATYPE_INT
+      An integer.
 
-   An integer.
+   .. c:macro:: TS_RECORDDATATYPE_FLOAT
 
-.. c:member:: TSRecordType TS_RECORDDATATYPE_FLOAT
+       Floating point.
 
-    Floating point.
+   .. c:macro:: TS_RECORDDATATYPE_STRING
 
-.. c:member:: TSRecordType TS_RECORDDATATYPE_STRING
+      A string.
 
-   A string.
+   .. c:macro:: TS_RECORDDATATYPE_COUNTER
 
-.. c:member:: TSRecordType TS_RECORDDATATYPE_COUNTER
+      A counter which has a count and a sum.
 
-   A counter which has a count and a sum.
+   .. c:macro:: TS_RECORDDATATYPE_STAT_CONST
 
-.. c:member:: TSRecordType TS_RECORDDATATYPE_STAT_CONST
+      A value that is unchangeable.
 
-   A value that is unchangeable.
+   .. c:macro:: TS_RECORDDATATYPE_STAT_FX
 
-.. c:member:: TSRecordType TS_RECORDDATATYPE_STAT_FX
-
-   Unknown.
+      Unknown.
 
 Description
 ===========
 
-This data type describes the data stored in a management value such as a configuration value
or a statistic value.
\ No newline at end of file
+This data type describes the data stored in a management value such as a configuration value
or a statistic value.
diff --git a/doc/developer-guide/api/types/TSRecordType.en.rst b/doc/developer-guide/api/types/TSRecordType.en.rst
index 70e2480..316d3bd 100644
--- a/doc/developer-guide/api/types/TSRecordType.en.rst
+++ b/doc/developer-guide/api/types/TSRecordType.en.rst
@@ -26,30 +26,33 @@ Synopsis
 
 .. c:type:: TSRecordType
 
-Enum typedef.
+   Effectively the scope of the record.
 
-Enumeration Members
-===================
+   .. c:macro:: TS_RECORDTYPE_NULL
 
-.. c:member:: TSRecordType TS_RECORDTYPE_NULL
+   .. c:macro:: TS_RECORDTYPE_CONFIG
 
-.. c:member:: TSRecordType TS_RECORDTYPE_CONFIG
+      A configuration record.
 
-   A configuration record.
+   .. c:macro:: TS_RECORDTYPE_PROCESS
 
-.. c:member:: TSRecordType TS_RECORDTYPE_PROCESS
+   .. c:macro:: TS_RECORDTYPE_NODE
 
-.. c:member:: TSRecordType TS_RECORDTYPE_NODE
+   .. c:macro:: TS_RECORDTYPE_CLUSTER
 
-.. c:member:: TSRecordType TS_RECORDTYPE_CLUSTER
+      Deprecated - shared among a cluster.
 
-.. c:member:: TSRecordType TS_RECORDTYPE_LOCAL
+   .. c:macro:: TS_RECORDTYPE_LOCAL
 
-.. c:member:: TSRecordType TS_RECORDTYPE_PLUGIN
+      Deprecated - not shared among a cluster.
 
-.. c:member:: TSRecordType TS_RECORDTYPE_ALL
+   .. c:macro:: TS_RECORDTYPE_PLUGIN
+
+      Created by a plugin.
+
+   .. c:macro:: TS_RECORDTYPE_ALL
 
 Description
 ===========
 
-The management role for a management value. In practice only :c:member:`TS_RECORDTYPE_CONFIG`
is usable.
\ No newline at end of file
+The management role for a management value. In practice only :c:macro:`TS_RECORDTYPE_CONFIG`
is usable.
diff --git a/doc/developer-guide/plugins/adding-statistics.en.rst b/doc/developer-guide/plugins/adding-statistics.en.rst
index 9a0b952..87fd200 100644
--- a/doc/developer-guide/plugins/adding-statistics.en.rst
+++ b/doc/developer-guide/plugins/adding-statistics.en.rst
@@ -22,23 +22,22 @@
 Adding Statistics
 *****************
 
-This chapter describes how to add statistics to your plugins.  The
-|TS| statistics API functions add your plugin's statistics so you
-can view your plugin statistics as you would any other |TS| statistic,
-using :program:`traffic_ctl` or the c:func:`TSRecordDump` API.
-
-A statistic is an opaque object referred to by an integral handle
-returned by c:func:`TSStatCreate`. Only integer statistics are
-supported, so the :arg:`type` argument to c:func:`TSStatCreate` must
-be c:data:`TS_RECORDDATATYPE_INT`.
-
-The following example shows how to add custom statistics to your
-plugin. Typically, you would attempt to find the statistic by name
-before creating is. This technique is useful if you want to increment
-a statistic from multiple plugins. Once you have a handle to the
-statistic, set the value with c:func:`TSStatIntSet`, and increment it with
-c:func:`TSStatIntIncrement` or c:func:`TSStatIntDecrement`.
+This chapter describes how to add statistics to your plugins. The |TS| statistics API functions
add
+your plugin's statistics so you can view your plugin statistics as you would any other |TS|
+statistic, using :program:`traffic_ctl` or the :c:func:`TSRecordDump` API.
+
+A statistic is an opaque object referred to by an integral handle returned by
+:c:func:`TSStatCreate`. Only integer statistics are supported, so the :arg:`type` argument
to
+:c:func:`TSStatCreate` must be :c:macro:`TS_RECORDDATATYPE_INT`.
+
+The following example shows how to add custom statistics to your plugin. Typically, you would
+attempt to find the statistic by name before creating is. This technique is useful if you
want to
+increment a statistic from multiple plugins. Once you have a handle to the statistic, set
the value
+with :c:func:`TSStatIntSet`, and increment it with :c:func:`TSStatIntIncrement` or
+:c:func:`TSStatIntDecrement`.
 
 .. literalinclude:: ../../../example/statistic/statistic.cc
    :language: c
    :lines: 30-
+
+:func:`TSStatFind` can be used to check if the statistic already exists or to provide a generic
interface to statistics. In the example above you can see the code first verifies the statistic
does not already exist before creating it. In general, though, this should be handled by not
executing the registration code twice. If done only from plugin initialization then this will
be the case. It can be the case however that statistics are based on configuration data which
may be reloaded and [...]

-- 
To stop receiving notification emails like this one, please contact
['"commits@trafficserver.apache.org" <commits@trafficserver.apache.org>'].

Mime
View raw message