Configuration blocks on Grafana Labs

argument

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

`argument`

argument is an optional configuration block used to specify parameterized input to a custom component. argument blocks must be given a label which determines the name of the argument.

The argument block may only be specified inside the definition of a declare block.

Usage

argument "<ARGUMENT_NAME>" {}

Arguments

Note
For clarity, “argument” in this section refers to arguments which can be given to the argument block. “Module argument” refers to the argument being defined for a module, determined by the label of the argument block.

You can use the following arguments with argument:

Name	Type	Description	Default	Required
`comment`	`string`	Description for the argument.	`""`	no
`default`	`any`	Default value for the argument.	`null`	no
`optional`	`bool`	Whether the argument may be omitted.	`false`	no

By default, all module arguments are required. The optional argument can be used to mark the module argument as optional. When optional is true, the initial value for the module argument is specified by default.

Exported fields

The following fields are exported and can be referenced by other components:

Name	Type	Description
`value`	`any`	The current value of the argument.

If you use a custom component, you are responsible for determining the values for arguments. Other expressions within a custom component may use argument.ARGUMENT_NAME.value to retrieve the value you provide.

Example

This example creates a custom component that self-collects process metrics and forwards them to an argument specified by the user of the custom component:

declare "self_collect" {
  argument "metrics_output" {
    optional = false
    comment  = "Where to send collected metrics."
  }

  prometheus.scrape "selfmonitor" {
    targets = [{
      __address__ = "127.0.0.1:12345",
    }]

    forward_to = [argument.metrics_output.value]
  }
}

declare

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

`declare`

declare is an optional configuration block used to define a new custom component. declare blocks must be given a label that determines the name of the custom component.

Usage

declare "<COMPONENT_NAME>" {
    <COMPONENT_DEFINITION>
}

Arguments

The declare block has no predefined schema for its arguments. The body of the declare block is used as the component definition. The body can contain the following:

argument blocks
export blocks
declare blocks
import blocks
Component definitions (either built-in or custom components)

The declare block may not contain any configuration blocks that aren’t listed above.

Exported fields

The declare block has no predefined schema for its exports. The fields exported by the declare block are determined by the export blocks found in its definition.

Example

This example creates and uses a custom component that self-collects process metrics and forwards them to an argument specified by the user of the custom component:

declare "self_collect" {
  argument "metrics_output" {
    optional = false
    comment  = "Where to send collected metrics."
  }

  prometheus.scrape "selfmonitor" {
    targets = [{
      __address__ = "127.0.0.1:12345",
    }]

    forward_to = [argument.metrics_output.value]
  }
}

self_collect "example" {
  metrics_output = prometheus.remote_write.example.receiver
}

prometheus.remote_write "example" {
  endpoint {
    url = <REMOTE_WRITE_URL>
  }
}

export

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

`export`

export is an optional configuration block used to specify an emitted value of a custom component. export blocks must be given a label which determine the name of the export.

The export block may only be specified inside the definition of a declare block.

Usage

export "<ARGUMENT_NAME>" {
  value = <ARGUMENT_VALUE>
}

Arguments

You can use the following arguments with export:

Name	Type	Description	Default	Required
`value`	`any`	Value to export.		yes

The value argument determines what the value of the export is. To expose an exported field of another component, set value to an expression that references that exported value.

Exported fields

The export block doesn’t export any fields.

Example

This example creates a custom component where the output of discovering Kubernetes pods and nodes are exposed to the user:

declare "pods_and_nodes" {
  discovery.kubernetes "pods" {
    role = "pod"
  }

  discovery.kubernetes "nodes" {
    role = "node"
  }

  export "kubernetes_resources" {
    value = array.concat(
      discovery.kubernetes.pods.targets,
      discovery.kubernetes.nodes.targets,
    )
  }
}

foreach

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

`foreach`

EXPERIMENTAL: This 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.

The foreach block runs a separate pipeline for each item inside a list.

Usage

foreach "<LABEL>" {
  collection = [...]
  var        = "<VAR_NAME>"
  template {
    ...
  }
}

Arguments

You can use the following arguments with foreach:

Name	Type	Description	Default	Required
`collection`	`list(any)`	A list of items to loop over.		yes
`var`	`string`	Name of the variable referring to the current item in the collection.		yes
`enable_metrics`	`bool`	Whether to expose debug metrics in the Alloy `/metrics` endpoint.	`false`	no
`hash_string_id`	`bool`	Whether to hash the string representation of the id of the collection items.	`false`	no
`id`	`string`	Name of the field to use from collection items for child component’s identification.	`""`	no

The items in the collection list can be of any type type, such as a bool, a string, a list, or a map.

When using a collection of strings or when the id field is a string, you can set hash_string_id to true to hash the string representation of the id field instead of using the string itself. This is recommended when the strings are long because the values are used to identify the components that are created dynamically in metrics, logs, and in the UI.

Warning
Setting enable_metrics to true when collection has lots of elements may cause a large number of metrics to appear on the Alloy /metric endpoint.

Note
When id is set and enable_metrics is true, component paths in metrics use the value of the specified field from collection items instead of a hash of the entire item. For example:
Alloy
foreach "pods" {
    collection = [
        { namespace = "prod", name = "app-1" },
        { namespace = "dev", name = "app-1" },
        { namespace = "prod", name = "app-2" }
    ]
    var = "each"
    id = "name"
    enable_metrics = true
    template { ... }
}
This results in component paths like the following:
text
/foreach.pods/foreach_app-1_1/component.default
/foreach.pods/foreach_app-1_2/component.default
/foreach.pods/foreach_app-2_1/component.default
If the collection item isn’t an object or the specified field doesn’t exist, it falls back to using the entire item for identification.

Blocks

You can use the following block with foreach:

Block	Description	Required
`template`	A component pipeline to run.	yes

`template`

The template block contains the definition of Alloy components used for every item in the collection. The contents of the block look like a normal Alloy configuration file, except that you can use the keyword defined in var to refer to the current item in the collection.

Components inside the template block can use exports of components defined outside of the foreach block. However, components outside of the foreach can’t use exports from components defined inside the template block of a foreach.

Example

The following example shows you how to run Prometheus exporters dynamically on service discovery targets.

prometheus.exporter.* components often require the address of one particular instance being monitored. For example, prometheus.exporter.redis has a redis_addr attribute for the Redis instance under observation. On the other hand, discovery.* components such as discovery.kubernetes output a list of targets such as this:

[
    {
    __address__                                          = "10.42.0.16:5432",
    __meta_kubernetes_namespace                          = "ns1",
    __meta_kubernetes_pod_container_id                   = "containerd://96b77d035d0bbe27bb173d8fc0c56d21965892a50e4e6eab9f6cffdb90b275fb",
    __meta_kubernetes_pod_container_image                = "postgres:bullseye",
    __meta_kubernetes_pod_container_init                 = "false",
    __meta_kubernetes_pod_container_name                 = "pgcont",
    __meta_kubernetes_pod_container_port_name            = "pg-db",
    __meta_kubernetes_pod_container_port_number          = "5432",
    __meta_kubernetes_pod_container_port_protocol        = "TCP",
    __meta_kubernetes_pod_controller_kind                = "ReplicaSet",
    __meta_kubernetes_pod_controller_name                = "postgres-db-cd54547b9",
    __meta_kubernetes_pod_host_ip                        = "172.25.0.2",
    __meta_kubernetes_pod_ip                             = "10.42.0.16",
    __meta_kubernetes_pod_label_name                     = "postgres-db",
    __meta_kubernetes_pod_label_pod_template_hash        = "cd54547b9",
    __meta_kubernetes_pod_labelpresent_name              = "true",
    __meta_kubernetes_pod_labelpresent_pod_template_hash = "true",
    __meta_kubernetes_pod_name                           = "postgres-db-cd54547b9-4zpds",
    __meta_kubernetes_pod_node_name                      = "k3d-asserts-test-server-0",
    __meta_kubernetes_pod_phase                          = "Running",
    __meta_kubernetes_pod_ready                          = "true",
    __meta_kubernetes_pod_uid                            = "7cdcacdc-4a2d-460a-b1fb-6340700c4cac",
    },
    {
    __address__                                          = "10.42.0.20:6379",
    __meta_kubernetes_namespace                          = "ns1",
    __meta_kubernetes_pod_container_id                   = "containerd://68f2f0eacd880eb4a141d833aafc1f297f7d9bdf00f4c787f9fcc964a039d278",
    __meta_kubernetes_pod_container_image                = "redis:latest",
    __meta_kubernetes_pod_container_init                 = "false",
    __meta_kubernetes_pod_container_name                 = "redis-cont",
    __meta_kubernetes_pod_container_port_name            = "redis-db",
    __meta_kubernetes_pod_container_port_number          = "6379",
    __meta_kubernetes_pod_container_port_protocol        = "TCP",
    __meta_kubernetes_pod_controller_kind                = "ReplicaSet",
    __meta_kubernetes_pod_controller_name                = "redis-db-778b66cb7d",
    __meta_kubernetes_pod_host_ip                        = "172.25.0.2",
    __meta_kubernetes_pod_ip                             = "10.42.0.20",
    __meta_kubernetes_pod_label_name                     = "redis-db",
    __meta_kubernetes_pod_label_pod_template_hash        = "778b66cb7d",
    __meta_kubernetes_pod_labelpresent_name              = "true",
    __meta_kubernetes_pod_labelpresent_pod_template_hash = "true",
    __meta_kubernetes_pod_name                           = "redis-db-778b66cb7d-wxmf6",
    __meta_kubernetes_pod_node_name                      = "k3d-asserts-test-server-0",
    __meta_kubernetes_pod_phase                          = "Running",
    __meta_kubernetes_pod_ready                          = "true",
    __meta_kubernetes_pod_uid                            = "ae74e400-8eda-4b02-b4c8-669473fb001b",
    }
]

You can use a foreach to loop over each target and start a separate component pipeline for it. The following example configuration shows how a prometheus.exporter.redis instance is started for each Redis instance discovered by discovery.kubernetes. Additional Kubernetes labels from discovery.kubernetes are also added to the metrics created by prometheus.exporter.redis.

discovery.kubernetes "default" {
    role = "pod"
}

discovery.relabel "redis" {
    targets = discovery.kubernetes.default.targets

    // Remove all targets except the Redis ones.
    rule {
        source_labels = ["__meta_kubernetes_pod_container_name"]
        regex         = "redis-cont"
        action        = "keep"
    }
}

// Collect metrics for each Redis instance.
foreach "redis" {
    collection = discovery.relabel.redis.output
    var        = "each"

    template {
        prometheus.exporter.redis "default" {
            // This is the "__address__" label from discovery.kubernetes.
            redis_addr = each["__address__"]
        }

        prometheus.scrape "default" {
            targets    = prometheus.exporter.redis.default.targets
            forward_to = [prometheus.relabel.default.receiver]
        }

        // Add labels from discovery.kubernetes.
        prometheus.relabel "default" {
            rule {
                replacement  = each["__meta_kubernetes_namespace"]
                target_label = "k8s_namespace"
                action       = "replace"
            }

            rule {
                replacement  = each["__meta_kubernetes_pod_container_name"]
                target_label = "k8s_pod_container_name"
                action       = "replace"
            }

            forward_to = [prometheus.remote_write.mimir.receiver]
        }
    }
}

prometheus.remote_write "mimir" {
    endpoint {
        url = "https://prometheus-xxx.grafana.net/api/prom/push"

        basic_auth {
            username = sys.env("<PROMETHEUS_USERNAME>")
            password = sys.env("<GRAFANA_CLOUD_API_KEY>")
        }
    }
}

Replace the following:

<PROMETHEUS_USERNAME>: Your Prometheus username.
<GRAFANA_CLOUD_API_KEY>: Your Grafana Cloud API key.

http

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

`http`

http is an optional configuration block used to customize how the Alloy HTTP server functions. http is specified without a label and can only be provided once per configuration file.

Usage

http {

}

Arguments

The http block doesn’t support any arguments. You can configure this block with inner blocks.

Blocks

You can use the following blocks with http:

Block	Description	Required
`auth`	Configure server authentication.	no
`auth` > `basic`	Configure basic authentication.	no
`auth` > `filter`	Configure authentication filter.	no
`tls`	Define TLS settings for the HTTP server.	no
`tls` > `windows_certificate_filter`	Configure Windows certificate store for all certificates.	no
`tls` > `windows_certificate_filter` > `client`	Configure client certificates for Windows certificate filter.	no
`tls` > `windows_certificate_filter` > `server`	Configure server certificates for Windows certificate filter.	no

The > symbol indicates deeper levels of nesting. For example, auth > basic refers to an basic block defined inside an auth block.

`auth`

The auth block configures server authentication for the http block. This can be used to enable basic authentication and to set authentication filters for specified API paths.

`basic`

The basic block enables basic HTTP authentication by requiring both a username and password for access.

Name	Type	Description	Default	Required
`password`	`secret`	The password to use for basic authentication.		yes
`username`	`string`	The username to use for basic authentication.		yes

`filter`

The filter block is used to configure which API paths should be protected by authentication. It allows you to specify a list of paths, using prefix matching, that will require authentication.

Name	Type	Description	Default	Required
`authenticate_matching_paths`	`bool`	If `true`, authentication is required for all matching paths. If `false`, authentication is excluded for these paths.	`true`	no
`paths`	`list(string)`	List of API paths to be protected by authentication. The paths are matched using prefix matching.	`[]`	no

`tls`

The tls block configures TLS settings for the HTTP server.

Warning
If you add the tls block and reload the configuration when Alloy is running, existing connections continue communicating over plain text. Similarly, if you remove the tls block and reload the configuration when Alloy is running, existing connections continue communicating over TLS.

To ensure all connections use TLS, configure the tls block before you start Alloy.

Name	Type	Description	Default	Required
`cert_file`	`string`	Path to the server TLS certificate on disk.	`""`	conditionally
`cert_pem`	`string`	PEM data of the server TLS certificate.	`""`	conditionally
`key_file`	`string`	Path to the server TLS key on disk.	`""`	conditionally
`key_pem`	`string`	PEM data of the server TLS key.	`""`	conditionally
`cipher_suites`	`list(string)`	Set of cipher suites to use.	`[]`	no
`client_auth_type`	`string`	Client authentication to use.	`"NoClientCert"`	no
`client_ca_file`	`string`	Path to the client CA file on disk to validate requests against.	`""`	no
`client_ca_pem`	`string`	PEM data of the client CA to validate requests against.	`""`	no
`curve_preferences`	`list(string)`	Set of elliptic curves to use in a handshake.	`[]`	no
`max_version`	`string`	Newest TLS version to accept from clients.	`""`	no
`min_version`	`string`	Oldest TLS version to accept from clients.	`""`	no

When the tls block is specified, arguments for the TLS certificate (using cert_pem or cert_file) and for the TLS key (using key_pem or key_file) are required.

The following pairs of arguments are mutually exclusive, and only one may be configured at a time:

cert_pem and cert_file
key_pem and key_file
client_ca_pem and client_ca_file

The client_auth_type argument determines whether to validate client certificates. The default value, NoClientCert, indicates that the client certificate isn’t validated. The client_ca_pem and client_ca_file arguments may only be configured when client_auth_type is not NoClientCert.

The following values are accepted for client_auth_type:

NoClientCert: client certificates are neither requested nor validated.
RequestClientCert: requests clients to send an optional certificate. Certificates provided by clients aren’t validated.
RequireAnyClientCert: requires at least one certificate from clients. Certificates provided by clients aren’t validated.
VerifyClientCertIfGiven: requests clients to send an optional certificate. If a certificate is sent, it must be valid.
RequireAndVerifyClientCert: requires clients to send a valid certificate.

The client_ca_pem or client_ca_file arguments may be used to perform client certificate validation. These arguments may only be provided when client_auth_type isn’t set to NoClientCert.

The cipher_suites argument determines what cipher suites to use. If you don’t provide cipher suite, a default list is used. The set of cipher suites specified may be from the following:

Cipher	Allowed in BoringCrypto builds
`TLS_RSA_WITH_AES_128_CBC_SHA`	no
`TLS_RSA_WITH_AES_256_CBC_SHA`	no
`TLS_RSA_WITH_AES_128_GCM_SHA256`	yes
`TLS_RSA_WITH_AES_256_GCM_SHA384`	yes
`TLS_AES_128_GCM_SHA256`	no
`TLS_AES_256_GCM_SHA384`	no
`TLS_CHACHA20_POLY1305_SHA256`	no
`TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA`	no
`TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA`	no
`TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA`	no
`TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA`	no
`TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256`	yes
`TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384`	yes
`TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256`	yes
`TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384`	yes
`TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256`	no
`TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256`	no

The curve_preferences argument determines the set of elliptic curves to prefer during a handshake in preference order. If not provided, a default list is used. The set of elliptic curves specified may be from the following:

Curve	Allowed in BoringCrypto builds
`CurveP256`	yes
`CurveP384`	yes
`CurveP521`	yes
`X25519`	no

The min_version and max_version arguments determine the oldest and newest TLS version that’s acceptable from clients. If you don’t provide the min and max TLS version, a default value is used.

The following versions are recognized:

TLS13 for TLS 1.3
TLS12 for TLS 1.2
TLS11 for TLS 1.1
TLS10 for TLS 1.0

`windows certificate filter`

The windows_certificate_filter block is used to configure retrieving certificates from the built-in Windows certificate store. When you use the windows_certificate_filter block the following TLS settings are overridden and cause an error if defined.

cert_pem
cert_file
key_pem
key_file
client_ca
client_ca_file

Warning
This feature is only available on Windows.

TLS min and max may not be compatible with the certificate stored in the Windows certificate store. The windows_certificate_filter serves the certificate even if it isn’t compatible with the specified TLS version.

`client`

The client block is used to check the certificate presented to the server.

Name	Type	Description	Default	Required
`issuer_common_names`	`list(string)`	Issuer common names to check against.		no
`subject_regex`	`string`	Regular expression to match Subject name.	`""`	no
`template_id`	`string`	Client Template ID to match in ASN1 format, for example, “1.2.3”.	`""`	no

`server`

The server block is used to find the certificate to check the signer. If multiple certificates are found, the windows_certificate_filter chooses the certificate with the expiration farthest in the future.

Name	Type	Description	Default	Required
`store`	`string`	Name of the store to look for the server Certificate. For example, `MY` or `CA`.	`""`	yes
`system_store`	`string`	Name of the system store to look for the server Certificate. For example, `LocalMachine` or `CurrentUser`.	`""`	yes
`issuer_common_names`	`list(string)`	Issuer common names to check against.		no
`refresh_interval`	`string`	How often to check for a new server certificate.	`"5m"`	no
`template_id`	`string`	Server Template ID to match in ASN1 format, for example, “1.2.3”.	`""`	no

Examples

Example of enforcing authentication on /metrics and every endpoint that has /v1 as prefix:

http {
  auth {
    basic {
      username = sys.env("BASIC_AUTH_USERNAME")
      password = sys.env("BASIC_AUTH_PASSWORD")
    }

    filter {
      paths                       = ["/metrics", "/v1"]
      authenticate_matching_paths = true
    }
  }
}

Example enforcing authentication on all endpoints except /metrics:

http {
  auth {
    basic {
      username = sys.env("BASIC_AUTH_USERNAME")
      password = sys.env("BASIC_AUTH_PASSWORD")
    }

    filter {
      paths                       = ["/metrics"]
      authenticate_matching_paths = false
    }
  }
}

import.file

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

`import.file`

The import.file block imports custom components from a file or a directory and exposes them to the importer. import.file blocks must be given a label that determines the namespace where custom components are exposed.

Imported directories are treated as single modules to support composability. That means that you can define a custom component in one file and use it in another custom component in another file in the same directory.

You can use the keyword module_path in combination with the stdlib function file.path_join to import a module relative to the current module’s path. The module_path keyword works for modules that are imported via import.file, import.git, and import.string.

Usage

import.file "<NAMESPACE>" {
  filename = <PATH_NAME>
}

Arguments

You can use the following arguments with import.file:

Name	Type	Description	Default	Required
`filename`	`string`	Path of the file or directory on disk to watch.		yes
`detector`	`string`	Which file change detector to use, `fsnotify` or `poll`.	`"fsnotify"`	no
`poll_frequency`	`duration`	How often to poll for file changes.	`"1m"`	no

File change detectors

File change detectors detect when the file needs to be re-read from disk. local.file supports two detectors: fsnotify and poll.

`fsnotify`

The fsnotify detector subscribes to filesystem events, which indicate when the watched file is updated. This detector requires a filesystem that supports events at the operating system level. Network-based filesystems like NFS or FUSE won’t work.

The component re-reads the watched file when a filesystem event is received. This re-read happens for any filesystem event related to the file, including a permissions change.

fsnotify also polls for changes to the file with the configured poll_frequency as a fallback.

fsnotify stops receiving filesystem events if the watched file has been deleted, renamed, or moved. The subscription is re-established on the next poll once the watched file exists again.

`poll`

The poll file change detector causes the watched file to be re-read every poll_frequency, regardless of whether the file changed.

Examples

Import a module from a local file

This example imports a module from a file and instantiates a custom component from the import that adds two numbers:

main.alloy

import.file "math" {
  filename = "module.alloy"
}

math.add "default" {
  a = 15
  b = 45
}

module.alloy

declare "add" {
  argument "a" {}
  argument "b" {}

  export "sum" {
    value = argument.a.value + argument.b.value
  }
}

Import a module in a module imported via import.git

This example imports a module from a file inside of a module that’s imported via import.git:

main.alloy

import.git "math" {
  repository = "https://github.com/wildum/module.git"
  path       = "relative_math.alloy"
  revision   = "master"
}

math.add "default" {
  a = 15
  b = 45
}

relative_math.alloy

import.file "lib" {
  filename = file.path_join(module_path, "lib.alloy")
}

declare "add" {
  argument "a" {}
  argument "b" {}

  lib.plus "default" {
    a = argument.a.value
    b = argument.b.value
  }

  export "output" {
    value = lib.plus.default.sum
  }
}

lib.alloy

declare "plus" {
  argument "a" {}
  argument "b" {}

  export "sum" {
    value = argument.a.value + argument.b.value
  }
}

Import a module in a module imported via import.file

This example imports a module from a file inside of a module that’s imported via another import.file:

main.alloy

import.file "math" {
  filename = "path/to/module/relative_math.alloy"
}

math.add "default" {
  a = 15
  b = 45
}

relative_math.alloy

import.file "lib" {
  filename = file.path_join(module_path, "lib.alloy")
}

declare "add" {
  argument "a" {}
  argument "b" {}

  lib.plus "default" {
    a = argument.a.value
    b = argument.b.value
  }

  export "output" {
    value = lib.plus.default.sum
  }
}

lib.alloy

declare "plus" {
  argument "a" {}
  argument "b" {}

  export "sum" {
    value = argument.a.value + argument.b.value
  }
}

import.git

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

`import.git`

The import.git block imports custom components from a Git repository and exposes them to the importer. import.git blocks must be given a label that determines the namespace where custom components are exposed.

The entire repository is cloned, and the module path is accessible via the module_path keyword. This enables, for example, your module to import other modules within the repository by setting relative paths in the import.file blocks.

Usage

import.git "<NAMESPACE>" {
  repository = "<GIT_REPOSTORY>"
  path       = "<PATH_TO_MODULE>"
}

Arguments

You can use the following arguments with import.git:

Name	Type	Description	Default	Required
`path`	`string`	The path in the repository where the module is stored.		yes
`repository`	`string`	The Git repository address to retrieve the module from.		yes
`pull_frequency`	`duration`	The frequency to pull the repository for updates.	`"60s"`	no
`revision`	`string`	The Git revision to retrieve the module from.	`"HEAD"`	no

You must set the repository attribute to a repository address that Git would recognize with a git clone <REPOSITORY_ADDRESS> command, such as https://github.com/grafana/alloy.git.

When provided, the revision attribute must be set to a valid branch, tag, or commit SHA within the repository.

You must set the path attribute to a path accessible from the repository’s root. It can either be an Alloy configuration file such as <FILE_NAME>.alloy or <DIR_NAME>/<FILE_NAME>.alloy or a directory containing Alloy configuration files such as <DIR_NAME> or . if the Alloy configuration files are stored at the root of the repository.

If pull_frequency isn’t "0s", the Git repository is pulled for updates at the frequency specified. If it’s set to "0s", the Git repository is pulled once on init.

Warning
Pulling hosted Git repositories too often can result in throttling.

Blocks

You can use the following blocks with import.git:

Block	Description	Required
`basic_auth`	Configure `basic_auth` for authenticating to the repository.	no
`ssh_key`	Configure an SSH Key for authenticating to the repository.	no

`basic_auth`

Name	Type	Description	Default	Required
`password`	`secret`	Basic auth password.		no
`username`	`string`	Basic auth username.		no

`ssh_key`

Name	Type	Description	Default	Required
`username`	`string`	SSH username.	`""`	yes
`key_file`	`string`	SSH private key path.	`""`	no
`key`	`secret`	SSH private key.		no
`passphrase`	`secret`	Passphrase for SSH key if needed.		no

Examples

This example imports custom components from a Git repository and uses a custom component to add two numbers:

import.git "math" {
  repository = "https://github.com/wildum/module.git"
  revision   = "master"
  path       = "math.alloy"
}

math.add "default" {
  a = 15
  b = 45
}

This example imports custom components from a directory in a Git repository and uses a custom component to add two numbers:

import.git "math" {
  repository = "https://github.com/wildum/module.git"
  revision   = "master"
  path       = "modules"
}

math.add "default" {
  a = 15
  b = 45
}

import.http

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

`import.http`

import.http retrieves a module from an HTTP server.

Usage

import.http "<LABEL>" {
  url = <URL>
}

Arguments

You can use the following arguments with import.http:

Name	Type	Description	Default	Required
`url`	`string`	URL to poll.		yes
`headers`	`map(string)`	Custom headers for the request.	`{}`	no
`method`	`string`	Define the HTTP method for the request.	`"GET"`	no
`poll_frequency`	`duration`	Frequency to poll the URL.	`"1m"`	no
`poll_timeout`	`duration`	Timeout when polling the URL.	`"10s"`	no

Blocks

You can use the following blocks with import.http:

Block	Description	Required
`client`	HTTP client settings when connecting to the endpoint.	no
`client` > `authorization`	Configure generic authorization to the endpoint.	no
`client` > `basic_auth`	Configure `basic_auth` for authenticating to the endpoint.	no
`client` > `oauth2`	Configure OAuth 2.0 for authenticating to the endpoint.	no
`client` > `oauth2` > `tls_config`	Configure TLS settings for connecting to the endpoint.	no
`client` >`tls_config`	Configure TLS settings for connecting to the endpoint.	no

The > symbol indicates deeper levels of nesting. For example, client > basic_auth refers to an basic_auth block defined inside a client block.

`client`

The client block configures settings used to connect to the HTTP server.

Name	Type	Description	Default	Required
`bearer_token_file`	`string`	File containing a bearer token to authenticate with.		no
`bearer_token`	`secret`	Bearer token to authenticate with.		no
`enable_http2`	`bool`	Whether HTTP2 is supported for requests.	`true`	no
`follow_redirects`	`bool`	Whether redirects returned by the server should be followed.	`true`	no
`http_headers`	`map(list(secret))`	Custom HTTP headers to be sent along with each request. The map key is the header name.		no
`proxy_url`	`string`	HTTP proxy to send requests through.		no
`no_proxy`	`string`	Comma-separated list of IP addresses, CIDR notations, and domain names to exclude from proxying.		no
`proxy_from_environment`	`bool`	Use the proxy URL indicated by environment variables.	`false`	no
`proxy_connect_header`	`map(list(secret))`	Specifies headers to send to proxies during CONNECT requests.		no

bearer_token, bearer_token_file, basic_auth, authorization, and oauth2 are mutually exclusive, and only one can be provided inside of a http_client_config block.

no_proxy can contain IPs, CIDR notations, and domain names. IP and domain names can contain port numbers. proxy_url must be configured if no_proxy is configured.

proxy_from_environment uses the environment variables HTTP_PROXY, HTTPS_PROXY, and NO_PROXY (or the lowercase versions thereof). Requests use the proxy from the environment variable matching their scheme, unless excluded by NO_PROXY. proxy_url and no_proxy must not be configured if proxy_from_environment is configured.

proxy_connect_header should only be configured if proxy_url or proxy_from_environment are configured.

`authorization`

The authorization block configures custom authorization to use when polling the configured URL.

Name	Type	Description	Required
`credentials_file`	`string`	File containing the secret value.	no
`credentials`	`secret`	Secret value.	no
`type`	`string`	Authorization type, for example, “Bearer”.	no

credential and credentials_file are mutually exclusive, and only one can be provided inside an authorization block.

Warning
Using credentials_file causes the file to be read on every outgoing request. Use the local.file component with the credentials attribute instead to avoid unnecessary reads.

`basic_auth`

The basic_auth block configures basic authentication to use when polling the configured URL.

Name	Type	Description	Required
`password_file`	`string`	File containing the basic auth password.	no
`password`	`secret`	Basic auth password.	no
`username`	`string`	Basic auth username.	no

password and password_file are mutually exclusive, and only one can be provided inside a basic_auth block.

Warning
Using password_file causes the file to be read on every outgoing request. Use the local.file component with the password attribute instead to avoid unnecessary reads.

`oauth2`

The oauth2 block configures OAuth 2.0 authorization to use when polling the configured URL.

Name	Type	Description	Default	Required
`client_id`	`string`	OAuth2 client ID.		no
`client_secret_file`	`string`	File containing the OAuth2 client secret.		no
`client_secret`	`secret`	OAuth2 client secret.		no
`endpoint_params`	`map(string)`	Optional parameters to append to the token URL.		no
`no_proxy`	`string`	Comma-separated list of IP addresses, CIDR notations, and domain names to exclude from proxying.		no
`proxy_connect_header`	`map(list(secret))`	Specifies headers to send to proxies during CONNECT requests.		no
`proxy_from_environment`	`bool`	Use the proxy URL indicated by environment variables.	`false`	no
`proxy_url`	`string`	HTTP proxy to send requests through.		no
`scopes`	`list(string)`	List of scopes to authenticate with.		no
`token_url`	`string`	URL to fetch the token from.		no

client_secret and client_secret_file are mutually exclusive, and only one can be provided inside an oauth2 block.

Warning
Using client_secret_file causes the file to be read on every outgoing request. Use the local.file component with the client_secret attribute instead to avoid unnecessary reads.

The oauth2 block may also contain a separate tls_config sub-block.

no_proxy can contain IPs, CIDR notations, and domain names. IP and domain names can contain port numbers. proxy_url must be configured if no_proxy is configured.

proxy_connect_header should only be configured if proxy_url or proxy_from_environment are configured.

`tls_config`

The tls_config block configures TLS settings for connecting to HTTPS servers.

Name	Type	Description	Required
`ca_pem`	`string`	CA PEM-encoded text to validate the server with.	no
`ca_file`	`string`	CA certificate to validate the server with.	no
`cert_pem`	`string`	Certificate PEM-encoded text for client authentication.	no
`cert_file`	`string`	Certificate file for client authentication.	no
`insecure_skip_verify`	`bool`	Disables validation of the server certificate.	no
`key_file`	`string`	Key file for client authentication.	no
`key_pem`	`secret`	Key PEM-encoded text for client authentication.	no
`min_version`	`string`	Minimum acceptable TLS version.	no
`server_name`	`string`	ServerName extension to indicate the name of the server.	no

The following pairs of arguments are mutually exclusive and can’t both be set simultaneously:

ca_pem and ca_file
cert_pem and cert_file
key_pem and key_file

When configuring client authentication, both the client certificate (using cert_pem or cert_file) and the client key (using key_pem or key_file) must be provided.

When min_version isn’t provided, the minimum acceptable TLS version is inherited from Go’s default minimum version, TLS 1.2. If min_version is provided, it must be set to one of the following strings:

"TLS10" (TLS 1.0)
"TLS11" (TLS 1.1)
"TLS12" (TLS 1.2)
"TLS13" (TLS 1.3)

Example

This example imports custom components from an HTTP response and instantiates a custom component for adding two numbers:

module.alloy

declare "add" {
  argument "a" {}
  argument "b" {}

  export "sum" {
    value = argument.a.value + argument.b.value
  }
}

main.alloy

import.http "math" {
  url = <SERVER_URL>
}

math.add "default" {
  a = 15
  b = 45
}

import.string

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

import.string

The import.string block imports custom components from a string and exposes them to the importer. import.string blocks must be given a label that determines the namespace where custom components are exposed.

Usage

import.string "<NAMESPACE>" {
  content = <CONTENT>
}

Arguments

You can use the following argument with import.string:

Name	Type	Description	Default	Required
`content`	`secret` or `string`	The contents of the module to import as a secret or string.		yes

content is a string that contains the configuration of the module to import. content is typically loaded by using the exports of another component. For example,

local.file.<LABEL>.content
remote.http.<LABEL>.content
remote.s3.<LABEL>.content

Example

This example imports a module from the content of a file stored in an S3 bucket and instantiates a custom component from the import that adds two numbers:

remote.s3 "module" {
  path = "s3://test-bucket/module.alloy"
}

import.string "math" {
  content = remote.s3.module.content
}

math.add "default" {
  a = 15
  b = 45
}

livedebugging

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

`livedebugging`

livedebugging is an optional configuration block that enables the live debugging feature, that streams real-time data from your components directly to the Alloy UI.

By default, live debugging is disabled and must be explicitly enabled through this configuration block to make the debugging data visible in the Alloy UI.

Note
The live debugging feature uses the Alloy UI to provide detailed insights into the data flowing through your pipelines. To ensure that your data remains secure while live debugging is enabled, configure TLS in the http block.

Usage

livedebugging {

}

Arguments

You can use the following arguments with livedebugging:

Name	Type	Description	Default	Required
`enabled`	`bool`	Enables the live debugging feature.	`false`	no

Example

The following example enables livedebugging:

livedebugging {
  enabled = true
}

logging

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

`logging`

logging is an optional configuration block used to customize how Alloy produces log messages. logging is specified without a label and can only be provided once per configuration file.

Usage

logging {

}

Arguments

You can use the following arguments with logging:

Name	Type	Description	Default	Required
`format`	`string`	Format to use for writing log lines	`"logfmt"`	no
`level`	`string`	Level at which log lines should be written	`"info"`	no
`write_to`	`list(LogsReceiver)`	List of receivers to send log entries to	`[]`	no

Log level

The following strings are recognized as valid log levels:

"error": Only write logs at the error level.
"warn": Only write logs at the warn level or above.
"info": Only write logs at info level or above.
"debug": Write all logs, including debug level logs.

Log format

The following strings are recognized as valid log line formats:

"json": Write logs as JSON objects.
"logfmt": Write logs as logfmt lines.

Log receivers

The write_to argument allows Alloy to tee its log entries to one or more loki.* component log receivers in addition to the default location. This, for example can be the export of a loki.write component to send log entries directly to Loki, or a loki.relabel component to add a certain label first.

Log location

Alloy writes all logs to stderr.

When you run Alloy as a systemd service, you can view logs written to stderr through journald.

When you run Alloy as a container, you can view logs written to stderr through docker logs or kubectl logs, depending on whether Docker or Kubernetes was used for deploying Alloy.

When you run Alloy as a Windows service, logs are written as event logs. You can view the logs through Event Viewer.

In other cases, redirect stderr of the Alloy process to a file for logs to persist on disk.

Retrieve logs

You can retrieve the logs in different ways depending on your platform and installation method:

Linux:

If you’re running Alloy with systemd, use journalctl -u alloy.
If you’re running Alloy in a Docker container, use docker logs CONTAINER_ID.

macOS:

If you’re running Alloy with Homebrew as a service, use brew services info grafana/grafana/alloy to check status and tail -f $(brew --prefix)/var/log/alloy.log for logs.
If you’re running Alloy with launchd, use log show --predicate 'process == "alloy"' --info or check /usr/local/var/log/alloy.log.
If you’re running Alloy in a Docker container, use docker logs CONTAINER_ID.

Windows:

If you’re running Alloy as a Windows service, check the Windows Event Viewer under Windows Logs > Application for Alloy-related events.
If you’re running Alloy that is manually installed, check the log files in %PROGRAMDATA%\Grafana\Alloy\logs\ or the directory specified in your configuration.
If you’re running Alloy in a Docker container, use docker logs CONTAINER_ID.

All platforms:

Alloy writes logs to stderr if started directly without a service manager.

Example

logging {
  level  = "info"
  format = "logfmt"
}

remotecfg

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

`remotecfg`

remotecfg is an optional configuration block that enables Alloy to fetch and load the configuration from a remote endpoint. remotecfg is specified without a label and can only be provided once per configuration file.

The API definition for managing and fetching configuration that the remotecfg block uses is available under the Apache 2.0 license.

Usage

remotecfg {

}

Arguments

You can use the following arguments with remotecfg:

Name	Type	Description	Default	Required
`attributes`	`map(string)`	A set of self-reported attributes.	`{}`	no
`bearer_token_file`	`string`	File containing a bearer token to authenticate with.		no
`bearer_token`	`secret`	Bearer token to authenticate with.		no
`enable_http2`	`bool`	Whether HTTP2 is supported for requests.	`true`	no
`follow_redirects`	`bool`	Whether redirects returned by the server should be followed.	`true`	no
`http_headers`	`map(list(secret))`	Custom HTTP headers to be sent along with each request. The map key is the header name.		no
`id`	`string`	A self-reported ID.	see below	no
`name`	`string`	A human-readable name for the collector.	`""`	no
`no_proxy`	`string`	Comma-separated list of IP addresses, CIDR notations, and domain names to exclude from proxying.	`""`	no
`poll_frequency`	`duration`	How often to poll the API for new configuration.	`"1m"`	no
`proxy_connect_header`	`map(list(secret))`	Specifies headers to send to proxies during CONNECT requests.		no
`proxy_from_environment`	`bool`	Use the proxy URL indicated by environment variables.	`false`	no
`proxy_url`	`string`	HTTP proxy to send requests through.	`""`	no
`url`	`string`	The address of the API to poll for configuration.	`""`	no

If the url isn’t set, then the service block is a no-op.

If not set, the self-reported id that Alloy uses is a randomly generated, anonymous unique ID (UUID) that is stored as an alloy_seed.json file in the Alloy storage path so that it can persist across restarts. You can use the name field to set another human-friendly identifier for the specific Alloy instance.

The id and attributes fields are used in the periodic request sent to the remote endpoint so that the API can decide what configuration to serve.

The attribute map keys can include any custom value except the reserved prefix collector.. The reserved label prefix is for automatic system attributes. You can’t override this prefix.

collector.os: The operating system where Alloy is running.
collector.version: The version of Alloy.

The poll_frequency must be set to at least "10s".

At most, one of the following can be provided:

no_proxy can contain IPs, CIDR notations, and domain names. IP and domain names can contain port numbers. proxy_url must be configured if no_proxy is configured.

proxy_connect_header should only be configured if proxy_url or proxy_from_environment are configured.

Blocks

You can use the following blocks with remotecfg:

Block	Description	Required
`authorization`	Configure generic authorization to the endpoint.	no
`basic_auth`	Configure `basic_auth` for authenticating to the endpoint.	no
`oauth2`	Configure OAuth 2.0 for authenticating to the endpoint.	no
`oauth2` > `tls_config`	Configure TLS settings for connecting to the endpoint.	no
`tls_config`	Configure TLS settings for connecting to the endpoint.	no

The > symbol indicates deeper levels of nesting. For example, oauth2 > tls_config refers to a tls_config block defined inside an oauth2 block.

`authorization`

Name	Type	Description	Required
`credentials_file`	`string`	File containing the secret value.	no
`credentials`	`secret`	Secret value.	no
`type`	`string`	Authorization type, for example, “Bearer”.	no

credential and credentials_file are mutually exclusive, and only one can be provided inside an authorization block.

Warning
Using credentials_file causes the file to be read on every outgoing request. Use the local.file component with the credentials attribute instead to avoid unnecessary reads.

`basic_auth`

Name	Type	Description	Required
`password_file`	`string`	File containing the basic auth password.	no
`password`	`secret`	Basic auth password.	no
`username`	`string`	Basic auth username.	no

password and password_file are mutually exclusive, and only one can be provided inside a basic_auth block.

Warning
Using password_file causes the file to be read on every outgoing request. Use the local.file component with the password attribute instead to avoid unnecessary reads.

`oauth2`

Name	Type	Description	Default	Required
`client_id`	`string`	OAuth2 client ID.		no
`client_secret_file`	`string`	File containing the OAuth2 client secret.		no
`client_secret`	`secret`	OAuth2 client secret.		no
`endpoint_params`	`map(string)`	Optional parameters to append to the token URL.		no
`no_proxy`	`string`	Comma-separated list of IP addresses, CIDR notations, and domain names to exclude from proxying.		no
`proxy_connect_header`	`map(list(secret))`	Specifies headers to send to proxies during CONNECT requests.		no
`proxy_from_environment`	`bool`	Use the proxy URL indicated by environment variables.	`false`	no
`proxy_url`	`string`	HTTP proxy to send requests through.		no
`scopes`	`list(string)`	List of scopes to authenticate with.		no
`token_url`	`string`	URL to fetch the token from.		no

client_secret and client_secret_file are mutually exclusive, and only one can be provided inside an oauth2 block.

Warning
Using client_secret_file causes the file to be read on every outgoing request. Use the local.file component with the client_secret attribute instead to avoid unnecessary reads.

The oauth2 block may also contain a separate tls_config sub-block.

no_proxy can contain IPs, CIDR notations, and domain names. IP and domain names can contain port numbers. proxy_url must be configured if no_proxy is configured.

proxy_connect_header should only be configured if proxy_url or proxy_from_environment are configured.

`tls_config`

Name	Type	Description	Required
`ca_pem`	`string`	CA PEM-encoded text to validate the server with.	no
`ca_file`	`string`	CA certificate to validate the server with.	no
`cert_pem`	`string`	Certificate PEM-encoded text for client authentication.	no
`cert_file`	`string`	Certificate file for client authentication.	no
`insecure_skip_verify`	`bool`	Disables validation of the server certificate.	no
`key_file`	`string`	Key file for client authentication.	no
`key_pem`	`secret`	Key PEM-encoded text for client authentication.	no
`min_version`	`string`	Minimum acceptable TLS version.	no
`server_name`	`string`	ServerName extension to indicate the name of the server.	no

The following pairs of arguments are mutually exclusive and can’t both be set simultaneously:

ca_pem and ca_file
cert_pem and cert_file
key_pem and key_file

When configuring client authentication, both the client certificate (using cert_pem or cert_file) and the client key (using key_pem or key_file) must be provided.

"TLS10" (TLS 1.0)
"TLS11" (TLS 1.1)
"TLS12" (TLS 1.2)
"TLS13" (TLS 1.3)

Example

remotecfg {
    url = "<SERVICE_URL>"
    basic_auth {
        username      = "<USERNAME>"
        password_file = "<PASSWORD_FILE>"
    }

    id             = constants.hostname
    attributes     = {"cluster" = "dev", "namespace" = "otlp-dev"}
    poll_frequency = "5m"
}

tracing

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

`tracing`

tracing is an optional configuration block used to customize how Alloy produces traces. tracing is specified without a label and can only be provided once per configuration file.

Usage

tracing {

}

Arguments

You can use the following arguments with tracing:

Name	Type	Description	Default	Required
`sampling_fraction`	`number`	Fraction of traces to keep.	`0.1`	no
`write_to`	`list(otelcol.Consumer)`	Inputs from `otelcol` components to send traces to.	`[]`	no
`send_traceparent`	`bool`	Send traceparent header with requests.	`false`	no

The write_to argument controls which components to send traces to for processing. The elements in the array can be any otelcol component that accept traces, including processors and exporters. When write_to is set to an empty array [], all traces are dropped.

Note
Any traces generated before the tracing block has been evaluated,such as at the early start of the process’ lifetime, are dropped.

The sampling_fraction argument controls what percentage of generated traces should be sent to the consumers specified by write_to. When set to 1 or greater, 100% of traces are kept. When set to 0 or lower, 0% of traces are kept.

The send_traceparent argument controls whether the traceparent header is sent with requests to other services.

Blocks

You can use the following blocks with tracing:

Block	Description	Required
`sampler`	Define custom sampling on top of the base sampling fraction.	no
`sampler` > `jaeger_remote`	Retrieve sampling information via a Jaeger remote sampler.	no

The > symbol indicates deeper levels of nesting. For example, sampler > jaeger_remote refers to a jaeger_remote block defined inside an sampler block.

`sampler`

The sampler block contains a definition of a custom sampler to use. The sampler block supports no arguments and is controlled fully through inner blocks.

It’s invalid to define more than one sampler to use in the sampler block.

`jaeger_remote`

The jaeger_remote block configures the retrieval of sampling information through a remote server that exposes Jaeger sampling strategies.

Name	Type	Description	Default	Required
`max_operations`	`number`	Limit number of operations which can have custom sampling.	`256`	no
`refresh_interval`	`duration`	Frequency to poll the URL for new sampling strategies.	`"1m"`	no
`url`	`string`	URL to retrieve sampling strategies from.	`"http://127.0.0.1:5778/sampling"`	no

The remote sampling strategies are retrieved from the URL specified by the url argument, and polled for updates on a timer. The frequency for how often polling occurs is controlled by the refresh_interval argument.

Requests to the remote sampling strategies server are made through an HTTP GET request to the configured url argument. A service=alloy query parameter is always added to the URL to allow the server to respond with service-specific strategies. The HTTP response body is read as JSON matching the schema specified in the Jaeger strategies.json file.

The max_operations limits the amount of custom span names that can have custom sampling rules. If the remote sampling strategy exceeds the limit, sampling decisions fall back to the default sampler.

Example

tracing {
  sampling_fraction = 0.1
  send_traceparent = true

  write_to = [otelcol.exporter.otlp.tempo.input]
}

otelcol.exporter.otlp "tempo" {
  // Send traces to a locally running Tempo without TLS enabled.
  client {
    endpoint = sys.env("TEMPO_OTLP_ENDPOINT")

    tls {
      insecure = true
    }
  }
}