expvar.go

Documentation: expvar

     1  // Copyright 2009 The Go Authors. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  // Package expvar provides a standardized interface to public variables, such
     6  // as operation counters in servers. It exposes these variables via HTTP at
     7  // /debug/vars in JSON format.
     8  //
     9  // Operations to set or modify these public variables are atomic.
    10  //
    11  // In addition to adding the HTTP handler, this package registers the
    12  // following variables:
    13  //
    14  //	cmdline   os.Args
    15  //	memstats  runtime.Memstats
    16  //
    17  // The package is sometimes only imported for the side effect of
    18  // registering its HTTP handler and the above variables. To use it
    19  // this way, link this package into your program:
    20  //
    21  //	import _ "expvar"
    22  package expvar
    23  
    24  import (
    25  	"encoding/json"
    26  	"fmt"
    27  	"log"
    28  	"math"
    29  	"net/http"
    30  	"os"
    31  	"runtime"
    32  	"sort"
    33  	"strconv"
    34  	"strings"
    35  	"sync"
    36  	"sync/atomic"
    37  )
    38  
    39  // Var is an abstract type for all exported variables.
    40  type Var interface {
    41  	// String returns a valid JSON value for the variable.
    42  	// Types with String methods that do not return valid JSON
    43  	// (such as time.Time) must not be used as a Var.
    44  	String() string
    45  }
    46  
    47  // Int is a 64-bit integer variable that satisfies the Var interface.
    48  type Int struct {
    49  	i int64
    50  }
    51  
    52  func (v *Int) Value() int64 {
    53  	return atomic.LoadInt64(&v.i)
    54  }
    55  
    56  func (v *Int) String() string {
    57  	return strconv.FormatInt(atomic.LoadInt64(&v.i), 10)
    58  }
    59  
    60  func (v *Int) Add(delta int64) {
    61  	atomic.AddInt64(&v.i, delta)
    62  }
    63  
    64  func (v *Int) Set(value int64) {
    65  	atomic.StoreInt64(&v.i, value)
    66  }
    67  
    68  // Float is a 64-bit float variable that satisfies the Var interface.
    69  type Float struct {
    70  	f uint64
    71  }
    72  
    73  func (v *Float) Value() float64 {
    74  	return math.Float64frombits(atomic.LoadUint64(&v.f))
    75  }
    76  
    77  func (v *Float) String() string {
    78  	return strconv.FormatFloat(
    79  		math.Float64frombits(atomic.LoadUint64(&v.f)), 'g', -1, 64)
    80  }
    81  
    82  // Add adds delta to v.
    83  func (v *Float) Add(delta float64) {
    84  	for {
    85  		cur := atomic.LoadUint64(&v.f)
    86  		curVal := math.Float64frombits(cur)
    87  		nxtVal := curVal + delta
    88  		nxt := math.Float64bits(nxtVal)
    89  		if atomic.CompareAndSwapUint64(&v.f, cur, nxt) {
    90  			return
    91  		}
    92  	}
    93  }
    94  
    95  // Set sets v to value.
    96  func (v *Float) Set(value float64) {
    97  	atomic.StoreUint64(&v.f, math.Float64bits(value))
    98  }
    99  
   100  // Map is a string-to-Var map variable that satisfies the Var interface.
   101  type Map struct {
   102  	m      sync.Map // map[string]Var
   103  	keysMu sync.RWMutex
   104  	keys   []string // sorted
   105  }
   106  
   107  // KeyValue represents a single entry in a Map.
   108  type KeyValue struct {
   109  	Key   string
   110  	Value Var
   111  }
   112  
   113  func (v *Map) String() string {
   114  	var b strings.Builder
   115  	fmt.Fprintf(&b, "{")
   116  	first := true
   117  	v.Do(func(kv KeyValue) {
   118  		if !first {
   119  			fmt.Fprintf(&b, ", ")
   120  		}
   121  		fmt.Fprintf(&b, "%q: ", kv.Key)
   122  		if kv.Value != nil {
   123  			fmt.Fprintf(&b, "%v", kv.Value)
   124  		} else {
   125  			fmt.Fprint(&b, "null")
   126  		}
   127  		first = false
   128  	})
   129  	fmt.Fprintf(&b, "}")
   130  	return b.String()
   131  }
   132  
   133  // Init removes all keys from the map.
   134  func (v *Map) Init() *Map {
   135  	v.keysMu.Lock()
   136  	defer v.keysMu.Unlock()
   137  	v.keys = v.keys[:0]
   138  	v.m.Range(func(k, _ any) bool {
   139  		v.m.Delete(k)
   140  		return true
   141  	})
   142  	return v
   143  }
   144  
   145  // addKey updates the sorted list of keys in v.keys.
   146  func (v *Map) addKey(key string) {
   147  	v.keysMu.Lock()
   148  	defer v.keysMu.Unlock()
   149  	// Using insertion sort to place key into the already-sorted v.keys.
   150  	if i := sort.SearchStrings(v.keys, key); i >= len(v.keys) {
   151  		v.keys = append(v.keys, key)
   152  	} else if v.keys[i] != key {
   153  		v.keys = append(v.keys, "")
   154  		copy(v.keys[i+1:], v.keys[i:])
   155  		v.keys[i] = key
   156  	}
   157  }
   158  
   159  func (v *Map) Get(key string) Var {
   160  	i, _ := v.m.Load(key)
   161  	av, _ := i.(Var)
   162  	return av
   163  }
   164  
   165  func (v *Map) Set(key string, av Var) {
   166  	// Before we store the value, check to see whether the key is new. Try a Load
   167  	// before LoadOrStore: LoadOrStore causes the key interface to escape even on
   168  	// the Load path.
   169  	if _, ok := v.m.Load(key); !ok {
   170  		if _, dup := v.m.LoadOrStore(key, av); !dup {
   171  			v.addKey(key)
   172  			return
   173  		}
   174  	}
   175  
   176  	v.m.Store(key, av)
   177  }
   178  
   179  // Add adds delta to the *Int value stored under the given map key.
   180  func (v *Map) Add(key string, delta int64) {
   181  	i, ok := v.m.Load(key)
   182  	if !ok {
   183  		var dup bool
   184  		i, dup = v.m.LoadOrStore(key, new(Int))
   185  		if !dup {
   186  			v.addKey(key)
   187  		}
   188  	}
   189  
   190  	// Add to Int; ignore otherwise.
   191  	if iv, ok := i.(*Int); ok {
   192  		iv.Add(delta)
   193  	}
   194  }
   195  
   196  // AddFloat adds delta to the *Float value stored under the given map key.
   197  func (v *Map) AddFloat(key string, delta float64) {
   198  	i, ok := v.m.Load(key)
   199  	if !ok {
   200  		var dup bool
   201  		i, dup = v.m.LoadOrStore(key, new(Float))
   202  		if !dup {
   203  			v.addKey(key)
   204  		}
   205  	}
   206  
   207  	// Add to Float; ignore otherwise.
   208  	if iv, ok := i.(*Float); ok {
   209  		iv.Add(delta)
   210  	}
   211  }
   212  
   213  // Delete deletes the given key from the map.
   214  func (v *Map) Delete(key string) {
   215  	v.keysMu.Lock()
   216  	defer v.keysMu.Unlock()
   217  	i := sort.SearchStrings(v.keys, key)
   218  	if i < len(v.keys) && key == v.keys[i] {
   219  		v.keys = append(v.keys[:i], v.keys[i+1:]...)
   220  		v.m.Delete(key)
   221  	}
   222  }
   223  
   224  // Do calls f for each entry in the map.
   225  // The map is locked during the iteration,
   226  // but existing entries may be concurrently updated.
   227  func (v *Map) Do(f func(KeyValue)) {
   228  	v.keysMu.RLock()
   229  	defer v.keysMu.RUnlock()
   230  	for _, k := range v.keys {
   231  		i, _ := v.m.Load(k)
   232  		val, _ := i.(Var)
   233  		f(KeyValue{k, val})
   234  	}
   235  }
   236  
   237  // String is a string variable, and satisfies the Var interface.
   238  type String struct {
   239  	s atomic.Value // string
   240  }
   241  
   242  func (v *String) Value() string {
   243  	p, _ := v.s.Load().(string)
   244  	return p
   245  }
   246  
   247  // String implements the Var interface. To get the unquoted string
   248  // use Value.
   249  func (v *String) String() string {
   250  	s := v.Value()
   251  	b, _ := json.Marshal(s)
   252  	return string(b)
   253  }
   254  
   255  func (v *String) Set(value string) {
   256  	v.s.Store(value)
   257  }
   258  
   259  // Func implements Var by calling the function
   260  // and formatting the returned value using JSON.
   261  type Func func() any
   262  
   263  func (f Func) Value() any {
   264  	return f()
   265  }
   266  
   267  func (f Func) String() string {
   268  	v, _ := json.Marshal(f())
   269  	return string(v)
   270  }
   271  
   272  // All published variables.
   273  var (
   274  	vars      sync.Map // map[string]Var
   275  	varKeysMu sync.RWMutex
   276  	varKeys   []string // sorted
   277  )
   278  
   279  // Publish declares a named exported variable. This should be called from a
   280  // package's init function when it creates its Vars. If the name is already
   281  // registered then this will log.Panic.
   282  func Publish(name string, v Var) {
   283  	if _, dup := vars.LoadOrStore(name, v); dup {
   284  		log.Panicln("Reuse of exported var name:", name)
   285  	}
   286  	varKeysMu.Lock()
   287  	defer varKeysMu.Unlock()
   288  	varKeys = append(varKeys, name)
   289  	sort.Strings(varKeys)
   290  }
   291  
   292  // Get retrieves a named exported variable. It returns nil if the name has
   293  // not been registered.
   294  func Get(name string) Var {
   295  	i, _ := vars.Load(name)
   296  	v, _ := i.(Var)
   297  	return v
   298  }
   299  
   300  // Convenience functions for creating new exported variables.
   301  
   302  func NewInt(name string) *Int {
   303  	v := new(Int)
   304  	Publish(name, v)
   305  	return v
   306  }
   307  
   308  func NewFloat(name string) *Float {
   309  	v := new(Float)
   310  	Publish(name, v)
   311  	return v
   312  }
   313  
   314  func NewMap(name string) *Map {
   315  	v := new(Map).Init()
   316  	Publish(name, v)
   317  	return v
   318  }
   319  
   320  func NewString(name string) *String {
   321  	v := new(String)
   322  	Publish(name, v)
   323  	return v
   324  }
   325  
   326  // Do calls f for each exported variable.
   327  // The global variable map is locked during the iteration,
   328  // but existing entries may be concurrently updated.
   329  func Do(f func(KeyValue)) {
   330  	varKeysMu.RLock()
   331  	defer varKeysMu.RUnlock()
   332  	for _, k := range varKeys {
   333  		val, _ := vars.Load(k)
   334  		f(KeyValue{k, val.(Var)})
   335  	}
   336  }
   337  
   338  func expvarHandler(w http.ResponseWriter, r *http.Request) {
   339  	w.Header().Set("Content-Type", "application/json; charset=utf-8")
   340  	fmt.Fprintf(w, "{\n")
   341  	first := true
   342  	Do(func(kv KeyValue) {
   343  		if !first {
   344  			fmt.Fprintf(w, ",\n")
   345  		}
   346  		first = false
   347  		fmt.Fprintf(w, "%q: %s", kv.Key, kv.Value)
   348  	})
   349  	fmt.Fprintf(w, "\n}\n")
   350  }
   351  
   352  // Handler returns the expvar HTTP Handler.
   353  //
   354  // This is only needed to install the handler in a non-standard location.
   355  func Handler() http.Handler {
   356  	return http.HandlerFunc(expvarHandler)
   357  }
   358  
   359  func cmdline() any {
   360  	return os.Args
   361  }
   362  
   363  func memstats() any {
   364  	stats := new(runtime.MemStats)
   365  	runtime.ReadMemStats(stats)
   366  	return *stats
   367  }
   368  
   369  func init() {
   370  	http.HandleFunc("/debug/vars", expvarHandler)
   371  	Publish("cmdline", Func(cmdline))
   372  	Publish("memstats", Func(memstats))
   373  }
   374
View as plain text