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

misc: create new README.md for Alloy #40

Merged
merged 1 commit into from
Mar 19, 2024
Merged

misc: create new README.md for Alloy #40

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
178 changes: 97 additions & 81 deletions README.md
View file
Open in desktop
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" />
Copy link
Member Author

Choose a reason for hiding this comment

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

Note that this link won't work until the repo is public

</a>

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