src/runtime/metrics/sample.go

   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
   5 package metrics
   6
   7 import (
   8         _ "runtime" // depends on the runtime via a linkname'd function
   9         "unsafe"
  10 )
  11
  12 // Sample captures a single metric sample.
  13 type 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.
  25 func 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.
  45 func Read(m []Sample) {
  46         runtime_readMetrics(unsafe.Pointer(&m[0]), len(m), cap(m))
  47 }