varnish-cache/include/vapi/vsc.h
0
/*-
1
 * Copyright (c) 2006 Verdens Gang AS
2
 * Copyright (c) 2006-2015 Varnish Software AS
3
 * All rights reserved.
4
 *
5
 * Author: Poul-Henning Kamp <phk@phk.freebsd.dk>
6
 *
7
 * SPDX-License-Identifier: BSD-2-Clause
8
 *
9
 * Redistribution and use in source and binary forms, with or without
10
 * modification, are permitted provided that the following conditions
11
 * are met:
12
 * 1. Redistributions of source code must retain the above copyright
13
 *    notice, this list of conditions and the following disclaimer.
14
 * 2. Redistributions in binary form must reproduce the above copyright
15
 *    notice, this list of conditions and the following disclaimer in the
16
 *    documentation and/or other materials provided with the distribution.
17
 *
18
 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
19
 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21
 * ARE DISCLAIMED.  IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE
22
 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23
 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24
 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25
 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26
 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27
 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28
 * SUCH DAMAGE.
29
 *
30
 * This is the public API for the VSC access.
31
 *
32
 * VSC is a sub-category of VSM.
33
 *
34
 */
35
36
#ifndef VAPI_VSC_H_INCLUDED
37
#define VAPI_VSC_H_INCLUDED
38
39
struct vsm;
40
struct vsc;
41
struct vsm_fantom;
42
43
struct VSC_level_desc {
44
        const char *name;               /* name */
45
        const char *label;              /* label */
46
        const char *sdesc;              /* short description */
47
        const char *ldesc;              /* long description */
48
};
49
50
struct VSC_point {
51
        const volatile uint64_t *ptr;   /* field value                  */
52
        const char *name;               /* field name                   */
53
        const char *ctype;              /* C-type                       */
54
        int semantics;                  /* semantics
55
                                         * 'c' = Counter
56
                                         * 'g' = Gauge
57
                                         * 'b' = bitmap
58
                                         * '?' = unknown
59
                                         */
60
        int format;                     /* display format
61
                                         * 'i' = integer
62
                                         * 'B' = bytes
63
                                         * 'b' = bitmap
64
                                         * 'd' = duration
65
                                         * '?' = unknown
66
                                         */
67
        const struct VSC_level_desc *level; /* verbosity level          */
68
        const char *sdesc;              /* short description            */
69
        const char *ldesc;              /* long description             */
70
        void *priv;                     /* return val from VSC_new_f    */
71
        unsigned raw;                   /* adjusted or raw value        */
72
};
73
74
/*---------------------------------------------------------------------
75
 * Function pointers
76
 */
77
78
typedef void *VSC_new_f(void *priv, const struct VSC_point *const pt);
79
        /*
80
         * priv is from VSC_State().
81
         *
82
         * The return value is installed in pt->priv
83
         */
84
85
typedef void VSC_destroy_f(void *priv, const struct VSC_point *const pt);
86
        /*
87
         * priv is from VSC_State().
88
         */
89
90
typedef int VSC_iter_f(void *priv, const struct VSC_point *const pt);
91
        /*
92
         * priv is the argument to VSC_Iter() and not from VSC_State().
93
         *
94
         * A non-zero return terminates the iteration
95
         */
96
97
/*---------------------------------------------------------------------
98
 * VSC level access functions
99
 */
100
101
struct vsc *VSC_New(void);
102
        /*
103
         * Create a new VSC instance
104
         */
105
106
void VSC_Destroy(struct vsc **, struct vsm *);
107
        /*
108
         * Destroy a VSC instance
109
         *
110
         * If a destroy function was installed with VSC_State()
111
         * it will be called for all remaining points
112
         */
113
114
int VSC_Arg(struct vsc *, char arg, const char *opt);
115
        /*
116
         * Handle standard stat-presenter arguments
117
         *      'I' - field inclusion glob
118
         *      'X' - field exclusion glob
119
         *      'R' - required field glob
120
         *      'f' - legacy field filter glob (deprecated)
121
         *      'r' - toggle raw gauges
122
         *
123
         * Return:
124
         *      -1 error, VSM_Error() returns diagnostic string
125
         *       0 not handled
126
         *       1 Handled.
127
         */
128
129
void VSC_State(struct vsc *, VSC_new_f *, VSC_destroy_f *, void *);
130
        /*
131
         * Install function pointers for create/destroy and their
132
         * priv pointer.  All arguments can be NULL.
133
         */
134
135
int VSC_Iter(struct vsc *, struct vsm *, VSC_iter_f *, void *priv);
136
        /*
137
         * Iterate over all statistics counters, calling a function for
138
         * each counter not suppressed by any "-f" arguments.
139
         *
140
         * To discover new/deleted points, call VSM_Status() first.
141
         *
142
         * The returned points are valid until the next call to VSC_Iter()
143
         *
144
         * Not safe for concurrent reads with the same vsc and vsm
145
         * handles.  For concurrency, initialize and attach separate
146
         * structs vsc and vsm.
147
         *
148
         * Arguments:
149
         *          vd: The vsm context
150
         *        func: The callback function
151
         *        priv: Passed as argument to func
152
         *
153
         * Returns:
154
         *      !=0:    func returned non-zero
155
         *      0:      Done
156
         */
157
158
const struct VSC_level_desc *VSC_ChangeLevel(const struct VSC_level_desc*, int);
159
        /*
160
         * Change a level up or down.
161
         */
162
163
unsigned VSC_IsRaw(const struct vsc *);
164
        /*
165
         * Returns zero if gauges are adjusted by VSC_Value().
166
         */
167
168
static inline uint64_t
169 173420
VSC_Value(const struct VSC_point * const pt)
170
{
171
        uint64_t val;
172
173 173420
        val = *pt->ptr;
174 173420
        if (!pt->raw && pt->semantics == 'g' && val > INT64_MAX)
175 0
                val = 0;
176 173420
        return (val);
177
}
178
179
#endif /* VAPI_VSC_H_INCLUDED */