This repository provides self-contained, runnable scenarios that show how to use Grafana Alloy for telemetry collection and processing. Most scenarios include Docker Compose files for Alloy and the backends that demo needs, such as Loki, Grafana, Prometheus, and Tempo. Each scenario also includes pre-configured dashboards when Grafana is part of the stack.
Ensure you have the following:
- Docker and Docker Compose.
- Git, to clone the repository.
Navigate to the scenario directory and open the README file. The scenario README documents everything you need to know to deploy and explore the scenario.
From the repository root, you can start Docker-based scenarios with pinned image versions: ./run-example.sh <scenario-dir>.
Image versions are in image-versions.env.
Kubernetes scenarios use Helm charts.
Most Docker-based scenarios expose Grafana at http://localhost:3000 and the Alloy UI at http://localhost:12345. You don't need to log in to Grafana in these scenarios. Refer to the scenario README for additional endpoints.
Browse scenarios by telemetry type. Each row links to a directory with a README and all the configuration files required to deploy and run the scenario.
These scenarios focus on log collection, log parsing, log routing, and log redaction.
| Scenario | Description |
|---|---|
| Amazon Data Firehose logs | Ingest Amazon Data Firehose deliveries with loki.source.awsfirehose. Uses a local sender. No AWS account required. |
| GELF log ingestion | Ingest Graylog Extended Log Format logs over UDP. |
| Kafka logs | Consume and process logs from Apache Kafka topics. |
| Log API gateway | Use Alloy as a centralized log gateway that accepts logs via a Loki-compatible push API endpoint. |
| Log routing | Route logs from multiple sources to different Loki tenants based on log content and origin. |
| Log secret filtering | Redact sensitive credentials and secrets from logs with pattern rules before storage. |
| Logs from file | Tail log files with Alloy. |
| Logs over TCP | Receive and process TCP logs in JSON format. |
| Popular logging frameworks | Parse logs from popular logging frameworks across 7 programming languages. |
| Structured log parsing | Parse structured logs into labels and structured metadata. |
| Syslog monitoring | Monitor non-RFC5424 compliant syslog messages with rsyslog and Alloy. |
| systemd journal | Forward systemd journal entries to Loki with filters and labels tuned for fast queries. |
| Windows security events | Forward Windows Security event logs to Loki with filters and field extraction for security operations center workflows. |
These scenarios show distributed tracing with OpenTelemetry and Tempo.
| Scenario | Description |
|---|---|
| Distributed tracing | Learn distributed tracing through a sofa delivery workflow from order to doorstep. |
| Game of tracing | Play an interactive strategy game that teaches distributed tracing, sampling, and service graphs. |
| OpenTelemetry basic tracing | Collect and visualize OpenTelemetry traces with Alloy and Tempo. |
| OpenTelemetry service graphs | Generate service graphs with the Alloy servicegraph connector. |
| OpenTelemetry span metrics | Generate RED metrics from OpenTelemetry traces with the span metrics connector. Request rate, error rate, and duration. |
| OpenTelemetry tail sampling | Apply tail sampling policies to OpenTelemetry traces with Alloy and Tempo. |
These scenarios collect and forward metrics with Alloy.
| Scenario | Description |
|---|---|
| Alloy clustering | Run a three-node Alloy cluster that consistent-hashes prometheus.scrape targets across nodes. Stop a node and its targets redistribute to the survivors within seconds. |
| Blackbox probing | Monitor endpoint availability and response times with synthetic HTTP probes. |
| OTel metrics pipeline | Forward OpenTelemetry metrics from applications through Alloy. Alloy batches and transforms samples before it sends them to Prometheus. |
These scenarios collect continuous profiles from applications.
| Scenario | Description |
|---|---|
| Continuous profiling | Collect and visualize CPU, memory, and goroutine profiles from Go applications with Grafana Pyroscope. |
| eBPF host profiling | Profile every process on a Linux host with pyroscope.ebpf -- no language agents, no application code changes. Uses Docker container discovery to attribute samples per workload. |
These scenarios load credentials and configuration from external stores.
| Scenario | Description |
|---|---|
| Vault secrets | Pull prometheus.remote_write basic_auth credentials from HashiCorp Vault at runtime with remote.vault. Credentials reload on rotation. |
These scenarios collect telemetry from browser applications.
| Scenario | Description |
|---|---|
| Faro frontend observability | Collect frontend web telemetry, including logs, errors, and web vitals, from browser applications with the Faro Web SDK. |
These scenarios pull telemetry from cloud provider APIs.
| Scenario | Description |
|---|---|
| Amazon CloudWatch metrics | Pull metrics from Amazon CloudWatch into Prometheus with prometheus.exporter.cloudwatch. Uses LocalStack for offline reproducibility. No AWS account required. |
These scenarios monitor hosts, containers, and network devices.
| Scenario | Description |
|---|---|
| Docker monitoring | Monitor Docker container metrics and logs. |
| Linux monitoring | Collect Linux system metrics, journal entries, and log files with Alloy. |
| Windows monitoring | Monitor Windows system metrics and Event Logs. |
| NGINX monitoring | Monitor NGINX access and error logs plus stub_status metrics with Alloy. |
| Self-monitoring | Configure Alloy to monitor itself and collect its own metrics and logs. |
| SNMP monitoring | Monitor devices with the Alloy SNMP exporter for Simple Network Management Protocol. |
These scenarios monitor databases and in-memory caches.
| Scenario | Description |
|---|---|
| Elasticsearch monitoring | Monitor Elasticsearch cluster health, node status, and performance metrics. |
| Memcached monitoring | Monitor Memcached instance metrics, including connections, memory usage, and command performance. |
| MongoDB monitoring | Monitor MongoDB op-counters, connection pool, and replica-set replication metrics with prometheus.exporter.mongodb. Runs a single-node replica set with an insert load generator. |
| MySQL monitoring | Monitor MySQL database server metrics and performance indicators. |
| PostgreSQL monitoring | Monitor PostgreSQL transaction statistics, connections, and server configuration. |
| RabbitMQ monitoring | Monitor RabbitMQ queue, connection, and channel metrics plus broker container logs. |
| Redis monitoring | Monitor Redis instance metrics, including connections, memory usage, and command throughput. |
The k8s/ directory groups Helm-based and manifest-based examples for Alloy on Kubernetes.
| Scenario | Description |
|---|---|
| Kubernetes | Scenarios for Alloy on Kubernetes with the k8s-monitoring Helm chart or plain manifests. See subdirectories for logs, metrics, profiling, tracing, and cluster events. |
Alloy v1.14 and later include an experimental OTel Engine that runs standard OpenTelemetry Collector YAML configurations directly. These scenarios use OTel YAML syntax for teh OTel Engine and a minimal Alloy configuration to enable the Alloy UI. Refer to the OTel examples README for details.
| Scenario | Description |
|---|---|
| Cost control | Drop health checks, filter debug logs, and apply probabilistic sampling to cut telemetry volume. |
| Count connector | Derive request rate and error rate metrics from traces and logs with the count connector. |
| File log processing | Collect and parse mixed-format log files with the OTel filelog receiver and operator chains. |
| Host metrics | Collect CPU, memory, disk, and network metrics with the hostmetrics receiver. |
| Kafka buffer | Buffer traces through Kafka for durability and backpressure control. |
| Multi-pipeline fan-out | Send traces to two backends. Each destination runs its own process path. |
| Multi-tenant routing | Route logs to different Loki tenants based on resource attributes with fan-out and filter. |
| OTTL transform cookbook | A cookbook of OpenTelemetry Transformation Language patterns for JSON parsing, severity mapping, attribute promotion, and truncation. |
| PII redaction | Scrub personally identifiable information, credit cards, emails, and IP addresses from traces and logs with OpenTelemetry Transformation Language replace_pattern. |
| Resource enrichment | Attach host, OS, and Docker metadata to all signals with resourcedetection. |
Contributions of scenarios and improvements are welcome. You can contribute in several ways.
Share an idea when you don't have time to implement a full scenario.
- Open an issue on GitHub with the label
scenario-suggestion - Describe the scenario and what it would show
- Explain why this would be valuable to the community
- Outline any special requirements or considerations
Add a complete scenario to the repository.
- Fork this repository and create a branch
- Create a directory in the root of this repository with a descriptive name for your scenario
- Follow the scenario template section below
- Submit a pull request with your scenario
Update a scenario you want to change.
- Fork this repository and create a branch
- Make your improvements to the scenario
- Submit a pull request with a clear description of your changes
Include the following files when you create a scenario:
docker-compose.yml: Docker Compose file with the observability backends and Alloydocker-compose.coda.yml: Docker Compose override with the demo app services for use with thecodaCLI or-fflagconfig.alloy: Alloy configuration file for the scenarioREADME.md: Documentation that explains the scenario- Any additional files needed for your scenario, such as scripts or data files
Confirm the following items before you submit your scenario:
- Create a directory in the root of this repository with a descriptive name
- Include a
docker-compose.ymlfile with the necessary components, such as Loki, Grafana, Prometheus, or a subset - Create a complete
config.alloyfile that shows the monitoring approach - Write a
README.mdwith:- A clear description of what the scenario shows
- Prerequisites to run the demo
- Step-by-step instructions to run the demo
- Expected output and what to look for
- Explanation of key configuration elements
- Add the scenario to the table in this
README.md - Ensure the scenario works with the centralized image management system
- Verify all components start correctly with
docker compose up -d
Follow these guidelines when you author or update a scenario:
- Keep the scenario focused on one concept
- Use clear, descriptive component and variable names
- Add comments to explain complex parts of your Alloy configuration
- Include a Customize section in your
README.mdwith information about how readers might change the setup - Provide sample queries for Grafana, Prometheus, Loki, or Tempo that work with your scenario
- Use environment variables for versions and configurable parameters
If you have questions about a scenario or Alloy configuration, use these resources:
- Join the Grafana Labs Community Forums
- Read the Grafana Alloy documentation
This repository is licensed under the Apache License, Version 2.0. Refer to LICENSE for the full license text.