first draft of alloy overview rewrite #2031
Conversation
Co-authored-by: Clayton Cornell <[email protected]>
Co-authored-by: Clayton Cornell <[email protected]>
Co-authored-by: Clayton Cornell <[email protected]>
Co-authored-by: Clayton Cornell <[email protected]>
Co-authored-by: Clayton Cornell <[email protected]>
Co-authored-by: Clayton Cornell <[email protected]>
Co-authored-by: Clayton Cornell <[email protected]>
| * GitOps compatibility | ||
| * Clustering support | ||
| * Security | ||
| * Debugging utilities | ||
|
|
||
| {{< param "PRODUCT_NAME" >}} is flexible, and you can easily configure it to fit your needs in on-prem, cloud-only, or a mix of both. | ||
|
|
There was a problem hiding this comment.
One thing to add here is a clear call to action, which is for them to install, configure, and collect forward telemetry data.
We could do that by including the section on getting started in the original draft on the overview page
OR
include a blurb saying, "Getting started with Alloy consists of 3 major steps.
Click here to get started." Then, link it to a new page with content in the original draft as shown below.
New page:
Getting started with Alloy consists of 3 major steps:
- Install {{< param "PRODUCT_NAME" >}}
- Configure {{< param "PRODUCT_NAME" >}}
- Collect and forward telemetry data to the observability backend of your choice.
In addition, you can use the Grafana dashboard to visualize the data collected from the app or infrastructure.
For a quick overview of this process, check out the following tutorials.
- Use Grafana Alloy to send logs to Loki
- Use Grafana Alloy to send metrics to Prometheus
- For more tutorials, check out the tutorial page
What do you think?
There was a problem hiding this comment.
Some thoughts on this:
- I'd really like to keep this landing page as simple as possible... and in-line with the other Grafana product landing pages.
- We should never use
Click herein any documentation. - The
3 major stepspart doesn't fit in so well... if we want to dive into this level of detail, then it should be on a child page. - The landing page should simply introduce the product, not provide steps/instructions.
There was a problem hiding this comment.
Agreed. @clayton-cornell Why don't we leave out the call to action part and include the suggested text on the Get Started page?
https://grafana.com/docs/alloy/latest/get-started/
| * GitOps compatibility | ||
| * Clustering support | ||
| * Security | ||
| * Debugging utilities | ||
|
|
||
| {{< param "PRODUCT_NAME" >}} is flexible, and you can easily configure it to fit your needs in on-prem, cloud-only, or a mix of both. | ||
|
|
There was a problem hiding this comment.
One thing to add here is a clear call to action, which is for them to install, configure, and collect forward telemetry data.
We could do that by including the section on getting started in the original draft on the overview page
OR
include a blurb saying, "Getting started with Alloy consists of 3 major steps.
Click here to get started." Then, link it to a new page with content in the original draft as shown below.
New page:
Getting started with Alloy consists of 3 major steps:
Install {{< param "PRODUCT_NAME" >}}
Configure {{< param "PRODUCT_NAME" >}}
Collect and forward telemetry data to the observability backend of your choice.
In addition, you can use the Grafana dashboard to visualize the data collected from the app or infrastructure.
For a quick overview of this process, check out the following tutorials.
Use Grafana Alloy to send logs to Loki
Use Grafana Alloy to send metrics to Prometheus
For more tutorials, check out the tutorial page
What do you think?
There was a problem hiding this comment.
It's normally clear to users that they have to install and configure it. The main issue is that there are many ways to do so. For example, do they have to deploy one Alloy per server? Or one central Alloy instance? What if they use OpenTelemetry? Or Prometheus? I think we should simply link to several articles which help them get started quickly with the sort of telemetry they are interested in. The ones you linked to are a good choice:
Use Grafana Alloy to send logs to Loki
Use Grafana Alloy to send metrics to PrometheusUse Grafana Alloy to send logs to Loki
Use Grafana Alloy to send metrics to Prometheus
I'd also add one more about collecting OpenTelemetry. I do also wonder if we should rename those pages like this
- send metrics to Prometheus -> collect infrastructure metrics
- send logs to Loki -> collect infrastructure logs
- send OpenTelemetry signals -> collect application telemetry
This reflects the current guidance on how to use components.
There was a problem hiding this comment.
@ptodev, this is such a great point.
@clayton-cornell recommended that we do not add a CTA to an overview page, which makes sense.
I suggest we include this information on the get started page: https://grafana.com/docs/alloy/latest/get-started/
Why don't we touch base on this when we restructure and improve the getting started page of the doc?
| @@ -54,30 +58,18 @@ hero: | |||
|
|
|||
| Collecting the relevant telemetry data, such as metrics, logs, and traces, for analysis is an indispensable part of understanding the health of your system. | |||
|
|
|||
| {{< param "PRODUCT_NAME" >}} is a multifunction tool you can use to collect, process, and forward telemetry data to the observability backend of your choosing. | |||
| {{< param "PRODUCT_NAME" >}} is more than just a collector. You can use {{< param "PRODUCT_NAME" >}} to collect, process, and forward telemetry data to the observability backend of your choosing. | |||
There was a problem hiding this comment.
Why don't we change this sentence to:
Alloy is a software that collects, processes, and forwards telemetry data to an observability backend of your choice, where they can be stored & visualized.
There was a problem hiding this comment.
or:
Alloy collects, processes, and forwards telemetry data to an observability backend where is stored and visualized.
| @@ -17,31 +17,34 @@ hero: | |||
| width: 110 | |||
| height: 110 | |||
| description: >- | |||
| Grafana Alloy is a vendor-neutral distribution of the OpenTelemetry (OTel) Collector. Alloy uniquely combines the very best OSS observability signals in the community. | |||
| cards: | |||
| Grafana Alloy is a vendor-neutral distribution of the OpenTelemetry (OTel) Collector. With Alloy, you can instrument your application or infrastructure to collect, process, and forward telemetry data to the observability backend of your choice. | |||
There was a problem hiding this comment.
you can instrument your application
Technically, Alloy is not used for application instrumentation. Normally "application instrumentation" refers to the SDK which users use for instrumenting - e.g. Prometheus or OTel.
There was a problem hiding this comment.
Thank you for catching this @ptodev !
What role does Alloy play in data collection for applications?
Is Prometheus or OTel used to instrument an app, and the data is sent to Alloy for processing and forwarding?
If that is the case, why wouldn't they just use Prometheus or OTel to handle all of that?
There was a problem hiding this comment.
@ptodev , perhaps we could change the sentence to
"Alloy is a software that collects, processes, and forwards telemetry data to an observability backend of your choice, where they can be stored & visualized."
docs/sources/_index.md
Outdated
| {{< param "PRODUCT_NAME" >}} is flexible, and you can easily configure it to fit your needs in on-prem, cloud-only, or a mix of both. | ||
| Collecting the relevant telemetry data, such as metrics, logs, and traces, for analysis is an indispensable part of understanding the health of your system. | ||
|
|
||
| {{< param "PRODUCT_NAME" >}} is more than just a collector. You can use {{< param "PRODUCT_NAME" >}} to collect, process, and forward telemetry data to the observability backend of your choosing. |
There was a problem hiding this comment.
| {{< param "PRODUCT_NAME" >}} is more than just a collector. You can use {{< param "PRODUCT_NAME" >}} to collect, process, and forward telemetry data to the observability backend of your choosing. | |
| You can use {{< param "PRODUCT_NAME" >}} to collect, process, and forward telemetry data to the observability backend of your choosing. |
Collecting,, processing, and forwarding is what any collector does :)
There was a problem hiding this comment.
The initial sentence was an attempt to rework some other suggested wording that didn't quite fit. I agree, it's better to simply drop it altogether.
There was a problem hiding this comment.
What do you think about changing this sentence to:
Alloy is a software that collects, processes, and forwards telemetry data to an observability backend of your choice, where they can be stored & visualized.
| * Custom components | ||
| * GitOps compatibility | ||
| * Clustering support | ||
| * Security | ||
| * Debugging utilities |
There was a problem hiding this comment.
Unless those bullet points are links, this might be too abstract and people may not understand it. We could either make them links, or explain it in more simple terms. Probably links are the better option.
There was a problem hiding this comment.
@ptodev , agreed.
I was trying to simplify what was on the original page but perhaps it's better to leave it out completely and explain this on another page. What do you think?
| * GitOps compatibility | ||
| * Clustering support | ||
| * Security | ||
| * Debugging utilities | ||
|
|
||
| {{< param "PRODUCT_NAME" >}} is flexible, and you can easily configure it to fit your needs in on-prem, cloud-only, or a mix of both. | ||
|
|
There was a problem hiding this comment.
It's normally clear to users that they have to install and configure it. The main issue is that there are many ways to do so. For example, do they have to deploy one Alloy per server? Or one central Alloy instance? What if they use OpenTelemetry? Or Prometheus? I think we should simply link to several articles which help them get started quickly with the sort of telemetry they are interested in. The ones you linked to are a good choice:
Use Grafana Alloy to send logs to Loki
Use Grafana Alloy to send metrics to PrometheusUse Grafana Alloy to send logs to Loki
Use Grafana Alloy to send metrics to Prometheus
I'd also add one more about collecting OpenTelemetry. I do also wonder if we should rename those pages like this
- send metrics to Prometheus -> collect infrastructure metrics
- send logs to Loki -> collect infrastructure logs
- send OpenTelemetry signals -> collect application telemetry
This reflects the current guidance on how to use components.
| * GitOps compatibility | ||
| * Clustering support | ||
| * Security | ||
| * Debugging utilities | ||
|
|
||
| {{< param "PRODUCT_NAME" >}} is flexible, and you can easily configure it to fit your needs in on-prem, cloud-only, or a mix of both. | ||
|
|
There was a problem hiding this comment.
Some thoughts on this:
- I'd really like to keep this landing page as simple as possible... and in-line with the other Grafana product landing pages.
- We should never use
Click herein any documentation. - The
3 major stepspart doesn't fit in so well... if we want to dive into this level of detail, then it should be on a child page. - The landing page should simply introduce the product, not provide steps/instructions.
Co-authored-by: Clayton Cornell <[email protected]>
Co-authored-by: Clayton Cornell <[email protected]>
Co-authored-by: Paulin Todev <[email protected]>
Co-authored-by: Paulin Todev <[email protected]>
| @@ -17,31 +17,34 @@ hero: | |||
| width: 110 | |||
| height: 110 | |||
| description: >- | |||
| Grafana Alloy is a vendor-neutral distribution of the OpenTelemetry (OTel) Collector. Alloy uniquely combines the very best OSS observability signals in the community. | |||
| cards: | |||
| Grafana Alloy is a vendor-neutral distribution of the OpenTelemetry (OTel) Collector. With Alloy, you can instrument your application or infrastructure to collect, process, and forward telemetry data to the observability backend of your choice. | |||
There was a problem hiding this comment.
| Grafana Alloy is a vendor-neutral distribution of the OpenTelemetry (OTel) Collector. With Alloy, you can instrument your application or infrastructure to collect, process, and forward telemetry data to the observability backend of your choice. | |
| Grafana Alloy is a vendor-neutral distribution of the OpenTelemetry (OTel) Collector. | |
| Alloy collects, processes, and forwards telemetry data to an observability backend where is stored and visualized. |
The distribution of OTel or not part isn't finalized on the OTel side (at least I don't think it has been... yet, so we can leave that as-is.
| @@ -54,30 +58,18 @@ hero: | |||
|
|
|||
| Collecting the relevant telemetry data, such as metrics, logs, and traces, for analysis is an indispensable part of understanding the health of your system. | |||
|
|
|||
| {{< param "PRODUCT_NAME" >}} is a multifunction tool you can use to collect, process, and forward telemetry data to the observability backend of your choosing. | |||
| {{< param "PRODUCT_NAME" >}} is more than just a collector. You can use {{< param "PRODUCT_NAME" >}} to collect, process, and forward telemetry data to the observability backend of your choosing. | |||
There was a problem hiding this comment.
or:
Alloy collects, processes, and forwards telemetry data to an observability backend where is stored and visualized.
|
@LisaHJung This PR has been open a while we may need to port everything over to a new PR - rebasing the content without breaking things isn't easy. |
PR Description
Editing overview page of Alloy
Which issue(s) this PR fixes
Notes to the Reviewer
PR Checklist