search

grafana / alloy

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

[task doc] Setting up continuous profiling with Pyroscope #293

Open thampiotr opened 11 months ago

thampiotr commented 11 months ago

Use format for task docs from writer's toolkit.

ptodev commented 11 months ago

There are already Pyroscope docs which can be ported to the Agent docs namespace. I mentioned this in a comment a few days ago.

thampiotr commented 11 months ago

Ah, right. Could we just link to them instead?

ptodev commented 11 months ago

I was hoping to move them to the Agent's Get Started section. Maybe @knylander-grafana and @Rperry2174 have thoughts on this?

knylander-grafana commented 10 months ago

We can definitely link from the Pyroscope doc to the Agent's get started content. If we need to, we can also share content between repositories instead ofd copy-pasting stuff.

knylander-grafana commented 4 months ago

Here's additional content: https://grafana.com/docs/pyroscope/latest/configure-client/grafana-agent/

I"m currently working on updating the content from Agent to Alloy, so these docs have a bit of a mix: https://github.com/grafana/pyroscope/issues/3271

knylander-grafana commented 1 month ago

We just updated the docs for Pyroscope to use Alloy. https://grafana.com/docs/pyroscope/latest/configure-client/grafana-alloy/

Does this cover the request for docs for this? There's a lot of content here. If you want to include it in the Alloy docs, we'd have to mount multiple files.

My suggestion is to create a single page in the Alloy docs that summarizes the options for Pyroscope using Alloy and then link to the content in the Pyroscope docs. This provides additional visibility and a fast solution.

We can also see about mounting the Pyroscope Alloy docs into Alloy. This requires more thoughtful planning and considerations. For example, we'll have to consider whether any content does or does not apply to Alloy / Pyroscope.

@clayton-cornell What do you think?

clayton-cornell commented 1 month ago

I'd go with the "summary and link" suggestion. There's a "collect data" section in the Alloy docs: https://grafana.com/docs/alloy/latest/collect/ (it needs work to align the terminology) Woudl this be the right place to drop in a Pyroscope summary topic?

ptodev commented 1 month ago

I also think that for now it'd be best to add a link in the Collect and forward data with Grafana Alloy page. But in the long term I think the docs should be in Alloy's namespace, and Pyroscope should link to the docs in the Alloy namespace.

The main issue with documenting Alloy behaviour in docs that are not owned by Alloy is that they can go out of date. For example, the Pyroscope docs even document all the config arguments for the pyroscope.java component. I am almost certain that when one day these config arguments change, people will forget to update the Pyroscope docs (or they wouldn't even know they have to do it in the first place).

In the latest Alloy release, we are even removing a component. We updated all our docs to reflect this, but now I wonder if there are any other such docs that reference it, outside the Alloy namespace.

Mounting pages should IMO be a last resort solution, since it looks like duplication from the point of view of the user. It also causes identical docs to pop up when using the search function of the website and can be confusing.