blob: 4f66848f1fe4cf94ea9b50f02beef556ec57270d [file] [log] [blame]
// Copyright 2009 The Go Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
// Package expvar provides a standardized interface to public variables, such
// as operation counters in servers. It exposes these variables via HTTP at
// /debug/vars in JSON format. As of Go 1.22, the /debug/vars request must
// use GET.
//
// Operations to set or modify these public variables are atomic.
//
// In addition to adding the HTTP handler, this package registers the
// following variables:
//
// cmdline os.Args
// memstats runtime.Memstats
//
// The package is sometimes only imported for the side effect of
// registering its HTTP handler and the above variables. To use it
// this way, link this package into your program:
//
// import _ "expvar"
package expvar
import (
"encoding/json"
"internal/godebug"
"log"
"math"
"net/http"
"os"
"runtime"
"slices"
"strconv"
"sync"
"sync/atomic"
"unicode/utf8"
)
// Var is an abstract type for all exported variables.
type Var interface {
// String returns a valid JSON value for the variable.
// Types with String methods that do not return valid JSON
// (such as time.Time) must not be used as a Var.
String() string
}
type jsonVar interface {
// appendJSON appends the JSON representation of the receiver to b.
appendJSON(b []byte) []byte
}
// Int is a 64-bit integer variable that satisfies the [Var] interface.
type Int struct {
i atomic.Int64
}
func (v *Int) Value() int64 {
return v.i.Load()
}
func (v *Int) String() string {
return string(v.appendJSON(nil))
}
func (v *Int) appendJSON(b []byte) []byte {
return strconv.AppendInt(b, v.i.Load(), 10)
}
func (v *Int) Add(delta int64) {
v.i.Add(delta)
}
func (v *Int) Set(value int64) {
v.i.Store(value)
}
// Float is a 64-bit float variable that satisfies the [Var] interface.
type Float struct {
f atomic.Uint64
}
func (v *Float) Value() float64 {
return math.Float64frombits(v.f.Load())
}
func (v *Float) String() string {
return string(v.appendJSON(nil))
}
func (v *Float) appendJSON(b []byte) []byte {
return strconv.AppendFloat(b, math.Float64frombits(v.f.Load()), 'g', -1, 64)
}
// Add adds delta to v.
func (v *Float) Add(delta float64) {
for {
cur := v.f.Load()
curVal := math.Float64frombits(cur)
nxtVal := curVal + delta
nxt := math.Float64bits(nxtVal)
if v.f.CompareAndSwap(cur, nxt) {
return
}
}
}
// Set sets v to value.
func (v *Float) Set(value float64) {
v.f.Store(math.Float64bits(value))
}
// Map is a string-to-Var map variable that satisfies the [Var] interface.
type Map struct {
m sync.Map // map[string]Var
keysMu sync.RWMutex
keys []string // sorted
}
// KeyValue represents a single entry in a [Map].
type KeyValue struct {
Key string
Value Var
}
func (v *Map) String() string {
return string(v.appendJSON(nil))
}
func (v *Map) appendJSON(b []byte) []byte {
return v.appendJSONMayExpand(b, false)
}
func (v *Map) appendJSONMayExpand(b []byte, expand bool) []byte {
afterCommaDelim := byte(' ')
mayAppendNewline := func(b []byte) []byte { return b }
if expand {
afterCommaDelim = '\n'
mayAppendNewline = func(b []byte) []byte { return append(b, '\n') }
}
b = append(b, '{')
b = mayAppendNewline(b)
first := true
v.Do(func(kv KeyValue) {
if !first {
b = append(b, ',', afterCommaDelim)
}
first = false
b = appendJSONQuote(b, kv.Key)
b = append(b, ':', ' ')
switch v := kv.Value.(type) {
case nil:
b = append(b, "null"...)
case jsonVar:
b = v.appendJSON(b)
default:
b = append(b, v.String()...)
}
})
b = mayAppendNewline(b)
b = append(b, '}')
b = mayAppendNewline(b)
return b
}
// Init removes all keys from the map.
func (v *Map) Init() *Map {
v.keysMu.Lock()
defer v.keysMu.Unlock()
v.keys = v.keys[:0]
v.m.Clear()
return v
}
// addKey updates the sorted list of keys in v.keys.
func (v *Map) addKey(key string) {
v.keysMu.Lock()
defer v.keysMu.Unlock()
// Using insertion sort to place key into the already-sorted v.keys.
i, found := slices.BinarySearch(v.keys, key)
if found {
return
}
v.keys = slices.Insert(v.keys, i, key)
}
func (v *Map) Get(key string) Var {
i, _ := v.m.Load(key)
av, _ := i.(Var)
return av
}
func (v *Map) Set(key string, av Var) {
// Before we store the value, check to see whether the key is new. Try a Load
// before LoadOrStore: LoadOrStore causes the key interface to escape even on
// the Load path.
if _, ok := v.m.Load(key); !ok {
if _, dup := v.m.LoadOrStore(key, av); !dup {
v.addKey(key)
return
}
}
v.m.Store(key, av)
}
// Add adds delta to the *[Int] value stored under the given map key.
func (v *Map) Add(key string, delta int64) {
i, ok := v.m.Load(key)
if !ok {
var dup bool
i, dup = v.m.LoadOrStore(key, new(Int))
if !dup {
v.addKey(key)
}
}
// Add to Int; ignore otherwise.
if iv, ok := i.(*Int); ok {
iv.Add(delta)
}
}
// AddFloat adds delta to the *[Float] value stored under the given map key.
func (v *Map) AddFloat(key string, delta float64) {
i, ok := v.m.Load(key)
if !ok {
var dup bool
i, dup = v.m.LoadOrStore(key, new(Float))
if !dup {
v.addKey(key)
}
}
// Add to Float; ignore otherwise.
if iv, ok := i.(*Float); ok {
iv.Add(delta)
}
}
// Delete deletes the given key from the map.
func (v *Map) Delete(key string) {
v.keysMu.Lock()
defer v.keysMu.Unlock()
i, found := slices.BinarySearch(v.keys, key)
if found {
v.keys = slices.Delete(v.keys, i, i+1)
v.m.Delete(key)
}
}
// Do calls f for each entry in the map.
// The map is locked during the iteration,
// but existing entries may be concurrently updated.
func (v *Map) Do(f func(KeyValue)) {
v.keysMu.RLock()
defer v.keysMu.RUnlock()
for _, k := range v.keys {
i, _ := v.m.Load(k)
val, _ := i.(Var)
f(KeyValue{k, val})
}
}
// String is a string variable, and satisfies the [Var] interface.
type String struct {
s atomic.Value // string
}
func (v *String) Value() string {
p, _ := v.s.Load().(string)
return p
}
// String implements the [Var] interface. To get the unquoted string
// use [String.Value].
func (v *String) String() string {
return string(v.appendJSON(nil))
}
func (v *String) appendJSON(b []byte) []byte {
return appendJSONQuote(b, v.Value())
}
func (v *String) Set(value string) {
v.s.Store(value)
}
// Func implements [Var] by calling the function
// and formatting the returned value using JSON.
type Func func() any
func (f Func) Value() any {
return f()
}
func (f Func) String() string {
v, _ := json.Marshal(f())
return string(v)
}
// All published variables.
var vars Map
// Publish declares a named exported variable. This should be called from a
// package's init function when it creates its Vars. If the name is already
// registered then this will log.Panic.
func Publish(name string, v Var) {
if _, dup := vars.m.LoadOrStore(name, v); dup {
log.Panicln("Reuse of exported var name:", name)
}
vars.keysMu.Lock()
defer vars.keysMu.Unlock()
vars.keys = append(vars.keys, name)
slices.Sort(vars.keys)
}
// Get retrieves a named exported variable. It returns nil if the name has
// not been registered.
func Get(name string) Var {
return vars.Get(name)
}
// Convenience functions for creating new exported variables.
func NewInt(name string) *Int {
v := new(Int)
Publish(name, v)
return v
}
func NewFloat(name string) *Float {
v := new(Float)
Publish(name, v)
return v
}
func NewMap(name string) *Map {
v := new(Map).Init()
Publish(name, v)
return v
}
func NewString(name string) *String {
v := new(String)
Publish(name, v)
return v
}
// Do calls f for each exported variable.
// The global variable map is locked during the iteration,
// but existing entries may be concurrently updated.
func Do(f func(KeyValue)) {
vars.Do(f)
}
func expvarHandler(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Content-Type", "application/json; charset=utf-8")
w.Write(vars.appendJSONMayExpand(nil, true))
}
// Handler returns the expvar HTTP Handler.
//
// This is only needed to install the handler in a non-standard location.
func Handler() http.Handler {
return http.HandlerFunc(expvarHandler)
}
func cmdline() any {
return os.Args
}
func memstats() any {
stats := new(runtime.MemStats)
runtime.ReadMemStats(stats)
return *stats
}
func init() {
if godebug.New("httpmuxgo121").Value() == "1" {
http.HandleFunc("/debug/vars", expvarHandler)
} else {
http.HandleFunc("GET /debug/vars", expvarHandler)
}
Publish("cmdline", Func(cmdline))
Publish("memstats", Func(memstats))
}
// TODO: Use json.appendString instead.
func appendJSONQuote(b []byte, s string) []byte {
const hex = "0123456789abcdef"
b = append(b, '"')
for _, r := range s {
switch {
case r < ' ' || r == '\\' || r == '"' || r == '<' || r == '>' || r == '&' || r == '\u2028' || r == '\u2029':
switch r {
case '\\', '"':
b = append(b, '\\', byte(r))
case '\n':
b = append(b, '\\', 'n')
case '\r':
b = append(b, '\\', 'r')
case '\t':
b = append(b, '\\', 't')
default:
b = append(b, '\\', 'u', hex[(r>>12)&0xf], hex[(r>>8)&0xf], hex[(r>>4)&0xf], hex[(r>>0)&0xf])
}
case r < utf8.RuneSelf:
b = append(b, byte(r))
default:
b = utf8.AppendRune(b, r)
}
}
b = append(b, '"')
return b
}