Source file 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  }
    48  

View as plain text