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 <[email protected]>
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
['"[email protected]" <[email protected]>'].
