go/opentelemetry-go
1
0
Fork 0
mirror of https://github.com/open-telemetry/opentelemetry-go.git synced 2026-06-03 18:35:08 +02:00
Code Issues Releases Activity

metric: clarify sync vs observable Gauge in package godoc (#8225)

Browse Source 
## Description

The "Measurements" description in the
\`go.opentelemetry.io/otel/metric\` package godoc stated that a Gauge is
used when "the most recent measurement needs to be conveyed about an
asynchronous measurement" and only listed \`Int64ObservableGauge\` and
\`Float64ObservableGauge\`. Synchronous Gauge types (\`Int64Gauge\`,
\`Float64Gauge\`) were added to the API but are not reflected in this
paragraph.

This PR updates the sentence to list all four Gauge types and briefly
note the difference (sync records an instantaneous value at a specific
point in code; observable samples via a callback once per collection
cycle).

Partially addresses #4801 (the "explain the differences between
instrument types" request) by correcting the Gauge coverage
specifically. Happy to follow up with a broader summary-by-example list
if @pellared thinks that's still valuable.

Fixes #4801.

## Checklist

- [x] CHANGELOG.md entry added (placeholder `#XXXX`, will update with
real PR number once assigned).
- [ ] Tests updated (godoc-only change, no behavior change).

---------

Signed-off-by: Ali <alliasgher123@gmail.com>
Co-authored-by: Robert Pająk <pellared@hotmail.com>
Co-authored-by: Tyler Yahn <MrAlias@users.noreply.github.com>
This commit is contained in:
Ali Asghar
2026-04-22 02:07:22 +05:00
committed by GitHub
parent 6f81801cd8
commit c5045485b4
1 changed files with 14 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files
metric/doc.go
+14 -12
View File
@@ -24,10 +24,10 @@ all instruments fall into two overlapping logical categories: asynchronous or
synchronous, and int64 or float64.
All synchronous instruments ([Int64Counter], [Int64UpDownCounter],
[Int64Histogram], [Float64Counter], [Float64UpDownCounter], and
[Float64Histogram]) are used to measure the operation and performance of source
code during the source code execution. These instruments only make measurements
when the source code they instrument is run.
[Int64Histogram], [Int64Gauge], [Float64Counter], [Float64UpDownCounter],
[Float64Histogram], and [Float64Gauge]) are used to measure the operation and
performance of source code during the source code execution. These instruments
only make measurements when the source code they instrument is run.
All asynchronous instruments ([Int64ObservableCounter],
[Int64ObservableUpDownCounter], [Int64ObservableGauge],
@@ -50,9 +50,11 @@ incrementally increase in value. UpDownCounters ([Int64UpDownCounter],
values that can increase and decrease. When more information needs to be
conveyed about all the synchronous measurements made during a collection cycle,
a Histogram ([Int64Histogram] and [Float64Histogram]) should be used. Finally,
when just the most recent measurement needs to be conveyed about an
asynchronous measurement, a Gauge ([Int64ObservableGauge] and
[Float64ObservableGauge]) should be used.
when just the most recent measurement needs to be conveyed, a Gauge
([Int64Gauge], [Float64Gauge], [Int64ObservableGauge], and
[Float64ObservableGauge]) should be used: the synchronous variants record an
instantaneous value at a specific point in code, while the observable variants
sample the value via a callback once per collection cycle.
See the [OpenTelemetry documentation] for more information about instruments
and their intended use.
@@ -80,11 +82,11 @@ Measurements are made by recording values and information about the values with
an instrument. How these measurements are recorded depends on the instrument.
Measurements for synchronous instruments ([Int64Counter], [Int64UpDownCounter],
[Int64Histogram], [Float64Counter], [Float64UpDownCounter], and
[Float64Histogram]) are recorded using the instrument methods directly. All
counter instruments have an Add method that is used to measure an increment
value, and all histogram instruments have a Record method to measure a data
point.
[Int64Histogram], [Int64Gauge], [Float64Counter], [Float64UpDownCounter],
[Float64Histogram], and [Float64Gauge]) are recorded using the instrument
methods directly. All counter instruments have an Add method that is used to
measure an increment value, and all histogram and synchronous gauge
instruments have a Record method to measure a data point.
Asynchronous instruments ([Int64ObservableCounter],
[Int64ObservableUpDownCounter], [Int64ObservableGauge],