Opentelemetry-specification: Properly communicate the stability for OTLP

[carlosalberto]

Based on feedback during the SIG call today, we need to be even more explicit about OTLP/protos still being in (relative) flux, and the fact it shouldn't be used in production systems these days. See https://github.com/open-telemetry/opentelemetry-proto#maturity-level - Also, there's the need to add Logs to this table, as either Experimental or Alpha.

Specially important as we are approaching Kubecon and we need to make things the community expectations are the proper ones ;)

cc @tigrannajaryan

[andrewhsu]

Just wanted to make this point: it'd be good to have OTLP used in production with the understanding that at this point some portions of the proto may change drastically between releases, like logs, and some portions don't have an intention of changing and have been hardened a lot more, like trace. Feedback from the user from running this in production is valuable in both cases but different expectations ought to be set for different parts of the protocol.

From the conversation that evolved from the spec sig mtg today, perhaps documentation or blog posts may help in setting this expectation.

[jsuereth]

I want to call out two things I think may send mixed signals:

1. The fact that everything is called "v1" in the proto repository: https://github.com/open-telemetry/opentelemetry-proto
   
   
   
   • While the readme in the repository outlines the expected compatibility level of the protocol, it's possible someone is consuming those protos without having to read the readme and sees the "v1" in the type.
   
   
   • I understand there are legacy reasons why this was done. I think we could take action on non-GA items within the protocol, e.g. when GA release "v1", then we should not include items that are not stable.
   
   
2. Communication around adoption of OpenTelemetry and usage of the collector.
   
   
   
   • If people find OTLP configuration in releases of the open telemetry collector, or language SDKs, they may not read the warnings that have been placed around them by the OT project itself.
   
   
   • When advertising the collector in blog posts and conference talks, we should be careful to ALWAYS denote that some components are not stable, but others are so folks know to check before assuming. Announcements on readiness and calls to try something out tend to imply a level of maturity we may not be adhering too.
   
   

[tigrannajaryan]

Added a clarification for OTLP Logs: https://github.com/open-telemetry/opentelemetry-proto/pull/228

[tigrannajaryan]

We now have stability labels in both proto repo and in this repo in the "protocol" directory. I believe this issue is resolved. If any additional communication is needed please re-open or create a new issue that describes what else is needed.