Set up Grafana Alloy on Grafana Labs

Supported platforms

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

Supported platforms

The following operating systems and hardware architectures are supported.

Linux

Architectures: AMD64, ARM64
Within the Linux distribution lifecycle

Windows

Minimum version: Windows Server 2016 or later, or Windows 10 or later.
Architectures: AMD64

macOS

Minimum version: macOS 10.13 or later
Architectures: AMD64 on Intel, ARM64 on Apple Silicon

FreeBSD

Within the FreeBSD lifecycle
Architectures: AMD64

Install Grafana Alloy

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

Install Grafana Alloy

You can install Alloy on Docker, Kubernetes, Linux, macOS, or Windows.

Alloy supports the following architectures:

Linux: AMD64, ARM64
Windows: AMD64
macOS: AMD64 on Intel, ARM64 on Apple Silicon
FreeBSD: AMD64

Note
Installing Alloy on other operating systems is possible, but isn’t recommended or supported.

Data collection

By default, Alloy sends anonymous usage information to Grafana Labs. Refer to data collection for more information about what data Grafana collects and how you can opt-out.

Migrate to Grafana Alloy

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

Migrate to Grafana Alloy

This section details how to migrate to Alloy from other common solutions.

Run Grafana Alloy

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

Run Grafana Alloy

Use the following pages to learn how to start, restart, and stop Alloy after it’s installed. For installation instructions, refer to Install Grafana Alloy.

The OpenTelemetry Engine

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

The Alloy OpenTelemetry Engine

You can run the OTel Engine using the CLI, Helm chart, or service installation.

Prerequisites

There are no additional prerequisites. The tools needed to run the OTel Engine are shipped within Alloy.

Before you start, validate your OpenTelemetry YAML configuration with the validate command:

alloy otel validate --config=<CONFIG_FILE>

While this is an experimental feature, it isn’t hidden behind an experimental feature flag like regular components. This maintains compatibility with the OpenTelemetry Collector.

Run with the CLI

The OTel Engine is available under the Alloy otel command. The CLI is the easiest way to experiment locally or on a single host. Refer to the OTel CLI documentation for more information.

The following example configuration file accepts telemetry over OTLP and sends it to the configured backend:

extensions:
  basicauth/my_auth:
    client_auth:
      username: <USERNAME>
      password: <PASSWORD>

receivers:
  otlp:
    protocols:
      grpc: {}
      http: {}

processors:
  batch:
    timeout: 1s
    send_batch_size: 512

exporters:
  otlphttp/my_backend:
    endpoint: <URL>
    auth:
      authenticator: basicauth/my_auth

service:
  extensions: [basicauth/my_auth]
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp/my_backend]

Replace the following:

<USERNAME>: Your username. If you’re using Grafana Cloud, this is your Grafana Cloud instance ID.
<PASSWORD>: Your password. If you’re using Grafana Cloud, this is your Grafana Cloud API token.
<URL>: The URL to export data to. If you’re using Grafana Cloud, this is your Grafana Cloud OTLP endpoint URL.

For more information about where to find these values for Grafana Cloud, refer to Send data using OpenTelemetry Protocol.

To start the OTel Engine, run the following command:

alloy otel --config=<CONFIG_FILE> [<FLAGS> ...]

Alloy then accepts incoming OTLP data on 0.0.0.0:4317 for gRPC and 0.0.0.0:4318 for HTTP requests. Metrics are also available on the default collector port and endpoint at 0.0.0.0:8888/metrics. Since the Default Engine isn’t running, the UI and metrics aren’t available at 0.0.0.0:12345/metrics.

Run the Alloy Engine extension

You can also run the OTel Engine with the Default Engine. Modify your YAML configuration to include the alloyengine extension. This extension accepts a path to the Default Engine configuration and starts a Default Engine pipeline alongside the OTel Engine pipeline.

The following example shows the configuration:

extensions:
  basicauth/my_auth:
    client_auth:
      username: <USERNAME>
      password: <PASSWORD>
  alloyengine:
    config:
      file: <ALLOY_CONFIG_PATH>
    flags:
      server.http.listen-addr: 0.0.0.0:12345

receivers:
  otlp:
    protocols:
      grpc: {}
      http: {}

processors:
  batch:
    timeout: 1s
    send_batch_size: 512

exporters:
  otlphttp/my_backend:
    endpoint: <URL>
    auth:
      authenticator: basicauth/my_auth

service:
  extensions: [basicauth/my_auth, alloyengine]
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp/my_backend]

Replace the following:

<ALLOY_CONFIG_PATH>: The path to your Default Engine configuration file.
<USERNAME>: Your username. If you’re using Grafana Cloud, this is your Grafana Cloud instance ID.
<PASSWORD>: Your password. If you’re using Grafana Cloud, this is your Grafana Cloud API token.
<URL>: The URL to export data to. If you’re using Grafana Cloud, this is your Grafana Cloud OTLP endpoint URL.

This example adds the alloyengine block in the extension declarations and enables the extension in the service block. You can then run Alloy with the exact same command as before:

alloy otel --config=<CONFIG_FILE> [<FLAGS> ...]

This command starts both the Default Engine and OTel Engine. The output of both engines is visible in the logs. You can access the Default Engine UI and metrics on port 12345.

Run with the OpenTelemetry Collector Helm chart

Use the upstream OpenTelemetry Collector Helm chart to run the OTel Engine. This approach delivers an identical upstream collector experience. It also ensures you get improvements, bug fixes, and security updates as they’re released.

The following example Helm values.yaml incorporates the same configuration seen above into a Kubernetes Deployment.

Note
In this configuration, binding port 8888 to 0.0.0.0 makes the metrics endpoint listen on all interfaces inside the Pod. This lets other Pods in the cluster reach it without using kubectl port-forward.

The configuration also sets the command.name key to bin/otelcol. This is the binary that runs the alloy otel sub-command. The Helm chart doesn’t expose custom commands, so this setting is necessary.

image:
  repository: grafana/alloy
  tag: latest

command: 
  name: "bin/otelcol"

mode: deployment

ports:
  metrics:
    enabled: true

alternateConfig:
  extensions:
    health_check:
      endpoint: 0.0.0.0:13133 # This is necessary for the k8s liveliness check
    basicauth/my_auth:
      client_auth:
        username: <USERNAME>
        password: <PASSWORD>

  receivers:
    otlp:
      protocols:
        grpc: {}
        http: {}

  processors:
    batch:
      timeout: 1s
      send_batch_size: 512

  exporters:
    otlphttp/my_backend:
      endpoint: <URL>
      auth:
        authenticator: basicauth/my_auth

  service:
    telemetry:
      metrics:
        readers:
          - pull:
              exporter:
                prometheus:
                  host: 0.0.0.0 
                  port: 8888
    extensions: [basicauth/my_auth, health_check]
    pipelines:
      traces:
        receivers: [otlp]
        processors: [batch]
        exporters: [otlphttp/my_backend]

Replace the following:

<USERNAME>: Your username. If you’re using Grafana Cloud, this is your Grafana Cloud instance ID.
<PASSWORD>: Your password. If you’re using Grafana Cloud, this is your Grafana Cloud API token.
<URL>: The URL to export data to. If you’re using Grafana Cloud, this is your Grafana Cloud OTLP endpoint URL.

The Helm chart ships with a default OpenTelemetry Collector configuration in the config field. The upstream Helm chart documentation describes this field. If you want to completely override that default configuration, use the alternateConfig field. In the example above, the alternateConfig field ensures the configuration matches the other examples in this document and doesn’t inherit any of the chart’s defaults. Alternatively, you can omit both config and alternateConfig to use the default configuration as-is. You can also provide your own config block that merges with the chart’s default configuration.

Refer to the upstream documentation for more information about how to configure the helm chart to work for your use case.

Run with service installation

Service installation support for systemd, launchd, and similar systems isn’t included in the initial experimental release. Service installers work seamlessly with the OTel Engine as the feature matures. In the meantime, use the CLI or Helm options for testing.

Considerations

Storage configuration: The Default Engine accepts the --storage.path flag to set a base directory for components to store data on disk. The OTel Engine uses the filestorage extension instead of a CLI flag. Refer to the upstream documentation for more information.
Server ports: The Default Engine exposes its HTTP server on port 12345. The OTel Engine exposes its HTTP server on port 8888. The OTel Engine HTTP server doesn’t expose a UI, support bundles, or reload endpoint functionality like the Default Engine does.
Fleet management: Grafana Fleet Management doesn’t support the OTel Engine yet. You must define and manage the input configuration manually.

Next steps

Refer to OpenTelemetry in Alloy for information about the included components.
Refer to the OTel CLI reference for more information about the OTel CLI.

Deploy Grafana Alloy

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

Deploy Grafana Alloy

Alloy is a flexible, vendor-neutral telemetry collector. This flexibility means that Alloy doesn’t enforce a specific deployment topology but can work in multiple scenarios.

This page lists common topologies used for Alloy deployments, when to consider using each topology, issues you may run into, and scaling considerations.

As a centralized collection service

Deploying Alloy as a centralized service is recommended for collecting application telemetry. This topology allows you to use a smaller number of collectors to coordinate service discovery, collection, and remote writing.

Using this topology requires deploying Alloy on separate infrastructure, and making sure that they can discover and reach these applications over the network. The main predictor for the size of an Alloy deployment is the number of active Prometheus metrics series it’s scraping. A rule of thumb is approximately 10 KB of memory for each series. We recommend you start looking towards horizontal scaling around the 1 million active series mark.

Use Kubernetes StatefulSets

Deploying Alloy as a StatefulSet is the recommended option for Prometheus metrics collection. The persistent Pod identifiers make it possible to consistently match volumes with pods so that you can use them for the WAL directory.

You can also use a Kubernetes Deployment in cases where persistent storage isn’t required, such as a traces-only pipeline.

Pros

Straightforward scaling using clustering
Minimizes the “noisy neighbor” effect
Easy to meta-monitor

Cons

Requires running on separate infrastructure

Use for

Scalable telemetry collection

Don’t use for

Host-level metrics and logs

As a host daemon

Deploying one Alloy instance per machine is required for collecting machine-level Prometheus metrics and logs, such as node_exporter hardware and network metrics or journald system logs.

Each Alloy instance requires you to open an outgoing connection for each remote endpoint it’s shipping data to. This can lead to NAT port exhaustion on the egress infrastructure. Each egress IP can support up to (65535 - 1024 = 64511) outgoing connections on different ports. So, if all Alloys are sending Prometheus metrics and log data, an egress IP can support up to 32,255 collectors.

Use Kubernetes DaemonSets

The simplest use case of the host daemon topology is a Kubernetes DaemonSet, and it’s required for node-level observability (for example cAdvisor metrics) and collecting Pod logs.

Pros

Doesn’t require running on separate infrastructure
Typically leads to smaller-sized collectors
Lower network latency to instrumented applications

Cons

Requires planning a process for provisioning Alloy on new machines, as well as keeping configuration up to date to avoid configuration drift
Not possible to scale independently when using Kubernetes DaemonSets
Scaling the topology can strain external APIs (like service discovery) and network infrastructure (like firewalls, proxy servers, and egress points)

Use for

Collecting machine-level Prometheus metrics and logs (for example, node_exporter hardware metrics, Kubernetes Pod logs)

Don’t use for

Scenarios where Alloy grows so large it can become a noisy neighbor
Collecting an unpredictable amount of telemetry

As a container sidecar

Deploying Alloy as a container sidecar is only recommended for short-lived applications or specialized Alloy deployments.

Use Kubernetes Pod sidecars

In a Kubernetes environment, the sidecar model consists of deploying Alloy as an extra container on the Pod. The Pod’s controller, network configuration, enabled capabilities, and available resources are shared between the actual application and the sidecar Alloy.

Pros

Doesn’t require running on separate infrastructure
Straightforward networking with partner applications

Cons

Doesn’t scale separately
Makes resource consumption harder to monitor and predict
Each Alloy instance doesn’t have a life cycle of its own, making it harder to do things like recovering from network outages

Use for

Serverless services
Job/batch applications that work with a push model
Air-gapped applications that can’t be otherwise reached over the network

Don’t use for

Long-lived applications
Scenarios where the Alloy deployment size grows so large it can become a noisy neighbor

Process different types of telemetry in different Alloy instances

If the load on Alloy is small, you can process all necessary telemetry signals in the same Alloy process. For example, a single Alloy deployment can process all of the incoming metrics, logs, traces, and profiles.

However, if the load on Alloy is big, it may be beneficial to process different telemetry signals in different deployments of Alloy.

This provides better stability due to the isolation between processes. For example, an overloaded Alloy instance processing traces won’t impact an Alloy instance processing metrics. Different types of signal collection require different methods for scaling:

“Pull” components such as prometheus.scrape and pyroscope.scrape are scaled using hashmod sharing or clustering.
“Push” components such as otelcol.receiver.otlp are scaled by placing a load balancer in front of the components.

Traces

Scaling Alloy instances for tracing is very similar to scaling OpenTelemetry Collector instances. This similarity is because most Alloy components used for tracing are based on components from the OTel Collector.

When to scale

To decide whether scaling is necessary, check metrics such as:

otelcol_receiver_refused_spans_total from receivers such as otelcol.receiver.otlp.
otelcol_receiver_refused_spans_total from processors such as otelcol.processor.batch.
otelcol_exporter_send_failed_spans_total from exporters such as otelcol.exporter.otlp and otelcol.exporter.loadbalancing.

Stateful and stateless components

In the context of tracing, a “stateful component” is a component that needs to aggregate certain spans to work correctly. A “stateless Alloy” is an Alloy instance which doesn’t contain stateful components.

Scaling stateful Alloy instances is more difficult, because spans must be forwarded to a specific Alloy instance according to a span property such as trace ID or a service.name attribute. You can forward spans with otelcol.exporter.loadbalancing.

Examples of stateful components:

otelcol.processor.tail_sampling
otelcol.connector.spanmetrics
otelcol.connector.servicegraph

A “stateless component” doesn’t need to aggregate specific spans to work correctly. It can work correctly even if it only has some of the spans of a trace.

A stateless Alloy instance can be scaled without using otelcol.exporter.loadbalancing. For example, you could use an off-the-shelf load balancer to do a round-robin load balancing.

Examples of stateless components:

otelcol.processor.probabilistic_sampler
otelcol.processor.transform
otelcol.processor.attributes
otelcol.processor.span

Configure autoscaling

You can configure Alloy to automatically scale based on resource utilization using a Kubernetes Horizontal Pod Autoscaler (HPA).

The following example shows how to configure autoscaling using the Kubernetes Monitoring Helm chart:

cluster:
  name: autoscaling-example-cluster

destinations:
  - name: prometheus
    type: prometheus
    url: http://prometheus.prometheus.svc:9090/api/v1/write

clusterMetrics:
  enabled: true

alloy-metrics:
  enabled: true
  alloy:
    resources:
      requests:
        cpu: "1m"
        memory: "500Mi"
  controller:
    autoscaling:
      enabled: true
      minReplicas: 2
      maxReplicas: 10
      targetCPUUtilizationPercentage: 0
      targetMemoryUtilizationPercentage: 80

This configuration:

Sets minimum and maximum replica counts. In this example, the range is 2 to 10.
Targets 80% memory utilization as the scaling threshold.
Disables CPU-based scaling by setting targetCPUUtilizationPercentage to 0.

Memory-based scaling is typically more effective for Alloy because memory usage correlates more directly with the number of active series.

Estimate Grafana Alloy resource usage

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

Estimate Grafana Alloy resource usage

This page provides guidance for expected resource usage of Alloy for each telemetry type, based on operational experience of some of the Alloy maintainers.

Note
The resource usage depends on the workload, hardware, and the configuration used. The information on this page is a good starting point for most users, but your actual usage may be different.

Prometheus metrics

The Prometheus metrics resource usage depends mainly on the number of active series that need to be scraped and the scrape interval.

As a rule of thumb, per each 1 million active series and with the default scrape interval, you can expect to use approximately:

0.4 CPU cores
11 GiB of memory
1.5 MiB/s of total network bandwidth, send and receive

These recommendations are based on deployments that use clustering, but they broadly apply to other deployment modes. Refer to Deploy Grafana Alloy for more information on how to deploy Alloy.

Loki logs

Loki logs resource usage depends mainly on the volume of logs ingested.

As a rule of thumb, per each 1 MiB/second of logs ingested, you can expect to use approximately:

1 CPU core
120 MiB of memory

These recommendations are based on Kubernetes DaemonSet deployments on clusters with relatively small number of nodes and high logs volume on each. The resource usage can be higher per each 1 MiB/second of logs if you have a large number of small nodes due to the constant overhead of running the Alloy on each node.

Additionally, factors such as number of labels, number of files and average log line length may all play a role in the resource usage.

Pyroscope profiles

Pyroscope profiles resource usage depends mainly on the volume of profiles.

As a rule of thumb, per each 100 profiles/second, you can expect to use approximately:

1 CPU core
10 GiB of memory

Factors such as size of each profile and frequency of fetching them also play a role in the overall resource usage.