Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document the callback registered with a Meter according to the specification #3563

Closed
MrAlias opened this issue Jan 5, 2023 · 0 comments · Fixed by #3564
Closed

Document the callback registered with a Meter according to the specification #3563

MrAlias opened this issue Jan 5, 2023 · 0 comments · Fixed by #3564
Assignees
Labels
area:metrics Part of OpenTelemetry Metrics pkg:API Related to an API package

Comments

@MrAlias
Copy link
Contributor

MrAlias commented Jan 5, 2023

The OpenTelemetry specification states:

Callback functions MUST be documented as follows for the end user:

  • Callback functions SHOULD be reentrant safe. The SDK expects to evaluate callbacks for each MetricReader independently.
  • Callback functions SHOULD NOT take an indefinite amount of time.
  • Callback functions SHOULD NOT make duplicate observations (more than one Measurement with the same attributes) across all registered callbacks.

Currently the callback passed to a Meter's RegisterCallback method is not documented as such:

// RegisterCallback registers f to be called during the collection of a
// measurement cycle.
//
// If Unregister of the returned Registration is called, f needs to be
// unregistered and not called during collection.
//
// The instruments f is registered with are the only instruments that f may
// observe values for.
//
// If no instruments are passed, f should not be registered nor called
// during collection.
RegisterCallback(instruments []instrument.Asynchronous, f func(context.Context)) (Registration, error)

Proposal

Define a Callback type in that file that takes the place of func(context.Context). Document that type with pertinent information, including the OTel required information. For example,

type Meter interface {
	// ...
	RegisterCallback(instruments []instrument.Asynchronous, f Callback) (Registration, error)
}

// Callback is a function registered with a Meter that makes observations for
// the set of instruments it is registered with.
//
// The function needs to complete in a finite amount of time and the deadline
// of the passed context is expected to be honored.
//
// The function needs to make unique observations across all registered
// callbacks. It should not report duplicate measurements for an instruments
// with the same attributes as another Callback.
//
// The function needs to be concurrent safe.
type Callback func(context.Context)
@MrAlias MrAlias added pkg:API Related to an API package area:metrics Part of OpenTelemetry Metrics labels Jan 5, 2023
@MrAlias MrAlias added this to the Metric v0.35.0 milestone Jan 5, 2023
@MrAlias MrAlias self-assigned this Jan 5, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
area:metrics Part of OpenTelemetry Metrics pkg:API Related to an API package
Projects
No open projects
Status: Done
Development

Successfully merging a pull request may close this issue.

1 participant