.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "PLUGIN STATISTICS" "3ts" "Jan 06, 2024" "9.2" "Apache Traffic Server"
.SH NAME
Plugin Statistics \- a plugin can create statistics (metrics) that are accessible in the same way as Traffic Server core
statistics. In general monitoring the behavior of plugins in production is easier to do in this way
in contrast to processing log files
.SH SYNOPSIS
.INDENT 0.0
.INDENT 3.5
.sp
.EX
#include <ts/ts.h>
.EE
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B int TSStatCreate(const char *name, \fI\%TSRecordDataType\fP type, \fI\%TSStatPersistence\fP persistence, \fI\%TSStatSync\fP sync_style) 
.UNINDENT
.INDENT 0.0
.TP
.B \fI\%TSReturnCode\fP TSStatFindName(const char *name, int *idx_ptr) 
.UNINDENT
.INDENT 0.0
.TP
.B \fI\%TSMgmtInt\fP TSStatIntGet(int idx) 
.UNINDENT
.INDENT 0.0
.TP
.B void TSStatIntSet(int idx, \fI\%TSMgmtInt\fP value) 
.UNINDENT
.INDENT 0.0
.TP
.B void TSStatIntIncrement(int idx, \fI\%TSMgmtInt\fP value) 
.UNINDENT
.INDENT 0.0
.TP
.B void TSStatIntDecrement(int idx, \fI\%TSMgmtInt\fP value) 
.UNINDENT
.INDENT 0.0
.TP
.B typedef void (*TSRecordDumpCb)(\fI\%TSRecordType\fP *type, void *edata, int registered, const char *name, \fI\%TSRecordDataType\fP type, \fI\%TSRecordData\fP *datum) 
.UNINDENT
.INDENT 0.0
.TP
.B void TSRecordDump(\fI\%TSRecordType\fP rect_type, \fI\%TSRecordDumpCb\fP callback, void *edata) 
.UNINDENT
.SH DESCRIPTION
.sp
A plugin statistic is created by \fI\%TSStatCreate()\fP\&. The \fIname\fP 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 supported
therefore \fItype\fP must be \fI\%TS_RECORDDATATYPE_INT\fP\&. The return value is
the index of the statistic. In general this should work but if it doesn\(aqt it will \fBassert\fP\&. 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 Traffic Server is reloaded.
.sp
\fI\%TSStatFindName()\fP locates a statistic by \fIname\fP\&. If found the function returns
\fBTS_SUCCESS\fP and the value pointed at by \fIidx_ptr\fP is updated to be the index of the
statistic. Otherwise it returns \fBTS_ERROR\fP\&.
.sp
The values in statistics are manipulated by \fI\%TSStatIntSet()\fP to set the statistic directly,
\fI\%TSStatIntIncrement()\fP to increase it by \fIvalue\fP, and \fI\%TSStatIntDecrement()\fP to
decrease it by \fIvalue\fP\&.
.sp
A group of records can be examined via \fI\%TSRecordDump()\fP\&. A set of records is specified and the
iterated over. For each record in the set the callbac \fIcallback\fP is invoked.
.sp
The records are specified by the \fI\%TSRecordType\fP\&. If this is
\fI\%TS_RECORDTYPE_NULL\fP then all records are examined. The callback is passed
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
.B \fItype\fP
The record type.
.TP
.B \fIedata\fP
Callback context. This is the \fIedata\fP value passed to \fI\%TSRecordDump()\fP\&.
.TP
.B \fIregistered\fP
A flag indicating if the value has been registered.
.TP
.B \fIname\fP
The name of the record. This is nul terminated.
.TP
.B \fItype\fP
The storage type of the data in the record.
.TP
.B \fIdatum\fP
The record data.
.UNINDENT
.UNINDENT
.UNINDENT
.SH RETURN VALUES
.sp
\fI\%TSMgmtStringCreate()\fP and \fI\%TSMgmtIntCreate()\fP return \fBTS_SUCCESS\fP if the management
value was created and \fBTS_ERROR\fP if not.
.SH SEE ALSO
.sp
\fI\%Adding Statistics\fP
\fBTSAPI(3ts)\fP
.SH COPYRIGHT
2024, dev@trafficserver.apache.org
.\" Generated by docutils manpage writer.
.