Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Replace relrefs with docrefs in Agent concepts and Agent monitoring topics #5603

Merged
merged 8 commits into from
Oct 26, 2023

Conversation

clayton-cornell
Copy link
Contributor

PR Description

Which issue(s) this PR fixes

Notes to the Reviewer

PR Checklist

  • CHANGELOG.md updated
  • Documentation added
  • Tests updated
  • Config converters updated

@clayton-cornell clayton-cornell added type/docs Docs Squad label across all Grafana Labs repos backport release-v0.37 labels Oct 25, 2023
@clayton-cornell clayton-cornell requested a review from a team October 25, 2023 18:04
@clayton-cornell clayton-cornell changed the title Repalce relrefs with docrefs in Agent concepts and Agent monitoring topics Replace relrefs with docrefs in Agent concepts and Agent monitoring topics Oct 25, 2023
Copy link
Contributor

@ptodev ptodev left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm rubber stamping the PR, but I have a few concerns regarding content duplication:

  • Are the Grafana Cloud docs page just a copy pasted version of the Agent docs? Or are they imported from the Agent repo?
  • If the GC docs are copy pasted, how do we keep them in sync?
  • How does GC decide which version of the Agent to use for docs?
  • I don't see a Flow section in the GC Agent docs? I'm not sure why we are adding GC links even though they don't exist? Is it for future proofing?

I personally really think GC should just link to the Agent docs instead of duplicating the content... I can't see an advantage in duplication. Maybe the intent is to make it easier for GC users to find. But I think it's even confusing to the users because when they search our docs they see duplicate pages with the same information.

@clayton-cornell
Copy link
Contributor Author

clayton-cornell commented Oct 26, 2023

@ptodev Some answers

  1. The Agent docs are mounted in Cloud, not copy/pasted. That means a single source and multiple publish locations.
  2. They stay in sync because we have one source of information :-)
  3. Cloud uses latest (as far as I know)
  4. Flow is not yet mounted in Cloud docs. It was, and we disconnected it. Currently only Static is mounted there.
  5. The work here is preparing when we actually do mount Flow docs into Cloud. Relrefs work with a single mount point - currently just the OSS docs. Things can get weird or broken when you have single source docs mounted in multiple locations with non-identical pathing.

The intent is to provide a Cloud-specific doc set (since Cloud is a collection ot things presented as a single solution) vs a scattered set of docs.

@clayton-cornell clayton-cornell merged commit 5960333 into main Oct 26, 2023
7 checks passed
@clayton-cornell clayton-cornell deleted the docs/update-relrefs-patch3 branch October 26, 2023 16:26
grafanabot pushed a commit that referenced this pull request Oct 26, 2023
…opics (#5603)

* Update relrefs in component metrics topic

* Update relrefs in controller metrics topic

* Update relrefs in debugging topic

* Update relrefs in modules topic

* Update relrefs in clustering topic

* Update relrefs in component controller topic

* Update relrefs in config-language topic

(cherry picked from commit 5960333)
clayton-cornell added a commit that referenced this pull request Oct 26, 2023
…opics (#5603) (#5622)

* Update relrefs in component metrics topic

* Update relrefs in controller metrics topic

* Update relrefs in debugging topic

* Update relrefs in modules topic

* Update relrefs in clustering topic

* Update relrefs in component controller topic

* Update relrefs in config-language topic

(cherry picked from commit 5960333)

Co-authored-by: Clayton Cornell <[email protected]>
@ptodev
Copy link
Contributor

ptodev commented Oct 26, 2023

@clayton-cornell thank you for clarifying! IMO the approach of always using the latest version works well for Mimir/Loki/Tempo, but it doesn't work so well for the Agent. It's because the databases on the Cloud are naturally always on the latest version, but the Agent runs on the client's machines and the clients may run any version of it.

@github-actions github-actions bot added the frozen-due-to-age Locked due to a period of inactivity. Please open new issues or PRs if more discussion is needed. label Feb 21, 2024
@github-actions github-actions bot locked as resolved and limited conversation to collaborators Feb 21, 2024
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
backport release-v0.37 frozen-due-to-age Locked due to a period of inactivity. Please open new issues or PRs if more discussion is needed. type/docs Docs Squad label across all Grafana Labs repos
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants