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.
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.
9 // Operations to set or modify these public variables are atomic.
11 // In addition to adding the HTTP handler, this package registers the
12 // following variables:
15 // memstats runtime.Memstats
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:
37 // Var is an abstract type for all exported variables.
42 // Int is a 64-bit integer variable that satisfies the Var interface.
48 func (v
*Int
) String() string {
51 return strconv
.FormatInt(v
.i
, 10)
54 func (v
*Int
) Add(delta
int64) {
60 func (v
*Int
) Set(value
int64) {
66 // Float is a 64-bit float variable that satisfies the Var interface.
72 func (v
*Float
) String() string {
75 return strconv
.FormatFloat(v
.f
, 'g', -1, 64)
78 // Add adds delta to v.
79 func (v
*Float
) Add(delta
float64) {
85 // Set sets v to value.
86 func (v
*Float
) Set(value
float64) {
92 // Map is a string-to-Var map variable that satisfies the Var interface.
96 keys
[]string // sorted
99 // KeyValue represents a single entry in a Map.
100 type KeyValue
struct {
105 func (v
*Map
) String() string {
111 v
.doLocked(func(kv KeyValue
) {
113 fmt
.Fprintf(&b
, ", ")
115 fmt
.Fprintf(&b
, "%q: %v", kv
.Key
, kv
.Value
)
122 func (v
*Map
) Init() *Map
{
123 v
.m
= make(map[string]Var
)
127 // updateKeys updates the sorted list of keys in v.keys.
128 // must be called with v.mu held.
129 func (v
*Map
) updateKeys() {
130 if len(v
.m
) == len(v
.keys
) {
136 v
.keys
= append(v
.keys
, k
)
141 func (v
*Map
) Get(key
string) Var
{
147 func (v
*Map
) Set(key
string, av Var
) {
154 func (v
*Map
) Add(key
string, delta
int64) {
159 // check again under the write lock
170 // Add to Int; ignore otherwise.
171 if iv
, ok
:= av
.(*Int
); ok
{
176 // AddFloat adds delta to the *Float value stored under the given map key.
177 func (v
*Map
) AddFloat(key
string, delta
float64) {
182 // check again under the write lock
193 // Add to Float; ignore otherwise.
194 if iv
, ok
:= av
.(*Float
); ok
{
199 // Do calls f for each entry in the map.
200 // The map is locked during the iteration,
201 // but existing entries may be concurrently updated.
202 func (v
*Map
) Do(f
func(KeyValue
)) {
208 // doLocked calls f for each entry in the map.
209 // v.mu must be held for reads.
210 func (v
*Map
) doLocked(f
func(KeyValue
)) {
211 for _
, k
:= range v
.keys
{
212 f(KeyValue
{k
, v
.m
[k
]})
216 // String is a string variable, and satisfies the Var interface.
222 func (v
*String
) String() string {
225 return strconv
.Quote(v
.s
)
228 func (v
*String
) Set(value
string) {
234 // Func implements Var by calling the function
235 // and formatting the returned value using JSON.
236 type Func
func() interface{}
238 func (f Func
) String() string {
239 v
, _
:= json
.Marshal(f())
243 // All published variables.
246 vars
= make(map[string]Var
)
247 varKeys
[]string // sorted
250 // Publish declares a named exported variable. This should be called from a
251 // package's init function when it creates its Vars. If the name is already
252 // registered then this will log.Panic.
253 func Publish(name
string, v Var
) {
256 if _
, existing
:= vars
[name
]; existing
{
257 log
.Panicln("Reuse of exported var name:", name
)
260 varKeys
= append(varKeys
, name
)
261 sort
.Strings(varKeys
)
264 // Get retrieves a named exported variable.
265 func Get(name
string) Var
{
267 defer mutex
.RUnlock()
271 // Convenience functions for creating new exported variables.
273 func NewInt(name
string) *Int
{
279 func NewFloat(name
string) *Float
{
285 func NewMap(name
string) *Map
{
291 func NewString(name
string) *String
{
297 // Do calls f for each exported variable.
298 // The global variable map is locked during the iteration,
299 // but existing entries may be concurrently updated.
300 func Do(f
func(KeyValue
)) {
302 defer mutex
.RUnlock()
303 for _
, k
:= range varKeys
{
304 f(KeyValue
{k
, vars
[k
]})
308 func expvarHandler(w http
.ResponseWriter
, r
*http
.Request
) {
309 w
.Header().Set("Content-Type", "application/json; charset=utf-8")
310 fmt
.Fprintf(w
, "{\n")
312 Do(func(kv KeyValue
) {
314 fmt
.Fprintf(w
, ",\n")
317 fmt
.Fprintf(w
, "%q: %s", kv
.Key
, kv
.Value
)
319 fmt
.Fprintf(w
, "\n}\n")
322 func cmdline() interface{} {
326 func memstats() interface{} {
327 stats
:= new(runtime
.MemStats
)
328 runtime
.ReadMemStats(stats
)
333 http
.HandleFunc("/debug/vars", expvarHandler
)
334 Publish("cmdline", Func(cmdline
))
335 Publish("memstats", Func(memstats
))