mage: check that links are live in the OTel README

[mauri870]

This PR adds a utility based on the link-patrol command to check if links in a given file are live. This utility should be reusable so we can use it to validate other files in the repository.

Also added a check in the check and otel:readme mage targets to validate all links in the Otel Readme are valid.

What does this PR do?

Why is it important?

• My code follows the style guidelines of this project
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• I have made corresponding change to the default configuration files
• I have added tests that prove my fix is effective or that my feature works
• I have added an entry in ./changelog/fragments using the changelog tool
• I have added an integration test or an E2E test

How to test this PR locally

You can either run mage check or mage otel:readme to trigger the link check.

To test it indeed fails if a link is invalid you can introduce a typo and it should fail in subsequent runs.

sed -i 's/featuregate/fff/' internal/pkg/otel/templates/README.md.tmpl

Related issues

• Closes Automatically verify links in OTel README file #5117

[elasticmachine]

Pinging @elastic/elastic-agent-control-plane (Team:Elastic-Agent-Control-Plane)

[mergify]

This pull request does not have a backport label. Could you fix it @mauri870? 🙏
To fixup this pull request, you need to add the backport labels for the needed
branches, such as:

• backport-v./d./d./d is the label to automatically backport to the 8./d branch. /d is the digit

NOTE: backport-skip has been added to this pull request.

[swiatekm]

The changes look good to me. I do have three questions about the semantics of this check:

1. Are we checking all the links every time? Is there a mode available where we only check the PR diff?
2. What happens if the site we check is slow or unavailable? How does the tool behave in that case?
3. Do we have special cases (I imagine mostly around releases and changelog generation) where we'd run into a chicken-and-egg situation where links will only become valid after the PR is merged?

[mauri870]

The changes look good to me. I do have three questions about the semantics of this check:

1. Are we checking all the links every time? Is there a mode available where we only check the PR diff?

2. What happens if the site we check is slow or unavailable? How does the tool behave in that case?

3. Do we have special cases (I imagine mostly around releases and changelog generation) where we'd run into a chicken-and-egg situation where links will only become valid after the PR is merged?

Thanks for the feedback, I'll try to reply to the points in order.

1. Yes,it checks the links every time. The tool I'm relying on (link-patrol) needs to scan the entire file every time. Now that you mentioned this, this tool only works with markdown files, which would not work well in diffs, the parser can fail with broken mardown in a partial diff. I could not find any other alternatives written in Go. I found https://github.com/untitaker/hyperlink which seems to be more robust. I don't think this task can work well in PR diffs, but I could be mistaken.

2. It retries once. If the request times out, it doesn’t count as a failure. Only explicit errors, such as 404, will cause the check to fail.

3. Perhaps, but in this case (the OTel README), the file is generated via a template. As far as I know, the resulting file is always valid and isn’t meant to be changed manually.

[mergify]

This pull request is now in conflicts. Could you fix it? 🙏
To fixup this pull request, you can check out it locally. See documentation: https://help.github.com/articles/checking-out-pull-requests-locally/

git fetch upstream
git checkout -b feature/mage-check-links upstream/feature/mage-check-links
git merge upstream/main
git push upstream feature/mage-check-links

[swiatekm]

👍

[swiatekm]

Yes,it checks the links every time. The tool I'm relying on (link-patrol) needs to scan the entire file every time. Now that you mentioned this, this tool only works with markdown files, which would not work well in diffs, the parser can fail with broken mardown in a partial diff. I could not find any other alternatives written in Go. I found https://github.com/untitaker/hyperlink which seems to be more robust. I don't think this task can work well in PR diffs, but I could be mistaken.

We could only run it on files changed in the PR, but I'm not sure that would really improve much. There's not a lot of markdown files in this repo. I was mostly concerned about run times. If we're annoyed by the time it takes to run or by general flakiness, we can look into making it better.

[mauri870]

We could only run it on files changed in the PR, but I'm not sure that would really improve much. There's not a lot of markdown files in this repo. I was mostly concerned about run times. If we're annoyed by the time it takes to run or by general flakiness, we can look into making it better.

Definitely. For now it will only check the OTel README, but if we want to extend it to other files we might have to look closer to runtime performance, timeouts and the noisy output that the tool generates.

[mergify]

backport-v8.x has been added to help with the transition to the new branch 8.x.

[mergify]

backport-v8.x has been added to help with the transition to the new branch 8.x.

[mergify]

This pull request is now in conflicts. Could you fix it? 🙏
To fixup this pull request, you can check out it locally. See documentation: https://help.github.com/articles/checking-out-pull-requests-locally/

git fetch upstream
git checkout -b feature/mage-check-links upstream/feature/mage-check-links
git merge upstream/main
git push upstream feature/mage-check-links

[mauri870]

/test

[elastic-sonarqube]

Quality Gate passed

Issues
0 New issues
0 Fixed issues
0 Accepted issues

Measures
0 Security Hotspots
No data about Coverage
0.0% Duplication on New Code

See analysis details on SonarQube