add notes indicating the source of metrics

open-telemetry · May 21, 2024 · 9d185f2 · 9d185f2
1 parent bf32e4f
commit 9d185f2
Show file tree

Hide file tree

Showing 2 changed files with 47 additions and 10 deletions.
diff --git a/docs/runtime/go-metrics.md b/docs/runtime/go-metrics.md
@@ -40,7 +40,9 @@ This metric is obtained from Go's [`runtime/metrics`][RuntimeMetrics] package us
 <!-- semconv metric.go.memory.used(metric_table) -->
 | Name     | Instrument Type | Unit (UCUM) | Description    | Stability |
 | -------- | --------------- | ----------- | -------------- | --------- |
-| `go.memory.used` | UpDownCounter | `By` | Memory used by the Go runtime. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `go.memory.used` | UpDownCounter | `By` | Memory used by the Go runtime. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+
+**[1]:** Computed from (/memory/classes/total:bytes - /memory/classes/heap/released:bytes).
 <!-- endsemconv -->
 
 <!-- semconv metric.go.memory.used(full) -->
@@ -52,8 +54,10 @@ This metric is obtained from Go's [`runtime/metrics`][RuntimeMetrics] package us
 
 | Value  | Description | Stability |
 |---|---|---|
-| `stack` | Memory allocated from the heap that is reserved for stack space, whether or not it is currently in-use. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `stack` | Memory allocated from the heap that is reserved for stack space, whether or not it is currently in-use. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | `other` | Memory used by the Go runtime, excluding other categories of memory usage. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+
+**[1]:** Computed from /memory/classes/heap/stacks:bytes.
 <!-- endsemconv -->
 
 ### Metric: `go.memory.released`
@@ -64,7 +68,9 @@ This metric is obtained from Go's [`runtime/metrics`][RuntimeMetrics] package us
 <!-- semconv metric.go.memory.released(metric_table) -->
 | Name     | Instrument Type | Unit (UCUM) | Description    | Stability |
 | -------- | --------------- | ----------- | -------------- | --------- |
-| `go.memory.released` | UpDownCounter | `By` | Memory that is completely free and has been returned to the underlying system. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `go.memory.released` | UpDownCounter | `By` | Memory that is completely free and has been returned to the underlying system. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+
+**[1]:** Computed from /memory/classes/heap/released:bytes.
 <!-- endsemconv -->
 
 <!-- semconv metric.go.memory.released(full) -->
@@ -78,7 +84,9 @@ This metric is obtained from Go's [`runtime/metrics`][RuntimeMetrics] package us
 <!-- semconv metric.go.memory.limit(metric_table) -->
 | Name     | Instrument Type | Unit (UCUM) | Description    | Stability |
 | -------- | --------------- | ----------- | -------------- | --------- |
-| `go.memory.limit` | UpDownCounter | `By` | Go runtime memory limit configured by the user, otherwise math.MaxInt64. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `go.memory.limit` | UpDownCounter | `By` | Go runtime memory limit configured by the user, otherwise math.MaxInt64. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+
+**[1]:** Computed from /gc/gomemlimit:bytes.
 <!-- endsemconv -->
 
 <!-- semconv metric.go.memory.limit(full) -->
@@ -93,7 +101,9 @@ This metric is obtained from Go's [`runtime/metrics`][RuntimeMetrics] package us
 <!-- semconv metric.go.memory.allocated(metric_table) -->
 | Name     | Instrument Type | Unit (UCUM) | Description    | Stability |
 | -------- | --------------- | ----------- | -------------- | --------- |
-| `go.memory.allocated` | Counter | `By` | Memory allocated to the heap by the application. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `go.memory.allocated` | Counter | `By` | Memory allocated to the heap by the application. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+
+**[1]:** Computed from /gc/heap/allocs:bytes.
 <!-- endsemconv -->
 
 <!-- semconv metric.go.memory.allocated(full) -->
@@ -107,7 +117,9 @@ This metric is obtained from Go's [`runtime/metrics`][RuntimeMetrics] package us
 <!-- semconv metric.go.memory.allocations(metric_table) -->
 | Name     | Instrument Type | Unit (UCUM) | Description    | Stability |
 | -------- | --------------- | ----------- | -------------- | --------- |
-| `go.memory.allocations` | Counter | `{allocation}` | Count of allocations to the heap by the application. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `go.memory.allocations` | Counter | `{allocation}` | Count of allocations to the heap by the application. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+
+**[1]:** Computed from /gc/heap/allocs:objects.
 <!-- endsemconv -->
 
 <!-- semconv metric.go.memory.allocations(full) -->
@@ -125,7 +137,9 @@ This metric is obtained from Go's [`runtime/metrics`][RuntimeMetrics] package us
 <!-- semconv metric.go.memory.gc.goal(metric_table) -->
 | Name     | Instrument Type | Unit (UCUM) | Description    | Stability |
 | -------- | --------------- | ----------- | -------------- | --------- |
-| `go.memory.gc.goal` | UpDownCounter | `By` | Heap size target for the end of the GC cycle. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `go.memory.gc.goal` | UpDownCounter | `By` | Heap size target for the end of the GC cycle. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+
+**[1]:** Computed from /gc/heap/goal:bytes.
 <!-- endsemconv -->
 
 <!-- semconv metric.go.memory.gc.goal(full) -->
@@ -141,7 +155,7 @@ This metric is obtained from Go's [`runtime/metrics`][RuntimeMetrics] package us
 | -------- | --------------- | ----------- | -------------- | --------- |
 | `go.memory.gc.user_goal` | UpDownCounter | `1` | Heap size target ratio for the end of the GC cycle, as configured by the user. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 
-**[1]:** The value range is [0.0,1.0].
+**[1]:** The value range is [0.0,1.0]. Computed from /gc/gogc:percent.
 <!-- endsemconv -->
 
 <!-- semconv metric.go.memory.gc.user_goal(full) -->
@@ -159,7 +173,9 @@ This metric is obtained from Go's [`runtime/metrics`][RuntimeMetrics] package `/
 <!-- semconv metric.go.thread.limit(metric_table) -->
 | Name     | Instrument Type | Unit (UCUM) | Description    | Stability |
 | -------- | --------------- | ----------- | -------------- | --------- |
-| `go.thread.limit` | UpDownCounter | `{thread}` | The number of OS threads that can execute user-level Go code simultaneously. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `go.thread.limit` | UpDownCounter | `{thread}` | The number of OS threads that can execute user-level Go code simultaneously. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+
+**[1]:** Computed from /sched/gomaxprocs:threads.
 <!-- endsemconv -->
 
 <!-- semconv metric.go.thread.limit(full) -->
@@ -177,7 +193,9 @@ This metric is obtained from Go's [`runtime/metrics`][RuntimeMetrics] package `/
 <!-- semconv metric.go.schedule.duration(metric_table) -->
 | Name     | Instrument Type | Unit (UCUM) | Description    | Stability |
 | -------- | --------------- | ----------- | -------------- | --------- |
-| `go.schedule.duration` | Histogram | `s` | The time goroutines have spent in the scheduler in a runnable state before actually running. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `go.schedule.duration` | Histogram | `s` | The time goroutines have spent in the scheduler in a runnable state before actually running. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+
+**[1]:** Computed from /sched/latencies:seconds.
 <!-- endsemconv -->
 
 <!-- semconv metric.go.schedule.duration(full) -->

diff --git a/model/metrics/go-metrics.yaml b/model/metrics/go-metrics.yaml
@@ -3,6 +3,8 @@ groups:
     type: metric
     metric_name: go.memory.used
     brief: "Memory used by the Go runtime."
+    note: >
+      Computed from (/memory/classes/total:bytes - /memory/classes/heap/released:bytes).
     instrument: updowncounter
     prefix: go.memory
     unit: "By"
@@ -15,6 +17,8 @@ groups:
             - id: stack
               value: 'stack'
               brief: 'Memory allocated from the heap that is reserved for stack space, whether or not it is currently in-use.'
+              note: >
+                Computed from /memory/classes/heap/stacks:bytes.
               stability: experimental
             - id: other
               value: 'other'
@@ -29,6 +33,8 @@ groups:
     type: metric
     metric_name: go.memory.released
     brief: "Memory that is completely free and has been returned to the underlying system."
+    note: >
+      Computed from /memory/classes/heap/released:bytes.
     instrument: updowncounter
     unit: "By"
     stability: experimental
@@ -37,6 +43,8 @@ groups:
     type: metric
     metric_name: go.memory.limit
     brief: "Go runtime memory limit configured by the user, otherwise math.MaxInt64."
+    note: >
+      Computed from /gc/gomemlimit:bytes.
     instrument: updowncounter
     unit: "By"
     stability: experimental
@@ -45,6 +53,8 @@ groups:
     type: metric
     metric_name: go.memory.allocated
     brief: "Memory allocated to the heap by the application."
+    note: >
+      Computed from /gc/heap/allocs:bytes.
     instrument: counter
     unit: "By"
     stability: experimental
@@ -53,6 +63,8 @@ groups:
     type: metric
     metric_name: go.memory.allocations
     brief: "Count of allocations to the heap by the application."
+    note: >
+      Computed from /gc/heap/allocs:objects.
     instrument: counter
     unit: "{allocation}"
     stability: experimental
@@ -61,6 +73,8 @@ groups:
     type: metric
     metric_name: go.memory.gc.goal
     brief: "Heap size target for the end of the GC cycle."
+    note: >
+      Computed from /gc/heap/goal:bytes.
     instrument: updowncounter
     unit: "By"
     stability: experimental
@@ -73,12 +87,15 @@ groups:
     unit: "1"
     note: >
       The value range is [0.0,1.0].
+      Computed from /gc/gogc:percent.
     stability: experimental
 
   - id: metric.go.thread.limit
     type: metric
     metric_name: go.thread.limit
     brief: "The number of OS threads that can execute user-level Go code simultaneously."
+    note: >
+      Computed from /sched/gomaxprocs:threads.
     instrument: updowncounter
     unit: "{thread}"
     stability: experimental
@@ -87,6 +104,8 @@ groups:
     type: metric
     metric_name: go.schedule.duration
     brief: "The time goroutines have spent in the scheduler in a runnable state before actually running."
+    note: >
+      Computed from /sched/latencies:seconds.
     instrument: histogram
     unit: "s"
     stability: experimental