stat

Documentation

Overview

Reads Varnish statistics (like `varnishstat` does) from the Varnish Shared Memory (VSM) using libvarnishapi's VSC (Varnish Statistics Counters) API.

Index

• type Counter
• type Flags
  • func (f Flags) MarshalText() ([]byte, error)
  • func (f Flags) String() string
• type Semantics
  • func (s Semantics) MarshalText() ([]byte, error)
  • func (s Semantics) String() string
• type StatReader
  • func (r *StatReader) Close()
  • func (r *StatReader) Counter(name string) (uint64, error)
  • func (r *StatReader) Update() (added, removed []string, err error)
• type StatReaderBuilder
  • func New() *StatReaderBuilder
  • func (b *StatReaderBuilder) Attach() (*StatReader, error)
  • func (b *StatReaderBuilder) SetName(name string) *StatReaderBuilder
  • func (b *StatReaderBuilder) SetTimeout(timeout time.Duration) *StatReaderBuilder

Examples

• StatReader.Update

Types

type Counter

type Counter struct {
	SDesc     string    `json:"description" yaml:"description"`               // short description
	LDesc     string    `json:"longDescription"       yaml:"longDescription"` // long description
	Value     *uint64   `json:"value"       yaml:"value"`                     // current value at the time of the last Update
	Semantics Semantics `json:"semantics"   yaml:"semantics"`
	Flags     Flags     `json:"flags"       yaml:"flags"`
}

Counter is a snapshot of a single Varnish statistic, mirroring VSC_point. The Value field is a pointer to the counter's value in shared memory, this means it will be continuously updated.

Important: A Counter is valid only until the next call to StatReader.Update, which may remove it from the Stats map and invalidate its Value pointer.

type Flags

type Flags int

Flags describes the preferred display format of a counter's value.

const (
	FlagsUnknown  Flags = iota // unrecognised format character
	FlagsInteger               // 'i': plain integer
	FlagsBytes                 // 'B': byte quantity
	FlagsBitmap                // 'b': bitmask
	FlagsBoolean               // 'q': boolean
	FlagsDuration              // 'd': duration in seconds
)

func (Flags) MarshalText

func (f Flags) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler so that Flags serializes as a human-readable string in JSON, YAML, and other text-based encodings.

func (Flags) String

func (f Flags) String() string

type Semantics

type Semantics int

Semantics describes how a counter's value should be interpreted.

const (
	SemanticsUnknown Semantics = iota // unrecognised semantics character
	SemanticsCounter                  // 'c': monotonically increasing count
	SemanticsGauge                    // 'g': instantaneous level, may decrease
	SemanticsBitmap                   // 'b': bitmask
	SemanticsBoolean                  // 'q': boolean flag
)

func (Semantics) MarshalText

func (s Semantics) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler so that Semantics serializes as a human-readable string in JSON, YAML, and other text-based encodings.

func (Semantics) String

func (s Semantics) String() string

type StatReader

type StatReader struct {
	Stats map[string]Counter
	// contains filtered or unexported fields
}

StatReader reads VSC statistics from a Varnish instance. Obtain one via StatReaderBuilder.Attach. Call StatReader.Update to refresh the counter set, then query it with StatReader.Stats or StatReader.Counter. Call StatReader.Close when done.

Important:StatReader.Stats is read-only and must not be modified by the caller.

func (*StatReader) Close

func (r *StatReader) Close()

Close releases all resources held by the StatReader. It must be called exactly once when the StatReader is no longer needed.

func (*StatReader) Counter

func (r *StatReader) Counter(name string) (uint64, error)

Counter returns the current value of the named counter (e.g. "MAIN.cache_hit"), or an error if the counter is not found.

func (*StatReader) Update

func (r *StatReader) Update() (added, removed []string, err error)

Update will refresh the StatReader.Stats map to remove deleted counters and add new ones.

Example

package main

import (
	"fmt"
	"log"
	"time"

	"github.com/varnish/varnish-go/stat"
)

func main() {
	r, err := stat.New().
		SetName("/var/lib/varnish/myinstance").
		SetTimeout(5 * time.Second).
		Attach()
	if err != nil {
		log.Fatal(err)
	}
	defer r.Close()

	for {
		time.Sleep(time.Second)
		r.Update()
		if c, ok := r.Stats["MAIN.client_req"]; ok {
			fmt.Println(*c.Value)
		}
	}
}

type StatReaderBuilder

type StatReaderBuilder struct {
	// contains filtered or unexported fields
}

StatReaderBuilder configures the connection to a Varnish instance. Obtain one with New, optionally call StatReaderBuilder.SetName and StatReaderBuilder.SetTimeout, then call StatReaderBuilder.Attach to get a StatReader.

func New

func New() *StatReaderBuilder

New returns a new StatReaderBuilder with default settings. You can customize it with StatReaderBuilder.SetName, StatReaderBuilder.SetTimeout, etc. before calling StatReaderBuilder.Attach to get a StatReader.

func (*StatReaderBuilder) Attach

func (b *StatReaderBuilder) Attach() (*StatReader, error)

Attach connects to the Varnish shared memory segment and returns a StatReader. If progress is a non-negative file descriptor, a period is written to it for each second spent waiting; pass -1 to suppress progress output. On failure the underlying VSM and VSC handles are freed; the StatReaderBuilder must not be used again.

func (*StatReaderBuilder) SetName

func (b *StatReaderBuilder) SetName(name string) *StatReaderBuilder

SetName sets the Varnish instance name (workdir path) to connect to. Corresponds to the -n flag of varnishd.

func (*StatReaderBuilder) SetTimeout

func (b *StatReaderBuilder) SetTimeout(timeout time.Duration) *StatReaderBuilder

SetTimeout sets how long StatReaderBuilder.Attach will wait for the Varnish manager to become available. A zero duration uses the libvarnishapi default (five seconds).