The Grafana Alloy command-line interface on Grafana Labs

convert

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

`convert`

Public preview: This is a public preview component. Public preview components are subject to breaking changes, and may be replaced with equivalent functionality that cover the same use case. To enable and use a public preview component, you must set the stability.level flag to public-preview or below.

The convert command converts a supported configuration format to the Alloy configuration format.

Usage

alloy convert [<FLAG> ...] <FILE_NAME>

Replace the following:

<FLAG>: One or more flags that define the input and output of the command.
<FILE_NAME>: The Alloy configuration file.

If the <FILE_NAME> argument isn’t provided or if the <FILE_NAME> argument is equal to -, convert converts the contents of standard input. Otherwise, convert reads and converts the file from disk specified by the argument.

There are several different flags available for the convert command. You can use the --output flag to write the contents of the converted configuration to a specified path. You can use the --report flag to generate a diagnostic report. The --bypass-errors flag allows you to bypass any errors generated during the file conversion.

The command fails if the source configuration has syntactically incorrect configuration or can’t be converted to an Alloy configuration.

The following flags are supported:

--output, -o: The filepath and filename where the output is written.
--report, -r: The filepath and filename where the report is written.
--source-format, -f: Required. The format of the source file. Supported formats: otelcol, prometheus, promtail, static.
--bypass-errors, -b: Enable bypassing errors when converting.
--extra-args, -e: Extra arguments from the original format used by the converter.

Defaults

Alloy defaults are managed as follows:

If a provided source configuration value matches an Alloy default value, the property is left off the output.
If a non-provided source configuration value default matches an Alloy default value, the property is left off the output.
If a non-provided source configuration value default doesn’t match an Alloy default value, the default value is included in the output.

Errors

Errors are defined as non-critical issues identified during the conversion where an output can still be generated. You can use the --bypass-errors flag to bypass these errors.

OpenTelemetry Collector

You can use the --source-format=otelcol to convert the source configuration from an OpenTelemetry Collector to a Alloy configuration.

Many OpenTelemetry Collector components are supported. Review the otelcol.* component information in the Component Reference for more information about otelcol components that you can convert. If a source configuration has unsupported features, you will receive errors when you convert it to an Alloy configuration. The converter raises warnings for configuration options that may require your attention.

Refer to Migrate from OpenTelemetry Collector to Alloy for a detailed migration guide.

Prometheus

Using the --source-format=prometheus will convert the source configuration from Prometheus v2.45 to an Alloy configuration.

This includes Prometheus features such as scrape_config, relabel_config, metric_relabel_configs, remote_write, and many supported *_sd_configs. Unsupported features in a source configuration result in errors.

Refer to Migrate from Prometheus to Alloy for a detailed migration guide.

Promtail

Using the --source-format=promtail will convert the source configuration from Promtail v2.8.x to an Alloy configuration.

Nearly all Promtail features are supported and can be converted to Alloy configuration.

If you have unsupported features in a source configuration, you will receive errors when you convert to an Alloy configuration. The converter will also raise warnings for configuration options that may require your attention.

Refer to Migrate from Promtail to Alloy for a detailed migration guide.

Static

Using the --source-format=static will convert the source configuration from a Grafana Agent Static configuration to an Alloy configuration.

Include --extra-args for passing additional command line flags from the original format. For example, --extra-args="-enable-features=integrations-next" converts a Grafana Agent Static integrations-next configuration to an Alloy configuration. You can also expand environment variables with --extra-args="-config.expand-env". You can combine multiple command line flags with a space between each flag, for example --extra-args="-enable-features=integrations-next -config.expand-env".

If you have unsupported features in a Grafana Agent Static mode source configuration, you will receive errors when you convert to an Alloy configuration. The converter also raises warnings for configuration options that may require your attention.

Refer to Migrate from Grafana Agent Static to Alloy for a detailed migration guide.

fmt

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

`fmt`

The fmt command formats a given Alloy configuration file.

Usage

alloy fmt [<FLAG> ...] <FILE_NAME>

Replace the following:

<FLAG>: One or more flags that define the input and output of the command.
<FILE_NAME>: The Alloy configuration file.

If the <FILE_NAME> argument isn’t provided or if the <FILE_NAME> argument is equal to -, fmt formats the contents of standard input. Otherwise, fmt reads and formats the file from disk specified by the argument.

The --write flag can be specified to replace the contents of the original file on disk with the formatted results. --write can only be provided when fmt isn’t reading from standard input.

The --test flag can be specified to test if the contents of the file are formatted correctly.

The --write and --test flags are mutually exclusive.

The command fails if the file being formatted has syntactically incorrect Alloy configuration, but doesn’t validate whether Alloy components are configured properly.

The following flags are supported:

--write, -w: Write the formatted file back to disk when not reading from standard input.
--test, -t: Only test the input and return a non-zero exit code if changes would have been made.

run

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

`run`

The run command runs the Alloy Default Engine in the foreground until an interrupt is received.

Usage

alloy run [<FLAG> ...] <PATH_NAME>

Replace the following:

<FLAG>: One or more flags that define the input and output of the command.
<PATH_NAME>: Required. The Alloy configuration file or directory path.

If the <PATH_NAME> argument isn’t provided, or if the configuration path can’t be loaded or contains errors during the initial load, the run command immediately exits and shows an error message.

If you provide a directory path for the <PATH_NAME>, Alloy finds *.alloy files, ignoring nested directories, and loads them as a single configuration source. However, component names must be unique across all Alloy configuration files, and configuration blocks must not be repeated.

Alloy continues 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, Alloy continues 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. (default true).
--server.http.memory-addr: Address to listen for in-memory HTTP traffic on (default "alloy.internal:12345").
--server.http.listen-addr: Address to listen for HTTP traffic on (default "127.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 (default "data-alloy/").
--disable-reporting: Disable data collection (default false).
--disable-support-bundle: Disable support bundle endpoint (default false).
--cluster.enabled: Start Alloy in clustered mode (default false).
--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 ""). Mutually exclusive with --cluster.discover-peers.
--cluster.discover-peers: List of key-value tuples for discovering peers (default ""). Mutually exclusive with --cluster.join-addresses.
--cluster.rejoin-interval: How often to rejoin the list of peers (default "60s").
--cluster.advertise-address: Address to advertise to other cluster nodes (default "").
--cluster.advertise-interfaces: List of interfaces used to infer an address to advertise. Set to all to use all available network interfaces on the system. (default "eth0,en0").
--cluster.max-join-peers: Number of peers to join from the discovered set (default 5).
--cluster.name: Name to prevent nodes without this identifier from joining the cluster (default "").
--cluster.enable-tls: Specifies whether TLS should be used for communication between peers (default false).
--cluster.tls-ca-path: Path to the CA certificate file used for peer communication over TLS.
--cluster.tls-cert-path: Path to the certificate file used for peer communication over TLS.
--cluster.tls-key-path: Path to the key file used for peer communication over TLS.
--cluster.tls-server-name: Server name used for peer communication over TLS.
--cluster.wait-for-size: Wait for the cluster to reach the specified number of instances before allowing components that use clustering to begin processing. Zero means disabled (default 0).
--cluster.wait-timeout: Maximum duration to wait for minimum cluster size before proceeding with available nodes. Zero means wait forever, no timeout (default 0).
--config.format: Specifies the source file format. Supported formats: alloy, otelcol, prometheus, promtail, and static (default "alloy").
--config.bypass-conversion-errors: Enable bypassing errors during conversion (default false).
--config.extra-args: Extra arguments from the original format used by the converter.
--stability.level: The minimum permitted stability level of functionality. Supported values: experimental, public-preview, and generally-available (default "generally-available").
--feature.community-components.enabled: Enable community components (default false).
--feature.component-shutdown-deadline: Maximum duration to wait for a component to shut down before giving up and logging an error (default "10m").
--feature.prometheus.direct-fanout.enabled: Enable experimental direct fanout for metric forwarding without a global label store.
--windows.priority: The priority to set for the Alloy process when running on Windows. This is only available on Windows. Supported values: above_normal, below_normal, normal, high, idle, or realtime (default "normal").

Note
The --feature.prometheus.direct-fanout.enabled flag is an experimental feature. Experimental features are subject to frequent breaking changes, and may be removed with no equivalent replacement. To enable and use an experimental feature, you must set the stability.level flag to experimental.

Note
The --windows.priority flag is in Public preview and is not covered by Grafana Alloy backward compatibility guarantees.

Deprecated flags

--feature.prometheus.metric-validation-scheme: This flag is deprecated and has no effect. You can configure the metric validation scheme individually for each prometheus.scrape component in your Alloy configuration file.

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 Alloy 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.

Permitted stability levels

By default, Alloy only allows you to use functionality that is marked Generally available.

To use Experimental or Public preview functionality, set the --stability.level flag to the level you want to use:

--stability.level=experimental: Use functionality marked as Experimental and above.
--stability.level=public-preview: Use functionality marked as Public preview and above.
--stability.level=generally-available: Use functionality marked as Generally available.

Caution
Setting --stability.level to experimental or public-preview may enable Experimental or Public preview behavior for items otherwise marked Generally available, such as:

The component controller

Components in the main configuration or in imported modules

Configuration blocks in the main configuration

Refer to Release life cycle for Grafana Labs for the definition of each stability level.

Clustering

The --cluster.enabled command-line argument starts Alloy 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 fall back to bootstrapping a new cluster of their own.

Peers communicate over HTTP/2 on the 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 isn’t explicitly set, Alloy tries to infer a suitable one from --cluster.advertise-interfaces. If --cluster.advertise-interfaces isn’t explicitly set, Alloy infers one from the eth0 and en0 local network interfaces. Alloy will fail to start if it can’t determine the advertised address. Since Windows doesn’t use the interface names eth0 or en0, Windows users must explicitly pass at least one valid network interface for --cluster.advertise-interfaces or a value for --cluster.advertise-address.

The comma-separated list of addresses provided in --cluster.join-addresses can either be IP addresses or DNS names to lookup (supports SRV and A/AAAA records). In both cases, the port number can be specified with a :<port> suffix. If ports aren’t provided, default of the port used for the HTTP listener is used. If you don’t provide the port number explicitly, you must ensure that all instances use the same port for the HTTP listener. Optionally, you may specify a DNS query type as a prefix for each address. See join addresses format for more information.

The --cluster.enable-tls flag can be set to enable TLS for peer-to-peer communications. Additional arguments are required to configure the TLS client, including the CA certificate, the TLS certificate, the key, and the server name.

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 tuple 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.

The --cluster.rejoin-interval flag defines how often each node should rediscover peers based on the contents of the --cluster.join-addresses and --cluster.discover-peers flags and try to rejoin them. This operation is useful for addressing split-brain issues if the initial bootstrap is unsuccessful and for making clustering easier to manage in dynamic environments. To disable this behavior, set the --cluster.rejoin-interval flag to "0s".

If --cluster.rejoin-interval is set to 0s, then discovering peers using the --cluster.join-addresses and --cluster.discover-peers flags only happens at startup. After that, cluster nodes depend on gossiping messages with each other to converge on the cluster’s state.

The first node that’s used to bootstrap a new cluster (also known as the “seed node”) can either omit the flags that specify peers to join or can try to connect to itself.

To join or rejoin a cluster, Alloy tries to connect to a number of random peers limited by the --cluster.max-join-peers flag. This flag can be useful for clusters of significant sizes because connecting to a high number of peers can be an expensive operation. To disable this behavior, set the --cluster.max-join-peers flag to 0. If the value of --cluster.max-join-peers is higher than the number of peers discovered, Alloy connects to all of them.

The --cluster.wait-for-size flag specifies the minimum cluster size required before components that use clustering begin processing traffic. When set to a value greater than zero, a node will join the cluster but the components that use clustering will not take on any work until enough nodes are available. This ensures adequate cluster capacity - refer to estimate resource usage for guidelines. The default value is 0, which disables this feature.

The --cluster.wait-timeout flag sets how long a node will wait for the cluster to reach the size specified by --cluster.wait-for-size. If the timeout expires, the node will proceed with available nodes. Setting this to 0 (the default) means wait indefinitely. For production environments, consider setting a timeout of several minutes as a fallback.

The --cluster.name flag can be used to prevent clusters from accidentally merging. When --cluster.name is provided, nodes only join peers who share the same cluster name value. By default, the cluster name is empty, and any node that doesn’t set the flag can join. Attempting to join a cluster with a wrong --cluster.name results in a “failed to join memberlist” error.

Join Address Format

The --cluster.join-addresses flag supports DNS names with discovery mode prefix. You select a discovery mode by adding one of the following supported prefixes to the address:

dns+
The domain name after the prefix is looked up as an A/AAAA query.
For example: dns+alloy.local:11211.
dnssrv+
The domain name after the prefix is looked up as a SRV query, and then each SRV record is resolved as an A/AAAA record.
For example: dnssrv+_alloy._tcp.alloy.namespace.svc.cluster.local.
dnssrvnoa+
The domain name after the prefix is looked up as a SRV query, with no A/AAAA lookup made after that.
For example: dnssrvnoa+_alloy-memberlist._tcp.service.consul

If no prefix is provided, Alloy will attempt to resolve the name using both A/AAAA and DNSSRV queries.

Clustering states

Clustered Alloys are in one of three states:

Viewer: Alloy has a read-only view of the cluster and isn’t participating in workload distribution.
Participant: Alloy is participating in workload distribution for components that have clustering enabled.
Terminating: Alloy is shutting down and no longer assigning new work to itself.

Each Alloy initially joins the cluster in the viewer state and then transitions to the participant state after the process startup completes. Each Alloy then transitions to the terminating state when shutting down.

The current state of a clustered Alloy is shown on the clustering page in the UI.

Configuration conversion

Public preview: This is a public preview component. Public preview components are subject to breaking changes, and may be replaced with equivalent functionality that cover the same use case. To enable and use a public preview component, you must set the stability.level flag to public-preview or below.

When you use the --config.format command-line argument with a value other than alloy, Alloy converts the configuration file from the source format to Alloy and immediately starts running with the new configuration. This conversion uses the converter API described in the alloy convert docs.

If you include the --config.bypass-conversion-errors command-line argument, Alloy ignores errors from the converter. Use this argument with caution because the resulting conversion may not be equivalent to the original configuration.

Include --config.extra-args to pass additional command line flags from the original format to the converter. Refer to alloy convert for more details on how extra-args work.

otel

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

`otel`

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

The otel command runs Alloy with the OTel Engine. This command accepts OpenTelemetry Collector YAML configuration files.

The OTel Engine includes receivers, processors, exporters, extensions, and connectors from the OpenTelemetry Collector core and contrib repositories. This includes components for OTLP, Prometheus, Kafka, Zipkin, and other popular integrations.

As with the run command, this runs in the foreground until an interrupt is received.

Usage

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

Replace the following:

<CONFIG_FILE>: Path to an OpenTelemetry Collector configuration file.
<FLAGS>: One or more flags that configure the OpenTelemetry Collector. These flags are the same as upstream. Run alloy otel --help to show the complete list of supported flags.

Configuration

The otel command accepts standard OpenTelemetry Collector YAML configuration files. The configuration file defines receivers, processors, exporters, and other components that make up your telemetry pipeline.

Run the Default Engine in parallel

The OTel Engine includes the option to run pipelines with the Default Engine alongside the OTel Engine. Use the built-in Alloy Engine extension to enable this.

This runs a Default Engine pipeline in parallel to the OTel Engine pipeline. The two pipelines can’t natively interact.

Examples

Refer to The OpenTelemetry Engine for examples that show you how to run the OTel Engine and Alloy Engine extension.

OpenTelemetry Collector documentation: Official OpenTelemetry Collector documentation.

tools

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

`tools`

The tools command contains command line tooling grouped by Alloy component.

Caution
Utilities in this command have no backward compatibility guarantees and may change or be removed between releases.

Subcommands

prometheus.remote_write sample-stats

alloy tools prometheus.remote_write sample-stats [<FLAG> ...] <WAL_DIRECTORY>

Replace the following:

<FLAG>: One or more flags that define the input and output of the command.
<WAL_DIRECTORY>: The WAL directory.

The sample-stats command reads the Write-Ahead Log (WAL) specified by <WAL_DIRECTORY> and collects information on metric samples within it.

For each metric discovered, sample-stats emits:

The timestamp of the oldest sample received for that metric.
The timestamp of the newest sample received for that metric.
The total number of samples discovered for that metric.

By default, sample-stats returns information for every metric in the WAL. You can pass the --selector flag to filter the reported metrics to a smaller set.

The following flag is supported:

--selector: A PromQL label selector to filter data by. (default {})

prometheus.remote_write target-stats

alloy tools prometheus.remote_write target-stats --job JOB --instance INSTANCE WAL_DIRECTORY

The target-stats command reads the Write-Ahead Log (WAL) specified by WAL_DIRECTORY and collects metric cardinality information for a specific target.

For the target specified by the --job and --instance flags, unique metric names for that target are printed along with the number of series with that metric name.

The following flags are supported:

--job: The job label of the target.
--instance: The instance label of the target.

The --job and --instance labels are required.

prometheus.remote_write wal-stats

alloy tools prometheus.remote_write wal-stats <WAL_DIRECTORY>

Replace the following:

<WAL_DIRECTORY>: The WAL directory.

The wal-stats command reads the Write-Ahead Log (WAL) specified by <WAL_DIRECTORY> and collects general information about it.

The following information is reported:

The timestamp of the oldest sample in the WAL.
The timestamp of the newest sample in the WAL.
The total number of unique series defined in the WAL.
The total number of samples in the WAL.
The number of hash collisions detected, if any.
The total number of invalid records in the WAL, if any.
The most recent WAL checkpoint segment number.
The oldest segment number in the WAL.
The newest segment number in the WAL.

Additionally, wal-stats reports per-target information, where a target is defined as a unique combination of the job and instance label values. For each target, wal-stats reports the number of series and the number of metric samples associated with that target.

The wal-stats command doesn’t support any flags.

Environment variables

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

Environment variables

You can use environment variables to control the run-time behavior of Grafana Alloy.

The following environment variables are supported:

GODEBUG
HTTP_PROXY
HTTPS_PROXY
NO_PROXY
PPROF_MUTEX_PROFILING_PERCENT
PPROF_BLOCK_PROFILING_RATE
GOMEMLIMIT
AUTOMEMLIMIT
AUTOMEMLIMIT_EXPERIMENT
GOGC
GOMAXPROCS
GOTRACEBACK

Refer to the Go runtime documentation for more information about Go runtime environment variables.

`GODEBUG`

You can use the GODEBUG environment variable to control the debugging variables within the Go runtime. The following arguments are supported.

Argument	Description	Default
`x509usefallbackroots`	Enforce a fallback on the X.509 trusted root certificates. Set to `1` to enable.	`0`
`netdns`	Control the DNS resolver and debugging. Set to `"go"` for a pure Go resolver, `"cgo"` or `"win32"` for a native resolver. Add `+1` or `+2` for debugging output. Example: `netdns=go+1`.	-

`HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY`

Note
For many Alloy components, there is an attribute named proxy_from_environment that must be set to true for the component’s HTTP client to use the proxy-related environment variables. For example, in the prometheus.remote_write component, this attribute is found within the endpoint block.

If Alloy doesn’t appear to be respecting your proxy configuration, make sure you configure the component to use proxy environment variables.

You can use the HTTP_PROXY environment variable to define the hostname or IP address of the proxy server for HTTP requests. For example, you can set the proxy to http://proxy.example.com.

You can use the HTTPS_PROXY environment variable to define the proxy server for HTTPS requests in the same manner as HTTP_PROXY.

The NO_PROXY environment variable is used to define any hosts that should be excluded from proxying. NO_PROXY should contain a comma delimited list of any of the following options.

Option	Description	Examples
IP Address	A single IP address (with optional port)	`1.2.3.4` or `1.2.3.4:80`
CIDR Block	A group of IP addresses that share a network prefix.	`1.2.3.4/8`
Domain	A domain name matches that name and all subdomains. A domain name with a leading “.” matches subdomains only.	`example.com` or `.example.com`
Asterisk	A single asterisk indicates that no proxying should be done.	`*`

`PPROF_MUTEX_PROFILING_PERCENT`

You can use the PPROF_MUTEX_PROFILING_PERCENT environment variable to define the percentage of mutex profiles to retrieve from the pprof mutex endpoint. If you set this variable to 5, then 5 percent of the mutexes are sampled. By default, the sampling rate is set to 0.1%

`PPROF_BLOCK_PROFILING_RATE`

You can use the PPROF_BLOCK_PROFILING_RATE environment variable to define the rate that goroutine blocking events are tracked. You can use the following values with this environment variable. The default value is 10000.

0: Nothing is tracked.
1: All blocking events are tracked.
A value greater than 1: The number of nanoseconds between samples.

`GOMEMLIMIT`

Usually, the Go runtime releases memory back to the operating system when requested. In some environments, this may cause issues such as Out Of Memory (OOM) errors. You can use the GOMEMLIMIT environment variable to set a soft memory cap and limit the maximum memory Alloy can use. You can set GOMEMLIMIT to a numeric value in bytes with an optional unit suffix. The supported unit suffixes are B, KiB, MiB, GiB, and TiB. Don’t treat the GOMEMLIMIT environment variable as a hard memory limit. Alloy processes can use more memory if that memory is required. A rough number is to set GOMEMLIMIT to is 90% of the maximum memory required. For example, if you want to keep memory usage below 10GiB, use GOMEMLIMIT=9GiB.

Automatically set `GOMEMLIMIT`

The GOMEMLIMIT environment variable is either automatically set to 90% of an available cgroup value using the automemlimit module, or you can explicitly set the GOMEMLIMIT environment variable before you run Alloy. You can also change the 90% ratio by setting the AUTOMEMLIMIT environment variable to a float value between 0 and 1.0. No changes occur if the limit can’t be determined and you didn’t explicitly define a GOMEMLIMIT value. The AUTOMEMLIMIT_EXPERIMENT variable can be set to system to use the automemlimit module’s System provider, which sets GOMEMLIMIT based on the same ratio applied to the total system memory. As cgroup is a Linux specific concept, this is the only way to use the automemlimit module to automatically set GOMEMLIMIT on non-Linux OSes.

`GOGC`

The GOGC environment variable controls the mechanism that triggers Go’s garbage collection. It represents the garbage collection target percentage. A collection is triggered when the ratio of freshly allocated data to live data remaining after the previous collection reaches this percentage. If you don’t provide this variable, GOGC defaults to 100. You can set GOGC=off to disable garbage collection.

Configuring this value in conjunction with GOMEMLIMIT can help in situations where Alloy is consuming too much memory. Go provides a very in-depth guide to understanding GOGC and GOMEMLIMIT.

`GOMAXPROCS`

The GOMAXPROCS environment variable defines the limit of OS threads that can simultaneously execute user-level Go code. This limit doesn’t affect the number of threads that can be blocked in system calls on behalf of Go code and those threads aren’t counted against GOMAXPROCS.

`GOTRACEBACK`

The GOTRACEBACK environment variable defines the behavior of the Go panic output. The standard panic output behavior is usually sufficient to debug and resolve an issue. If required, you can use this setting to collect additional information from the runtime. The following values are supported:

Value	Description	Traces include runtime internal functions
`none` or `0`	Omit goroutine stack traces entirely from the panic output.	-
`single`	Print the stack trace for the current goroutine.	No
`all` or `1`	Print the stack traces for all user-created goroutines.	No
`system` or `2`	Print the stack traces for all user-created and runtime-created goroutines.	Yes
`crash`	Similar to `system`, but also triggers OS-specific additional behavior. For example, on Unix systems, this raises a SIGABRT to trigger a code dump.	Yes
`wer`	Similar to `crash`, but doesn’t disable Windows Error Reporting.	Yes

validate

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

`validate`

The validate command validates an Alloy configuration file or directory path.

Usage

alloy validate [<FLAG> ...] <PATH_NAME>

Replace the following:

<FLAG>: One or more flags that define the input and output of the command.
<PATH_NAME>: Required. The Alloy configuration file or directory path.

If the configuration file is valid, the validate command returns a zero exit code. If the configuration file is invalid, the command returns a non-zero exit code and prints diagnostics generated during validation to stderr.

If you provide a directory path for the <PATH_NAME>, Alloy finds *.alloy files, ignoring nested directories, and loads them as a single configuration source.

The following flags are supported:

--config.format: Specifies the source file format. Supported formats: alloy, otelcol, prometheus, promtail, and static (default "alloy").
--config.bypass-conversion-errors: Enable bypassing errors during conversion (default false).
--config.extra-args: Extra arguments from the original format used by the converter.
--stability.level: The minimum permitted stability level of functionality. Supported values: experimental, public-preview, and generally-available (default "generally-available").
--feature.community-components.enabled: Enable community components (default false).

Note
When you validate the Alloy configuration, you must set the --stability.level and --feature.community-components.enabled arguments to the same values you want to use when you run Alloy.

Limitations

Validation is limited in scope. It currently checks for:

Syntax errors in the Alloy configuration syntax
Missing components
Component name conflicts
Required properties are set
Unknown properties
foreach blocks
declare blocks

The Grafana Alloy command-line interface on Grafana Labs

convert

convert

Usage

Defaults

Errors

OpenTelemetry Collector

Prometheus

Promtail

Static

fmt

fmt

Usage

run

run

Usage

Deprecated flags

Update the configuration file

Permitted stability levels

Clustering

Join Address Format

Clustering states

Configuration conversion

otel

otel

Usage

Configuration

Run the Default Engine in parallel

Examples

Related documentation

tools

tools

Subcommands

prometheus.remote_write sample-stats

prometheus.remote_write target-stats

prometheus.remote_write wal-stats

Environment variables

Environment variables

GODEBUG

HTTP_PROXY, HTTPS_PROXY, NO_PROXY

PPROF_MUTEX_PROFILING_PERCENT

PPROF_BLOCK_PROFILING_RATE

GOMEMLIMIT

Automatically set GOMEMLIMIT

GOGC

GOMAXPROCS

GOTRACEBACK

validate

validate

Usage

Limitations

`convert`

`fmt`

`run`

`otel`

`tools`

`GODEBUG`

`HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY`

`PPROF_MUTEX_PROFILING_PERCENT`

`PPROF_BLOCK_PROFILING_RATE`

`GOMEMLIMIT`

Automatically set `GOMEMLIMIT`

`GOGC`

`GOMAXPROCS`

`GOTRACEBACK`

`validate`