search

grafana / alloy

OpenTelemetry Collector distribution with programmable pipelines
https://grafana.com/oss/alloy
Apache License 2.0
1.41k stars 205 forks source link

Rearrange the reference docs for Flow components #261

Open ptodev opened 9 months ago

ptodev commented 9 months ago

Request

Group the reference docs for components inside directories according to their namespace. Instead of every component being right under /flow/reference/components/, we could have directories such as:

This can also help users discover components which they may not know about, such as faro.receiver.

The downside to this is that the components page will no longer list all components. Instead, it'd only list the child directories. Maybe there could be a way to list all pages within those directories too? This could help with users who want to pull up a list of all components and search for a topic such as "mysql" or "kubernetes".

Note that there is no consensus yet on whether we should go ahead with this proposal. This issue will only be worked on after we reach consensus.

Use case

Agent Flow has a growing list of components. The navigation pane on the right side of the website is very long and it's hard to find what you're looking for without a Ctrl+F.

rfratto commented 9 months ago

If we do this, I'd request that there's always an alias for the full component name to the appropriate file in the namespace's directory so links from the UI continue to work.

thampiotr commented 9 months ago

/flow/reference/components/otelcol.receiver /flow/reference/components/otelcol.processor

Why have them separate, instead of in one otelcol folder? I think we should just take the first component of the name, before the . - we call it a namespace in our current naming conventions.

rfratto commented 9 months ago

Why have them separate, instead of in one otelcol folder? I think we should just take the first component of the name, before the . - we call it a namespace in our https://github.com/grafana/agent/issues/2059.

Personally, I would almost expect that we'd treat every level of namespace as a folder path, so that

/flow/reference/components/otelcol.receiver /flow/reference/components/otelcol.processor

Would instead be:

/flow/reference/components/otelcol/receiver /flow/reference/components/otelcol/processor

This extra level of organization would be particularly helpful for otelcol specifically, since its our largest namespace and already uses subnamespaces to increase organization.

ptodev commented 9 months ago

The main benefit of otelcol.receiver is that it minimises the amount of sub folders. The website isn't great with displaying deeply nested subfolders in the left navigation pane. I'm ok with having nested folders such as otelcol/receiver, but we might need to render it first to make sure that it looks good.

The website issue aside, I also think nested folders are the thing that makes the most sense.

github-actions[bot] commented 7 months ago

This issue has not had any activity in the past 30 days, so the needs-attention label has been added to it. If the opened issue is a bug, check to see if a newer release fixed your issue. If it is no longer relevant, please feel free to close this issue. The needs-attention label signals to maintainers that something has fallen through the cracks. No action is needed by you; your issue will be kept open and you do not have to respond to this comment. The label will be removed the next time this job runs if there is new activity. Thank you for your contributions!