From d1db6f8b295815c7d0d651ed627dca5f5774aea0 Mon Sep 17 00:00:00 2001 From: Robert Fratto Date: Tue, 19 Mar 2024 11:33:14 -0400 Subject: [PATCH] misc: create new README.md for Alloy (#40) This does not yet include the new logo or updated screenshots; that will come in a follow-up PR. --- README.md | 178 +++++++++++++++++++++++++++++------------------------- 1 file changed, 97 insertions(+), 81 deletions(-) diff --git a/README.md b/README.md index 87ba44ba8d..9010561f48 100644 --- a/README.md +++ b/README.md @@ -1,97 +1,104 @@

Grafana Alloy logo

-[Grafana Alloy][] is an OpenTelemetry Collector distribution with configuration -inspired by [Terraform][]. It is designed to be flexible, performant, and -compatible with multiple ecosystems such as Prometheus and OpenTelemetry. +

+ Latest Release + Documentation link +

-Grafana Alloy is based around **components**. Components are wired together to -form programmable observability **pipelines** for telemetry collection, -processing, and delivery. +Grafana Alloy is a vendor-agnostic OpenTelemetry Collector distribution with +extra capabilities for writing, running, and debugging powerful pipelines. -Grafana Alloy can collect, transform, and send data to: +

+ +

-* The [Prometheus][] ecosystem -* The [OpenTelemetry][] ecosystem -* The Grafana open source ecosystem ([Loki][], [Grafana][], [Tempo][], [Mimir][], [Pyroscope][]) +## What can Alloy do? -[Terraform]: https://terraform.io -[Grafana Alloy]: https://grafana.com/docs/alloy/latest/ -[Prometheus]: https://prometheus.io -[OpenTelemetry]: https://opentelemetry.io -[Loki]: https://github.com/grafana/loki -[Grafana]: https://github.com/grafana/grafana -[Tempo]: https://github.com/grafana/tempo -[Mimir]: https://github.com/grafana/mimir -[Pyroscope]: https://github.com/grafana/pyroscope - -## Why use Grafana Alloy? - -* **Vendor-neutral**: Fully compatible with the Prometheus, OpenTelemetry, and - Grafana open source ecosystems. -* **Every signal**: Collect telemetry data for metrics, logs, traces, and - continuous profiles. -* **Scalable**: Deploy on any number of machines to collect millions of active - series and terabytes of logs. -* **Battle-tested**: Grafana Alloy extends the existing battle-tested code from - the Prometheus and OpenTelemetry Collector projects. -* **Powerful**: Write programmable pipelines with ease, and debug them using a - [built-in UI][UI]. -* **Batteries included**: Integrate with systems like MySQL, Kubernetes, and - Apache to get telemetry that's immediately useful. - -[UI]: https://grafana.com/docs/alloy/latest/tasks/debug/#grafana-alloy-ui +* **Programmable pipelines**: Use a rich [expression-based syntax][syntax] for + configuring powerful observability pipelines. -## Getting started +* **OpenTelemetry Collector Distribution**: Alloy is a [distribution][] of + OpenTelemetry Collector and supports dozens of its components, alongside new + components that make use of Alloy's programmable pipelines. -Check out our [documentation][] to see: +* **Vendor-agnostic**: Alloy embraces Grafana's "big tent" philosophy, and has + components to perfectly integrate with multiple telemetry ecosystems: + + * [OpenTelemetry Collector][] + * [Prometheus][] + * [Grafana Loki][] + * [Grafana Pyroscope][] + +* **Kubernetes-native**: Use components to interact with native and custom + Kubernetes resources; no need to learn how to use a separate Kubernetes + operator. + +* **Shareable pipelines**: Use [modules][] to share your pipelines with the + world. -* [Installation instructions][] for Grafana Alloy -* Details about [Grafana Alloy][documentation] -* Steps for [Getting started][] with Grafana Alloy -* The list of Grafana Alloy [Components][] +* **Automatic workload distribution**: Configure Alloy instances to form a + [cluster][] for automatic workload distribution. -[documentation]: https://grafana.com/docs/alloy/ -[Installation instructions]: https://grafana.com/docs/alloy/latest/setup/install/ -[Getting started]: https://grafana.com/docs/alloy/latest/getting_started/ -[Components]: https://grafana.com/docs/alloy/latest/reference/components/ +* **Centralized configuration support**: Alloy supports retrieving its + configuration from a [server][remotecfg] for centralized configuration + management. + +* **Debugging utilities**: Use the [built-in UI][ui] for visualizing and + debugging pipelines. + +[syntax]: https://grafana.com/docs/alloy/latest/concepts/config-syntax/ +[distribution]: https://opentelemetry.io/docs/collector/distributions/ +[OpenTelemetry Collector]: https://opentelemetry.io +[Prometheus]: https://prometheus.io +[Grafana Loki]: https://github.com/grafana/loki +[Grafana Pyroscope]: https://github.com/grafana/pyroscope +[modules]: https://grafana.com/docs/alloy/latest/concepts/modules/ +[cluster]: https://grafana.com/docs/alloy/latest/concepts/clustering/ +[remotecfg]: https://grafana.com/docs/alloy/latest/reference/config-blocks/remotecfg/ +[ui]: https://grafana.com/docs/alloy/latest/tasks/debug/ ## Example -```river -// Discover Kubernetes pods to collect metrics from. -discovery.kubernetes "pods" { - role = "pod" -} +```alloy +otelcol.receiver.otlp "example" { + grpc { + endpoint = "127.0.0.1:4317" + } -// Collect metrics from Kubernetes pods. -prometheus.scrape "default" { - targets = discovery.kubernetes.pods.targets - forward_to = [prometheus.remote_write.default.receiver] + output { + metrics = [otelcol.processor.batch.example.input] + logs = [otelcol.processor.batch.example.input] + traces = [otelcol.processor.batch.example.input] + } } -// Get an API key from disk. -local.file "apikey" { - filename = "/var/data/my-api-key.txt" - is_secret = true +otelcol.processor.batch "example" { + output { + metrics = [otelcol.exporter.otlp.default.input] + logs = [otelcol.exporter.otlp.default.input] + traces = [otelcol.exporter.otlp.default.input] + } } -// Send metrics to a Prometheus remote_write endpoint. -prometheus.remote_write "default" { - endpoint { - url = "http://localhost:9009/api/prom/push" - - basic_auth { - username = "MY_USERNAME" - password = local.file.apikey.content - } +otelcol.exporter.otlp "default" { + client { + endpoint = "my-otlp-grpc-server:4317" } } ``` -We maintain an example [Docker Compose environment][] that can be used to -launch dependencies to play with Grafana Alloy locally. +## Getting started + +Check out our [documentation][] to see: + +* [Installation instructions][install] for Alloy +* Steps for [Getting started][get-started] with Alloy +* The list of Alloy [components][] -[Docker Compose environment]: ./example/docker-compose/ +[documentation]: https://grafana.com/docs/alloy/latest +[install]: https://grafana.com/docs/alloy/latest/setup/install/ +[get-started]: https://grafana.com/docs/alloy/latest/getting_started/ +[components]: https://grafana.com/docs/alloy/latest/reference/components/ ## Release cadence @@ -106,25 +113,34 @@ OpenTelemetry Collector code if new versions are available. Minor releases published outside of the release cadence may not include these dependency updates. -Patch and security releases may be created at any time. +Patch and security releases may be published at any time. ## Community -To engage with the Grafana Alloy community: +To engage with the Alloy community: * Chat with us on our community Slack channel. To invite yourself to the Grafana Slack, visit and join the `#alloy` channel. -* Ask questions on the [Discussions page][]. -* [File an issue][] for bugs, issues, and feature suggestions. -* Attend the monthly [community call][]. -[Discussions page]: https://github.com/grafana/alloy/discussions -[File an issue]: https://github.com/grafana/alloy/issues/new -[community call]: https://docs.google.com/document/d/1TqaZD1JPfNadZ4V81OCBPCG_TksDYGlNlGdMnTWUSpo +* Ask questions on the [Grafana community website][community]. -## Contribute +* [File an issue][issue] for bugs, issues, and feature suggestions. + +* Attend the monthly [community call][community-call]. + +[community]: https://community.grafana.com +[issue]: https://github.com/grafana/alloy/issues/new +[community-call]: https://docs.google.com/document/d/1TqaZD1JPfNadZ4V81OCBPCG_TksDYGlNlGdMnTWUSpo + +## Contributing Refer to our [contributors guide][] to learn how to contribute. -[contributors guide]: ./docs/developer/contributing.md +Thanks to all the people who have already contributed! + + + + + +[contributors guide]: https://github.com/grafana/alloy/blob/main/docs/developer/contributing.md