Introduction to Grafana Alloy on Grafana Labs

Why Grafana Alloy

Mon, 30 Mar 2026 15:47:22 +0000

Why Grafana Alloy

Grafana Alloy simplifies telemetry collection by consolidating multiple collectors into one solution.

The telemetry collection challenge

Telemetry collection in production environments can quickly become complex as different teams develop different needs over time.

Consider a common scenario. You start with infrastructure observability, using Prometheus to scrape metrics from Node Exporter. Your metrics flow to a Prometheus database, and you visualize them in Grafana dashboards. This works well for monitoring infrastructure.

Later, you want to add application observability and start analyzing distributed traces. Prometheus doesn’t support traces, so you add the OpenTelemetry Collector. Now you’re running two different collectors, each with its own configuration syntax, deployment requirements, and operational overhead.

As your observability needs grow, you might add a separate collector for logs, another tool for continuous profiling, and different agents for different environments. Before long, you’re managing multiple collectors, learning different configuration languages, troubleshooting various failure modes, and dealing with increased memory and CPU overhead.

Alloy addresses these challenges by handling all signal types in a single deployment with one configuration language. You learn one tool, deploy one collector, and maintain one system.

When to use Alloy

Alloy excels in several scenarios. The following sections help you identify whether it fits your needs.

You need multiple signal types

Alloy natively supports metrics from both Prometheus and OpenTelemetry sources, application and system logs, distributed traces using OpenTelemetry, and continuous profiling data.

If you’re running separate collectors for metrics and traces, or planning to add log collection to your metrics pipeline, Alloy lets you consolidate into a single solution.

For example, if you monitor infrastructure with Prometheus but want to add distributed tracing for your microservices, you can use Alloy to handle both with one collector instead of deploying multiple collectors.

You want to reduce collector complexity

Running multiple collectors creates operational overhead. You have to learn different configuration languages, manage separate deployments and upgrades, troubleshoot different failure modes, and monitor multiple systems—all while consuming more resources.

Alloy consolidates all of this. You learn one configuration language, manage one deployment, and use a single built-in UI for debugging. This unified approach reduces both complexity and resource consumption.

For example, if your team runs Prometheus for metrics, Fluentd for logs, and Jaeger agents for traces, Alloy can replace all three and simplify your telemetry architecture.

You need both Prometheus and OpenTelemetry

Alloy works with both ecosystems simultaneously. It includes native Prometheus remote write support, full OpenTelemetry protocol support, Prometheus service discovery mechanisms, OpenTelemetry instrumentation compatibility, and the ability to convert between formats.

You don’t have to choose between Prometheus and OpenTelemetry. If you have Prometheus deployments and instrumentation but your applications use OpenTelemetry, Alloy collects from both while you standardize on one collector.

You value vendor neutrality

Alloy supports sending data to Grafana Cloud, a self-managed Grafana stack with Loki, Mimir, Tempo, and Pyroscope, any Prometheus-compatible database, any OpenTelemetry-compatible backend, or multiple destinations simultaneously.

This flexibility means you’re not locked into a single vendor or backend. You can send data to Grafana Cloud for some telemetry and self-managed systems for others, or change backends without changing your collector.

For example, if you want to send metrics to Grafana Cloud but keep logs on-premises for compliance reasons, Alloy can send metrics to the cloud and logs to your local Loki instance from the same configuration.

Your observability needs are growing

Alloy provides features for scaling, including clustering to distribute workload across multiple instances for high availability and horizontal scaling, remote configuration to manage fleet-wide configurations from a central location, and automatic workload distribution across cluster members.

Start with a single Alloy instance and scale to clusters as your needs grow, without changing your approach.

You’re running on Kubernetes

Alloy offers Kubernetes-native features including first-class support for discovering Kubernetes resources, components that interact with Kubernetes APIs directly, native understanding of pods, services, and custom resources, and support for DaemonSet and Deployment patterns.

No separate Kubernetes operator is required. The Kubernetes discovery components automatically find and scrape pods as they start and stop, without additional configuration.

You want programmable pipelines

The Alloy configuration language lets you create conditional logic in your pipelines, reference data from one component in another, build reusable pipeline modules, transform and filter data with built-in functions, and respond dynamically to changing conditions.

If you need more than basic “collect and forward” functionality, the programmable approach provides the flexibility you need. Common scenarios include routing high-priority metrics to one backend while sampling lower-priority data, extracting useful labels from high-cardinality fields to manage storage costs, standardizing attribute names when different teams use inconsistent conventions, and redacting sensitive tokens or credentials from logs before they reach storage.

The module system allows you to create custom components that combine multiple steps, package and share pipelines with your team, use community-contributed modules, and maintain consistent collection patterns across services.

Your platform team can create a standard monitoring module that application teams import and configure with their specific settings, without understanding the underlying complexity.

What Alloy replaces

Alloy can consolidate multiple collectors. Replace Prometheus Agent to gain the same functionality plus support for logs, traces, and profiles. Replace the OpenTelemetry Collector to add native Prometheus support alongside OTLP. Replace specialized log collectors like Promtail, Fluentd, or Filebeat with a unified collection approach.

You can also run Alloy alongside collectors during migration to transition gradually without disrupting your observability. Refer to the migration guides for step-by-step instructions.

When Alloy might not be the right choice

Alloy is powerful and flexible, but it’s not always the best fit.

Consider alternatives if you only need basic Prometheus metrics scraping with no additional features, as Prometheus Agent might be simpler. If you’re deeply integrated with a specific collector’s ecosystem and don’t need multi-signal support, staying with your current solution may make more sense. If you have very specific requirements that available components don’t address, evaluate whether the benefits outweigh the effort of migration.

Next steps

Learn how Alloy works to understand the architecture
Review requirements and expectations to understand deployment considerations
Install Alloy to get started
Follow a tutorial for hands-on experience

How Grafana Alloy works

Mon, 30 Mar 2026 15:47:22 +0000

How Grafana Alloy works

Understanding the architecture and design of Alloy helps you use it effectively.

Where Alloy fits

A typical observability setup has three layers: data sources that generate telemetry, collection tools that gather and process it, and storage backends with visualization frontends for querying and exploring data.

Alloy operates in the collection layer, sitting between your data sources and your storage backends. It acts as the bridge between them, performing three main functions in your telemetry pipeline.

Collect telemetry data

Alloy gathers telemetry from any source in your infrastructure. You can configure it to scrape Prometheus endpoints for metrics or set up receivers to accept data pushed via the OpenTelemetry protocol. It tails log files and reads from system outputs to capture application and infrastructure logs. Service discovery automatically finds resources in Kubernetes, Docker, or cloud environments without requiring static configuration. You can also integrate with databases, message queues, and other systems to capture telemetry from specialized sources.

Transform and process data

Processing telemetry before sending it to backends optimizes costs and improves data quality. Create filters to drop unwanted data or redact sensitive information like tokens and credentials from logs before they reach storage. Add labels, metadata, or contextual information to enrich your data—for example, extract a cloud provider name from instance IDs to create useful aggregation labels. Standardize attribute names across services when different teams use inconsistent naming conventions. Implement sampling strategies to reduce high-volume data while preserving the signal you need for troubleshooting. Convert between formats, such as transforming Prometheus metrics to OpenTelemetry format, to ensure compatibility with your backends. Define routing rules to send different types of data to different destinations based on your operational requirements.

Send to backends

Alloy delivers processed telemetry to any storage system you choose. Send data to Grafana Cloud for managed observability, or export to your self-managed Grafana stack components. Connect to any Prometheus-compatible database for metrics and any OpenTelemetry-compatible backend for all signal types. Write to multiple destinations simultaneously, sending the same data to different systems or routing different data types to specialized backends.

Component-based architecture

Alloy uses modular components that work like building blocks. Each component performs a specific task, such as collecting metrics from Prometheus endpoints, receiving OpenTelemetry data, transforming and filtering telemetry, or sending data to backends.

You connect these components together to build pipelines that match your exact requirements. This modular approach makes configurations easier to understand, test, and maintain.

Programmable pipelines

Alloy uses a rich, expression-based configuration language that lets you reference data from one component in another, create dynamic configurations that respond to changing conditions, build reusable pipelines you can share across teams, and use built-in functions to transform and filter data.

Custom and shareable pipelines

You can create custom components that combine multiple components into a single, reusable unit. Share these custom components with your team or the community through the module system. Use pre-built modules from the community or create your own.

Enterprise-ready features

As your systems grow more complex, Alloy scales with you. Clustering lets you configure instances to form a cluster for automatic workload distribution and high availability. Centralized configuration retrieves settings from remote servers for fleet management. Kubernetes-native capabilities let you interact with Kubernetes resources directly without learning separate operators.

Built-in debugging tools

Alloy includes a built-in user interface that helps you visualize your component pipelines, inspect component states and outputs, troubleshoot configuration issues, and monitor performance.

Deployment patterns

Choose the deployment pattern that fits your architecture.

Edge deployment: Deploy Alloy close to your data sources for minimal latency. Run it as a DaemonSet in Kubernetes to collect from every node, install it on each host for infrastructure monitoring, or deploy it alongside applications for local processing.

Gateway deployment: Deploy Alloy as a centralized gateway. Configure your applications to send telemetry to Alloy gateways, which process and forward data to backends. Applications only need to know about the gateway endpoints.

Hybrid deployment: Combine edge and gateway approaches. Deploy edge instances to handle initial collection and filtering close to sources, then forward to gateway instances for aggregation and final processing. This pattern reduces bandwidth usage and enables centralized policy enforcement while maintaining local processing capabilities.

Integrations

Alloy integrates with Grafana Cloud and self-managed Grafana stacks, routing metrics to Mimir, logs to Loki, traces to Tempo, and profiles to Pyroscope. It also works with the broader Prometheus ecosystem through full compatibility with the Prometheus exposition format and service discovery mechanisms, and with any OpenTelemetry-compatible backend through OTLP support.

You can also connect to other ecosystems, including InfluxDB, Elasticsearch, and cloud platforms like AWS, Google Cloud Platform, and Azure.

Next steps

Review requirements and expectations to understand deployment considerations
Install Alloy to get started
Learn core concepts including components, expressions, and pipelines
Follow tutorials for hands-on experience
Explore the component reference to see available components

OpenTelemetry in Alloy

Mon, 30 Mar 2026 15:47:22 +0000

OpenTelemetry in Alloy

Grafana Alloy combines the Prometheus-native, production-grade collection features of Alloy with the broad ecosystem and standards of OpenTelemetry. The Alloy OpenTelemetry Engine is a bundled OpenTelemetry Collector distribution embedded within Alloy. It lets you run Alloy as a fully compatible OTel Collector while retaining access to all Alloy features and integrations.

EXPERIMENTAL: OTel Engine is an experimental feature. Experimental features are subject to frequent breaking changes, and may be removed with no equivalent replacement.

To maintain full compatibility of the OTel Engine with the upstream OpenTelemetry Collector and expose a compatible command line interface, the OTel Engine isn’t hidden behind a stability flag.

Make sure that you understand the risks involved before using an experimental feature in your production environments.

Terminology

Alloy supports two runtime engines and an extension:

Default Engine: The default Alloy runtime and configuration syntax. This remains the default, stable experience with backward compatibility guarantees for Alloy users.
OTel Engine: The standard OpenTelemetry Collector runtime embedded within Alloy. It uses upstream collector YAML configuration for pipelines and components.
Alloy Engine extension: An OpenTelemetry Collector extension that lets you run both the Default Engine and the OTel Engine in parallel.

Included components

The OTel Engine bundle includes:

Standard components from the OpenTelemetry Collector core
A curated selection of components from contributor repositories
The alloyengine extension

Alloy v1.15.1 bundles versions v0.147.0 of OpenTelemetry Collector components. You can find more information about the bundled version in both the OpenTelemetry Collector and OpenTelemetry Collector Contrib repositories.

The following sections list all included components:

To view the full list of components and their versions, refer to the OpenTelemetry Collector Builder manifest.

Next steps

Refer to The OTel Engine for information about how to run the OTel Engine.
Refer to the OTel CLI reference for more information about the OTel CLI.

Requirements and expectations

Mon, 30 Mar 2026 15:47:22 +0000

Requirements and expectations

Before you put Grafana Alloy into production, it helps to have a clear picture of where it runs well, how it’s usually deployed, and where people most often get surprised.

Before a first deployment, people usually want answers to a few basic questions:

Will Alloy run in my environment?
How should I deploy it the first time?
What kinds of constraints or trade-offs should I expect?

The guidance here focuses on the common, supported paths that work well for most users, without diving into every possible edge case.

Design expectations

Grafana Alloy makes telemetry collection explicit and predictable, even when that means exposing trade-offs that other tools try to hide.

A few design choices are worth keeping in mind:

Alloy favors explicit configuration over implicit behavior. You define pipelines, routing, and scaling decisions in configuration rather than relying on automatic inference.
Alloy exposes deployment and scaling choices instead of masking them. Changes in topology—such as switching from a DaemonSet to a centralized deployment—can affect behavior, and those effects are intentional and visible.
Alloy consolidates multiple collectors, but it doesn’t replicate every default or assumption from these other collectors. Similar concepts may behave differently when the underlying goals differ.
Alloy prioritizes predictability over “magic” defaults. Understanding how components connect and how work distributes is part of operating Alloy successfully.

Keeping these expectations in mind makes it easier to reason about configuration changes, scaling decisions, and observed behavior in production.

Supported platforms

Alloy runs on the following platforms:

Linux
Windows
macOS
FreeBSD

For supported architectures and version requirements, refer to Supported platforms.

For setup instructions, refer to Set up Alloy.

Network requirements

Alloy requires network access for its HTTP server and for sending data to backends.

HTTP server

Alloy runs an HTTP server for its UI, API, and metrics endpoints. By default, it listens on 127.0.0.1:12345.

For more information, refer to HTTP endpoints.

Outbound connectivity

Alloy needs outbound network access to send telemetry to your backends. Ensure firewall rules and egress rules allow connections to:

Remote write or OTLP endpoints for metrics, such as Mimir, Prometheus, or Thanos
Log ingestion endpoints, such as Loki, Elasticsearch, or OTLP-compatible backends
Trace ingestion endpoints, such as Tempo, Jaeger, or OTLP-compatible backends
Profile ingestion endpoints, such as Pyroscope

Cluster communication

When you enable clustering, Alloy nodes communicate over HTTP/2 using the same HTTP server port. Each node must be reachable by other cluster members on the configured listen address.

Permissions and access

Some Alloy components interact closely with the host, container runtime, or Kubernetes APIs. When that happens, Alloy needs enough access to complete the work.

This requirement most often comes up when collecting:

Host-level metrics, logs, traces, or profiles
Container or runtime information
Data that lives outside the application sandbox

Not every component can run in a fully locked-down environment. When Alloy runs with restricted permissions, certain components might fail or behave unexpectedly.

For information about running as a non-root user, refer to Run as a non-root user.

When you enable a component, check its documented requirements first. Refer to the component reference for component-specific constraints and limitations.

Security

Alloy supports TLS for secure communication. Configure TLS in component tls blocks for backend connections, or use the --cluster.enable-tls flag for clustered mode. Authentication methods such as basic auth, OAuth2, and bearer tokens are configured per component.

Secrets management

Store sensitive values like API keys and passwords outside your configuration files. Alloy supports environment variable references and integrations such as HashiCorp Vault, Kubernetes Secrets, AWS S3, and local files.

Refer to the component documentation for specific options.

Deployment patterns

Alloy supports edge, gateway, and hybrid deployment patterns. Refer to How Alloy works for guidance on choosing the right pattern for your architecture.

For detailed setup instructions, refer to Deploy Alloy.

Clustering and scaling behavior

Some Alloy behavior depends on how you deploy it, not just on configuration.

Alloy supports clustering to distribute work across multiple instances. Clustering uses a gossip protocol and consistent hashing to distribute scrape targets automatically.

Note
Target auto-distribution requires enabling clustering at both the instance level and the component level. Refer to Clustering for configuration details.

A few things that often surprise users:

More Alloy instances means more meta-monitoring metrics.
A switch between DaemonSet and centralized deployments can change observed series counts.
Scaling clustered collectors changes how targets distribute, even when the target list stays the same.

For resource planning guidance, refer to Estimate resource usage.

Data durability

Alloy uses a Write-Ahead Log (WAL) for metrics to handle temporary backend outages. The WAL buffers data locally and retries sending when the backend becomes available.

For the WAL to persist across restarts, configure persistent storage using the --storage.path flag.

Note
Without persistent storage, Alloy loses buffered data on restart. By default, Alloy stores data in a temporary directory.

Push-based pipelines for logs, traces, and profiles have different durability characteristics. Refer to component documentation for more information.

Monitor Alloy

Alloy exposes metrics about its own health and performance at the /metrics endpoint.

Key monitoring capabilities:

Internal metrics: Controller and component metrics in Prometheus format
Health endpoints: /-/ready and /-/healthy for load balancer checks
Debugging UI: Visual component graph and live debugging at /

Refer to Set up meta-monitoring for configuration examples.

Component capabilities

Each Alloy component has its own capabilities and limits. Before you rely on a component in production, check:

Which signal types it accepts and emits: metrics, logs, traces, and profiles
Whether the component is stable or still evolving
Whether it’s a native Alloy component or wraps upstream OpenTelemetry Collector functionality

Refer to the component reference for this information.

Troubleshoot issues

If something doesn’t behave as expected after deployment:

Review Troubleshooting and debugging.
Check the component documentation.
Revisit deployment patterns and clustering assumptions.

Introduction to Grafana Alloy on Grafana Labs

Why Grafana Alloy

Why Grafana Alloy

The telemetry collection challenge

When to use Alloy

You need multiple signal types

You want to reduce collector complexity

You need both Prometheus and OpenTelemetry

You value vendor neutrality

Your observability needs are growing

You’re running on Kubernetes

You want programmable pipelines

You want to share pipelines across teams

What Alloy replaces

When Alloy might not be the right choice

Next steps

How Grafana Alloy works

How Grafana Alloy works

Where Alloy fits

Collect telemetry data

Transform and process data

Send to backends

Component-based architecture

Programmable pipelines

Custom and shareable pipelines

Enterprise-ready features

Built-in debugging tools

Deployment patterns

Integrations

Next steps

OpenTelemetry in Alloy

OpenTelemetry in Alloy

Terminology

Included components

Next steps

Requirements and expectations

Requirements and expectations

Design expectations

Supported platforms

Network requirements

HTTP server

Outbound connectivity

Cluster communication

Permissions and access

Security

Secrets management

Deployment patterns

Clustering and scaling behavior

Data durability

Monitor Alloy

Component capabilities

Troubleshoot issues

Next steps