summaryrefslogtreecommitdiffabout
path: root/src/varnish-mib.8
blob: 71e7abc4aefecf3ccf0bb5998e7e871523775aca (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
.\" This file is part of Varnish-mib -*- nroff -*-
.\" Copyright (C) 2014-2018 Sergey Poznyakoff
.\"
.\" Varnish-mib is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 3, or (at your option)
.\" any later version.
.\"
.\" Varnish-mib is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with Varnish-mib.  If not, see <http://www.gnu.org/licenses/>.
.TH VARNISH-MIB 8 "February 5, 2018" "varnish-mib"
.SH NAME
varnish\-mib \- Net-SNMP module for Varnish Cache monitoring
.SH SYNOPSIS
In \fBsnmpd.conf\fR(5):
.PP
.B dlmod varnish_mib /usr/lib/snmp/varnish\-mib.so
.SH DESCRIPTION
Dynamically loadable object module for
.B net-snmp
that provides access to Varnish Cache statistics.  The module is
loaded into
.BR snmpd (8)
as shown above (actual path can of course differ, depending on how
the package was configured).  This version is written for Varnish
\fB5.2.0\fR.
.PP
The values in the OID branches
.BR client ,
.BR total ,
.BR master ,
.BR session ,
.BR threads ", and "
.B objects
are obtained from Varnish API.  
.PP
The OID branches
.BR backend ,
.BR bans ", and "
.B vcl
are obtained using \fBvarnishd\fR administrative interface (similar
to
.BR varnishadm (8)).
.PP
To retrieve this information, the module must
have enough permissions to scan the Varnish management directory and
read files located in it.  This directory is normally named 
\fB/var/lib/varnish/\fIHOSTNAME\fB/_.vsm_mgt\fR, where \fIHOSTNAME\fR
stands for the server's hostname.  Unless
.BR snmpd (8)
is run as root, special measures should be undertaken in order to
grant access rights.  For example, if the daemon runs as user
\fBsnmp\fR, running the following two commands after starting
\fBvarnishd\fR will do the trick:

.EX
  setfacl -m u:snmp:rx /var/lib/varnish/$(hostname)/_.vsm_mgt
  setfacl -m u:snmp:r /var/lib/varnish/$(hostname)/_.vsm_mgt/*
.EE
.PP

.SH CONFIGURATION OPTIONS
Configuration statements specific to
.B varnish\-mib
must appear in the
.B snmpd.conf
file, after the
.B dlmod
statement that loads the module.
.PP
The following configuration statements are available:
.TP
\fBvarnishBanTableTimeout\fR \fINUMBER\fR
To create \fBbanTable\fR (see below), \fBvarnish_mib\fR connects to
\fBvarnish\fR administration port and issues the \fBban.list\fR
command.  To minimize the performance impact, the information obtained
is cached for a predefined amount of time (60 seconds by default).
This amount (in seconds) is configured by \fBvarnishBanTableTimeout\fR
statement.
.TP
\fBvarnishBackendTableTimeout\fR \fINUMBER\fR
Update interval for \fBbackendTable\fR.  Default is 5 seconds.
.TP
\fBvarnishCLIPortTimeout\fR \fINUMBER\fR
Sets timeout for I/O operations with Varnish administrative port.
Default is 5 seconds.
.PP
The following two statements are not normally needed, but are
provided for completeness sake:
.TP
\fBvarnishCLISocket\fR \fIADDRESS\fR[:\fIPORT\fR]
Sets the address of Varnish administrative interface
socket.
.TP
\fBvarnishCLISecretFile\fR \fIFILE\fR
Sets the pathname of the Varnish secret file. 
.SH DEBUGGING
The module defines the following debugging tokens:
.TP
.B varnish_mib
Produces general debugging information.
.TP
.B varnish_mib:ban
Outputs verbose report about loading th ban table.
.TP
.B varnish_mib:vcli
Displays additional information regarding varnish
.B CLI
interaction.
.TP
.B varnish_mib:vcli:transcript
Enables full transcript of varnish CLI session.
.TP
.B varnish_mib:backend
Outputs verbose information about loading the backend information.
.SH OIDS
The following OIDs are defined in the
.B VARNISH-MIB.txt
file:
.SS Branch \(dqclient\(dq
.TP
.B clientAcceptedConnections
Number of accepted connections.
.TP
.B clientRequestsReceived
Number of received HTTP requests.
.TP
.B clientCacheHits
Number of cache hits.  A cache hit indicates that an object has been
delivered to a  client without fetching it from a backend server.
.TP
.B clientCacheHitsPass
Number of hits for pass.  A cache hit for pass indicates that Varnish
passes the request to the backend and this decision itself has been cached. 
.TP
.B clientCacheMisses
Number of misses.  A cache miss indicates the object was fetched from
the backend before delivering it to the client.
.TP
.B clientRequests400
Client requests received, subject to 400 errors.
.TP
.B clientBan
A write-only OID.  When set, invalidates the cache using the supplied
value as argument to ban.  When read, returns an empty string.  E.g.,
to invalidate caches of all \fBpng\fR images:

.EX
snmpset \fIhostname\fR VARNISH\-MIB::clientBan.0 s 'req.url ~ \(dq\\.png$\(dq'
.EE
.SS Branch \(dqbackend\(dq
.TP
.B backendConnSuccess
Number of successful connections to the backend.
.TP
.B backendConnNotAttempted
Number of backend connections not attempted, because of the unhealthy
status of the backend.
.TP
.B backendConnToMany
Number of backend connections failed because there were too many
connections open.
.TP
.B backendConnFailures
Number of failed backend connections.
.TP
.B backendConnReuses
Number of reused backend connections.  This counter is increased
whenever Varnish reuses a recycled connection.
.TP
.B backendConnRecycled
Number of backend connection recycles.  This counter is increased
whenever Varnish has keep-alive connection that is put back into
the pool of connections.  It has not yet been used, but it might be,
unless the backend closes it.
.TP
.B backendConnRetry
Backend connections retried.
.TP
.B backendRequests
Total backend requests made.
.TP
.B backendTable
This branch provides a conceptual table of backends with the
corresponding statistics.  It is indexed by \fBvbeIndex\fR.  Each row
has the following elements:
.RS
.TP
.B vbeIdent
A string uniqiely identifying the backend.
.TP
.B vbeIPv4
IPv4 address of the backend.  Empty if the backend has no IPv4 address.
.TP
.B vbeIPv6
IPv6 address of the backend.  Empty if the backend has no IPv6 address.
.TP
.B vbePort
Port number.
.TP
.B vbeHappyProbes
Number of successful health probes.
.TP 
.B vbeVcls
Number of VCL references.
.TP
.B vbeRequestHeaderBytes
Total number of request header bytes sent to that backend.
.TP
.B vbeRequestBodyBytes
Total number of request body bytes sent to that backend.
.TP
.B vbeResponseHeaderBytes
Total number of response header bytes received from that backend.
.TP
.B vbeResponseBodyBytes
Total number of response body bytes received from that backend.
.TP
.B vbePipeHeaderBytes
Total number of header bytes piped to that backend.
.TP
.B vbePipeIn
Total number of bytes piped to that backend.
.TP
.B vbePipeOut
Total number of bytes piped from that backend.
.RE
.SS Branch \(dqtotal\(dq
.TP
.B totalSessions
Total number of sessions served since the startup.
.TP
.B totalRequests
Total number of requests received since the startup.
.TP
.B totalPipe
Total number of requests piped to the backend.
.TP
.B totalPass
Total number of requests passed to the backend.
.TP
.B totalFetch
Total number of fetches.
.TP
.B totalRequestHeaderBytes
Total request header bytes received.
.TP
.B totalRequestBodyBytes
Total request body bytes received.
.TP
.B totalResponseHeaderBytes
Total header bytes sent out in responses.
.TP
.B totalResponseBodyBytes
Total body bytes sent out in responses.
.TP
.B totalPipeHeaderBytes
Total request header bytes received for piped sessions.
.TP
.B totalPipeIn
Total number of bytes forwarded from clients in pipe sessions.
.TP
.B totalPipeOut
Total number of bytes forwarded to clients in pipe sessions.
.SS Branch \(dqmaster\(dq
.TP
.B uptime
Master daemon uptime, in hundredths of a second.
.SS Branch \(dqsession\(dq
.TP
.B sessAccepted
Number of sessions succesfully accepted.
.TP
.B sessQueued
Number of times session was queued waiting for a thread.
.TP
.B sessDropped
Number of sessions dropped because session queue was full.
.TP
.B sessClosed
Number of sessions closed.
.TP
.B sessPipeline
This OID was used in Varnish \fR4.1\fR, but disappeared from version
\fB5.0\fR.
.TP
.B sessReadAhead
Session read-ahead.
.TP
.B sessHerd
Session herd.
.TP
.B sessDrop
Number of sessions dropped for thread.
.TP
.B sessFail
Number of session accept failures.
.TP
.B sessPipeOverflow
This OID was used in Varnish \fR4.1\fR, but disappeared in version
\fB5.0\fR.
.SS Branch \(dqthreads\(dq
.TP
.B threadsPools
Number of thread pools.
.TP
.B threadsTotal
Number of thread pools.
.TP
.B threadsLimitHits
Number of times more threads were needed, but limit was reached in a
thread pool. 
.TP
.B threadsCreated
Total number of threads created in all pools.
.TP
.B threadsDestroyed
Total number of threads destroyed in all pools.
.TP
.B threadsFailed
Number of times creating a thread failed.
.SS Branch \(dqbans\(dq
.TP
.B bansTotal
Total number of bans.
.TP
.B bansCompleted
Count of completed bans.
.TP
.B bansObj
Number of bans using \fBobj.*\fR.
.TP
.B bansReq
Number of bans using \fBreq.*\fR.
.TP
.B bansAdded
Number of bans added.
.TP
.B bansDeleted
Number of bans deleted.
.TP
.B bansTested
Number of bans tested against objects (lookup).
.TP
.B bansObjectsKilled
Number of objects killed by bans (lookup).
.TP
.B bansLurkerTested
Number of bans tested against objects (lurker).
.TP
.B bansTestTested
Number of ban tests tested against objects (lookup).
.TP
.B bansLurkerTestTested
Number of ban tests tested against objects (lurker).
.TP
.B bansLurkerObjKilled
Number of objects killed by bans (lurker).
.TP
.B bansDups
Number of ans superseded by other bans.
.TP
.B bansLurkerContention
Number of times lurker gave way for lookup.
.TP
.B bansPersistedBytes
Number of bytes used by the persisted ban lists.
.TP
.B bansPersistedFragmentation
Extra bytes in persisted ban lists due to fragmentation.
.TP
.B banTable
A table of configured varnish bans.  It is indexed by the
\fBbanIndex\fR OID.  Each row has the following elements:
.RS
.TP
.B banTime
Time when the ban was set.
.TP
.B banRefCount
Number of references to that ban.  This equals to the number of objects
in the varnish cache affected by that ban.
.TP
.B banExpression
VCL expression of the ban.
.RE

Notice that for performance reasons, the ban table is cached, so the
total number of rows in the \fBbanTable\fR may diverge from the value
of \fBbansTotal\fR variable.  The default update interval is 60
seconds.  It can be configured in the \fBsnmpd.conf\fR file
(see the \fBvarnishBanTableTimeout\fR statement above).
.SS Branch \(dqobjects\(dq
.TP
.B objectsCount
Approximate number of HTTP objects (headers + body, if present) in the cache.
.TP
.B objectsVampire
Number of unresurrected objects.
.TP
.B objectsCore
Approximate number of object metadata elements in the cache. Each
object needs an objectcore, extra objectcores are for
hit-for-miss, hit-for-pass and busy objects.
.TP
.B objectsHead
Approximate number of different hash entries in the cache.
.TP    
.B objectsExpired
Number of objects that expired from cache because of old age.
.TP    
.B objectsLRUNuked
How many objects have been forcefully evicted from storage to make
room for a new object. 
.TP
.B objectsLRUMoved
Number of move operations done on the LRU list.
.TP    
.B objectsPurges
Number of purge operations executed.
.TP
.B objectsObjPurged
.TP
.B objectsGzip
Number of gzip operations.
.TP    
.B objectsGunzip
Number of gunzip operations.
.SS Branch \(dqvcl\(dq
.TP
.B vclTotal
Number of loaded VCLs in total.
.TP
.B vclAvail
Number of VCLs available.
.TP    
.B vclDiscard
Number of discarded VCLs.
.TP    
.B vclFail
Number of VCL failures.
.SS Branch \(dqagent\(dq
The \fBagent\fR branch is reserved for
implementation-specific management.  It is not used currently.
.SH NOTES
The following OIDs were used in Varnish 4. They are no longer
available in Varnish 5:
.TP
.B clientRequests411
Client requests received, subject to 411 errors.  This variable is
available only in Varnish version \fR4.0\fR.
.TP
.B clientRequests413
Client requests received, subject to 413 errors.  This variable is
available only in Varnish version \fR4.0\fR.
.TP
.B backendConnUnused
Number of unused backend connections.  This variable is available only
in Varnish version \fR4.0\fR.
.PP
The OIDs
.B clientRequestsReceived
and
.B totalRequests
return the same value.
.SH "SEE ALSO"
.BR snmpd.conf (5),
.BR snmpd (8),
.BR varnish (7),
.BR varnishstat (1).
.SH AUTHORS
Sergey Poznyakoff
.SH "BUG REPORTS"
Report bugs to <gray@gnu.org>.
.SH COPYRIGHT
Copyright \(co 2014-2018 Sergey Poznyakoff
.br
.na
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
.br
.ad
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
.\" Local variables:
.\" eval: (add-hook 'write-file-hooks 'time-stamp)
.\" time-stamp-start: ".TH [A-Z_][A-Z0-9_.-]* [0-9] \""
.\" time-stamp-format: "%:B %:d, %:y"
.\" time-stamp-end: "\""
.\" time-stamp-line-limit: 20
.\" end:


Return to:

Send suggestions and report system problems to the System administrator.