diff options
Diffstat (limited to 'src/runtime/metrics/sample.go')
| -rw-r--r-- | src/runtime/metrics/sample.go | 20 |
1 files changed, 15 insertions, 5 deletions
diff --git a/src/runtime/metrics/sample.go b/src/runtime/metrics/sample.go index b4b0979aa6..4cf8cdf799 100644 --- a/src/runtime/metrics/sample.go +++ b/src/runtime/metrics/sample.go @@ -14,7 +14,7 @@ type Sample struct { // Name is the name of the metric sampled. // // It must correspond to a name in one of the metric descriptions - // returned by Descriptions. + // returned by All. Name string // Value is the value of the metric sample. @@ -27,11 +27,21 @@ func runtime_readMetrics(unsafe.Pointer, int, int) // Read populates each Value field in the given slice of metric samples. // // Desired metrics should be present in the slice with the appropriate name. -// The user of this API is encouraged to re-use the same slice between calls. +// The user of this API is encouraged to re-use the same slice between calls for +// efficiency, but is not required to do so. // -// Metric values with names not appearing in the value returned by Descriptions -// will have the value populated as KindBad to indicate that the name is -// unknown. +// Note that re-use has some caveats. Notably, Values should not be read or +// manipulated while a Read with that value is outstanding; that is a data race. +// This property includes pointer-typed Values (for example, Float64Histogram) +// whose underlying storage will be reused by Read when possible. To safely use +// such values in a concurrent setting, all data must be deep-copied. +// +// It is safe to execute multiple Read calls concurrently, but their arguments +// must share no underlying memory. When in doubt, create a new []Sample from +// scratch, which is always safe, though may be inefficient. +// +// Sample values with names not appearing in All will have their Value populated +// as KindBad to indicate that the name is unknown. func Read(m []Sample) { runtime_readMetrics(unsafe.Pointer(&m[0]), len(m), cap(m)) } |