1// Copyright 2020 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 5package metrics 6 7import ( 8 _ "runtime" // depends on the runtime via a linkname'd function 9 "unsafe" 10) 11 12// Sample captures a single metric sample. 13type Sample struct { 14 // Name is the name of the metric sampled. 15 // 16 // It must correspond to a name in one of the metric descriptions 17 // returned by All. 18 Name string 19 20 // Value is the value of the metric sample. 21 Value Value 22} 23 24// Implemented in the runtime. 25func runtime_readMetrics(unsafe.Pointer, int, int) 26 27// Read populates each [Value] field in the given slice of metric samples. 28// 29// Desired metrics should be present in the slice with the appropriate name. 30// The user of this API is encouraged to re-use the same slice between calls for 31// efficiency, but is not required to do so. 32// 33// Note that re-use has some caveats. Notably, Values should not be read or 34// manipulated while a Read with that value is outstanding; that is a data race. 35// This property includes pointer-typed Values (for example, [Float64Histogram]) 36// whose underlying storage will be reused by Read when possible. To safely use 37// such values in a concurrent setting, all data must be deep-copied. 38// 39// It is safe to execute multiple Read calls concurrently, but their arguments 40// must share no underlying memory. When in doubt, create a new []Sample from 41// scratch, which is always safe, though may be inefficient. 42// 43// Sample values with names not appearing in [All] will have their Value populated 44// as KindBad to indicate that the name is unknown. 45func Read(m []Sample) { 46 runtime_readMetrics(unsafe.Pointer(&m[0]), len(m), cap(m)) 47} 48