Specification & OTEP relationship: Provide references to implemented OTEPs

[svrnm]

What are you trying to achieve?

Please take a look at this issue by @hterik: open-telemetry/opentelemetry.io#3685, the particular issue is that it is not clear from the Spec on Span Status), what the intend of this section is. Only after going into the Git Blame View, digging up a related PR and issue, I was able to find the OTEP 136 which provides examples & background on why things are specified this way.

This is only one instance of an issue I had a few times now: while reading the spec, I missed the full picture of where things are coming from and why they are the way they are. Knowing how things work, I looked for the right OTEP to learn more. Outsiders lack this knowledge.

Therefore, what I want to suggest with this issue, is that the specification has in-place back links to the OTEPs that have been implemented by a certain section. Ideally as close as possible to the content, e.g. in the case of Span Status this shouldn't be a Reference section at the very bottom of the page, but a footnote at the title, or a line at the beginning stating that this is implementing this and that OTEP.

Many OTEPs contain a lot of valuable contextual details, so I think this would help people a lot to understand the specification better by having them accessible from the right spot in the spec.

Additional context.

So far I could identify the following places where a reference is provided:

• opentelemetry-specification/specification/schemas/README.md

  Line 78 in 3d60131

  Telemetry Schemas that were proposed and accepted in

• opentelemetry-specification/specification/metrics/README.md

  Line 104 in 3d60131

  ## References

• opentelemetry-specification/specification/logs/data-model.md

  Line 476 in 3d60131

  - Log Data Model [OTEP 0097](https://github.com/open-telemetry/oteps/blob/main/text/logs/0097-log-data-model.md)

• opentelemetry-specification/experimental/trace/zpages.md

  Line 27 in 3d60131

  The idea of "zPages" originates from one of OpenTelemetry's predecessors, [OpenCensus](https://opencensus.io/). You can read more about zPages from the OpenCensus docs [here](https://opencensus.io/zpages) or the OTEP [here](https://github.com/open-telemetry/oteps/blob/main/text/0110-z-pages.md). OpenCensus has different zPage implementations in [Java](https://opencensus.io/zpages/java/), [Go](https://opencensus.io/zpages/go/), and [Node](https://opencensus.io/zpages/node/) and there has been similar internal solutions developed at companies like Uber. Within OpenTelemetry, zPages are available in Go and Rust. The OTel Collector also has [an implementation](https://github.com/open-telemetry/opentelemetry-collector/tree/master/extension/zpagesextension) of zPages.

• opentelemetry-specification/specification/configuration/file-configuration.md

  Line 120 in 3d60131

  ## References

Tracking

• https://github.com/open-telemetry/oteps/tree/main/text/0001-telemetry-without-manual-instrumentation.md
• https://github.com/open-telemetry/oteps/tree/main/text/0005-global-init.md
• https://github.com/open-telemetry/oteps/tree/main/text/0007-no-out-of-band-reporting.md
• https://github.com/open-telemetry/oteps/tree/main/text/0016-named-tracers.md
• https://github.com/open-telemetry/oteps/tree/main/text/0035-opentelemetry-protocol.md
• https://github.com/open-telemetry/oteps/tree/main/text/0038-version-semantic-attribute.md
• https://github.com/open-telemetry/oteps/tree/main/text/0066-separate-context-propagation.md
• https://github.com/open-telemetry/oteps/tree/main/text/0083-component.md
• https://github.com/open-telemetry/oteps/tree/main/text/0099-otlp-http.md
• https://github.com/open-telemetry/oteps/tree/main/text/0110-z-pages.md
• https://github.com/open-telemetry/oteps/tree/main/text/0111-auto-resource-detection.md
• https://github.com/open-telemetry/oteps/tree/main/text/0119-standard-system-metrics.md
• https://github.com/open-telemetry/oteps/tree/main/text/0122-otlp-http-json.md
• https://github.com/open-telemetry/oteps/tree/main/text/0143-versioning-and-stability.md
• https://github.com/open-telemetry/oteps/tree/main/text/0147-upgrade-procedures.md
• https://github.com/open-telemetry/oteps/tree/main/text/0149-exponential-histogram.md
• https://github.com/open-telemetry/oteps/tree/main/text/0152-telemetry-schemas.md
• https://github.com/open-telemetry/oteps/tree/main/text/0155-external-modules.md
• https://github.com/open-telemetry/oteps/tree/main/text/experimental/0121-config-service.md
• https://github.com/open-telemetry/oteps/tree/main/text/logs/0091-logs-vocabulary.md
• https://github.com/open-telemetry/oteps/tree/main/text/logs/0092-logs-vision.md
• https://github.com/open-telemetry/oteps/tree/main/text/logs/0097-log-data-model.md
• https://github.com/open-telemetry/oteps/tree/main/text/logs/0130-logs-1.0ga-definition.md
• https://github.com/open-telemetry/oteps/tree/main/text/logs/0150-logging-library-sdk.md
• https://github.com/open-telemetry/oteps/tree/main/text/metrics/0003-measure-metric-type.md
• https://github.com/open-telemetry/oteps/tree/main/text/metrics/0008-metric-observer.md
• https://github.com/open-telemetry/oteps/tree/main/text/metrics/0009-metric-handles.md
• https://github.com/open-telemetry/oteps/tree/main/text/metrics/0010-cumulative-to-counter.md
• https://github.com/open-telemetry/oteps/tree/main/text/metrics/0049-metric-label-set.md
• https://github.com/open-telemetry/oteps/tree/main/text/metrics/0070-metric-bound-instrument.md
• https://github.com/open-telemetry/oteps/tree/main/text/metrics/0072-metric-observer.md
• https://github.com/open-telemetry/oteps/tree/main/text/metrics/0080-remove-metric-gauge.md
• https://github.com/open-telemetry/oteps/tree/main/text/metrics/0088-metric-instrument-optional-refinements.md
• https://github.com/open-telemetry/oteps/tree/main/text/metrics/0090-remove-labelset-from-metrics-api.md
• https://github.com/open-telemetry/oteps/tree/main/text/metrics/0098-metric-instruments-explained.md
• https://github.com/open-telemetry/oteps/tree/main/text/metrics/0108-naming-guidelines.md
• https://github.com/open-telemetry/oteps/tree/main/text/metrics/0113-exemplars.md
• https://github.com/open-telemetry/oteps/tree/main/text/metrics/0126-Configurable-Metric-Aggregations.md
• https://github.com/open-telemetry/oteps/tree/main/text/metrics/0131-otlp-export-behavior.md
• https://github.com/open-telemetry/oteps/tree/main/text/metrics/0146-metrics-prototype-scenarios.md
• https://github.com/open-telemetry/oteps/tree/main/text/trace/0002-remove-spandata.md
• https://github.com/open-telemetry/oteps/tree/main/text/trace/0006-sampling.md
• https://github.com/open-telemetry/oteps/tree/main/text/trace/0059-otlp-trace-data-format.md
• https://github.com/open-telemetry/oteps/tree/main/text/trace/0136-error_flagging.md
• https://github.com/open-telemetry/oteps/tree/main/text/trace/0168-sampling-propagation.md
• https://github.com/open-telemetry/oteps/tree/main/text/trace/0170-sampling-probability.md

[dyladan]

I really like this idea. I believe it may also help the PR review process when new specification is added if it explicitly calls out the OTEP which motivates it directly in the text.

[hterik]

This sounds like good idea for easier traceability. One has to be careful to not rely too heavily on it though, linking to xEPs should not be a substitute for good documentation.

For an example of what can happen, see Python the typing module. Where the documentation was for a long time lacking and often referring back to old PEPs, that by time became superseded by later improvements and instead provided out-of-date examples. python/cpython#91533

[reyang]

We will have a discussion in the upcoming TC meeting next year (2024).

[austinlparker]

We don't have a project to assign this to yet, but this is on the GC to solve.

[tigrannajaryan]

OTEPs 0035, 0099, 0122 are linked from https://github.com/open-telemetry/opentelemetry-proto/blob/main/docs/specification.md

Marking as done.

[tigrannajaryan]

We are looking for volunteers to edit the spec and add the references to OTEPs.

[reyang]

I've updated the metrics related OTEPs. #4022