[editorial] Use path, not external URL, for link to spec page; and fix broken link

[chalin]

• This is part of an effort to normalize links, for improved link checking of the OTel website.
• Contributes to CI: external-link check follow up and link cleanup opentelemetry.io#2429
• Fixes the broken link to "Metric Metadata", which moved to another page via Move Prometheus/OpenMetrics compatibility to its own file #2952.

[chalin]

Since the following PR:

• Move Prometheus/OpenMetrics compatibility to its own file #2952

The link to "Metric Metadata" has moved. I've added the fix to this PR (through the second commit).

[chalin]

Maybe there should be a check (in this repo) to catch external links to local spec pages?

[chalin]

We'll be checking for this on the website side of things (FYI):

• Report issue if an external link to a local spec page is used opentelemetry.io#2477

[Oberon00]

Not sure how helpful that is, since the path starts with / which makes it still quite inflexible.

[chalin]

Hi @Oberon00. I'm not sure I understand your comment. Are you against using a path vs a full URL for local page references (because I noticed that you didn't give your approval for this PR)? Or are you saying that you'd prefer that the path be relative rather than absolute. Which extra flexibility are you looking for?

[chalin]

To clarify: there's an extra cost in checking external links, managing the external link caches etc., so it doesn't make sense to use an external URL for internal paths.

By the way, we do link checking (internal and external) for the entire OTel website, which includes the full specification, in 9 seconds -- for example see this build log:

7:49:24 PM: tmp/bin/htmltest --log-level 1
7:49:24 PM: htmltest started at 12:49:24 on public
7:49:24 PM: ========================================================================
7:49:33 PM: ✔✔✔ passed in 8.958333952s
7:49:33 PM: tested 347 documents

That's in contrast to the 180 seconds required by markdown-link-check running over only the spec. So it's worth paying careful attention to how links are encoded.

I hope this helps clarify the motivation behind this PR. Thanks!

[Oberon00]

because I noticed that you didn't give your approval for this PR

Sorry for misunderstandings, this was just a curious comment. I didn't mean to indicate disapproval (I haven't reviewed the PR just because I don't have a qualified opinion on it, and I don't review every PR I comment on 🙂)

[chalin]

@Oberon00 - no worries, thanks for clarifying. Thanks all for the review and merging.