search

open-telemetry / opentelemetry-specification

Specifications for OpenTelemetry
https://opentelemetry.io
Apache License 2.0
3.76k stars 890 forks source link

Initial cut at laying out core principles for Specification change. #4286

Closed jsuereth closed 3 days ago

jsuereth commented 2 weeks ago

Fixes #4276

Changes

Documents the values we use when evaluating specification changes. Also sort out the specification README to clarify which components cover Principles and Values.

jsuereth commented 1 week ago

@jack-berg I think maybe your specific things can be "examples" or "faq" section. I've been thinking about this comment (and @tigrannajaryan's) for a bit, I'm going to give this an update to account for that, will notify when it's complete.

Agree we should address common concerns and show the interplay of these principles.

carlosalberto commented 1 week ago

As we have enough approvals, one option is to address the important points raised by @jack-berg as a follow up.

jsuereth commented 1 week ago

@carlosalberto That sounds like a plan, it's going to be a new section anyway. I'll address @tigrannajaryan's comments and we can follow up with @jack-berg's in a future PR

jsuereth commented 1 week ago

I don't disagree with anything in here, but wish there was some way to give more practical advice on a few topics I see coming up a lot:

  • Should we extend an interface, even when its allowed? Extending interfaces is easier in some languages than others. Ideally we get it right the first time (and we should strive for this), but in the event we don't, when does the value of extending an interface trump the friction it causes in the languages where they are hard to extend? This is related the "be stable" value, but not entirely captured.
  • Language implementation or collector. We often have proposals for use cases that could be done in the collector, but could also be done in the SDK which is advantageous to some users who don't want to use the collector (or in some cases can't). Given that spec API / SDK features need to implemented 11 times, when is it appropriate to reject a API / SDK feature proposal that can be accomplished in the collector? Doing so can help us focus on more pressing problems, and potentially simplify user story by reducing the number of ways to accomplish the same thing.
  • Plugin extension point or structured config. There’s a trade off between SDK plugin extension points (i.e. exporters, processors, samplers), and a more limited or structured approach (i.e. exemplar filters, attribute limits). SDK plugin extension points offer more flexibility but generally have more cumbersome and less standardized configuration. Reducing flexibility (or adding guardrails) can add safety and improve UX in certain domains. When do we choose one or the other? This is related to the "be simple".

It could be the case that we don't have enough experience yet to extract out useful principles on these, but these are the types of questions I see recurring.

Approving because while I think there's even more we could offer contributors, I agree with what is written here.

Opened https://github.com/open-telemetry/opentelemetry-specification/issues/4293 to address