Modify Exporter format variables for 1.0 (allowing further specification post 1.0) #1358

jsuereth · 2021-01-20T17:42:03Z

Changes

Reserve ZIPKIN format environment variable for post 1.0 implementation.
Update specification to keep OTLP protocol + ZIPKIN protocol story consistent for 1.0 (request from @bogdandrutu, note: seeing this, I'm not sure I agree, looking for feedback)

Related issues #1336

iNikem · 2021-01-20T19:14:37Z

Can we define environment variables for protocols (both OTLP and Zipkin) together with possible values for those variables, but NOT require SDKs to implement ALL of them before 1.0?

specification/protocol/exporter.md

jsuereth · 2021-01-21T18:55:59Z

Can we define environment variables for protocols (both OTLP and Zipkin) together with possible values for those variables, but NOT require SDKs to implement ALL of them before 1.0?

@iNikem I think for OTLP yes. For Zipkin, there was some concern over what things meant. I think it'd be fine to open a PR following this one where that can be discussed, but the idea is to allow it to be specified after the 1.0 next week, in the event the discussion doesn't finish in time for 1.0.

specification/protocol/exporter.md

andrewhsu · 2021-01-25T17:31:58Z

@jsuereth is this PR ready for review?

jsuereth · 2021-01-25T17:38:07Z

@jsuereth is this PR ready for review?

yes! Sorry, didn't mean to leave WIP on it for that long.

iNikem · 2021-01-26T08:21:38Z

I am concerned that if SIGs can choose their own default protocols then, after we update the spec, SIGs will have to change their defaults, which will be a breaking change. What am I missing?

jsuereth · 2021-01-26T13:02:52Z

@!iNIkem we're not going to specify the default. If you want to force a protocol, you'll need to use the variable or configuration.

anuraaga · 2021-01-26T13:12:20Z

specification/protocol/exporter.md

+- `OTEL_EXPORTER_OTLP_TRACE_PROTOCOL`
+- `OTEL_EXPORTER_OTLP_METRIC_PROTOCOL`
+
+SDKs are free to choose a default, if no configuration is provided.


@jsuereth the issue seems to be this. If sdks can pick a default, they can end up with different defaults. The intent of the spec has generally been to have shared behavior outside of api idioms. For something completely contained in the SDK it could still be ok, but protocol leaks out. For example, if given an app written in lang1 and another in lang2, we would expect both to connect to the same collector with default settings. But if the collector only enables proto, and lang2 only supports json, the behavior of the defaults changes drastically.

No snark intended, if even JS, the most json-oriented language around, can support gRPC, I'm hoping we could converge on it being a required default to prevent surprises. Having no default, rather than an SDK-specific default, therefore requiring explicit user configuration seems fine though.

I agree that this isn't an ideal situation. This is called "limiting what we do for 1.0, and providing a stable release". We'll improve over time. When we're ready to make a breaking change (and understand this problem better) we could specify a default.

The proposal here is to unblock 1.0 and allow something better to come later.

To be clear: the plan is to improve this done by the time we do a 'full' release along with stable Metrics (or maybe even sooner). Hopefully we will triage the remaining bits accordingly ;)

@jsuereth if we say that SDK should not have a default and require this? It will be annoying for the users while we fix this, but this will make us fix it sooner than later and we have all the freedom?

I suggest calling this an "unspecified default".

@bogdandrutu Yes. Right now we don't know what protocols are supported across languages well enough to specifiy a default without severely risking the 1.0 release.

The idea here is we write down what we have, making room for later fixes. We will NOT break users, so yes this limits how we operate, and when a change to this specification could occur. The idea is: Ship a stable 1.0 and iterate on improvements instead of continually delaying.

I just want to make sure it's clear that I don't really like this solution, but this is the kind of thing we'll need to get used to if we want to offer compatibility + stability guarantees, with timely releases. We can't have a 1.0 release anytime soon AND fix this issue, so let's just give ourselves enough room to do something better for users in the future. I think it's impossible for us to have found every possible usability bug of this sort prior to 1.0. Hoping this will set a precedent for what we do with issues like this post-1.0 in the land of "keep things stable AND improve".

@jmacd +1 to that suggestion, added.

Ping @bogdandrutu

Ok, hopefully everyone understands this way :) Right now it is required for user to specify the values and SDK will not work without a value specified :) otherwise they actually define a default.

andrewhsu · 2021-01-26T16:36:03Z

discussed at the sig mtg today, and it is desired to have a resolution merged for GA so applying labels to this PR

carlosalberto · 2021-01-28T17:01:14Z

@open-telemetry/specs-approvers Please review/approve this PR ;)

jmacd · 2021-01-28T18:16:22Z

specification/protocol/exporter.md

+- `OTEL_EXPORTER_OTLP_TRACE_PROTOCOL`
+- `OTEL_EXPORTER_OTLP_METRIC_PROTOCOL`
+
+SDKs are free to choose a default, if no configuration is provided.


I suggest calling this an "unspecified default".

carlosalberto · 2021-01-29T12:57:13Z

@open-telemetry/specs-approvers Please review (or approve) this one ;)

anuraaga · 2021-01-29T13:12:40Z

While I understand the pressure to release something, I still feel like this is brushing under the rug too much. We've identified a point that could create compatibility problems - if we ignore it, we'll have even more to deal with than the issues we didn't think about in advance which are definitely going to appear!

Rather than converging on an ambiguous spec, no spec should be better right? These options come to mind

Don't mark environment variables as stable for the 1.0 release. These are the last thing anyone implements - the fact that we find issues late in the game for them is understandable, and just reflects low baking time. Other features are better baked and could go out first. Languages add disclaimers in LOUD WORDS that the variables may change until a future date.
Don't mark environment variables stable ever. From what I've seen people really get unhappy when a breaking change forces them to fix their code and rebuild it again. But breaking changes in environment variables do not have this aspect, if a change was needed a rebuild is never required. Never committing to env vars on breaking changes means even if languages have different defaults now, they could converge in the future. I think this lack of stability needs to be more clearly called out than just an unspecified default, and could apply generally, not just this particular change.

And btw if the intent of this change is along these lines, than I think it's not explicit enough - it should make clear what we want the languages to commit to in terms of messaging about their stability guarantees.

iNikem · 2021-01-29T13:40:45Z

I have nothing to say about @anuraaga concerns, but I disagree with your options :) I think we have to declare env variable stable.

anuraaga · 2021-01-29T14:32:10Z

I think we have to declare env variable stable.

Do you think this means prioritizing stabilizing them over consistency among languages which is questionable with unspecified defaults? If we're good with it then that's fine too (it's been so hard to get divergence among languages of API concerns didn't think env vars would be so easy ;)

iNikem · 2021-01-29T15:10:23Z

I think we have to declare env variable stable.

Do you think this means prioritizing stabilizing them over consistency among languages which is questionable with unspecified defaults? If we're good with it then that's fine too (it's been so hard to get divergence among languages of API concerns didn't think env vars would be so easy ;)

Yes, I think stable 1.0 which includes env variables is more important that consistency of unspecified behaviour across languages :)

bogdandrutu · 2021-01-29T18:14:24Z

@jsuereth please rebase

- Ensure environment variables have consistent names - Update documentation to leave format UNSPECIFIED in 1.0 with an allowance to add config later.

Co-authored-by: Anuraag Agrawal <[email protected]>

Co-authored-by: Bartlomiej Obecny <[email protected]>

jsuereth · 2021-01-29T21:31:18Z

Languages add disclaimers in LOUD WORDS that the variables may change until a future date.

This is only as effective as users reading the docs. In my experience, users will ignore all "warnings" if they have a strong need for something and then be upset with you when you break it. We only have so much friction we can cause and this doesn't seem like a good use of social capital.

Don't mark environment variables stable ever. From what I've seen people really get unhappy when a breaking change forces them to fix their code and rebuild it again. But breaking changes in environment variables do not have this aspect, if a change was needed a rebuild is never required. Never committing to env vars on breaking changes means even if languages have different defaults now, they could converge in the future. I think this lack of stability needs to be more clearly called out than just an unspecified default, and could apply generally, not just this particular change.

This hasn't been my experience. Also, I don't think anything is locked down such that it can't be slowly evolved/migrated. We should be avoiding unnecessary churn (e.g. ENV variable renames) post 1.0 because it just causes friction and unrest for users. If we really want this project to be stable and widely adopted, then we need to make sure users are succesful and not surprised. Changing environment variables is probably one of the MOST surprising things, especially if you switch from something on-default to something default.

And btw if the intent of this change is along these lines, than I think it's not explicit enough - it should make clear what we want the languages to commit to in terms of messaging about their stability guarantees

Suggestions welcome. The intent here was to specify a minimum (what we felt was already common) so SDKs won't diverge past that minimum, but not spin cycles gaining consensus on the full specification.

Regarding whether ENVIRONMENT variables are considered in Semantic Conventions + versioning, I think that belongs in a different PR than this, but I'm happy to take a stab at it.

jsuereth · 2021-01-29T21:31:37Z

@bogdandrutu it's rebased now.

carlosalberto · 2021-02-02T15:48:34Z

We have enough approvals. Let's merge this by the end of the day 😃

arminru

Please add an entry to CHANGELOG.md. Thanks!

codeboten · 2021-02-02T17:04:43Z

specification/protocol/exporter.md

+the future:
+
+- `OTEL_EXPORTER_OTLP_PROTOCOL`
+- `OTEL_EXPORTER_OTLP_TRACE_PROTOCOL`


Should this be OTEL_EXPORTER_OTLP_TRACES_PROTOCOL?

Yes please :)

carlosalberto · 2021-02-03T15:23:25Z

Merging to expedite things. Will cook a follow-up PR myself.

…ion post 1.0) (open-telemetry#1358) * OAdapt open-telemetry#1340 for 1.0 of Trace. - Ensure environment variables have consistent names - Update documentation to leave format UNSPECIFIED in 1.0 with an allowance to add config later.

jsuereth requested review from a team January 20, 2021 17:42

github-actions bot assigned bogdandrutu Jan 20, 2021

anuraaga reviewed Jan 21, 2021

View reviewed changes

specification/protocol/exporter.md Outdated Show resolved Hide resolved

obecny reviewed Jan 25, 2021

View reviewed changes

specification/protocol/exporter.md Outdated Show resolved Hide resolved

jsuereth changed the title ~~Wip exporter format variables~~ Modify Exporter format variables for 1.0 (allowing further specification post 1.0) Jan 25, 2021

carlosalberto approved these changes Jan 25, 2021

View reviewed changes

anuraaga reviewed Jan 26, 2021

View reviewed changes

andrewhsu added priority:p1 Highest priority level release:required-for-ga Must be resolved before GA release, or nice to have before GA labels Jan 26, 2021

Base automatically changed from master to main January 27, 2021 21:16

jmacd approved these changes Jan 28, 2021

View reviewed changes

jsuereth force-pushed the wip-exporter-format-variables branch from cbc9d63 to eba50fd Compare January 28, 2021 20:39

jsuereth and others added 3 commits January 29, 2021 16:21

OAdapt open-telemetry#1340 for 1.0 of Trace.

6a30cf2

- Ensure environment variables have consistent names - Update documentation to leave format UNSPECIFIED in 1.0 with an allowance to add config later.

Fix formatting.

c664bf4

Update specification/protocol/exporter.md

2fbe2a2

Co-authored-by: Anuraag Agrawal <[email protected]>

jsuereth and others added 2 commits January 29, 2021 16:21

Update specification/protocol/exporter.md

67d9ecb

Co-authored-by: Bartlomiej Obecny <[email protected]>

Fixes from review.

c17e324

jsuereth force-pushed the wip-exporter-format-variables branch from eba50fd to c17e324 Compare January 29, 2021 21:22

anuraaga approved these changes Jan 30, 2021

View reviewed changes

bogdandrutu approved these changes Feb 1, 2021

View reviewed changes

Merge branch 'main' into wip-exporter-format-variables

9ad2534

tigrannajaryan approved these changes Feb 1, 2021

View reviewed changes

cijothomas approved these changes Feb 2, 2021

View reviewed changes

codeboten approved these changes Feb 2, 2021

View reviewed changes

arminru reviewed Feb 2, 2021

View reviewed changes

codeboten reviewed Feb 2, 2021

View reviewed changes

Merge branch 'main' into wip-exporter-format-variables

95fba09

carlosalberto merged commit 61811e1 into open-telemetry:main Feb 3, 2021

carlosalberto mentioned this pull request Feb 3, 2021

Update CHANGELOG and OTLP env vars with the latest names. #1398

Merged

srikanthccv mentioned this pull request Feb 22, 2021

Add OTEL_EXPORTER_ZIPKIN_TRANSPORT_FORMAT to sdk-environment-variables #1340

Closed

MrAlias mentioned this pull request Mar 29, 2021

Update OTLP exporter configuration to conform to the specification open-telemetry/opentelemetry-go#1085

Closed

3 tasks

jsuereth deleted the wip-exporter-format-variables branch April 17, 2021 15:49

jack-berg mentioned this pull request Sep 3, 2021

Add OTLP protocol configuration options #1880

Merged

brettsam mentioned this pull request Mar 15, 2023

adding FunctionActivitySource to Worker; refactoring AppInsights support Azure/azure-functions-dotnet-worker#1307

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Modify Exporter format variables for 1.0 (allowing further specification post 1.0) #1358

Modify Exporter format variables for 1.0 (allowing further specification post 1.0) #1358

jsuereth commented Jan 20, 2021

iNikem commented Jan 20, 2021

jsuereth commented Jan 21, 2021

andrewhsu commented Jan 25, 2021

jsuereth commented Jan 25, 2021

iNikem commented Jan 26, 2021

jsuereth commented Jan 26, 2021

anuraaga Jan 26, 2021

jsuereth Jan 26, 2021

carlosalberto Jan 26, 2021

bogdandrutu Jan 26, 2021

jmacd Jan 28, 2021

jsuereth Jan 28, 2021

carlosalberto Jan 29, 2021

bogdandrutu Jan 29, 2021

andrewhsu commented Jan 26, 2021

carlosalberto commented Jan 28, 2021

jmacd Jan 28, 2021

carlosalberto commented Jan 29, 2021

anuraaga commented Jan 29, 2021

iNikem commented Jan 29, 2021

anuraaga commented Jan 29, 2021

iNikem commented Jan 29, 2021

bogdandrutu commented Jan 29, 2021

jsuereth commented Jan 29, 2021

jsuereth commented Jan 29, 2021

carlosalberto commented Feb 2, 2021

arminru left a comment

codeboten Feb 2, 2021

bogdandrutu Feb 2, 2021

carlosalberto commented Feb 3, 2021

Modify Exporter format variables for 1.0 (allowing further specification post 1.0) #1358

Modify Exporter format variables for 1.0 (allowing further specification post 1.0) #1358

Conversation

jsuereth commented Jan 20, 2021

Changes

iNikem commented Jan 20, 2021

jsuereth commented Jan 21, 2021

andrewhsu commented Jan 25, 2021

jsuereth commented Jan 25, 2021

iNikem commented Jan 26, 2021

jsuereth commented Jan 26, 2021

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

andrewhsu commented Jan 26, 2021

carlosalberto commented Jan 28, 2021

Choose a reason for hiding this comment

carlosalberto commented Jan 29, 2021

anuraaga commented Jan 29, 2021

iNikem commented Jan 29, 2021

anuraaga commented Jan 29, 2021

iNikem commented Jan 29, 2021

bogdandrutu commented Jan 29, 2021

jsuereth commented Jan 29, 2021

jsuereth commented Jan 29, 2021

carlosalberto commented Feb 2, 2021

arminru left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

carlosalberto commented Feb 3, 2021