VARNISH-MIB

NAME
SYNOPSIS
DESCRIPTION
OPTIONS
OIDS
NOTES
SEE ALSO
AUTHORS
BUG REPORTS
COPYRIGHT

NAME

varnish-mib - Net-SNMP agent for Varnish Cache monitoring

SYNOPSIS

varnish-mib [-ACHdfh] [-D ITOKEN[,TOKEN...]] [-L[eo]] [-Lf FILE] [-Ls FACILITY] [-LE PRI[-PRI2]] [-c FILE] [-n NAME] [-p FILE]

DESCRIPTION

An agent for snmpd(8) that provides access to Varnish Cache statistics. To successfully couple with the snmpd the latter must be started with the -x command line option, or with the master agentx directive in snmpd.conf(5) file.

The values in the OID branches client, total, master, session, threads, and objects are obtained from Varnish API.

The OID branches backend, bans, and vcl are obtained using varnishd administrative interface (similar to varnishadm(8)).

To retrieve this information, the agent must have enough permissions to scan the Varnish management directory and read files located in it. Normally this means that it must be started either as root or as the user varnishd is started as.

The configuration for varnish-mib is read from the file varnish-mib.conf located in one of the SNMP configuration path directories. The following configuration directives are understood:
pidfile FILE

Upon startup, write the process ID of the varnish-mib daemon to FILE. See also the -p command line option, below.

banTableTimeout NUMBER

To create banTable (see below), varnish_mib connects to varnish administration port and issues the ban.list 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 varnishBanTableTimeout statement.

backendTableTimeout NUMBER

Update interval for backendTable. Default is 5 seconds.

cliPortTimeout NUMBER

Set timeout for I/O operations with Varnish administrative port. Default is 5 seconds.

The following two statements are not normally needed, but are provided for completeness sake:
cliSocket ADDRESS[:PORT]

Set the address of Varnish administrative interface socket.

cliSecretFile FILE

Set the pathname of the Varnish secret file.

OPTIONS

-A

Append to the log file rather than truncating it.

-c FILE

Read FILE as a configuration file (or a comma-separated list of configuration files).

	-C		Do not read any configuration files except the ones specified by the -c option.
	-d		Dump (in hexadecimal) the sent and received SNMP packets.

-D ITOKEN[,TOKEN...]

Turn on debugging output for the given TOKEN(s). Special token ALL produces extremely verbose output. Other tokens available are:

varnish_mib

Produces general debugging information.

	ban		Outputs verbose report about loading th ban table.
	vcli		Displays additional information regarding varnish CLI interaction.

vcli:transcript

Enables full transcript of varnish CLI session.

backend

Outputs verbose information about loading the backend information.

	-f		Remain in the foreground.
	-h, -?		Print a short usage summary and exit.
	-H		Print a list of configuration file directives understood by the agent and then exit.

-Le, -Lo, -Lf FILE, -Ls FACILITY, -LE PRI[-PRI2]

Specify where logging output should be directed (standard error or output, to a file or via syslog). See LOGGING OPTIONS in snmpcmd(5) for details.

-n NAME

Set an alternative application name (which will affect the configuration files loaded). By default it is the same as the name of the binary.

-p FILE

Save the process ID of the daemon in FILE. This option overrides the pidfile configuration directive.

OIDS

The following OIDs are defined in the VARNISH-MIB.txt file:

Branch "client"
clientAcceptedConnections

Number of accepted connections.

clientRequestsReceived

Number of received HTTP requests.

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.

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.

clientCacheMisses

Number of misses. A cache miss indicates the object was fetched from the backend before delivering it to the client.

clientRequests400

Client requests received, subject to 400 errors.

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 png images:

snmpset hostname VARNISH-MIB::clientBan.0 s ’req.url ~ "\.png$"’

Branch "backend"
backendConnSuccess

Number of successful connections to the backend.

backendConnNotAttempted

Number of backend connections not attempted, because of the unhealthy status of the backend.

backendConnToMany

Number of backend connections failed because there were too many connections open.

backendConnFailures

Number of failed backend connections.

backendConnReuses

Number of reused backend connections. This counter is increased whenever Varnish reuses a recycled connection.

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.

backendConnRetry

Backend connections retried.

backendRequests

Total backend requests made.

backendTable

This branch provides a conceptual table of backends with the corresponding statistics. It is indexed by vbeIndex. Each row has the following elements:
vbeIdent

A string uniqiely identifying the backend.

vbeIPv4

IPv4 address of the backend. Empty if the backend has no IPv4 address.

vbeIPv6

IPv6 address of the backend. Empty if the backend has no IPv6 address.

vbePort

Port number.

vbeHappyProbes

Number of successful health probes.

vbeVcls

Number of VCL references.

vbeRequestHeaderBytes

Total number of request header bytes sent to that backend.

vbeRequestBodyBytes

Total number of request body bytes sent to that backend.

vbeResponseHeaderBytes

Total number of response header bytes received from that backend.

vbeResponseBodyBytes

Total number of response body bytes received from that backend.

vbePipeHeaderBytes

Total number of header bytes piped to that backend.

vbePipeIn

Total number of bytes piped to that backend.

vbePipeOut

Total number of bytes piped from that backend.

Branch "total"
totalSessions

Total number of sessions served since the startup.

totalRequests

Total number of requests received since the startup.

totalPipe

Total number of requests piped to the backend.

totalPass

Total number of requests passed to the backend.

totalFetch

Total number of fetches.

totalRequestHeaderBytes

Total request header bytes received.

totalRequestBodyBytes

Total request body bytes received.

totalResponseHeaderBytes

Total header bytes sent out in responses.

totalResponseBodyBytes

Total body bytes sent out in responses.

totalPipeHeaderBytes

Total request header bytes received for piped sessions.

totalPipeIn

Total number of bytes forwarded from clients in pipe sessions.

totalPipeOut

Total number of bytes forwarded to clients in pipe sessions.

Branch "master"

uptime

Master daemon uptime, in hundredths of a second.

Branch "session"
sessAccepted

Number of sessions succesfully accepted.

sessQueued

Number of times session was queued waiting for a thread.

sessDropped

Number of sessions dropped because session queue was full.

sessClosed

Number of sessions closed.

sessPipeline

This OID was used in Varnish 4.1, but disappeared from version 5.0.

sessReadAhead

Session read-ahead.

sessHerd

Session herd.

sessDrop

Number of sessions dropped for thread.

sessFail

Number of session accept failures.

sessPipeOverflow

This OID was used in Varnish 4.1, but disappeared in version 5.0.

Branch "threads"
threadsPools

Number of thread pools.

threadsTotal

Number of thread pools.

threadsLimitHits

Number of times more threads were needed, but limit was reached in a thread pool.

threadsCreated

Total number of threads created in all pools.

threadsDestroyed

Total number of threads destroyed in all pools.

threadsFailed

Number of times creating a thread failed.

Branch "bans"
bansTotal

Total number of bans.

bansCompleted

Count of completed bans.

bansObj

Number of bans using obj.*.

bansReq

Number of bans using req.*.

bansAdded

Number of bans added.

bansDeleted

Number of bans deleted.

bansTested

Number of bans tested against objects (lookup).

bansObjectsKilled

Number of objects killed by bans (lookup).

bansLurkerTested

Number of bans tested against objects (lurker).

bansTestTested

Number of ban tests tested against objects (lookup).

bansLurkerTestTested

Number of ban tests tested against objects (lurker).

bansLurkerObjKilled

Number of objects killed by bans (lurker).

bansDups

Number of ans superseded by other bans.

bansLurkerContention

Number of times lurker gave way for lookup.

bansPersistedBytes

Number of bytes used by the persisted ban lists.

bansPersistedFragmentation

Extra bytes in persisted ban lists due to fragmentation.

banTable

A table of configured varnish bans. It is indexed by the banIndex OID. Each row has the following elements:
banTime

Time when the ban was set.

banRefCount

Number of references to that ban. This equals to the number of objects in the varnish cache affected by that ban.

banExpression

VCL expression of the ban.

Notice that for performance reasons, the ban table is cached, so the total number of rows in the banTable may diverge from the value of bansTotal variable. The default update interval is 60 seconds. It can be configured in the snmpd.conf file (see the varnishBanTableTimeout statement above).

Branch "objects"
objectsCount

Approximate number of HTTP objects (headers + body, if present) in the cache.

objectsVampire

Number of unresurrected objects.

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.

objectsHead

Approximate number of different hash entries in the cache.

objectsExpired

Number of objects that expired from cache because of old age.

objectsLRUNuked

How many objects have been forcefully evicted from storage to make room for a new object.

objectsLRUMoved

Number of move operations done on the LRU list.

objectsPurges

Number of purge operations executed.

objectsObjPurged
objectsGzip

Number of gzip operations.

objectsGunzip

Number of gunzip operations.

Branch "vcl"
vclTotal

Number of loaded VCLs in total.

vclAvail

Number of VCLs available.

vclDiscard

Number of discarded VCLs.

vclFail

Number of VCL failures.

Branch "agent"
The agent branch is reserved for implementation-specific management. It is not used currently.

NOTES

The following OIDs were used in Varnish 4. They are no longer available in newer Varnish releases:
clientRequests411

Client requests received, subject to 411 errors.

clientRequests413

Client requests received, subject to 413 errors.

backendConnUnused

Number of unused backend connections.

The OIDs clientRequestsReceived and totalRequests return the same value.

AUTHORS

Sergey Poznyakoff

BUG REPORTS

Report bugs to <gray@gnu.org>.

COPYRIGHT

Copyright © 2014-2019 Sergey Poznyakoff
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.

Manpage server at man.gnu.org.ua.