metric: clarify sync vs observable Gauge in package godoc#8225
Open
alliasgher wants to merge 5 commits intoopen-telemetry:mainfrom
Open
metric: clarify sync vs observable Gauge in package godoc#8225alliasgher wants to merge 5 commits intoopen-telemetry:mainfrom
alliasgher wants to merge 5 commits intoopen-telemetry:mainfrom
Conversation
alliasgher
requested review from
MrAlias,
XSAM,
dashpole,
dmathieu,
flc1125 and
pellared
as code owners
alliasgher
force-pushed
the
docs/4801-gauge-sync-async
branch
from
094f031 to
dcc2cd8
Compare
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #8225 +/- ##
=======================================
- Coverage 82.6% 82.6% -0.1%
=======================================
Files 309 309
Lines 24621 24621
=======================================
- Hits 20356 20355 -1
- Misses 3888 3889 +1
Partials 377 377 🚀 New features to boost your workflow:
|
dashpole
approved these changes
Apr 17, 2026
dashpole
reviewed
Apr 17, 2026
The Measurements description in the metric package godoc stated that a Gauge is used when "the most recent measurement needs to be conveyed about an asynchronous measurement" and only referenced Int64ObservableGauge and Float64ObservableGauge. Synchronous Gauge types (Int64Gauge, Float64Gauge) were added to the API but not reflected here. Update the sentence to list all four Gauge types and briefly note when to use a synchronous variant vs an observable one. Fixes open-telemetry#4801 Signed-off-by: Ali <alliasgher123@gmail.com>
alliasgher
force-pushed
the
docs/4801-gauge-sync-async
branch
from
dcc2cd8 to
93cbc86
Compare
dmathieu
approved these changes
Apr 17, 2026
pellared
approved these changes
Apr 20, 2026
Contributor
There was a problem hiding this comment.
Pull request overview
Updates the go.opentelemetry.io/otel/metric package godoc to correctly describe Gauge instruments now that both synchronous and observable Gauge types exist in the API.
Changes:
- Expands the Gauge sentence to list both synchronous and observable Gauge types.
- Adds a short explanation distinguishing synchronous Gauge recording from observable Gauge callback sampling.
This comment was marked as resolved.
This comment was marked as resolved.
…tions Address Copilot review feedback on the Gauge sync/async clarification: list Int64Gauge and Float64Gauge in the "All synchronous instruments" enumeration, and in the "Measurements" section note that histograms and synchronous gauges both use Record. Signed-off-by: Ali <alliasgher123@gmail.com>
pellared
approved these changes
Apr 20, 2026
dmathieu
approved these changes
Apr 21, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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
#XXXX, will update with real PR number once assigned).