Skip to content

Commit

Permalink
misc: create new README.md for Alloy (#40)
Browse files Browse the repository at this point in the history 
This does not yet include the new logo or updated screenshots; that will
come in a follow-up PR.
  • Loading branch information
@rfratto
rfratto authored Mar 19, 2024
1 parent 4d5df55 commit d1db6f8
Showing 1 changed file with 97 additions and 81 deletions.
178 changes: 97 additions & 81 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,97 +1,104 @@
<p align="center"><img src="docs/sources/assets/logo_and_name.png" alt="Grafana Alloy logo"></p>

[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.
<p>
<a href="https://github.com/grafana/alloy/releases"><img src="https://img.shields.io/github/release/grafana/alloy.svg" alt="Latest Release"></a>
<a href="https://grafana.com/docs/alloy/latest"><img src="https://img.shields.io/badge/Documentation-link-blue?logo=gitbook" alt="Documentation link"></a>
</p>

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:
<p>
<img src="https://grafana.com/media/docs/agent/grafana-agent-screenshot.png">
</p>

* 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

Expand All @@ -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 <https://slack.grafana.com/> 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!

<a href="https://github.com/grafana/alloy/graphs/contributors">
<img src="https://contributors-img.web.app/image?repo=grafana/alloy" />
</a>

[contributors guide]: https://github.com/grafana/alloy/blob/main/docs/developer/contributing.md

0 comments on commit d1db6f8

Please sign in to comment.