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.

Sign up for GitHub

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

first draft of alloy overview rewrite #2031

Open
wants to merge 19 commits into
base: main
Choose a base branch
from
Open

first draft of alloy overview rewrite #2031

Show file tree
Hide file tree
Changes from 6 commits
Commits
Show all changes
19 commits
Select commit Hold shift + click to select a range
c3ad4bd
first draft of alloy overview rewrite
LisaHJung Nov 4, 2024
58a27d8
update Alloy and Otel versions
LisaHJung Nov 4, 2024
d566ee3
Apply suggestions from code review
LisaHJung Nov 4, 2024
1177caf
Apply suggestions from code review
LisaHJung Nov 4, 2024
276cabc
edited the template doc
LisaHJung Nov 4, 2024
515e175
Regenerate indext file
clayton-cornell Nov 4, 2024
3e7ce45
Update docs/sources/_index.md
LisaHJung Nov 5, 2024
7de5261
Update docs/sources/_index.md
LisaHJung Nov 5, 2024
6f49c90
Update docs/sources/_index.md
LisaHJung Nov 5, 2024
c149d4f
Update docs/sources/_index.md
LisaHJung Nov 5, 2024
122640e
Update docs/sources/_index.md
LisaHJung Nov 5, 2024
48a39ab
updated the overview page incorporating Clayton's feedback
LisaHJung Nov 14, 2024
a9c7fb6
Generate versioned topic
clayton-cornell Nov 14, 2024
ecce18a
General rework to align styles and content flow
clayton-cornell Nov 14, 2024
a34581e
corrected misspelling and abbreviation that was mistakenly left
LisaHJung Nov 15, 2024
62522e2
Update docs/sources/_index.md
LisaHJung Dec 5, 2024
8e2ef89
Update docs/sources/_index.md
LisaHJung Dec 5, 2024
1bec9f0
Update docs/sources/_index.md
LisaHJung Dec 5, 2024
bdfc6f4
Update docs/sources/_index.md
LisaHJung Dec 5, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 22 additions & 13 deletions docs/sources/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,8 +17,7 @@ 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 app or infrastrastructure to collect, process, and forward telemetry data to the data source of your choice.
LisaHJung marked this conversation as resolved.
Show resolved Hide resolved
title_class: pt-0 lh-1
items:
- title: Install Alloy
Expand Down Expand Up @@ -53,21 +52,31 @@ cards:

# Overview

{{< param "PRODUCT_NAME" >}} offers native pipelines for [OTel][], [Prometheus][], [Pyroscope][], [Loki][], and many other metrics, logs, traces, and profile tools.
In addition, you can use {{< param "PRODUCT_NAME" >}} pipelines to do different tasks, such as configure alert rules in Loki and [Mimir][].
{{< param "PRODUCT_NAME" >}} is fully compatible with the OTel Collector, Prometheus Agent, and [Promtail][].
You can use {{< param "PRODUCT_NAME" >}} as an alternative to either of these solutions or combine it into a hybrid system of multiple collectors and agents.
You can deploy {{< param "PRODUCT_NAME" >}} anywhere within your IT infrastructure and pair it with your Grafana LGTM stack, a telemetry backend from Grafana Cloud, or any other compatible backend from any other vendor.
Getting the relevant telemetry data (i.e. metrics, logs, and traces) for analysis is an indispensable part of understanding the health of your system.
LisaHJung marked this conversation as resolved.
Show resolved Hide resolved

Think of {{< param "PRODUCT_NAME" >}} as a Swiss army knife for collecting, processing, and forwarding telemetry data to the data source of your choosing.
LisaHJung marked this conversation as resolved.
Show resolved Hide resolved

{{< param "PRODUCT_NAME" >}} has the following features to help you customize, scale, secure, and troubleshoot your data pipeline.
1. Custom components
1. GitOps compatibility
1. Clustering support
1. Security
1. Debugging utilities

Check out the {{< param "PRODUCT_NAME" >}} [Introduction] page for more information on these and other key features.
LisaHJung marked this conversation as resolved.
Show resolved Hide resolved

{{< 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.
LisaHJung marked this conversation as resolved.
Show resolved Hide resolved

Copy link
Contributor Author

Choose a reason for hiding this comment

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

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:

  1. Install {{< param "PRODUCT_NAME" >}}
  2. Configure {{< param "PRODUCT_NAME" >}}
  3. 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.

What do you think?

Copy link
Contributor

@clayton-cornell clayton-cornell Dec 3, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

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 here in any documentation.
  • The 3 major steps part 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.

Copy link
Contributor Author

@LisaHJung LisaHJung Dec 5, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

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/

{{< admonition type="tip" >}}
{{< param "PRODUCT_NAME" >}} uses the same components, code, and concepts that were first introduced in Grafana Agent Flow.
{{< /admonition >}}
Getting started with Alloy consists of 3 major steps:
LisaHJung marked this conversation as resolved.
Show resolved Hide resolved
1. Install {{< param "PRODUCT_NAME" >}}
1. Configure {{< param "PRODUCT_NAME" >}}
1. Collect and forward telemetry data to the data source of choice
LisaHJung marked this conversation as resolved.
Show resolved Hide resolved

## What can {{% param "PRODUCT_NAME" %}} do?
In addition, you can use Grafana dashboard to visualize the data collected from app or infrastructure.
LisaHJung marked this conversation as resolved.
Show resolved Hide resolved

{{< param "PRODUCT_NAME" >}} is more than just observability signals like metrics, logs, and traces. It provides many features that help you quickly find and process your data in complex environments.
Some of these features include custom components, GitOps compatibility, clustering support, security, and debugging utilities. Refer to the {{< param "PRODUCT_NAME" >}} [Introduction] for more information on these and other key features.
For a quick overview of this process, check out the following tutorials.
LisaHJung marked this conversation as resolved.
Show resolved Hide resolved
* [Use Grafana Alloy to send logs to Loki](https://grafana.com/docs/alloy/latest/tutorials/send-logs-to-loki/)
* [Use Grafana Alloy to send metrics to Prometheus](https://grafana.com/docs/alloy/latest/tutorials/send-metrics-to-prometheus/)
LisaHJung marked this conversation as resolved.
Show resolved Hide resolved

## Explore

Expand Down
35 changes: 22 additions & 13 deletions docs/sources/_index.md.t
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,8 +17,7 @@ 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 app or infrastrastructure to collect, process, and forward telemetry data to the data source of your choice.
title_class: pt-0 lh-1
items:
- title: Install Alloy
Expand Down Expand Up @@ -53,21 +52,31 @@ cards:

# Overview

{{< param "PRODUCT_NAME" >}} offers native pipelines for [OTel][], [Prometheus][], [Pyroscope][], [Loki][], and many other metrics, logs, traces, and profile tools.
In addition, you can use {{< param "PRODUCT_NAME" >}} pipelines to do different tasks, such as configure alert rules in Loki and [Mimir][].
{{< param "PRODUCT_NAME" >}} is fully compatible with the OTel Collector, Prometheus Agent, and [Promtail][].
You can use {{< param "PRODUCT_NAME" >}} as an alternative to either of these solutions or combine it into a hybrid system of multiple collectors and agents.
You can deploy {{< param "PRODUCT_NAME" >}} anywhere within your IT infrastructure and pair it with your Grafana LGTM stack, a telemetry backend from Grafana Cloud, or any other compatible backend from any other vendor.
Getting the relevant telemetry data (i.e. metrics, logs, and traces) for analysis is an indispensable part of understanding the health of your system.

Think of {{< param "PRODUCT_NAME" >}} as a Swiss army knife for collecting, processing, and forwarding telemetry data to the data source of your choosing.

{{< param "PRODUCT_NAME" >}} has the following features to help you customize, scale, secure, and troubleshoot your data pipeline.
1. Custom components
1. GitOps compatibility
1. Clustering support
1. Security
1. Debugging utilities

Check out the {{< param "PRODUCT_NAME" >}} [Introduction] page for more information on these and other key features.

{{< 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.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

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?

Copy link
Collaborator

Choose a reason for hiding this comment

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

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

@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?

{{< admonition type="tip" >}}
{{< param "PRODUCT_NAME" >}} uses the same components, code, and concepts that were first introduced in Grafana Agent Flow.
{{< /admonition >}}
Getting started with Alloy consists of 3 major steps:
1. Install {{< param "PRODUCT_NAME" >}}
1. Configure {{< param "PRODUCT_NAME" >}}
1. Collect and forward telemetry data to the data source of choice

## What can {{% param "PRODUCT_NAME" %}} do?
In addition, you can use Grafana dashboard to visualize the data collected from app or infrastructure.

{{< param "PRODUCT_NAME" >}} is more than just observability signals like metrics, logs, and traces. It provides many features that help you quickly find and process your data in complex environments.
Some of these features include custom components, GitOps compatibility, clustering support, security, and debugging utilities. Refer to the {{< param "PRODUCT_NAME" >}} [Introduction] for more information on these and other key features.
For a quick overview of this process, check out the following tutorials.
* [Use Grafana Alloy to send logs to Loki](https://grafana.com/docs/alloy/latest/tutorials/send-logs-to-loki/)
* [Use Grafana Alloy to send metrics to Prometheus](https://grafana.com/docs/alloy/latest/tutorials/send-metrics-to-prometheus/)

## Explore

Expand Down