From 16d3a0aa3c22dfecdf76ba8be6a5def8ab0f9b81 Mon Sep 17 00:00:00 2001 From: David Ashpole Date: Mon, 29 Apr 2024 18:04:33 +0000 Subject: [PATCH 01/19] add experimental go runtime metrics semantic conventions --- .chloggen/go-runtime-metrics.yaml | 22 ++++ docs/runtime/README.md | 1 + docs/runtime/go-metrics.md | 173 ++++++++++++++++++++++++++++++ model/metrics/go-metrics.yaml | 88 +++++++++++++++ 4 files changed, 284 insertions(+) create mode 100644 .chloggen/go-runtime-metrics.yaml create mode 100644 docs/runtime/go-metrics.md create mode 100644 model/metrics/go-metrics.yaml diff --git a/.chloggen/go-runtime-metrics.yaml b/.chloggen/go-runtime-metrics.yaml new file mode 100644 index 0000000000..72e6aafe9a --- /dev/null +++ b/.chloggen/go-runtime-metrics.yaml @@ -0,0 +1,22 @@ +# Use this changelog template to create an entry for release notes. +# +# If your change doesn't affect end users you should instead start +# your pull request title with [chore] or use the "Skip Changelog" label. + +# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix' +change_type: new_component + +# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) +component: go + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Add new go namespace for Go runtime metrics + +# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists. +# The values here must be integers. +issues: [535] + +# (Optional) One or more lines of additional information to render under the primary note. +# These lines will be padded with 2 spaces and then inserted directly into the document. +# Use pipe (|) for multiline entries. +subtext: diff --git a/docs/runtime/README.md b/docs/runtime/README.md index 6285bc2c92..9762c5ba21 100644 --- a/docs/runtime/README.md +++ b/docs/runtime/README.md @@ -48,6 +48,7 @@ Also consider the semantic conventions when instrumenting runtime environments. - [JVM](jvm-metrics.md) +- [Go](go-metrics.md) ### Attributes diff --git a/docs/runtime/go-metrics.md b/docs/runtime/go-metrics.md new file mode 100644 index 0000000000..ed01d5df33 --- /dev/null +++ b/docs/runtime/go-metrics.md @@ -0,0 +1,173 @@ + + +# Semantic Conventions for Go Runtime Metrics + +**Status**: [Experimental][DocumentStatus] + +This document describes semantic conventions for Go runtime metrics in OpenTelemetry. + + + + + +- [Go Memory](#go-memory) + - [Metric: `go.memory.used`](#metric-gomemoryused) + - [Metric: `go.memory.limit`](#metric-gomemorylimit) + - [Metric: `go.memory.allocated`](#metric-gomemoryallocated) + - [Metric: `go.memory.allocations`](#metric-gomemoryallocations) +- [Go Garbage Collection](#go-garbage-collection) + - [Metric: `go.memory.gc.target`](#metric-gomemorygctarget) + - [Metric: `go.memory.gc.user_target`](#metric-gomemorygcuser_target) +- [Go Threads](#go-threads) + - [Metric: `go.thread.limit`](#metric-gothreadlimit) +- [Go Scheduler](#go-scheduler) + - [Metric: `go.schedule.duration`](#metric-goscheduleduration) + + + +## Go Memory + +**Description:** Go runtime metrics captured under the namespace `go.memory.*` + +### Metric: `go.memory.used` + +This metric is [recommended][MetricRecommended]. +This metric is obtained from Go's [`runtime/metrics`][RuntimeMetrics] package using `/memory/classes` metrics. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `go.memory.used` | UpDownCounter | `By` | Virtual memory mapped by the Go runtime. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| `go.memory.type` | string | The type of memory. | `released`; `stack` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`go.memory.type` MUST be one of the following: + +| Value | Description | Stability | +|---|---|---| +| `released` | Memory that is completely free and has been returned to the underlying system. | ![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. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `other` | All memory mapped by the Go runtime into the current process as read-write, excluding other categories of memory usage. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +### Metric: `go.memory.limit` + +This metric is [recommended][MetricRecommended]. +This metric is obtained from Go's [`runtime/metrics`][RuntimeMetrics] package using `/gc/gomemlimit:bytes`. + + +| 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) | + + + + + +### Metric: `go.memory.allocated` + +This metric is [recommended][MetricRecommended]. +This metric is obtained from Go's [`runtime/metrics`][RuntimeMetrics] package using `/gc/heap/allocs:bytes`. + + +| 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) | + + + + + +### Metric: `go.memory.allocations` + +This metric is [recommended][MetricRecommended]. +This metric is obtained from Go's [`runtime/metrics`][RuntimeMetrics] package using `/gc/heap/allocs:objects`. + + +| 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 Garbage Collection + +**Description:** Go metrics captured under the namespace `go.memory.gc.*` + +### Metric: `go.memory.gc.target` + +This metric is [recommended][MetricRecommended]. +This metric is obtained from Go's [`runtime/metrics`][RuntimeMetrics] package using `/gc/heap/goal:bytes`. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `go.memory.gc.target` | UpDownCounter | `By` | Heap size target for the end of the GC cycle. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + +### Metric: `go.memory.gc.user_target` + +This metric is [recommended][MetricRecommended]. +This metric is obtained from Go's [`runtime/metrics`][RuntimeMetrics] package using `/gc/gogc:percent`. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `go.memory.gc.user_target` | 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]. + + + + + +## Go Threads + +**Description:** Go metrics captured under the namespace `go.thread.*` + +### Metric: `go.thread.limit` + +This metric is [recommended][MetricRecommended]. +This metric is obtained from Go's [`runtime/metrics`][RuntimeMetrics] package `/sched/gomaxprocs:threads`. + + +| 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 Scheduler + +**Description:** Go metrics captured under the namespace `go.schedule.*` + +### Metric: `go.schedule.duration` + +This metric is [recommended][MetricRecommended]. +This metric is obtained from Go's [`runtime/metrics`][RuntimeMetrics] package `/sched/latencies:seconds`. + + +| 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) | + + + + + +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md +[MetricRecommended]: /docs/general/metric-requirement-level.md#recommended +[RuntimeMetrics]: https://pkg.go.dev/runtime/metrics diff --git a/model/metrics/go-metrics.yaml b/model/metrics/go-metrics.yaml new file mode 100644 index 0000000000..9e3dcc0766 --- /dev/null +++ b/model/metrics/go-metrics.yaml @@ -0,0 +1,88 @@ +groups: + - id: metric.go.memory.used + type: metric + metric_name: go.memory.used + brief: "Virtual memory mapped by the Go runtime." + instrument: updowncounter + prefix: go.memory + unit: "By" + attributes: + - id: type + stability: experimental + type: + allow_custom_values: false + members: + - id: released + value: 'released' + brief: 'Memory that is completely free and has been returned to the underlying system.' + stability: experimental + - id: stack + value: 'stack' + brief: 'Memory allocated from the heap that is reserved for stack space, whether or not it is currently in-use.' + stability: experimental + - id: other + value: 'other' + brief: 'All memory mapped by the Go runtime into the current process as read-write, excluding other categories of memory usage.' + stability: experimental + requirement_level: recommended + brief: The type of memory. + examples: ["released", "stack"] + stability: experimental + + - id: metric.go.memory.limit + type: metric + metric_name: go.memory.limit + brief: "Go runtime memory limit configured by the user, otherwise math.MaxInt64." + instrument: updowncounter + unit: "By" + stability: experimental + + - id: metric.go.memory.allocated + type: metric + metric_name: go.memory.allocated + brief: "Memory allocated to the heap by the application." + instrument: counter + unit: "By" + stability: experimental + + - id: metric.go.memory.allocations + type: metric + metric_name: go.memory.allocations + brief: "Count of allocations to the heap by the application." + instrument: counter + unit: "{allocation}" + stability: experimental + + - id: metric.go.memory.gc.target + type: metric + metric_name: go.memory.gc.target + brief: "Heap size target for the end of the GC cycle." + instrument: updowncounter + unit: "By" + stability: experimental + + - id: metric.go.memory.gc.user_target + type: metric + metric_name: go.memory.gc.user_target + brief: "Heap size target ratio for the end of the GC cycle, as configured by the user." + instrument: updowncounter + unit: "1" + note: > + The value range is [0.0,1.0]. + 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." + instrument: updowncounter + unit: "{thread}" + stability: experimental + + - id: metric.go.schedule.duration + type: metric + metric_name: go.schedule.duration + brief: "The time goroutines have spent in the scheduler in a runnable state before actually running." + instrument: histogram + unit: "s" + stability: experimental From bde0f9b58247a37ef9d8bf237583c22757a3b8d1 Mon Sep 17 00:00:00 2001 From: David Ashpole Date: Tue, 30 Apr 2024 14:59:54 +0000 Subject: [PATCH 02/19] rename gc.target -> gc.goal --- docs/runtime/go-metrics.md | 20 ++++++++++---------- model/metrics/go-metrics.yaml | 8 ++++---- 2 files changed, 14 insertions(+), 14 deletions(-) diff --git a/docs/runtime/go-metrics.md b/docs/runtime/go-metrics.md index ed01d5df33..23371a34c7 100644 --- a/docs/runtime/go-metrics.md +++ b/docs/runtime/go-metrics.md @@ -18,8 +18,8 @@ This document describes semantic conventions for Go runtime metrics in OpenTelem - [Metric: `go.memory.allocated`](#metric-gomemoryallocated) - [Metric: `go.memory.allocations`](#metric-gomemoryallocations) - [Go Garbage Collection](#go-garbage-collection) - - [Metric: `go.memory.gc.target`](#metric-gomemorygctarget) - - [Metric: `go.memory.gc.user_target`](#metric-gomemorygcuser_target) + - [Metric: `go.memory.gc.goal`](#metric-gomemorygcgoal) + - [Metric: `go.memory.gc.user_goal`](#metric-gomemorygcuser_goal) - [Go Threads](#go-threads) - [Metric: `go.thread.limit`](#metric-gothreadlimit) - [Go Scheduler](#go-scheduler) @@ -102,34 +102,34 @@ This metric is obtained from Go's [`runtime/metrics`][RuntimeMetrics] package us **Description:** Go metrics captured under the namespace `go.memory.gc.*` -### Metric: `go.memory.gc.target` +### Metric: `go.memory.gc.goal` This metric is [recommended][MetricRecommended]. This metric is obtained from Go's [`runtime/metrics`][RuntimeMetrics] package using `/gc/heap/goal:bytes`. - + | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `go.memory.gc.target` | 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. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - + -### Metric: `go.memory.gc.user_target` +### Metric: `go.memory.gc.user_goal` This metric is [recommended][MetricRecommended]. This metric is obtained from Go's [`runtime/metrics`][RuntimeMetrics] package using `/gc/gogc:percent`. - + | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `go.memory.gc.user_target` | 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) | +| `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]. - + ## Go Threads diff --git a/model/metrics/go-metrics.yaml b/model/metrics/go-metrics.yaml index 9e3dcc0766..66cbd8238f 100644 --- a/model/metrics/go-metrics.yaml +++ b/model/metrics/go-metrics.yaml @@ -53,17 +53,17 @@ groups: unit: "{allocation}" stability: experimental - - id: metric.go.memory.gc.target + - id: metric.go.memory.gc.goal type: metric - metric_name: go.memory.gc.target + metric_name: go.memory.gc.goal brief: "Heap size target for the end of the GC cycle." instrument: updowncounter unit: "By" stability: experimental - - id: metric.go.memory.gc.user_target + - id: metric.go.memory.gc.user_goal type: metric - metric_name: go.memory.gc.user_target + metric_name: go.memory.gc.user_goal brief: "Heap size target ratio for the end of the GC cycle, as configured by the user." instrument: updowncounter unit: "1" From bf32e4f2397ae2c6c864782a984d0f0e5f6dd538 Mon Sep 17 00:00:00 2001 From: David Ashpole Date: Tue, 30 Apr 2024 16:31:50 +0000 Subject: [PATCH 03/19] split reserved memory out of memory usage --- docs/runtime/go-metrics.md | 21 ++++++++++++++++++--- model/metrics/go-metrics.yaml | 16 ++++++++++------ 2 files changed, 28 insertions(+), 9 deletions(-) diff --git a/docs/runtime/go-metrics.md b/docs/runtime/go-metrics.md index 23371a34c7..287ab2ea3e 100644 --- a/docs/runtime/go-metrics.md +++ b/docs/runtime/go-metrics.md @@ -14,6 +14,7 @@ This document describes semantic conventions for Go runtime metrics in OpenTelem - [Go Memory](#go-memory) - [Metric: `go.memory.used`](#metric-gomemoryused) + - [Metric: `go.memory.released`](#metric-gomemoryreleased) - [Metric: `go.memory.limit`](#metric-gomemorylimit) - [Metric: `go.memory.allocated`](#metric-gomemoryallocated) - [Metric: `go.memory.allocations`](#metric-gomemoryallocations) @@ -39,7 +40,7 @@ This metric is obtained from Go's [`runtime/metrics`][RuntimeMetrics] package us | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `go.memory.used` | UpDownCounter | `By` | Virtual memory mapped by the Go runtime. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `go.memory.used` | UpDownCounter | `By` | Memory used by the Go runtime. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -51,9 +52,22 @@ This metric is obtained from Go's [`runtime/metrics`][RuntimeMetrics] package us | Value | Description | Stability | |---|---|---| -| `released` | Memory that is completely free and has been returned to the underlying system. | ![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. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `other` | All memory mapped by the Go runtime into the current process as read-write, excluding other categories of memory usage. | ![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) | + + +### Metric: `go.memory.released` + +This metric is [recommended][MetricRecommended]. +This metric is obtained from Go's [`runtime/metrics`][RuntimeMetrics] package using `/gc/gomemlimit:bytes`. + + +| 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) | + + + ### Metric: `go.memory.limit` @@ -70,6 +84,7 @@ This metric is obtained from Go's [`runtime/metrics`][RuntimeMetrics] package us + ### Metric: `go.memory.allocated` This metric is [recommended][MetricRecommended]. diff --git a/model/metrics/go-metrics.yaml b/model/metrics/go-metrics.yaml index 66cbd8238f..355912c902 100644 --- a/model/metrics/go-metrics.yaml +++ b/model/metrics/go-metrics.yaml @@ -2,7 +2,7 @@ groups: - id: metric.go.memory.used type: metric metric_name: go.memory.used - brief: "Virtual memory mapped by the Go runtime." + brief: "Memory used by the Go runtime." instrument: updowncounter prefix: go.memory unit: "By" @@ -12,23 +12,27 @@ groups: type: allow_custom_values: false members: - - id: released - value: 'released' - brief: 'Memory that is completely free and has been returned to the underlying system.' - stability: experimental - id: stack value: 'stack' brief: 'Memory allocated from the heap that is reserved for stack space, whether or not it is currently in-use.' stability: experimental - id: other value: 'other' - brief: 'All memory mapped by the Go runtime into the current process as read-write, excluding other categories of memory usage.' + brief: 'Memory used by the Go runtime, excluding other categories of memory usage.' stability: experimental requirement_level: recommended brief: The type of memory. examples: ["released", "stack"] stability: experimental + - id: metric.go.memory.released + type: metric + metric_name: go.memory.released + brief: "Memory that is completely free and has been returned to the underlying system." + instrument: updowncounter + unit: "By" + stability: experimental + - id: metric.go.memory.limit type: metric metric_name: go.memory.limit From 9d185f252a7e16983b20d8145f04eaad821af865 Mon Sep 17 00:00:00 2001 From: David Ashpole Date: Tue, 30 Apr 2024 16:40:31 +0000 Subject: [PATCH 04/19] add notes indicating the source of metrics --- docs/runtime/go-metrics.md | 38 ++++++++++++++++++++++++++--------- model/metrics/go-metrics.yaml | 19 ++++++++++++++++++ 2 files changed, 47 insertions(+), 10 deletions(-) diff --git a/docs/runtime/go-metrics.md b/docs/runtime/go-metrics.md index 287ab2ea3e..103c81c0d8 100644 --- 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 | 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). @@ -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. ### Metric: `go.memory.released` @@ -64,7 +68,9 @@ This metric is obtained from Go's [`runtime/metrics`][RuntimeMetrics] package us | 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. @@ -78,7 +84,9 @@ This metric is obtained from Go's [`runtime/metrics`][RuntimeMetrics] package us | 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. @@ -93,7 +101,9 @@ This metric is obtained from Go's [`runtime/metrics`][RuntimeMetrics] package us | 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. @@ -107,7 +117,9 @@ This metric is obtained from Go's [`runtime/metrics`][RuntimeMetrics] package us | 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. @@ -125,7 +137,9 @@ This metric is obtained from Go's [`runtime/metrics`][RuntimeMetrics] package us | 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. @@ -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. @@ -159,7 +173,9 @@ This metric is obtained from Go's [`runtime/metrics`][RuntimeMetrics] package `/ | 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. @@ -177,7 +193,9 @@ This metric is obtained from Go's [`runtime/metrics`][RuntimeMetrics] package `/ | 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. diff --git a/model/metrics/go-metrics.yaml b/model/metrics/go-metrics.yaml index 355912c902..9b0ebce5ac 100644 --- 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 From 79493afcb851c8e24f9f6f6e5fd21850236a6a92 Mon Sep 17 00:00:00 2001 From: David Ashpole Date: Tue, 30 Apr 2024 16:47:54 +0000 Subject: [PATCH 05/19] add go.goroutine.count --- docs/runtime/go-metrics.md | 20 ++++++++++++++++++++ model/metrics/go-metrics.yaml | 10 ++++++++++ 2 files changed, 30 insertions(+) diff --git a/docs/runtime/go-metrics.md b/docs/runtime/go-metrics.md index 103c81c0d8..38eb13b6a8 100644 --- a/docs/runtime/go-metrics.md +++ b/docs/runtime/go-metrics.md @@ -161,6 +161,26 @@ This metric is obtained from Go's [`runtime/metrics`][RuntimeMetrics] package us +## Go Goroutines + +**Description:** Go metrics captured under the namespace `go.goroutine.*` + +### Metric: `go.goroutine.count` + +This metric is [recommended][MetricRecommended]. +This metric is obtained from Go's [`runtime/metrics`][RuntimeMetrics] package `/sched/gomaxprocs:threads`. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `go.goroutine.count` | UpDownCounter | `{goroutine}` | Count of live goroutines. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** Computed from `/sched/goroutines:goroutines`. + + + + + ## Go Threads **Description:** Go metrics captured under the namespace `go.thread.*` diff --git a/model/metrics/go-metrics.yaml b/model/metrics/go-metrics.yaml index 9b0ebce5ac..067c0fdf99 100644 --- a/model/metrics/go-metrics.yaml +++ b/model/metrics/go-metrics.yaml @@ -90,6 +90,16 @@ groups: Computed from /gc/gogc:percent. stability: experimental + - id: metric.go.goroutine.count + type: metric + metric_name: go.goroutine.count + brief: "Count of live goroutines." + note: > + Computed from `/sched/goroutines:goroutines`. + instrument: updowncounter + unit: "{goroutine}" + stability: experimental + - id: metric.go.thread.limit type: metric metric_name: go.thread.limit From 66a99653119dc203e150e22043c583f8d6e04ea0 Mon Sep 17 00:00:00 2001 From: David Ashpole Date: Tue, 30 Apr 2024 16:51:32 +0000 Subject: [PATCH 06/19] cleanups --- docs/runtime/go-metrics.md | 35 ++++++++++++++--------------------- model/metrics/go-metrics.yaml | 22 +++++++++++----------- 2 files changed, 25 insertions(+), 32 deletions(-) diff --git a/docs/runtime/go-metrics.md b/docs/runtime/go-metrics.md index 38eb13b6a8..bcb3f5b678 100644 --- a/docs/runtime/go-metrics.md +++ b/docs/runtime/go-metrics.md @@ -7,6 +7,7 @@ linkTitle: Go Runtime **Status**: [Experimental][DocumentStatus] This document describes semantic conventions for Go runtime metrics in OpenTelemetry. +These metrics are obtained from Go's [`runtime/metrics`][RuntimeMetrics] package. @@ -21,6 +22,8 @@ This document describes semantic conventions for Go runtime metrics in OpenTelem - [Go Garbage Collection](#go-garbage-collection) - [Metric: `go.memory.gc.goal`](#metric-gomemorygcgoal) - [Metric: `go.memory.gc.user_goal`](#metric-gomemorygcuser_goal) +- [Go Goroutines](#go-goroutines) + - [Metric: `go.goroutine.count`](#metric-gogoroutinecount) - [Go Threads](#go-threads) - [Metric: `go.thread.limit`](#metric-gothreadlimit) - [Go Scheduler](#go-scheduler) @@ -35,20 +38,19 @@ This document describes semantic conventions for Go runtime metrics in OpenTelem ### Metric: `go.memory.used` This metric is [recommended][MetricRecommended]. -This metric is obtained from Go's [`runtime/metrics`][RuntimeMetrics] package using `/memory/classes` metrics. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | | `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). +**[1]:** Computed from `(/memory/classes/total:bytes - /memory/classes/heap/released:bytes)`. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| `go.memory.type` | string | The type of memory. | `released`; `stack` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `go.memory.type` | string | The type of memory. | `other`; `stack` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | `go.memory.type` MUST be one of the following: @@ -57,20 +59,19 @@ This metric is obtained from Go's [`runtime/metrics`][RuntimeMetrics] package us | `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. +**[1]:** Computed from `/memory/classes/heap/stacks:bytes`. ### Metric: `go.memory.released` This metric is [recommended][MetricRecommended]. -This metric is obtained from Go's [`runtime/metrics`][RuntimeMetrics] package using `/gc/gomemlimit:bytes`. | 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. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -**[1]:** Computed from /memory/classes/heap/released:bytes. +**[1]:** Computed from `/memory/classes/heap/released:bytes`. @@ -79,14 +80,13 @@ This metric is obtained from Go's [`runtime/metrics`][RuntimeMetrics] package us ### Metric: `go.memory.limit` This metric is [recommended][MetricRecommended]. -This metric is obtained from Go's [`runtime/metrics`][RuntimeMetrics] package using `/gc/gomemlimit:bytes`. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | | `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. +**[1]:** Computed from `/gc/gomemlimit:bytes`. @@ -96,14 +96,13 @@ This metric is obtained from Go's [`runtime/metrics`][RuntimeMetrics] package us ### Metric: `go.memory.allocated` This metric is [recommended][MetricRecommended]. -This metric is obtained from Go's [`runtime/metrics`][RuntimeMetrics] package using `/gc/heap/allocs:bytes`. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | | `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. +**[1]:** Computed from `/gc/heap/allocs:bytes`. @@ -112,14 +111,13 @@ This metric is obtained from Go's [`runtime/metrics`][RuntimeMetrics] package us ### Metric: `go.memory.allocations` This metric is [recommended][MetricRecommended]. -This metric is obtained from Go's [`runtime/metrics`][RuntimeMetrics] package using `/gc/heap/allocs:objects`. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | | `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. +**[1]:** Computed from `/gc/heap/allocs:objects`. @@ -132,14 +130,13 @@ This metric is obtained from Go's [`runtime/metrics`][RuntimeMetrics] package us ### Metric: `go.memory.gc.goal` This metric is [recommended][MetricRecommended]. -This metric is obtained from Go's [`runtime/metrics`][RuntimeMetrics] package using `/gc/heap/goal:bytes`. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | | `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. +**[1]:** Computed from `/gc/heap/goal:bytes`. @@ -148,14 +145,13 @@ This metric is obtained from Go's [`runtime/metrics`][RuntimeMetrics] package us ### Metric: `go.memory.gc.user_goal` This metric is [recommended][MetricRecommended]. -This metric is obtained from Go's [`runtime/metrics`][RuntimeMetrics] package using `/gc/gogc:percent`. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | | `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]. Computed from /gc/gogc:percent. +**[1]:** The value range is [0.0,1.0]. Computed from `/gc/gogc:percent`. @@ -168,7 +164,6 @@ This metric is obtained from Go's [`runtime/metrics`][RuntimeMetrics] package us ### Metric: `go.goroutine.count` This metric is [recommended][MetricRecommended]. -This metric is obtained from Go's [`runtime/metrics`][RuntimeMetrics] package `/sched/gomaxprocs:threads`. | Name | Instrument Type | Unit (UCUM) | Description | Stability | @@ -188,14 +183,13 @@ This metric is obtained from Go's [`runtime/metrics`][RuntimeMetrics] package `/ ### Metric: `go.thread.limit` This metric is [recommended][MetricRecommended]. -This metric is obtained from Go's [`runtime/metrics`][RuntimeMetrics] package `/sched/gomaxprocs:threads`. | 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. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -**[1]:** Computed from /sched/gomaxprocs:threads. +**[1]:** Computed from `/sched/gomaxprocs:threads`. @@ -208,14 +202,13 @@ This metric is obtained from Go's [`runtime/metrics`][RuntimeMetrics] package `/ ### Metric: `go.schedule.duration` This metric is [recommended][MetricRecommended]. -This metric is obtained from Go's [`runtime/metrics`][RuntimeMetrics] package `/sched/latencies:seconds`. | 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. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -**[1]:** Computed from /sched/latencies:seconds. +**[1]:** Computed from `/sched/latencies:seconds`. diff --git a/model/metrics/go-metrics.yaml b/model/metrics/go-metrics.yaml index 067c0fdf99..17e93384cd 100644 --- a/model/metrics/go-metrics.yaml +++ b/model/metrics/go-metrics.yaml @@ -4,7 +4,7 @@ groups: metric_name: go.memory.used brief: "Memory used by the Go runtime." note: > - Computed from (/memory/classes/total:bytes - /memory/classes/heap/released:bytes). + Computed from `(/memory/classes/total:bytes - /memory/classes/heap/released:bytes)`. instrument: updowncounter prefix: go.memory unit: "By" @@ -18,7 +18,7 @@ groups: 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. + Computed from `/memory/classes/heap/stacks:bytes`. stability: experimental - id: other value: 'other' @@ -26,7 +26,7 @@ groups: stability: experimental requirement_level: recommended brief: The type of memory. - examples: ["released", "stack"] + examples: ["other", "stack"] stability: experimental - id: metric.go.memory.released @@ -34,7 +34,7 @@ groups: 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. + Computed from `/memory/classes/heap/released:bytes`. instrument: updowncounter unit: "By" stability: experimental @@ -44,7 +44,7 @@ groups: metric_name: go.memory.limit brief: "Go runtime memory limit configured by the user, otherwise math.MaxInt64." note: > - Computed from /gc/gomemlimit:bytes. + Computed from `/gc/gomemlimit:bytes`. instrument: updowncounter unit: "By" stability: experimental @@ -54,7 +54,7 @@ groups: metric_name: go.memory.allocated brief: "Memory allocated to the heap by the application." note: > - Computed from /gc/heap/allocs:bytes. + Computed from `/gc/heap/allocs:bytes`. instrument: counter unit: "By" stability: experimental @@ -64,7 +64,7 @@ groups: metric_name: go.memory.allocations brief: "Count of allocations to the heap by the application." note: > - Computed from /gc/heap/allocs:objects. + Computed from `/gc/heap/allocs:objects`. instrument: counter unit: "{allocation}" stability: experimental @@ -74,7 +74,7 @@ groups: metric_name: go.memory.gc.goal brief: "Heap size target for the end of the GC cycle." note: > - Computed from /gc/heap/goal:bytes. + Computed from `/gc/heap/goal:bytes`. instrument: updowncounter unit: "By" stability: experimental @@ -87,7 +87,7 @@ groups: unit: "1" note: > The value range is [0.0,1.0]. - Computed from /gc/gogc:percent. + Computed from `/gc/gogc:percent`. stability: experimental - id: metric.go.goroutine.count @@ -105,7 +105,7 @@ groups: 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. + Computed from `/sched/gomaxprocs:threads`. instrument: updowncounter unit: "{thread}" stability: experimental @@ -115,7 +115,7 @@ groups: 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. + Computed from `/sched/latencies:seconds`. instrument: histogram unit: "s" stability: experimental From c527c4b64d19424b07ed25da43dedfb091b34084 Mon Sep 17 00:00:00 2001 From: David Ashpole Date: Tue, 30 Apr 2024 18:49:59 +0000 Subject: [PATCH 07/19] exclude max int-valued metrics --- docs/runtime/go-metrics.md | 4 ++-- model/metrics/go-metrics.yaml | 3 ++- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/runtime/go-metrics.md b/docs/runtime/go-metrics.md index bcb3f5b678..8401bf0277 100644 --- a/docs/runtime/go-metrics.md +++ b/docs/runtime/go-metrics.md @@ -84,9 +84,9 @@ This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `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) | +| `go.memory.limit` | UpDownCounter | `By` | Go runtime memory limit configured by the user, if a limit exists. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -**[1]:** Computed from `/gc/gomemlimit:bytes`. +**[1]:** Computed from `/gc/gomemlimit:bytes`. This metric is excluded if the limit obtained from the Go runtime is math.MaxInt64. diff --git a/model/metrics/go-metrics.yaml b/model/metrics/go-metrics.yaml index 17e93384cd..6f30f762d7 100644 --- a/model/metrics/go-metrics.yaml +++ b/model/metrics/go-metrics.yaml @@ -42,9 +42,10 @@ groups: - id: metric.go.memory.limit type: metric metric_name: go.memory.limit - brief: "Go runtime memory limit configured by the user, otherwise math.MaxInt64." + brief: "Go runtime memory limit configured by the user, if a limit exists." note: > Computed from `/gc/gomemlimit:bytes`. + This metric is excluded if the limit obtained from the Go runtime is math.MaxInt64. instrument: updowncounter unit: "By" stability: experimental From 3781bae6165b02f30d039b20c45fd920a67a0505 Mon Sep 17 00:00:00 2001 From: David Ashpole Date: Tue, 30 Apr 2024 18:51:42 +0000 Subject: [PATCH 08/19] lint --- docs/runtime/go-metrics.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/runtime/go-metrics.md b/docs/runtime/go-metrics.md index 8401bf0277..b4c4d00827 100644 --- a/docs/runtime/go-metrics.md +++ b/docs/runtime/go-metrics.md @@ -92,7 +92,6 @@ This metric is [recommended][MetricRecommended]. - ### Metric: `go.memory.allocated` This metric is [recommended][MetricRecommended]. From 79dad69aeae532a267c7ee56cf4bed108517e9c6 Mon Sep 17 00:00:00 2001 From: David Ashpole Date: Wed, 1 May 2024 18:16:58 +0000 Subject: [PATCH 09/19] change user_goal to go.config.gogc --- docs/runtime/go-metrics.md | 37 ++++++++++++++++++++--------------- model/metrics/go-metrics.yaml | 22 ++++++++++----------- 2 files changed, 32 insertions(+), 27 deletions(-) diff --git a/docs/runtime/go-metrics.md b/docs/runtime/go-metrics.md index b4c4d00827..1498d0beec 100644 --- a/docs/runtime/go-metrics.md +++ b/docs/runtime/go-metrics.md @@ -21,13 +21,14 @@ These metrics are obtained from Go's [`runtime/metrics`][RuntimeMetrics] package - [Metric: `go.memory.allocations`](#metric-gomemoryallocations) - [Go Garbage Collection](#go-garbage-collection) - [Metric: `go.memory.gc.goal`](#metric-gomemorygcgoal) - - [Metric: `go.memory.gc.user_goal`](#metric-gomemorygcuser_goal) - [Go Goroutines](#go-goroutines) - [Metric: `go.goroutine.count`](#metric-gogoroutinecount) - [Go Threads](#go-threads) - [Metric: `go.thread.limit`](#metric-gothreadlimit) - [Go Scheduler](#go-scheduler) - [Metric: `go.schedule.duration`](#metric-goscheduleduration) +- [Go Runtime Configuration](#go-runtime-configuration) + - [Metric: `go.config.gogc`](#metric-goconfiggogc) @@ -141,21 +142,6 @@ This metric is [recommended][MetricRecommended]. -### Metric: `go.memory.gc.user_goal` - -This metric is [recommended][MetricRecommended]. - - -| Name | Instrument Type | Unit (UCUM) | Description | Stability | -| -------- | --------------- | ----------- | -------------- | --------- | -| `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]. Computed from `/gc/gogc:percent`. - - - - - ## Go Goroutines **Description:** Go metrics captured under the namespace `go.goroutine.*` @@ -213,6 +199,25 @@ This metric is [recommended][MetricRecommended]. +## Go Runtime Configuration + +**Description:** Go metrics captured under the namespace `go.config.*` + +### Metric: `go.config.gogc` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `go.config.gogc` | UpDownCounter | `%` | Heap size target percentage configured by the user, otherwise 100. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** The value range is [0.0,100.0]. Computed from `/gc/gogc:percent`. + + + + + [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md [MetricRecommended]: /docs/general/metric-requirement-level.md#recommended [RuntimeMetrics]: https://pkg.go.dev/runtime/metrics diff --git a/model/metrics/go-metrics.yaml b/model/metrics/go-metrics.yaml index 6f30f762d7..74424f0b6d 100644 --- a/model/metrics/go-metrics.yaml +++ b/model/metrics/go-metrics.yaml @@ -80,17 +80,6 @@ groups: unit: "By" stability: experimental - - id: metric.go.memory.gc.user_goal - type: metric - metric_name: go.memory.gc.user_goal - brief: "Heap size target ratio for the end of the GC cycle, as configured by the user." - instrument: updowncounter - unit: "1" - note: > - The value range is [0.0,1.0]. - Computed from `/gc/gogc:percent`. - stability: experimental - - id: metric.go.goroutine.count type: metric metric_name: go.goroutine.count @@ -120,3 +109,14 @@ groups: instrument: histogram unit: "s" stability: experimental + + - id: metric.go.config.gogc + type: metric + metric_name: go.config.gogc + brief: "Heap size target percentage configured by the user, otherwise 100." + note: > + The value range is [0.0,100.0]. + Computed from `/gc/gogc:percent`. + instrument: updowncounter + unit: "%" + stability: experimental From 32e4ebe1f5d7aa2965564f6d2fd405a019b70fce Mon Sep 17 00:00:00 2001 From: David Ashpole Date: Thu, 2 May 2024 18:10:07 +0000 Subject: [PATCH 10/19] fix after rebase --- docs/runtime/go-metrics.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/docs/runtime/go-metrics.md b/docs/runtime/go-metrics.md index 1498d0beec..914f504d82 100644 --- a/docs/runtime/go-metrics.md +++ b/docs/runtime/go-metrics.md @@ -51,16 +51,14 @@ This metric is [recommended][MetricRecommended]. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| `go.memory.type` | string | The type of memory. | `other`; `stack` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`go.memory.type`](/docs/attributes-registry/go.md) | string | The type of memory. | `other`; `stack` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -`go.memory.type` MUST be one of the following: +`go.memory.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | |---|---|---| -| `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) | +| `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) | | `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`. ### Metric: `go.memory.released` From a7083523ce2c061bde5aab959f6a00901fae9b84 Mon Sep 17 00:00:00 2001 From: David Ashpole Date: Mon, 6 May 2024 15:22:12 +0000 Subject: [PATCH 11/19] add go attributes to the attributes registry --- .github/ISSUE_TEMPLATE/bug_report.yaml | 1 + .github/ISSUE_TEMPLATE/change_proposal.yaml | 1 + .github/ISSUE_TEMPLATE/new-conventions.yaml | 1 + docs/attributes-registry/README.md | 1 + docs/attributes-registry/go.md | 22 ++++++++++++++++++ model/metrics/go-metrics.yaml | 18 +-------------- model/registry/go.yaml | 25 +++++++++++++++++++++ 7 files changed, 52 insertions(+), 17 deletions(-) create mode 100644 docs/attributes-registry/go.md create mode 100644 model/registry/go.yaml diff --git a/.github/ISSUE_TEMPLATE/bug_report.yaml b/.github/ISSUE_TEMPLATE/bug_report.yaml index af486e4502..4aefd034cc 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yaml +++ b/.github/ISSUE_TEMPLATE/bug_report.yaml @@ -43,6 +43,7 @@ body: - area:file - area:gcp - area:gen-ai + - area:go - area:graphql - area:heroku - area:host diff --git a/.github/ISSUE_TEMPLATE/change_proposal.yaml b/.github/ISSUE_TEMPLATE/change_proposal.yaml index 3d00899d2d..2af8b08f70 100644 --- a/.github/ISSUE_TEMPLATE/change_proposal.yaml +++ b/.github/ISSUE_TEMPLATE/change_proposal.yaml @@ -36,6 +36,7 @@ body: - area:file - area:gcp - area:gen-ai + - area:go - area:graphql - area:heroku - area:host diff --git a/.github/ISSUE_TEMPLATE/new-conventions.yaml b/.github/ISSUE_TEMPLATE/new-conventions.yaml index 3985923373..0753cd8184 100644 --- a/.github/ISSUE_TEMPLATE/new-conventions.yaml +++ b/.github/ISSUE_TEMPLATE/new-conventions.yaml @@ -45,6 +45,7 @@ body: - area:file - area:gcp - area:gen-ai + - area:go - area:graphql - area:heroku - area:host diff --git a/docs/attributes-registry/README.md b/docs/attributes-registry/README.md index 66f750c036..a9253c650b 100644 --- a/docs/attributes-registry/README.md +++ b/docs/attributes-registry/README.md @@ -55,6 +55,7 @@ Currently, the following namespaces exist: - [File](file.md) - [GCP](gcp.md) - [Gen AI](gen-ai.md) +- [Go](go.md) - [GraphQL](graphql.md) - [Heroku](heroku.md) - [Host](host.md) diff --git a/docs/attributes-registry/go.md b/docs/attributes-registry/go.md new file mode 100644 index 0000000000..c234a55424 --- /dev/null +++ b/docs/attributes-registry/go.md @@ -0,0 +1,22 @@ + + + + + +# Go + +## Go Attributes + +This document defines Go related attributes. + +| Attribute | Type | Description | Examples | Stability | +| ---------------- | ------ | ------------------- | ---------------- | ---------------------------------------------------------------- | +| `go.memory.type` | string | The type of memory. | `stack`; `other` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`go.memory.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| 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) | +| `other` | Memory used by the Go runtime, excluding other categories of memory usage. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/model/metrics/go-metrics.yaml b/model/metrics/go-metrics.yaml index 74424f0b6d..e2edba5161 100644 --- a/model/metrics/go-metrics.yaml +++ b/model/metrics/go-metrics.yaml @@ -9,24 +9,8 @@ groups: prefix: go.memory unit: "By" attributes: - - id: type - stability: experimental - type: - allow_custom_values: false - members: - - 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' - brief: 'Memory used by the Go runtime, excluding other categories of memory usage.' - stability: experimental + - ref: go.memory.type requirement_level: recommended - brief: The type of memory. - examples: ["other", "stack"] stability: experimental - id: metric.go.memory.released diff --git a/model/registry/go.yaml b/model/registry/go.yaml new file mode 100644 index 0000000000..73170efb32 --- /dev/null +++ b/model/registry/go.yaml @@ -0,0 +1,25 @@ +groups: + - id: registry.go + type: attribute_group + prefix: go + brief: > + This document defines Go related attributes. + attributes: + - id: memory.type + stability: experimental + type: + allow_custom_values: false + members: + - 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' + brief: 'Memory used by the Go runtime, excluding other categories of memory usage.' + stability: experimental + requirement_level: recommended + brief: The type of memory. + examples: ["other", "stack"] From 7a4fb6dfefbd6693f83067acea5278c775e2b716 Mon Sep 17 00:00:00 2001 From: David Ashpole Date: Wed, 8 May 2024 14:02:57 +0000 Subject: [PATCH 12/19] remove go.memory.released --- docs/runtime/go-metrics.md | 16 ---------------- model/metrics/go-metrics.yaml | 10 ---------- 2 files changed, 26 deletions(-) diff --git a/docs/runtime/go-metrics.md b/docs/runtime/go-metrics.md index 914f504d82..eb3b7afaf4 100644 --- a/docs/runtime/go-metrics.md +++ b/docs/runtime/go-metrics.md @@ -15,7 +15,6 @@ These metrics are obtained from Go's [`runtime/metrics`][RuntimeMetrics] package - [Go Memory](#go-memory) - [Metric: `go.memory.used`](#metric-gomemoryused) - - [Metric: `go.memory.released`](#metric-gomemoryreleased) - [Metric: `go.memory.limit`](#metric-gomemorylimit) - [Metric: `go.memory.allocated`](#metric-gomemoryallocated) - [Metric: `go.memory.allocations`](#metric-gomemoryallocations) @@ -61,21 +60,6 @@ This metric is [recommended][MetricRecommended]. | `other` | Memory used by the Go runtime, excluding other categories of memory usage. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -### Metric: `go.memory.released` - -This metric is [recommended][MetricRecommended]. - - -| 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. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - -**[1]:** Computed from `/memory/classes/heap/released:bytes`. - - - - - ### Metric: `go.memory.limit` This metric is [recommended][MetricRecommended]. diff --git a/model/metrics/go-metrics.yaml b/model/metrics/go-metrics.yaml index e2edba5161..d423cf898c 100644 --- a/model/metrics/go-metrics.yaml +++ b/model/metrics/go-metrics.yaml @@ -13,16 +13,6 @@ groups: requirement_level: recommended stability: experimental - - id: metric.go.memory.released - 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 - - id: metric.go.memory.limit type: metric metric_name: go.memory.limit From 09aeb7786ba244ccee1ee876c4d55d27756381ce Mon Sep 17 00:00:00 2001 From: David Ashpole Date: Wed, 8 May 2024 23:47:12 +0000 Subject: [PATCH 13/19] rename go.thread.limit to go.processor.limit --- docs/runtime/go-metrics.md | 26 +++++++++++++------------- model/metrics/go-metrics.yaml | 10 +++++----- 2 files changed, 18 insertions(+), 18 deletions(-) diff --git a/docs/runtime/go-metrics.md b/docs/runtime/go-metrics.md index eb3b7afaf4..b32e6c91e1 100644 --- a/docs/runtime/go-metrics.md +++ b/docs/runtime/go-metrics.md @@ -15,15 +15,15 @@ These metrics are obtained from Go's [`runtime/metrics`][RuntimeMetrics] package - [Go Memory](#go-memory) - [Metric: `go.memory.used`](#metric-gomemoryused) - - [Metric: `go.memory.limit`](#metric-gomemorylimit) + - [Metric: `go.memory.soft_limit`](#metric-gomemorysoftlimit) - [Metric: `go.memory.allocated`](#metric-gomemoryallocated) - [Metric: `go.memory.allocations`](#metric-gomemoryallocations) - [Go Garbage Collection](#go-garbage-collection) - [Metric: `go.memory.gc.goal`](#metric-gomemorygcgoal) - [Go Goroutines](#go-goroutines) - [Metric: `go.goroutine.count`](#metric-gogoroutinecount) -- [Go Threads](#go-threads) - - [Metric: `go.thread.limit`](#metric-gothreadlimit) +- [Go Process](#go-process) + - [Metric: `go.processor.limit`](#metric-goprocessorlimit) - [Go Scheduler](#go-scheduler) - [Metric: `go.schedule.duration`](#metric-goscheduleduration) - [Go Runtime Configuration](#go-runtime-configuration) @@ -60,19 +60,19 @@ This metric is [recommended][MetricRecommended]. | `other` | Memory used by the Go runtime, excluding other categories of memory usage. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -### Metric: `go.memory.limit` +### Metric: `go.memory.soft_limit` This metric is [recommended][MetricRecommended]. - + | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `go.memory.limit` | UpDownCounter | `By` | Go runtime memory limit configured by the user, if a limit exists. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `go.memory.soft_limit` | UpDownCounter | `By` | Go runtime memory limit configured by the user, if a limit exists. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** Computed from `/gc/gomemlimit:bytes`. This metric is excluded if the limit obtained from the Go runtime is math.MaxInt64. - + ### Metric: `go.memory.allocated` @@ -143,23 +143,23 @@ This metric is [recommended][MetricRecommended]. -## Go Threads +## Go Processor -**Description:** Go metrics captured under the namespace `go.thread.*` +**Description:** Go metrics captured under the namespace `go.processor.*` -### Metric: `go.thread.limit` +### Metric: `go.processor.limit` This metric is [recommended][MetricRecommended]. - + | 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. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `go.processor.limit` | UpDownCounter | `{processor}` | 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`. - + ## Go Scheduler diff --git a/model/metrics/go-metrics.yaml b/model/metrics/go-metrics.yaml index d423cf898c..4d4ec925d5 100644 --- a/model/metrics/go-metrics.yaml +++ b/model/metrics/go-metrics.yaml @@ -13,9 +13,9 @@ groups: requirement_level: recommended stability: experimental - - id: metric.go.memory.limit + - id: metric.go.memory.soft_limit type: metric - metric_name: go.memory.limit + metric_name: go.memory.soft_limit brief: "Go runtime memory limit configured by the user, if a limit exists." note: > Computed from `/gc/gomemlimit:bytes`. @@ -64,14 +64,14 @@ groups: unit: "{goroutine}" stability: experimental - - id: metric.go.thread.limit + - id: metric.go.processor.limit type: metric - metric_name: go.thread.limit + metric_name: go.processor.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}" + unit: "{processor}" stability: experimental - id: metric.go.schedule.duration From 998b8ced138864a20d64939ad5f1ffc908681dcb Mon Sep 17 00:00:00 2001 From: David Ashpole Date: Wed, 8 May 2024 23:53:49 +0000 Subject: [PATCH 14/19] document that histogram bucket boundaries are determined by the runtime --- docs/runtime/go-metrics.md | 2 +- model/metrics/go-metrics.yaml | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/runtime/go-metrics.md b/docs/runtime/go-metrics.md index b32e6c91e1..baabf1cee4 100644 --- a/docs/runtime/go-metrics.md +++ b/docs/runtime/go-metrics.md @@ -175,7 +175,7 @@ This metric is [recommended][MetricRecommended]. | -------- | --------------- | ----------- | -------------- | --------- | | `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`. +**[1]:** Computed from `/sched/latencies:seconds`. Bucket boundaries are provided by the runtime, and are subject to change. diff --git a/model/metrics/go-metrics.yaml b/model/metrics/go-metrics.yaml index 4d4ec925d5..b60b8b9c0c 100644 --- a/model/metrics/go-metrics.yaml +++ b/model/metrics/go-metrics.yaml @@ -80,6 +80,7 @@ groups: brief: "The time goroutines have spent in the scheduler in a runnable state before actually running." note: > Computed from `/sched/latencies:seconds`. + Bucket boundaries are provided by the runtime, and are subject to change. instrument: histogram unit: "s" stability: experimental From 65fca8d4a2aaa21fbe4cf97602ba97c21e9f1055 Mon Sep 17 00:00:00 2001 From: David Ashpole Date: Thu, 9 May 2024 00:10:57 +0000 Subject: [PATCH 15/19] toc --- docs/runtime/go-metrics.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/runtime/go-metrics.md b/docs/runtime/go-metrics.md index baabf1cee4..5e827bd20e 100644 --- a/docs/runtime/go-metrics.md +++ b/docs/runtime/go-metrics.md @@ -15,14 +15,14 @@ These metrics are obtained from Go's [`runtime/metrics`][RuntimeMetrics] package - [Go Memory](#go-memory) - [Metric: `go.memory.used`](#metric-gomemoryused) - - [Metric: `go.memory.soft_limit`](#metric-gomemorysoftlimit) + - [Metric: `go.memory.soft_limit`](#metric-gomemorysoft_limit) - [Metric: `go.memory.allocated`](#metric-gomemoryallocated) - [Metric: `go.memory.allocations`](#metric-gomemoryallocations) - [Go Garbage Collection](#go-garbage-collection) - [Metric: `go.memory.gc.goal`](#metric-gomemorygcgoal) - [Go Goroutines](#go-goroutines) - [Metric: `go.goroutine.count`](#metric-gogoroutinecount) -- [Go Process](#go-process) +- [Go Processor](#go-processor) - [Metric: `go.processor.limit`](#metric-goprocessorlimit) - [Go Scheduler](#go-scheduler) - [Metric: `go.schedule.duration`](#metric-goscheduleduration) From 7ecfa39b6b432e3019319b87b7d0eb0b73d0dc2a Mon Sep 17 00:00:00 2001 From: David Ashpole Date: Mon, 13 May 2024 20:31:35 +0000 Subject: [PATCH 16/19] change the unit for go.processor.limit to {thread} --- docs/runtime/go-metrics.md | 2 +- model/metrics/go-metrics.yaml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/runtime/go-metrics.md b/docs/runtime/go-metrics.md index 5e827bd20e..6bc219621c 100644 --- a/docs/runtime/go-metrics.md +++ b/docs/runtime/go-metrics.md @@ -154,7 +154,7 @@ This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `go.processor.limit` | UpDownCounter | `{processor}` | The number of OS threads that can execute user-level Go code simultaneously. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `go.processor.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`. diff --git a/model/metrics/go-metrics.yaml b/model/metrics/go-metrics.yaml index b60b8b9c0c..b142cb053e 100644 --- a/model/metrics/go-metrics.yaml +++ b/model/metrics/go-metrics.yaml @@ -71,7 +71,7 @@ groups: note: > Computed from `/sched/gomaxprocs:threads`. instrument: updowncounter - unit: "{processor}" + unit: "{thread}" stability: experimental - id: metric.go.schedule.duration From d1ad50f4e671866841ba8e514f77febf68a6c9b0 Mon Sep 17 00:00:00 2001 From: David Ashpole Date: Wed, 15 May 2024 13:57:48 +0000 Subject: [PATCH 17/19] rename go.memory.soft_limit to go.memory.limit --- docs/runtime/go-metrics.md | 10 +++++----- model/metrics/go-metrics.yaml | 4 ++-- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/runtime/go-metrics.md b/docs/runtime/go-metrics.md index 6bc219621c..b541378e7c 100644 --- a/docs/runtime/go-metrics.md +++ b/docs/runtime/go-metrics.md @@ -15,7 +15,7 @@ These metrics are obtained from Go's [`runtime/metrics`][RuntimeMetrics] package - [Go Memory](#go-memory) - [Metric: `go.memory.used`](#metric-gomemoryused) - - [Metric: `go.memory.soft_limit`](#metric-gomemorysoft_limit) + - [Metric: `go.memory.limit`](#metric-gomemorylimit) - [Metric: `go.memory.allocated`](#metric-gomemoryallocated) - [Metric: `go.memory.allocations`](#metric-gomemoryallocations) - [Go Garbage Collection](#go-garbage-collection) @@ -60,19 +60,19 @@ This metric is [recommended][MetricRecommended]. | `other` | Memory used by the Go runtime, excluding other categories of memory usage. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -### Metric: `go.memory.soft_limit` +### Metric: `go.memory.limit` This metric is [recommended][MetricRecommended]. - + | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | -| `go.memory.soft_limit` | UpDownCounter | `By` | Go runtime memory limit configured by the user, if a limit exists. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `go.memory.limit` | UpDownCounter | `By` | Go runtime memory limit configured by the user, if a limit exists. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** Computed from `/gc/gomemlimit:bytes`. This metric is excluded if the limit obtained from the Go runtime is math.MaxInt64. - + ### Metric: `go.memory.allocated` diff --git a/model/metrics/go-metrics.yaml b/model/metrics/go-metrics.yaml index b142cb053e..8b7c14c79a 100644 --- a/model/metrics/go-metrics.yaml +++ b/model/metrics/go-metrics.yaml @@ -13,9 +13,9 @@ groups: requirement_level: recommended stability: experimental - - id: metric.go.memory.soft_limit + - id: metric.go.memory.limit type: metric - metric_name: go.memory.soft_limit + metric_name: go.memory.limit brief: "Go runtime memory limit configured by the user, if a limit exists." note: > Computed from `/gc/gomemlimit:bytes`. From c456bb3aec3bccc8357f642bad4785d60f56b0c8 Mon Sep 17 00:00:00 2001 From: David Ashpole Date: Wed, 15 May 2024 14:11:42 +0000 Subject: [PATCH 18/19] changes after rebase --- docs/attributes-registry/go.md | 12 +- docs/runtime/go-metrics.md | 215 ++++++++++++++++++++++++++++++++- 2 files changed, 221 insertions(+), 6 deletions(-) diff --git a/docs/attributes-registry/go.md b/docs/attributes-registry/go.md index c234a55424..9ecf0831e7 100644 --- a/docs/attributes-registry/go.md +++ b/docs/attributes-registry/go.md @@ -12,11 +12,13 @@ This document defines Go related attributes. | Attribute | Type | Description | Examples | Stability | | ---------------- | ------ | ------------------- | ---------------- | ---------------------------------------------------------------- | -| `go.memory.type` | string | The type of memory. | `stack`; `other` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `go.memory.type` | string | The type of memory. | `other`; `stack` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | `go.memory.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. -| 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) | -| `other` | Memory used by the Go runtime, excluding other categories of memory usage. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| Value | Description | Stability | +| ------- | ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | +| `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`. diff --git a/docs/runtime/go-metrics.md b/docs/runtime/go-metrics.md index b541378e7c..68f1f3ac4f 100644 --- a/docs/runtime/go-metrics.md +++ b/docs/runtime/go-metrics.md @@ -40,14 +40,33 @@ These metrics are obtained from Go's [`runtime/metrics`][RuntimeMetrics] package This metric is [recommended][MetricRecommended]. + + + + + + | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | | `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)`. + + + + + + + + + + + + | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`go.memory.type`](/docs/attributes-registry/go.md) | string | The type of memory. | `other`; `stack` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -56,8 +75,18 @@ This metric is [recommended][MetricRecommended]. | 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`. + + + + + + + + ### Metric: `go.memory.limit` @@ -65,14 +94,37 @@ This metric is [recommended][MetricRecommended]. This metric is [recommended][MetricRecommended]. + + + + + + | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | | `go.memory.limit` | UpDownCounter | `By` | Go runtime memory limit configured by the user, if a limit exists. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + **[1]:** Computed from `/gc/gomemlimit:bytes`. This metric is excluded if the limit obtained from the Go runtime is math.MaxInt64. + + + + + + + + + + + + + + + + ### Metric: `go.memory.allocated` @@ -80,14 +132,37 @@ This metric is [recommended][MetricRecommended]. This metric is [recommended][MetricRecommended]. + + + + + + | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | | `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`. + + + + + + + + + + + + + + + + ### Metric: `go.memory.allocations` @@ -95,14 +170,37 @@ This metric is [recommended][MetricRecommended]. This metric is [recommended][MetricRecommended]. + + + + + + | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | | `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`. + + + + + + + + + + + + + + + + ## Go Garbage Collection @@ -114,14 +212,37 @@ This metric is [recommended][MetricRecommended]. This metric is [recommended][MetricRecommended]. + + + + + + | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | | `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`. + + + + + + + + + + + + + + + + ## Go Goroutines @@ -133,14 +254,37 @@ This metric is [recommended][MetricRecommended]. This metric is [recommended][MetricRecommended]. + + + + + + | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | | `go.goroutine.count` | UpDownCounter | `{goroutine}` | Count of live goroutines. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + **[1]:** Computed from `/sched/goroutines:goroutines`. + + + + + + + + + + + + + + + + ## Go Processor @@ -152,14 +296,37 @@ This metric is [recommended][MetricRecommended]. This metric is [recommended][MetricRecommended]. + + + + + + | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | | `go.processor.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`. + + + + + + + + + + + + + + + + ## Go Scheduler @@ -171,14 +338,37 @@ This metric is [recommended][MetricRecommended]. This metric is [recommended][MetricRecommended]. + + + + + + | 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. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + **[1]:** Computed from `/sched/latencies:seconds`. Bucket boundaries are provided by the runtime, and are subject to change. + + + + + + + + + + + + + + + + ## Go Runtime Configuration @@ -190,14 +380,37 @@ This metric is [recommended][MetricRecommended]. This metric is [recommended][MetricRecommended]. + + + + + + | Name | Instrument Type | Unit (UCUM) | Description | Stability | | -------- | --------------- | ----------- | -------------- | --------- | | `go.config.gogc` | UpDownCounter | `%` | Heap size target percentage configured by the user, otherwise 100. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + **[1]:** The value range is [0.0,100.0]. Computed from `/gc/gogc:percent`. + + + + + + + + + + + + + + + + [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md From eed3414fcb9f9de88f413d8a813cb4c451fc41b9 Mon Sep 17 00:00:00 2001 From: David Ashpole Date: Tue, 21 May 2024 14:30:46 +0000 Subject: [PATCH 19/19] address feedback --- docs/attributes-registry/go.md | 2 +- docs/runtime/go-metrics.md | 2 +- model/registry/go.yaml | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/attributes-registry/go.md b/docs/attributes-registry/go.md index 9ecf0831e7..5c47c1a4cd 100644 --- a/docs/attributes-registry/go.md +++ b/docs/attributes-registry/go.md @@ -19,6 +19,6 @@ This document defines Go related attributes. | Value | Description | Stability | | ------- | ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | | `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) | +| `other` | Memory used by the Go runtime, excluding other categories of memory usage described in this enumeration. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** Computed from `/memory/classes/heap/stacks:bytes`. diff --git a/docs/runtime/go-metrics.md b/docs/runtime/go-metrics.md index 68f1f3ac4f..5641dc40a9 100644 --- a/docs/runtime/go-metrics.md +++ b/docs/runtime/go-metrics.md @@ -76,7 +76,7 @@ This metric is [recommended][MetricRecommended]. | Value | Description | Stability | |---|---|---| | `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) | +| `other` | Memory used by the Go runtime, excluding other categories of memory usage described in this enumeration. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** Computed from `/memory/classes/heap/stacks:bytes`. diff --git a/model/registry/go.yaml b/model/registry/go.yaml index 73170efb32..d599102301 100644 --- a/model/registry/go.yaml +++ b/model/registry/go.yaml @@ -18,7 +18,7 @@ groups: stability: experimental - id: other value: 'other' - brief: 'Memory used by the Go runtime, excluding other categories of memory usage.' + brief: 'Memory used by the Go runtime, excluding other categories of memory usage described in this enumeration.' stability: experimental requirement_level: recommended brief: The type of memory.