Skip to content

Commit

Permalink
cleanups
Browse files Browse the repository at this point in the history
  • Loading branch information
@dashpole
dashpole committed May 21, 2024
1 parent 79493af commit 66a9965
Show file tree
Hide file tree
Showing 2 changed files with 25 additions and 32 deletions.
35 changes: 14 additions & 21 deletions docs/runtime/go-metrics.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.

<!-- Re-generate TOC with `markdown-toc --no-first-h1 -i` -->

Expand All @@ -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)
Expand All @@ -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.

<!-- 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. [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)`.
<!-- endsemconv -->

<!-- semconv metric.go.memory.used(full) -->
| 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:

Expand All @@ -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`.
<!-- endsemconv -->

### Metric: `go.memory.released`

This metric is [recommended][MetricRecommended].
This metric is obtained from Go's [`runtime/metrics`][RuntimeMetrics] package using `/gc/gomemlimit:bytes`.

<!-- 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. [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`.
<!-- endsemconv -->

<!-- semconv metric.go.memory.released(full) -->
Expand All @@ -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`.

<!-- 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. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) |

**[1]:** Computed from /gc/gomemlimit:bytes.
**[1]:** Computed from `/gc/gomemlimit:bytes`.
<!-- endsemconv -->

<!-- semconv metric.go.memory.limit(full) -->
Expand All @@ -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`.

<!-- 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. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) |

**[1]:** Computed from /gc/heap/allocs:bytes.
**[1]:** Computed from `/gc/heap/allocs:bytes`.
<!-- endsemconv -->

<!-- semconv metric.go.memory.allocated(full) -->
Expand All @@ -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`.

<!-- 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. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) |

**[1]:** Computed from /gc/heap/allocs:objects.
**[1]:** Computed from `/gc/heap/allocs:objects`.
<!-- endsemconv -->

<!-- semconv metric.go.memory.allocations(full) -->
Expand All @@ -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`.

<!-- 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. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) |

**[1]:** Computed from /gc/heap/goal:bytes.
**[1]:** Computed from `/gc/heap/goal:bytes`.
<!-- endsemconv -->

<!-- semconv metric.go.memory.gc.goal(full) -->
Expand All @@ -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`.

<!-- semconv metric.go.memory.gc.user_goal(metric_table) -->
| 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`.
<!-- endsemconv -->

<!-- semconv metric.go.memory.gc.user_goal(full) -->
Expand All @@ -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`.

<!-- semconv metric.go.goroutine.count(metric_table) -->
| Name | Instrument Type | Unit (UCUM) | Description | Stability |
Expand All @@ -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`.

<!-- 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. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) |

**[1]:** Computed from /sched/gomaxprocs:threads.
**[1]:** Computed from `/sched/gomaxprocs:threads`.
<!-- endsemconv -->

<!-- semconv metric.go.thread.limit(full) -->
Expand All @@ -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`.

<!-- 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. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) |

**[1]:** Computed from /sched/latencies:seconds.
**[1]:** Computed from `/sched/latencies:seconds`.
<!-- endsemconv -->

<!-- semconv metric.go.schedule.duration(full) -->
Expand Down
22 changes: 11 additions & 11 deletions model/metrics/go-metrics.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand All @@ -18,23 +18,23 @@ 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'
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"]
examples: ["other", "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."
note: >
Computed from /memory/classes/heap/released:bytes.
Computed from `/memory/classes/heap/released:bytes`.
instrument: updowncounter
unit: "By"
stability: experimental
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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

0 comments on commit 66a9965

Please sign in to comment.