Skip to content

Refactor advice API#5848

Merged
jack-berg merged 1 commit into
open-telemetry:mainfrom
jack-berg:refactor-advice-api
Oct 6, 2023
Merged

Refactor advice API#5848
jack-berg merged 1 commit into
open-telemetry:mainfrom
jack-berg:refactor-advice-api

Conversation

@jack-berg

Copy link
Copy Markdown
Member

The explicit bucket boundaries advice API is now stable: open-telemetry/opentelemetry-specification#3694

Before it stabilized, there was a change made to adjust advice from encapsulating 1 or more parameters to being a class / category of parameter. The idea was to be able to offer simplified ergonomics to users:

// From this:
meter.histogramBuilder("foo")
  .setAdvice(advice -> advice
    .setExplicitBucketBoundaries(...)
    .setAttributes(..));

// to something like this:
meter.histogramBuilder("foo")
  .setExplicitBucketBoundariesAdvice(...)
  .setAttributesAdvice(...);

Would like to try to get our explicit bucket boundary stable, but first want to explore this as an option and collect feedback.

@jack-berg
jack-berg requested a review from a team September 21, 2023 19:38
@trask

trask commented Sep 21, 2023

Copy link
Copy Markdown
Member
// From this:
meter.histogramBuilder("foo")
  .setAdvice(advice -> advice
    .setExplicitBucketBoundaries(...)
    .setAttributes(..));

// to something like this:
meter.histogramBuilder("foo")
  .setExplicitBucketBoundariesAdvice(...)
  .setAttributesAdvice(...);

the second one looks simpler, so 👍🤷‍♂️ (but no really strong feelings)

one thing that's nice about the single setAdvice() method is that it gives one place to explain the whole advice story, but since the advice story differs a bit per advice type, maybe that's not much of an advantage(?)

@jack-berg

Copy link
Copy Markdown
Member Author

Yeah I'm kind of a partial to the API proposed here. Another reason to go with separate methods is that the pattern of passing in a consumer to configure parameters may not be intuitive for every user.

@trask

trask commented Sep 26, 2023

Copy link
Copy Markdown
Member

Another reason to go with separate methods is that the pattern of passing in a consumer to configure parameters may not be intuitive for every user.

ya, I've noticed confusion about the autoconfiguration builder which uses this pattern

@jack-berg

Copy link
Copy Markdown
Member Author

@open-telemetry/java-approvers PTAL. Would like to get this in for the next release so we can stabilize the API in the following. Or, potentially stabilize in the next release with this updated API.


@Override
public DoubleCounterAdviceConfigurer setAttributes(List<AttributeKey<?>> attributes) {
public ExtendedDoubleCounterBuilder setAttributesAdvice(List<AttributeKey<?>> attributes) {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

can we return this external interface without causing trouble for people using this class without the incubator code present?

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The incubator code is always present on the classpath. Its just an implementation dependency instead of api, so users have to add it as a dependency of their own to access the extended behavior. Including the incubator as a implementation dependency is acceptable because its not part of the public API of the SDK, and it doesn't include any transitive dependencies that would make it questionable.

@jkwatson jkwatson left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Seems reasonable to me. one question about returning an interface from another, optional module.

@jack-berg
jack-berg merged commit 92abcb8 into open-telemetry:main Oct 6, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants