Grafana Alloy setup for metrics, logs and traces

What Grafana Alloy does in a self-hosted Grafana stack

Most teams reach Grafana Alloy after running several agents side by side: one for host metrics, another for container logs, a tracing agent for spans and perhaps a separate profiler. Each has its own configuration, upgrade cycle and failure mode. Grafana Alloy is an open source distribution of the OpenTelemetry Collector with built-in Prometheus pipelines, and it handles metrics, logs, traces and profiles in one tool. It builds each pipeline from components that receive, transform or export data, so one deployment can replace several agents when your signals can all leave through the same collector. Alloy is the collector, not the backend. It gathers telemetry from your hosts, applications and Kubernetes clusters and forwards it. Storage and querying stay with the systems you choose: Prometheus or another Prometheus-compatible store for metrics, Loki for logs, Tempo for traces and Pyroscope for profiles. Grafana sits on top of those stores to visualize the data and correlate it. Before you commit, confirm which backend receives each signal in your design, because Alloy does not replace any of them.

Standardizing on one collector shifts work rather than removing it. Your team will own component configuration, the access Alloy needs to each source, and the credentials it uses to reach each backend. Decide early whether collectors run on each host, as gateways in front of the backends, or both, since that choice drives how many instances you operate and where failures are isolated. Also confirm that the Alloy release you pick supports every component your pipelines need, and check its release notes before each upgrade, because collector components vary in maturity and the upstream OpenTelemetry Collector documentation describes how the core project is layered.

Prerequisites before installing Alloy

Alloy sits between your workloads and the stores that keep their telemetry, so most setup problems start before any configuration is written. Confirm the destinations, the paths to them and the hosts you will collect from before choosing an install method.

Grafana and query endpoints

Grafana reads from every store Alloy writes to, so the team needs a working Grafana instance with data sources planned for metrics, logs, and any traces or profiles. Grafana stores its own configuration in a database, and the installation docs say SQLite is not suited to production, so confirm the database choice before you wire up data sources. Check that Grafana can reach each backend, not only that Alloy can write to it.

Prometheus-compatible metrics store

Alloy's Prometheus pipelines send metrics to a Prometheus-compatible endpoint, which may be a single Prometheus server, a remote write receiver or a long-term store. A single Prometheus server is not clustered or replicated, so decide how long metrics must be kept and who manages that storage. Confirm the remote write endpoint, the expected sample volume and whether any series need to leave your network.

Loki and other signal backends

Loki receives logs from Alloy and needs object storage for chunks and its index in production, so confirm the bucket and retention plan before pointing Alloy at it. If traces or profiles are in scope, name the trace backend and profile backend now, since each one needs its own endpoint and credentials. Note that Loki has no built-in authentication layer, so writes must pass through an authenticating proxy or use a tenant header your team controls.

Alloy version and release channel

Record the Alloy version and release channel your team will standardize on, and check the release notes against each component you plan to use. Components differ in stability, and the OpenTelemetry Collector documents that core components have mixed stability levels, so confirm the maturity of each receiver and exporter. Pin the version in your deployment tooling so upgrades happen on purpose.

Network paths and endpoint authentication

List every connection Alloy will open, with its protocol, port and direction, and confirm each one through your firewalls and proxies. Decide how each endpoint authenticates: tokens, mutual TLS, basic auth or an OIDC-based authenticator extension where the Collector supports it. Store those credentials in a secrets system, not in plain configuration files.

Host and Kubernetes collection targets

Inventory the hosts, containers and Kubernetes clusters Alloy will collect from, including operating systems, log file locations and the scrape targets each team owns. Agents on each host or DaemonSets on each node differ in permissions and failure modes, so record which nodes need elevated access to read logs. Use this list to size the rollout and to decide which targets go into the first wave.

Configuring Alloy pipelines step by step

This sequence takes a self-hosted Grafana stack from a bare Alloy install to one collector that sends metrics, logs, traces and profiles to their backends. Each step ends with a check you can run before moving on, so faults stay isolated to the stage that introduced them.

Install Alloy on hosts or in the cluster
Your platform team installs Grafana Alloy on the hosts or Kubernetes nodes that will collect data, using the package or container method that matches your build process. Decide early whether Alloy runs as an agent beside each workload or as a gateway that receives from many sources, since that choice changes where your OTLP endpoints live. Confirm the install by checking that the Alloy service starts, that its built-in UI loads on the configured address, and that the configuration file loads without errors. Keep the file in version control from this point.
Define metric receivers and scrape jobs
Next, add Prometheus-compatible scrape components for the targets you already know, such as node exporters, application metrics endpoints and Kubernetes services. Set the scrape targets and intervals to match what your Prometheus-compatible store can hold, and label each job with the environment and team identifiers your dashboards will filter on. Check the result in Grafana by querying a series from one target in Explore and confirming its labels match the job definition. If the series is missing, check the target's endpoint from the Alloy host before changing the pipeline.
Collect logs into the pipeline
Add a log collection component that reads the files, container output or journal entries on each host and forwards them as log streams. Keep the label set small and stable, since Loki indexes labels and high-cardinality values such as request IDs belong in the log line instead. Verify the step by generating a known test message on a source host, then running a LogQL query in Grafana for the label set you configured. The test line should appear within the query window, with the labels you expected attached to it.
Add OTLP receivers for traces and profiles
Add an OTLP receiver so instrumented applications can send traces through Alloy, and add a profiling receiver if you plan to run Pyroscope. Pick the listening addresses and restrict them to the networks your applications use, because the OpenTelemetry Collector's configuration guidance advises limiting exposure of receivers and adding authentication where data crosses trust boundaries. Confirm the step by sending one test span from an application or a test client, then checking that Alloy logs show it was received without errors.
Add processors for labels and filtering
Insert processing components between receivers and exporters to drop noisy metrics, remove sensitive attributes, and normalize labels so the same service name appears across signals. Make each rule specific and document why it exists, because a broad filter can silently discard data that an alert depends on. Verify the processors by comparing one known series or log line before and after the change, and confirm the removed or renamed fields are gone from the output in Grafana.
Configure exporters to each backend
Finally, configure one exporter per backend: a Prometheus-compatible remote write target for metrics, Loki for logs, Tempo for traces and Pyroscope for profiles, each with the endpoint and tenant settings your deployment uses. Where a backend requires authentication, use the credentials mechanism your team has approved rather than inline secrets. Close the sequence with three checks: a series from the scrape job appears in a Grafana dashboard, a log line is queryable in Loki, and a trace from the test span is found in Tempo. Record each check so later changes can be tested against the same baseline.

Where Alloy replaces separate agents and where it does not

Alloy replaces a separate agent when the job it does is one of the collection, processing or forwarding roles Alloy already covers in a single configuration. In practice that usually means three agents retire: a Prometheus-style scraper that pulls metrics from targets, a log shipper that tails files or container output, and a trace forwarder that receives application spans and sends them onward. Each becomes a set of components in one Alloy configuration, so the team maintains one service, one set of credentials and one upgrade cycle instead of three. Before removing an agent, list the scrape jobs, log paths and trace receivers it currently handles and map each one to a component in the new configuration, so that nothing is dropped during cutover.

Log shipping needs the most careful review. Grafana's Loki documentation describes Alloy as Grafana's supported log shipper for Loki, so it is the natural replacement for Promtail, which the Loki docs also cover. Promtail is a separate agent with its own pipeline stages and label handling, and those stages do not map one to one onto Alloy components. Review each Promtail pipeline stage, relabeling rule and label set your dashboards and alert rules depend on, then confirm the equivalent behavior in a test environment. The same review applies to Fluent Bit, Fluentd or the Docker logging driver if your Loki ingestion uses them, because Loki accepts those senders directly and you may decide to keep them.

Keep a specialized agent when a system has no supported Alloy component, when its vendor requires its own agent for support, or when a host policy limits what can run. Agents for network devices, endpoint security tools or database-specific exporters are common examples. Confirm the component list for your Alloy version in the Alloy documentation before assuming coverage, and check whether a specialized agent can send its data to the same backends Alloy uses. Also plan for the cost of running two collection paths: alerting, retention and access rules must cover both, and the team must know which agent owns each signal. Document that ownership as part of the handover so that a failing exporter is not mistaken for a failing pipeline.

Agent or gateway: choosing the deployment pattern

In the agent pattern, a collector runs on every virtual machine or physical host and receives telemetry from the processes on that host. OpenTelemetry describes the agent role as a collector placed next to the services it observes, which keeps local collection close to the source and lets each host do light processing before export. Alloy follows the same model when it runs as a per-host service.

Local buffering: Data from a host is held near its source, so a short network interruption to the backend does not always lose telemetry, provided the collector's queue and memory settings are sized for the outage you expect.
Failure scope: A failed agent affects only the host it runs on, which keeps the blast radius small but multiplies the number of components you must monitor.
Configuration sprawl: Every host carries a copy of the pipeline, so changes to endpoints, credentials or labels must be rolled out across the fleet through configuration management.
Scaling: Capacity grows with the host count rather than with a central cluster, which suits fleets where each node has spare CPU and memory.
Resource use on busy hosts: Log tailing and profiling add load to the workload host, so measure overhead on representative machines before rolling out.

Before committing, confirm in the Alloy documentation which installation and deployment modes are supported for your operating systems and how each one manages upgrades and configuration files.

Signals, components and backends mapped

This table maps each of the four signals to its usual collection method, the Alloy component family that handles it, and the backend it typically lands in. Read each row as one pipeline you will need to build and verify, then confirm exact component names in the Alloy reference before writing configuration.

Signal	Collection method and source	Alloy component family and backend
Metrics	Prometheus-style scraping of HTTP targets found through discovery or static configuration, plus OTLP metrics from instrumented applications	Prometheus scrape and remote write components sending to a Prometheus-compatible store such as Prometheus itself
Logs	File or journal collection on hosts, container log collection, and OTLP logs from applications	Log collection and processing components sending to Grafana Loki, which stores chunks and index in object storage
Traces	OTLP receipt from instrumented applications using the OpenTelemetry protocol	OpenTelemetry-based receive, batch and export components forwarding to Grafana Tempo or another trace backend
Profiles	Continuous profiling collected from running processes by Alloy profiling components	Profiling components sending to Grafana Pyroscope
OTLP source data	Applications instrumented with OpenTelemetry SDKs send traces, metrics and logs to an OTLP receiver in Alloy	OTLP receive components, then routed to the metrics, logs or traces backends above
Pipeline building blocks	Each component receives, transforms or exports data and is wired to the next	Confirm component names, arguments and supported inputs in the Alloy component reference for your release

Securing the collector and its endpoints

Alloy receives telemetry on open ports and forwards it to backends that may hold sensitive operational data. Each card covers one control point: who can send data in, how the collector authenticates to its outputs, how secrets are kept out of configuration, and how the stores behind it are protected.

Authenticating incoming receiver connections

Collector authenticator extensions can check the identity of clients connecting to a receiver, for example through OIDC. Decide which applications and hosts may send telemetry, then confirm with your platform team which authenticator your Alloy build supports, since receiver-side authentication is only as strong as the identity source behind it. Test that an unauthenticated request is rejected before any pipeline goes live.

Authenticating outbound exporter requests

The same extension model can add credentials to requests the collector sends onward, such as the oauth2client extension for exporters. This keeps backends such as Loki or a Prometheus-compatible store from accepting unauthenticated writes from the collector. Confirm which token source your backend trusts and how the collector obtains and rotates its credentials.

Applying collector configuration best practices

The OpenTelemetry configuration best practices describe how to protect the collector's endpoints, including limiting network exposure and reviewing which receivers are enabled. Remove receivers and debug exporters that a pipeline does not need, and bind listeners to the interfaces that clients actually use. Treat the review as part of each configuration change, not a one-time hardening step.

Keeping secrets out of plain configuration

Tokens, passwords and client secrets written directly into Alloy configuration files end up in version control, backups and shared logs. Load them from environment variables, files managed by your secrets store, or Kubernetes secrets, and restrict who can read the configuration directory. Ask your team how credentials are rotated without editing and redeploying every pipeline.

Putting an authenticating proxy in front of Loki

Loki has no built-in authentication layer, so the Loki documentation requires an authenticating reverse proxy such as nginx, HAProxy, OAuth2 Proxy or Pomerium in front of it. When multi-tenancy is enabled, every request must carry the X-Scope-OrgID header that identifies the tenant. The proxy should set or validate that header so one team cannot read another team's logs by changing it.

Limiting network access to Prometheus

The Prometheus security model assumes that anyone who can reach its HTTP endpoints can read metrics and, depending on configuration, query or change data. Restrict access to the Prometheus port and its remote write and query endpoints to known networks, and place authentication in front of any endpoint exposed outside the cluster or data center. Confirm which endpoints Alloy must reach and block everything else.

Common failures when Alloy goes live

This table lists the failures teams most often hit when Alloy first ships telemetry, with the likely cause and the config or documentation check that confirms it. Read each row against your own pipeline, starting with the signal that is missing or duplicated, and verify the fix in a test environment before changing production.

Failure	Likely cause	Fix and check
Loki rejects writes for missing tenant	auth_enabled is true in Loki but Alloy's Loki write component sends no X-Scope-OrgID header	Set a tenant ID on the Loki write component or in front of it, and confirm the header on each request in the Loki multi-tenancy docs
Loki has no authentication layer	Alloy sends logs to a Loki endpoint exposed directly without an authenticating reverse proxy	Place nginx, HAProxy, OAuth2 Proxy or Pomerium in front of Loki, then test an unauthenticated request is refused
Scrape targets not discovered	Service discovery selectors or namespaces do not match live labels, or the Alloy pod lacks RBAC or network access to targets	Compare discovery output in the Alloy UI with the target labels, and check the service account and network policy used by Alloy
High-cardinality labels inflate Prometheus storage	Labels such as request IDs, user IDs or raw URLs are kept during relabeling	Drop or hash unbounded labels in relabel rules before remote write, and review series counts after rollout
Duplicate logs after migrating from an old shipper	Promtail, Fluent Bit or another agent still tails the same files while Alloy is also enabled	Stop the old shipper on each host first, then compare line counts per stream against the Loki send data guidance for your source
Metrics gaps during Prometheus restarts	Prometheus stores data on a single node with a local WAL and no replication, so restarts or failed nodes leave gaps	Plan restart windows, use remote write to durable long-term storage, and confirm the storage docs match your retention and recovery expectations
Unstable component behavior across Collector releases	Alloy and OpenTelemetry Collector components have mixed stability levels, and release lines change	Pin the Alloy version, read each component's stability notes before upgrading, and test pipelines in staging first
Pipelines broken by Prometheus LTS timing	Running a non-LTS Prometheus minor release that no longer receives bug fixes	Track the LTS line in the Prometheus release cycle page and schedule upgrades before a line reaches end of life

Questions buyers ask about Alloy setup

Is Grafana Alloy free to run, and what does it actually cost?

Grafana Alloy is an open source collector, so there is no license fee to install it. The costs come from the infrastructure that runs it, the storage and query systems that receive its data, implementation work, and the staff who keep configurations, upgrades and pipelines healthy. The supplied facts do not include Alloy licensing terms beyond its open source status, so confirm the license of any component you plan to use. Storage is usually the largest recurring cost, and it depends on how much telemetry you collect and how long you keep it. For a fixed-price view, ask for a written scope that lists each signal, each backend and each host group, because that scope is what a quote follows from.

How long does an Alloy setup take, and what makes it take longer?

Duration depends on the number of signals, hosts, Kubernetes clusters and backends, and on how much of the configuration is new. A single host sending metrics to one Prometheus-compatible store is a much smaller job than a fleet that sends metrics, logs, traces and profiles to separate backends. The main drivers are the number of distinct data sources, the authentication model for each receiver and exporter, label and naming decisions, and the testing needed before cutover. DeployOpen agrees timelines in writing before work starts, so ask for a timeline tied to the agreed scope rather than a generic estimate.

What does our team need to provide before an Alloy project starts?

A project moves faster when the client prepares the inputs that only the client can supply. Typical items include:

A list of hosts, Kubernetes clusters and services to instrument, with their operating systems and network zones
Endpoints for each backend, such as the Prometheus-compatible metrics store, Loki and any trace or profile systems
Credentials or identity setup for each receiver and exporter, handled through your secrets process
A label convention for environments, teams and services, so that dashboards and alerts can filter consistently
Change windows and a named owner who can approve cutover

Confirm these items with your platform and security teams early, since access approvals often take longer than the configuration itself.

Can a capable in-house team set up Alloy without a partner?

Yes, a capable team can set up Alloy alone, especially when it already runs Prometheus, Loki or OpenTelemetry. The collector and its component documentation are public, and the work is mostly configuration, testing and operations. What a partner adds is planning and experience across the whole setup: component choices, security of receivers and exporters, sizing, verification and handover. The questions to answer honestly are whether someone has time to own the project, whether they have done a similar rollout, and who will keep it upgraded. If the answer to any of these is unclear, a fixed-scope engagement with written deliverables can cover the gap while your team learns the system.

Does Alloy replace Promtail and other telemetry agents?

Alloy can replace several separate agents, but the replacement is a planning decision rather than an automatic swap. Alloy is a collector that handles metrics, logs, traces and profiles in one tool, built from components. The Loki documentation names Grafana Alloy as Grafana's supported log shipper, and the Loki documentation also states that Promtail is covered in its own guide. Promtail, Fluent Bit, Fluentd and other agents can still send data to Loki. Before you remove an agent, map each data source it reads, confirm that Alloy has an equivalent component, and run both in parallel during cutover so no logs or metrics are lost.

Why does the choice of OpenTelemetry Collector matter for Alloy?

Alloy is described as an OpenTelemetry Collector distribution with built-in Prometheus pipelines, so it sits within the OpenTelemetry ecosystem. OpenTelemetry standardizes how telemetry is generated and exported, but it does not store or visualize data. You still need a backend such as Prometheus, Loki, Tempo or another store. Ask your engineers which OpenTelemetry components they already use, because existing exporters and receivers may carry over. Also check that the component you need is stable enough for production, since the OpenTelemetry status page notes that component stability varies and is documented per component.

What should we check before accepting an Alloy configuration into production?

Review how receivers are authenticated, how exporters send credentials, and where configuration files and secrets are stored. The OpenTelemetry configuration guidance describes authenticator extensions that can check incoming connections and add credentials to outgoing requests, which is the right place to start a security review. Also check that each pipeline has a tested route to its backend, that labels are consistent, that resource use on hosts is acceptable, and that a rollback path exists. Ask for a written list of these checks as part of the agreed scope, so acceptance is based on evidence rather than on the configuration alone.

How DeployOpen scopes an Alloy collector project

DeployOpen plans and implements the Alloy collector inside your own infrastructure, in your cloud accounts, data centers or restricted networks, and most engagements are fixed-scope. Before work starts, the scope, deliverables and timeline are agreed in writing. The scope usually names the signals in play (metrics, logs, traces and profiles), the hosts or clusters that run Alloy, the backends each pipeline writes to, and the Grafana instance that will read the data. A quote follows from that written scope, so the more precisely your team lists these items, the more closely the quote reflects the work.

The written deliverables typically cover pipeline design, the component-based configuration files, test evidence and handover. Pipeline design records which receivers, processors and exporters handle each signal, how Prometheus scrape targets are discovered, and where authentication applies on incoming and outgoing connections. Testing confirms that data reaches each backend and that the collector behaves as expected under restarts and failed exports. Handover covers the runbook, configuration ownership and the steps for changing a pipeline. Ask for each of these items by name in the proposal so you can check them at acceptance.

Upgrades, configuration changes after handover and ongoing support are available as retainers, which suit teams that want a partner on call for new collection targets and collector version updates. Keep the retainer decision separate from the initial build in your planning. Confirm with your own team who will own the configuration once the project closes, which release line of Alloy you will standardize on, and how new services will be onboarded. Those answers decide how much of the work stays in-house and how much a retainer should cover.

How DeployOpen works on this

DeployOpen plans, builds, documents and supports Grafana Alloy inside your own infrastructure, so the collector that feeds your self-hosted Grafana stack is designed around your metrics, logs, traces and profiles. We agree the scope in writing before work starts, then hand over pipelines your team can operate and change.

How we scope

We inventory the telemetry sources, hosts, clusters and applications that Alloy will collect from.
We map each signal to its destination, covering Prometheus-compatible metrics, Loki logs, Tempo traces and Pyroscope profiles.
We agree the written scope, deliverables and timeline with you before any configuration begins.

How we build

We write component-based Alloy configuration per signal and test each pipeline against a non-production target first.
We confirm authentication, network paths and credentials for every exporter in your environment.
We check component stability levels and version compatibility for the Alloy release you choose to run.

How we hand over

We deliver the configuration files, deployment manifests and a runbook describing each pipeline and its owner.
We document how to add a new target, change a destination and roll back a configuration change.
We walk your platform and operations engineers through verification steps and alert checks before closing the engagement.

How we support

Ongoing support, Alloy upgrades and continuous testing are available as a retainer after handover.
Upgrades are planned against the Alloy and destination release notes so changes reach production in a controlled order.
Retainer scope and response expectations are set in writing, so you know what is covered before you sign.

Grafana Alloy setup for metrics, logs, traces and profiles