Caution
Grafana Alloy is the new name for our distribution of the OTel collector. Grafana Agent has been deprecated and is in Long-Term Support (LTS) through October 31, 2025. Grafana Agent will reach an End-of-Life (EOL) on November 1, 2025. Read more about why we recommend migrating to Grafana Alloy.
Important: This documentation is about an older version. It's relevant only to the release noted, many of the features and functions have been updated or replaced. Please view the current version.
The run command
The run
command runs Grafana Agent Flow in the foreground until an
interrupt is received.
Usage
Usage:
AGENT_MODE=flow grafana-agent run [FLAG ...] FILE_NAME
grafana-agent-flow run [FLAG ...] FILE_NAME
Replace the following:
FLAG
: One or more flags that define the input and output of the command.FILE_NAME
: Required. The Grafana Agent configuration file.
If the FILE_NAME
argument is not provided, or if the configuration file can’t be loaded or
contains errors during the initial load, the run
command will immediately exit and show an error message.
Grafana Agent Flow will continue to run if subsequent reloads of the configuration file fail, potentially marking components as unhealthy depending on the nature of the failure. When this happens, Grafana Agent Flow will continue functioning in the last valid state.
run
launches an HTTP server that exposes metrics about itself and its
components. The HTTP server is also exposes a UI at /
for debugging
running components.
The following flags are supported:
--server.http.enable-pprof
: Enable /debug/pprof profiling endpoints. (defaulttrue
)--server.http.memory-addr
: Address to listen for in-memory HTTP traffic on (defaultagent.internal:12345
).--server.http.listen-addr
: Address to listen for HTTP traffic on (default127.0.0.1:12345
).--server.http.ui-path-prefix
: Base path where the UI is exposed (default/
).--storage.path
: Base directory where components can store data (defaultdata-agent/
).--disable-reporting
: Disable data collection (defaultfalse
).--cluster.enabled
: Start the Agent in clustered mode (defaultfalse
).--cluster.node-name
: The name to use for this node (defaults to the environment’s hostname).--cluster.join-addresses
: Comma-separated list of addresses to join the cluster at (default""
).--cluster.advertise-address
: Address to advertise to other cluster nodes (default""
).--config.format
: The format of the source file. Supported formats: ‘flow’, ‘prometheus’ (default"flow"
).--config.bypass-conversion-errors
: Enable bypassing errors when converting (defaultfalse
).
Update the configuration file
The configuration file can be reloaded from disk by either:
- Sending an HTTP POST request to the
/-/reload
endpoint. - Sending a
SIGHUP
signal to the Grafana Agent process.
When this happens, the component controller synchronizes the set of running components with the latest set of components specified in the configuration file. Components that are no longer defined in the configuration file after reloading are shut down, and components that have been added to the configuration file since the previous reload are created.
All components managed by the component controller are reevaluated after reloading.
Clustering (beta)
The --cluster.enabled
command-line argument starts Grafana Agent in
clustering mode. The rest of the --cluster.*
command-line flags can be
used to configure how nodes discover and connect to one another.
Each cluster member’s name must be unique within the cluster. Nodes which try to join with a conflicting name are rejected and will fall back to bootstrapping a new cluster of their own.
Peers communicate over HTTP/2 on the agent’s built-in HTTP server. Each node
must be configured to accept connections on --server.http.listen-addr
and the
address defined or inferred in --cluster.advertise-address
.
If the --cluster.advertise-address
flag is not explicitly set, the agent
tries to infer a suitable one from the eth0
and en0
local network
interfaces. If the advertised address cannot be determined, the agent will
fail to start. Windows users must explicitly pass a value for
--cluster.advertise-address
, since Windows does not have interfaces name
eth0
or en0
.
The comma-separated list of addresses provided in --cluster.join-addresses
can either be IP addresses with an optional port, or DNS records to lookup.
The ports on the list of addresses default to the port used for the HTTP
listener if not explicitly provided. We recommend that you
align the port numbers on as many nodes as possible to simplify the deployment
process.
The --cluster.discover-peers
command-line flag expects a list of tuples in
the form of provider=XXX key=val key=val ...
. Clustering uses the
[go-discover] package to discover peers and fetch their IP addresses, based
on the chosen provider and the filtering key-values it supports. Clustering
supports the default set of providers available in go-discover and registers
the k8s
provider on top.
If either the key or the value in a pair contains a space, a backslash, or double quotes, then it must be quoted with double quotes. Within this quoted string, the backslash can be used to escape double quotes or the backslash itself.
Discovering peers using the --cluster.join-addresses
and
--cluster.discover-peers
flags only happens on startup; after that, cluster
nodes depend on gossiping messages with each other to converge on the cluster’s
state.
The first node that is used to bootstrap a new cluster (also known as the “seed node”) can either omit the flag that specifies peers to join or can try to connect to itself.
Clustering states
Clustered agents are in one of three states:
Viewer: The agent has a read-only view of the cluster and is not participating in workload distribution.
Participant: The agent is participating in workload distribution for components that have clustering enabled.
Terminating: The agent is shutting down and will no longer assign new work to itself.
Agents initially join the cluster in the viewer state and then transition to the participant state after the process startup completes. Agents then transition to the terminating state when shutting down.
The current state of a clustered agent is shown on the clustering page in the UI.
Configuration conversion (beta)
When you use the --config.format
command-line argument with a value
other than flow
, Grafana Agent converts the configuration file from
the source format to River and immediately starts running with the new
configuration. This conversion uses the converter API described in the
grafana-agent-flow convert docs.
If you also use the --config.bypass-conversion-errors
command-line argument,
Grafana Agent will ignore any errors from the converter. Use this argument
with caution because the resulting conversion may not be equivalent to the
original configuration.