prometheus on Grafana Labs

prometheus.echo

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

`prometheus.echo`

The prometheus.echo component receives Prometheus metrics and writes them to stdout in Prometheus exposition format. This component is useful for debugging and testing the flow of metrics through a pipeline, allowing you to see exactly what metrics are being received at a particular point in your configuration.

Usage

prometheus.echo "<LABEL>" {
}

Arguments

You can use the following arguments with prometheus.echo:

Name	Type	Description	Default	Required
`format`	`string`	The output format for metrics. Must be `text` or `openmetrics`.	`text`	no

The format argument controls how metrics are encoded when written to stdout:

text - Uses the Prometheus text exposition format (default).
openmetrics - Uses the OpenMetrics text format.

Blocks

The prometheus.echo component doesn’t support any blocks. You can configure this component with arguments.

Exported fields

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

Name	Type	Description
`receiver`	`MetricsReceiver`	A value that other components can use to send metrics to.

Component health

prometheus.echo is only reported as unhealthy if given an invalid configuration. In those cases, exported fields retain their last healthy values.

Debug information

prometheus.echo doesn’t expose any component-specific debug information.

Debug metrics

prometheus.echo doesn’t expose any component-specific debug metrics.

Example

This example creates a metrics generation and inspection pipeline:

prometheus.exporter.unix "default" {
}

prometheus.scrape "demo" {
  targets    = prometheus.exporter.unix.default.targets
  forward_to = [prometheus.echo.debug.receiver]
}

prometheus.echo "debug" {
  format = "text"
}

In this example:

The prometheus.exporter.unix component exposes system metrics.
The prometheus.scrape component scrapes those metrics.
The prometheus.echo component receives the scraped metrics and writes them to stdout in Prometheus text format.

When you run this configuration, you’ll see the metrics being written to stdout, which is useful to:

Debug metric collection issues
Verify metric labels and values
Test metric transformations
Understand the structure of metrics in your pipeline

Example with OpenMetrics format

prometheus.scrape "demo" {
  targets = [
    {"__address__" = "localhost:9090"},
  ]
  forward_to = [prometheus.echo.debug.receiver]
}

prometheus.echo "debug" {
  format = "openmetrics"
}

This example outputs metrics using the OpenMetrics format instead of the traditional Prometheus text format.

Compatible components

prometheus.echo has exports that can be consumed by the following components:

Components that consume Prometheus MetricsReceiver

Note
Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.

prometheus.enrich

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

`prometheus.enrich`

EXPERIMENTAL: This is an experimental component. Experimental components are subject to frequent breaking changes, and may be removed with no equivalent replacement. To enable and use an experimental component, you must set the stability.level flag to experimental.

The prometheus.enrich component enriches metrics with additional labels from service discovery targets. It matches a label from incoming metrics against a label from discovered targets, and copies specified labels from the matched target to the metric sample. If match doesn’t happen, the metrics will be passed through.

Usage

prometheus.enrich "<LABEL>" {
  targets = <DISCOVERY_COMPONENT>.targets
  
  target_match_label = "<LABEL>"
  
  forward_to = [<RECEIVER_LIST>]
}

Arguments

You can use the following arguments with prometheus.enrich:

Name	Type	Description	Required
`forward_to`	`list(MetricsReceiver)`	Where the metrics should be forwarded to, after enrichment.	yes
`target_match_label`	`string`	The label from discovered targets to match against, for example, `"__inventory_consul_service"`.	yes
`targets`	`list(map(string))`	List of targets from a discovery component.	yes
`labels_to_copy`	`list(string)`	List of labels to copy from discovered targets to metrics. If empty, all labels are copied.	no
`metrics_match_label`	`string`	The label from incoming metrics to match against discovered targets, for example `"service_name"`.	no

If not provided, the metrics_match_label attribute defaults to the value of target_match_label.

Blocks

The prometheus.enrich component doesn’t support any blocks. You can configure this component with arguments.

Exports

The following values are exported:

Name	Type	Description
`receiver`	`MetricsReceiver`	The input receiver where samples are sent to be enriched.

Debug information

prometheus.enrich doesn’t expose any component-specific debug information.

Debug metrics

prometheus_fanout_latency (histogram): Write latency for sending to direct and indirect components.
prometheus_forwarded_samples_total (counter): Total number of samples sent to downstream components.
prometheus_target_cache_size (gauge): The number of targets in the targets list.

Example

Enrich metrics from `prometheus.scrape`

The following example shows how the prometheus.enrich enriches incoming metrics from prometheus.scrape.default, using HTTP discovery, and forwards the results to prometheus.remote_write.default component:

discovery.http "default" {
    url = "http://network-inventory.example.com/prometheus_sd"
}

prometheus.scrape "default" {
  targets = [
    {"__address__" = "example-app:9001"},
  ]

  forward_to = [prometheus.enrich.default.receiver]
}

prometheus.enrich "default" {
	targets = discovery.http.default.targets

	target_match_label = "hostname"

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

prometheus.remote_write "default" {
  endpoint {
    url = "http://mimir:9009/api/v1/push"
  }
}

Enrich metrics from `prometheus.receive_http`

The following example shows how the prometheus.enrich enriches incoming metrics from prometheus.receive_http.default, using HTTP discovery, and forwards the results to prometheus.remote_write.default component:

discovery.file "network_devices" {  
   files = ["/etc/alloy/devices.json"]  
}  
  
prometheus.receive_http "default" {
  http {
    listen_address = "0.0.0.0"
    listen_port = 9999
  }
  
  forward_to = [prometheus.enrich.default.receiver]
}

prometheus.enrich "default" {  
    targets = discovery.file.network_devices.targets  
  
    target_match_label = "hostname"  
    
    forward_to = [prometheus.remote_write.default.receiver]  
}

prometheus.remote_write "default" {  
  endpoint {  
    url = "http://mimir:9009/api/v1/push"    
  }    
}

Compatible components

prometheus.enrich can accept arguments from the following components:

Components that export Targets
Components that export Prometheus MetricsReceiver

prometheus.enrich has exports that can be consumed by the following components:

Components that consume Prometheus MetricsReceiver

Note
Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.

prometheus.exporter.apache

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

`prometheus.exporter.apache`

The prometheus.exporter.apache component embeds apache_exporter for collecting mod_status statistics from an Apache server.

Usage

prometheus.exporter.apache "<LABEL>" {
}

Arguments

You can use the following arguments with prometheus.exporter.apache.

Name	Type	Description	Default	Required
`host_override`	`string`	Override for HTTP Host header.		no
`insecure`	`bool`	Ignore server certificate if using HTTPS.	`false`	no
`scrape_uri`	`string`	URI to Apache stub status page.	`"http://localhost/server-status?auto"`	no

Blocks

The prometheus.exporter.apache component doesn’t support any blocks. You can configure this component with arguments.

Exported fields

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

Name	Type	Description
`targets`	`list(map(string))`	The targets that can be used to collect exporter metrics.

For example, the targets can either be passed to a discovery.relabel component to rewrite the targets’ label sets or to a prometheus.scrape component that collects the exposed metrics.

The exported targets use the configured in-memory traffic address specified by the run command.

Component health

prometheus.exporter.apache is only reported as unhealthy if given an invalid configuration. In those cases, exported fields retain their last healthy values.

Debug information

prometheus.exporter.apache doesn’t expose any component-specific debug information.

Debug metrics

prometheus.exporter.apache doesn’t expose any component-specific debug metrics.

Example

This example uses a prometheus.scrape component to collect metrics from prometheus.exporter.apache:

prometheus.exporter.apache "example" {
  scrape_uri = "http://web.example.com/server-status?auto"
}

// Configure a prometheus.scrape component to collect apache metrics.
prometheus.scrape "demo" {
  targets    = prometheus.exporter.apache.example.targets
  forward_to = [prometheus.remote_write.demo.receiver]
}

prometheus.remote_write "demo" {
  endpoint {
    url = "<PROMETHEUS_REMOTE_WRITE_URL>"

    basic_auth {
      username = "<USERNAME>"
      password = "<PASSWORD>"
    }
  }
}

Replace the following:

<PROMETHEUS_REMOTE_WRITE_URL>: The URL of the Prometheus remote_write compatible server to send metrics to.
<USERNAME>: The username to use for authentication to the remote_write API.
<PASSWORD>: The password to use for authentication to the remote_write API.

Compatible components

prometheus.exporter.apache has exports that can be consumed by the following components:

Components that consume Targets

Note
Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.

prometheus.exporter.azure

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

`prometheus.exporter.azure`

The prometheus.exporter.azure component embeds azure-metrics-exporter to collect metrics from Azure Monitor.

The exporter supports all metrics defined by Azure Monitor. You can find the complete list of available metrics in the Azure Monitor documentation. Metrics for this integration are exposed with the template azure_{type}_{metric}_{aggregation}_{unit} by default. As an example, the Egress metric for BlobService would be exported as azure_microsoft_storage_storageaccounts_blobservices_egress_total_bytes.

The exporter offers the following two options for gathering metrics.

(Default) Use an Azure Resource Graph query to identify resources for gathering metrics.
1. This query makes one API call per resource identified.
2. Subscriptions with a reasonable amount of resources can hit the 12000 requests per hour rate limit Azure enforces.
Set the regions to gather metrics from and get metrics for all resources across those regions.
1. This option makes one API call per subscription, dramatically reducing the number of API calls.
2. This approach doesn’t work with all resource types, and Azure doesn’t document which resource types do or don’t work.
3. A resource type that’s not supported produces errors that look like Resource type: microsoft.containerservice/managedclusters not enabled for Cross Resource metrics.
4. If you encounter one of these errors you must use the default Azure Resource Graph based option to gather metrics.

Authentication

Alloy must be running in an environment with access to Azure. The exporter uses the Azure SDK for go and supports authentication.

The account used by Alloy needs:

When using an Azure Resource Graph query, read access to the resources that will be queried by Resource Graph.

Permissions to call the Microsoft.Insights Metrics API which should be the Microsoft.Insights/Metrics/Read permission.

Usage

prometheus.exporter.azure "<LABEL>" {
        subscriptions = [
                <SUB_ID_1>,
                <SUB_ID_2>,
                ...
        ]

        resource_type = "<RESOURCE_TYPE>"

        metrics = [
                "<METRIC_1>",
                "<METRIC_2>",
                ...
        ]
}

Arguments

You can use the following arguments with prometheus.exporter.azure:

Name	Type	Description	Default	Required
`metrics`	`list(string)`	The metrics to scrape from resources.		yes
`resource_type`	`string`	The Azure Resource Type to scrape metrics for.		yes
`subscriptions`	`list(string)`	List of subscriptions to scrape metrics from.		yes
`azure_cloud_environment`	`string`	Name of the cloud environment to connect to.	`"azurecloud"`	no
`included_dimensions`	`list(string)`	List of dimensions to include on the final metrics.		no
`included_resource_tags`	`list(string)`	List of resource tags to include on the final metrics.	`["owner"]`	no
`metric_aggregations`	`list(string)`	Aggregations to apply for the metrics produced.		no
`metric_help_template`	`string`	Description of the metric.	`"Azure metric {metric} for {type} with aggregation {aggregation} as {unit}"`	no
`metric_name_template`	`string`	Metric template used to expose the metrics.	`"azure_{type}_{metric}_{aggregation}_{unit}"`	no
`metric_namespace`	`string`	Namespace for `resource_type` which have multiple levels of metrics.		no
`regions`	`list(string)`	The list of regions for gathering metrics. Gathers metrics for all resources in the subscription. Can’t be used if `resource_graph_query_filter` is set.		no
`resource_graph_query_filter`	`string`	The Kusto query filter to apply when searching for resources. Can’t be used if `regions` is set.		no
`timespan`	`string`	ISO8601 Duration over which the metrics are being queried.	`"PT5M"` (5 minutes)	no
`interval`	`string`	ISO8601 Duration used when to generate individual datapoints in Azure Monitor. Must be smaller than `timespan`.	`"PT1M"` (1 minute)	no
`validate_dimensions`	`bool`	Enable dimension validation in the azure SDK.	`false`	no

The list of available resource_type values and their corresponding metrics can be found in Azure Monitor essentials.

The list of available regions to your subscription can be found by running the Azure CLI command az account list-locations --query '[].name'.

The resource_graph_query_filter can be embedded into a template query of the form Resources | where type =~ "<resource_type>" | <resource_graph_query_filter> | project id, tags.

Valid values for metric_aggregations are minimum, maximum, average, total, and count. If no aggregation is specified, the value is retrieved from the metric.

For example, the aggregation value of the metric Availability in Microsoft.ClassicStorage/storageAccounts is average.

Every metric has its own set of dimensions.

For example, the dimensions for the metric Availability in Microsoft.ClassicStorage/storageAccounts are GeoType, ApiName, and Authentication.

If a single dimension is requested, it will have the name dimension. If multiple dimensions are requested, they will have the name dimension<dimension_name>.

Tags in included_resource_tags will be added as labels with the name tag_<tag_name>.

Valid values for azure_cloud_environment are azurecloud, azurechinacloud, azuregovernmentcloud and azurepprivatecloud.

validate_dimensions is disabled by default to reduce the number of Azure exporter instances required when a resource_type has metrics with varying dimensions. When validate_dimensions is enabled you will need one exporter instance per metric + dimension combination which is more tedious to maintain.

timespan and interval are used to control how metrics are queried from Azure Monitor. The exporter queries metrics over the timespan and returns the most recent datapoint at the specified interval. If you are having issues with missing metrics, try increasing the timespan to a larger value, such as PT10M for 10 minutes, or PT15M for 15 minutes.

Blocks

The prometheus.exporter.azure component doesn’t support any blocks. You can configure this component with arguments.

Exported fields

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

Name	Type	Description
`targets`	`list(map(string))`	The targets that can be used to collect exporter metrics.

For example, the targets can either be passed to a discovery.relabel component to rewrite the targets’ label sets or to a prometheus.scrape component that collects the exposed metrics.

The exported targets use the configured in-memory traffic address specified by the run command.

Component health

prometheus.exporter.azure is only reported as unhealthy if given an invalid configuration. In those cases, exported fields retain their last healthy values.

Debug information

prometheus.exporter.azure doesn’t expose any component-specific debug information.

Debug metrics

prometheus.exporter.azure doesn’t expose any component-specific debug metrics.

Examples

prometheus.exporter.azure "example" {
    subscriptions    = "<SUBSCRIPTIONS>"
    resource_type    = "Microsoft.Storage/storageAccounts"
    regions          = [
        "westeurope",
    ]
    metric_namespace = "Microsoft.Storage/storageAccounts/blobServices"
    metrics          = [
        "Availability",
        "BlobCapacity",
        "BlobCount",
        "ContainerCount",
        "Egress",
        "IndexCapacity",
        "Ingress",
        "SuccessE2ELatency",
        "SuccessServerLatency",
        "Transactions",
    ]
    included_dimensions = [
        "ApiName",
        "TransactionType",
    ]
    timespan         = "PT1H"
}

// Configure a prometheus.scrape component to send metrics to.
prometheus.scrape "demo" {
    targets    = prometheus.exporter.azure.example.targets
    forward_to = [prometheus.remote_write.demo.receiver]
}

prometheus.remote_write "demo" {
    endpoint {
        url = "<PROMETHEUS_REMOTE_WRITE_URL>"

        basic_auth {
            username = "<USERNAME>"
            password = "<PASSWORD>"
        }
    }
}

Replace the following:

<SUBSCRIPTIONS>: The Azure subscription IDs holding the resources you are interested in.
<PROMETHEUS_REMOTE_WRITE_URL>: The URL of the Prometheus remote_write-compatible server to send metrics to.
<USERNAME>: The username to use for authentication to the remote_write API.
<PASSWORD>: The password to use for authentication to the remote_write API.

Compatible components

prometheus.exporter.azure has exports that can be consumed by the following components:

Components that consume Targets

Note
Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.

prometheus.exporter.blackbox

Mon, 13 Apr 2026 07:37:47 +0000

`prometheus.exporter.blackbox`

The prometheus.exporter.blackbox component embeds the blackbox_exporter. The blackbox_exporter lets you collect blackbox metrics (probes) and expose them as Prometheus metrics.

Usage

prometheus.exporter.blackbox "<LABEL>" {
  target {
    name    = "<NAME>"
    address = "<EXAMPLE_ADDRESS>"
  }
}

prometheus.exporter.blackbox "<LABEL>" {
  targets = <TARGET_LIST>
}

Arguments

You can use the following arguments with prometheus.exporter.blackbox:

Name	Type	Description	Default	Required
`config_file`	`string`	`blackbox_exporter` configuration file path.		no
`config`	`string` or `secret`	`blackbox_exporter` configuration as inline string.		no
`probe_timeout_offset`	`duration`	Offset in seconds to subtract from timeout when probing targets.	`"0.5s"`	no
`targets`	`list(map(string))`	Blackbox targets.		no

Either config_file or config must be specified. The config_file argument points to a YAML file defining which blackbox_exporter modules to use. The config argument must be a YAML document as string defining which blackbox_exporter modules to use. config is typically loaded by using the exports of another component. For example:

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

The timeout attribute in config or config_file has an effective upper limit of 10 seconds. Refer to the Prometheus blackbox exporter issue 751 for more information.

You can’t use both the targets argument and the [target][] block in the same configuration file. The targets argument must be used when blackbox targets can’t be passed as a target block because another component supplies them.

You can set the following labels to a target:

name: The name of the target to probe (required).
address: The address of the target to probe (required).
module: The blackbox module to use to probe.

The component passes any additional labels to the exported target.

Refer to blackbox_exporter for more information about generating a configuration file.

Blocks

You can use the following block with prometheus.exporter.blackbox:

Name	Description	Required
`target`	Configures a blackbox target.	no

`target`

Name	Type	Description	Default	Required
`address`	`string`	The address of the target to probe.		yes
`name`	`string`	The name of the target to probe.		yes
`labels`	`map(string)`	Labels to add to the target.		no
`module`	`string`	Blackbox module to use to probe.	`""`	no

The target block defines an individual blackbox target. The target block may be specified multiple times to define multiple targets. The name attribute is required and is used in the target’s job label.

Labels specified in the labels argument won’t override labels set by blackbox_exporter.

Exported fields

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

Name	Type	Description
`targets`	`list(map(string))`	The targets that can be used to collect exporter metrics.

For example, the targets can either be passed to a discovery.relabel component to rewrite the targets’ label sets or to a prometheus.scrape component that collects the exposed metrics.

The exported targets use the configured in-memory traffic address specified by the run command.

Component health

prometheus.exporter.blackbox is only reported as unhealthy if given an invalid configuration. In those cases, exported fields retain their last healthy values.

Debug information

prometheus.exporter.blackbox doesn’t expose any component-specific debug information.

Debug metrics

prometheus.exporter.blackbox doesn’t expose any component-specific debug metrics.

Examples

Collect metrics using a blackbox exporter configuration file

This example uses a prometheus.scrape component to collect metrics from prometheus.exporter.blackbox. It adds an extra label, env="dev", to the metrics emitted by the grafana target. The example target doesn’t have any added labels.

The config_file argument defines which blackbox_exporter modules to use. You can use the blackbox example configuration file.

prometheus.exporter.blackbox "example" {
  config_file = "blackbox_modules.yml"

  target {
    name    = "example"
    address = "https://example.com"
    module  = "http_2xx"
  }

  target {
    name    = "grafana"
    address = "https://grafana.com"
    module  = "http_2xx"
    labels = {
      "env" = "dev",
    }
  }
}

// Configure a prometheus.scrape component to collect blackbox metrics.
prometheus.scrape "demo" {
  targets    = prometheus.exporter.blackbox.example.targets
  forward_to = [prometheus.remote_write.demo.receiver]
}

prometheus.remote_write "demo" {
  endpoint {
    url = "<PROMETHEUS_REMOTE_WRITE_URL>"

    basic_auth {
      username = "<USERNAME>"
      password = "<PASSWORD>"
    }
  }
}

Replace the following:

<PROMETHEUS_REMOTE_WRITE_URL>: The URL of the Prometheus remote_write compatible server to send metrics to.
<USERNAME>: The username to use for authentication to the remote_write API.
<PASSWORD>: The password to use for authentication to the remote_write API.

Collect metrics using an embedded configuration

This example uses an embedded configuration:

prometheus.exporter.blackbox "example" {
  config = "{ modules: { http_2xx: { prober: http, timeout: 5s } } }"

  target {
    name    = "example"
    address = "https://example.com"
    module  = "http_2xx"
  }

  target {
    name    = "grafana"
    address = "https://grafana.com"
    module  = "http_2xx"
    labels = {
      "env" = "dev",
    }
  }
}

// Configure a prometheus.scrape component to collect blackbox metrics.
prometheus.scrape "demo" {
  targets    = prometheus.exporter.blackbox.example.targets
  forward_to = [prometheus.remote_write.demo.receiver]
}

prometheus.remote_write "demo" {
  endpoint {
    url = PROMETHEUS_REMOTE_WRITE_URL

    basic_auth {
      username = USERNAME
      password = PASSWORD
    }
  }
}

Collect metrics from a dynamic set of targets

This example is the same as above but the blackbox targets are discovered via a discovery.file component and sent to the prometheus.exporter.blackbox:

discovery.file "example" {
  files = ["targets.yml"]
}

prometheus.exporter.blackbox "example" {
  config = "{ modules: { http_2xx: { prober: http, timeout: 5s } } }"
  targets = discovery.file.example.targets
}

prometheus.scrape "example" {
  targets    = prometheus.exporter.blackbox.example.targets
  forward_to = [prometheus.remote_write.example.receiver]
}

prometheus.remote_write "example" {
  endpoint {
    url = "<PROMETHEUS_REMOTE_WRITE_URL>"

    basic_auth {
      username = "<USERNAME>"
      password = "<PASSWORD>"
    }
  }
}

The YAML file in this example looks like this:

- targets:
  - localhost:9009
  labels:
    name: t1
    module: http_2xx
    other_label: example
- targets:
  - localhost:9009
  labels:
    name: t2
    module: http_2xx

Replace the following:

<PROMETHEUS_REMOTE_WRITE_URL>: The URL of the Prometheus remote_write compatible server to send metrics to.
<USERNAME>: The username to use for authentication to the remote_write API.
<PASSWORD>: The password to use for authentication to the remote_write API.

Set instance label to target URL

Some dashboards may expect the instance label on the Blackbox metrics to contain the value of the target URL. The following example demonstrates how to achieve that with Prometheus relabeling:

prometheus.exporter.blackbox "example" {
  config = "{ modules: { http_2xx: { prober: http, timeout: 5s } } }"

  target {
    name    = "example"
    address = "example.com"
    module = "http_2xx"
  }
}

discovery.relabel "example" {
  targets = prometheus.exporter.blackbox.example.targets

  rule {
    source_labels = ["__param_target"]
    target_label = "instance"
  }
}

prometheus.scrape "example" {
  targets = discovery.relabel.example.output
  forward_to = [prometheus.remote_write.metrics_service.receiver]
}

Compatible components

prometheus.exporter.blackbox has exports that can be consumed by the following components:

Components that consume Targets

Note
Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.

prometheus.exporter.cadvisor

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

`prometheus.exporter.cadvisor`

The prometheus.exporter.cadvisor component collects container metrics with cAdvisor.

Note
We do not recommend using this exporter with clustering enabled.

The default instance label set by this exporter is the hostname of the machine running Alloy. Alloy clustering uses consistent hashing to distribute targets across the instances. This requires the discovered targets to be the same and have the same labels across all cluster instances.

If you do need to use this component in a cluster, use a dedicated prometheus.scrape component that’s used to scrape this exporter and doesn’t have clustering enabled. Alternatively, use discovery.relabel to set the instance label to a value that is the same across all cluster instances.

Note
The prometheus.exporter.cadvisor component only works on Linux systems. On other operating systems, Alloy writes a warning to the logs and the component doesn’t collect container metrics.

The component requires specific permissions and configuration depending on your deployment environment.

When you run Alloy as a Linux binary, systemd service, or with the non-root alloy user, you must grant the alloy user permissions to access the container runtime socket and related directories to collect metrics from containers on the host.

The component works with Docker, containerd, Container Runtime Interface for OpenShift (CRI-O), and systemd container runtimes.

For Docker, grant permissions using one of these approaches:

Add to docker group (recommended): Add the alloy user to the docker group:
Bash
```
sudo usermod -aG docker alloy
```
Then restart the Alloy service:
Bash
```
sudo systemctl restart alloy
```

Note
The docker group grants privileges equivalent to the root user. For more information about the security implications, refer to Docker security.

Using ACLs: Grant the alloy user read and execute permissions to /var/lib/docker/:

sudo setfacl -R -m d:u:alloy:rx /var/lib/docker/
sudo setfacl -R -m u:alloy:rx /var/lib/docker/

Note
You must rerun these commands when adding containers, as they don’t automatically apply to newly created directories.

Running as root: Modify the systemd service to run Alloy as root:
Bash
```
sudo systemctl edit alloy.service
```
Add the following override:
ini
```
[Service]
User=root
```

Caution
Running Alloy as root has security implications. Only use this approach if necessary for your environment.

For more information about running Alloy without root privileges, refer to Configure Alloy to run as a nonroot user.

When you run Alloy in Kubernetes to collect container metrics, deploy Alloy as a DaemonSet to collect metrics from each node.

The DaemonSet requires:

Host network access: To access the container runtime
Volume mounts: Access to the container runtime socket and system directories
Security context: Privileged access or specific capabilities

For detailed Kubernetes Deployment guidance, refer to the Kubernetes Deployment example section.

When you run Alloy itself as a Docker container to monitor other containers on the host, the Alloy container requires:

Privileged mode: Access to host resources
Volume mounts: Access to the container runtime socket and system directories

For a complete Docker container deployment example, refer to the Docker deployment example section.

Usage

prometheus.exporter.cadvisor "<LABEL>" {
}

Arguments

You can use the following arguments with prometheus.exporter.cadvisor:

Name	Type	Description	Default	Required
`allowlisted_container_labels`	`list(string)`	Allowlist of container labels to convert to Prometheus labels.	`[]`	no
`containerd_host`	`string`	The containerd endpoint.	`"/run/containerd/containerd.sock"`	no
`containerd_namespace`	`string`	The containerd namespace.	`"k8s.io"`	no
`disable_root_cgroup_stats`	`bool`	Disable collecting root Cgroup stats.	`false`	no
`disabled_metrics`	`list(string)`	List of metrics to be disabled which, if set, overrides the default disabled metrics.	(see below)	no
`docker_host`	`string`	Docker endpoint.	`"unix:///var/run/docker.sock"`	no
`docker_only`	`bool`	Only report docker containers in addition to root stats.	`false`	no
`docker_tls_ca`	`string`	Path to a trusted CA for TLS connection to docker.	`"ca.pem"`	no
`docker_tls_cert`	`string`	Path to client certificate for TLS connection to docker.	`"cert.pem"`	no
`docker_tls_key`	`string`	Path to private key for TLS connection to docker.	`"key.pem"`	no
`enabled_metrics`	`list(string)`	List of metrics to be enabled which, if set, overrides `disabled_metrics`.	`[]`	no
`env_metadata_allowlist`	`list(string)`	Allowlist of environment variable keys matched with a specified prefix that needs to be collected for containers.	`[]`	no
`perf_events_config`	`string`	Path to a JSON file containing the configuration of perf events to measure.	`""`	no
`raw_cgroup_prefix_allowlist`	`list(string)`	List of cgroup path prefixes that need to be collected, even when `docker_only` is specified.	`[]`	no
`resctrl_interval`	`duration`	Interval to update resctrl mon groups.	`"0"`	no
`storage_duration`	`duration`	Length of time to keep data stored in memory.	`"2m"`	no
`store_container_labels`	`bool`	Whether to convert container labels and environment variables into labels on Prometheus metrics for each container.	`true`	no
`use_docker_tls`	`bool`	Use TLS to connect to docker.	`false`	no

For allowlisted_container_labels to take effect, store_container_labels must be set to false.

If a container is using the overlayfs storage driver, ensure the containerd_host attribute is set correctly to be able to retrieve its metrics.

env_metadata_allowlist is only supported for containerd and Docker runtimes.

If perf_events_config isn’t set, measurement of perf events is disabled.

A resctrl_interval of 0 disables updating mon groups.

The values for enabled_metrics and disabled_metrics don’t correspond to Prometheus metrics, but to kinds of metrics that should or shouldn’t be exposed. The values that you can use are:

"advtcp"
"app"
"cpu_topology"
"cpu"
"cpuLoad"
"cpuset"
"disk"
"diskIO"
"hugetlb"
"memory_numa"
"memory"
"network"
"oom_event"
"percpu"
"perf_event"
"process"
"referenced_memory"
"resctrl"
"sched"
"tcp"
"udp"

By default the following metric kinds are disabled:

"advtcp"
"cpu_topology"
"cpuset"
"hugetlb"
"memory_numa"
"process"
"referenced_memory"
"resctrl"
"tcp"
"udp"

Blocks

The prometheus.exporter.cadvisor component doesn’t support any blocks. You can configure this component with arguments.

Exported fields

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

Name	Type	Description
`targets`	`list(map(string))`	The targets that can be used to collect exporter metrics.

For example, the targets can either be passed to a discovery.relabel component to rewrite the targets’ label sets or to a prometheus.scrape component that collects the exposed metrics.

The exported targets use the configured in-memory traffic address specified by the run command.

Component health

prometheus.exporter.cadvisor is only reported as unhealthy if given an invalid configuration. In those cases, exported fields retain their last healthy values.

Debug information

prometheus.exporter.cadvisor doesn’t expose any component-specific debug information.

Debug metrics

prometheus.exporter.cadvisor doesn’t expose any component-specific debug metrics.

Examples

Component configuration

This example uses a prometheus.scrape component to collect metrics from prometheus.exporter.cadvisor:

prometheus.exporter.cadvisor "example" {
  docker_host = "unix:///var/run/docker.sock"

  storage_duration = "5m"
}

// Configure a prometheus.scrape component to collect cadvisor metrics.
prometheus.scrape "scraper" {
  targets    = prometheus.exporter.cadvisor.example.targets
  forward_to = [ prometheus.remote_write.demo.receiver ]
}

prometheus.remote_write "demo" {
  endpoint {
    url = "<PROMETHEUS_REMOTE_WRITE_URL>"

    basic_auth {
      username = "<USERNAME>"
      password = "<PASSWORD>"
    }
  }
}

Replace the following:

<PROMETHEUS_REMOTE_WRITE_URL>: The URL of the Prometheus remote_write compatible server to send metrics to.
<USERNAME>: The username to use for authentication to the remote_write API.
<PASSWORD>: The password to use for authentication to the remote_write API.

Docker deployment example

To collect container metrics with Alloy in Docker, you must mount the necessary host directories and run the container in privileged mode.

Note
The prometheus.exporter.cadvisor component only works when the Alloy container runs on a Linux Docker host. Docker Desktop for Mac and Docker Desktop for Windows run containers in a Linux VM, which prevents direct host monitoring.

The following Docker Compose example shows the required configuration:

services:
  alloy:
    image: grafana/alloy:latest
    privileged: true
    ports:
      - "12345:12345"
    volumes:
      - ./config.alloy:/etc/alloy/config.alloy
      - /var/run/docker.sock:/var/run/docker.sock
      - /:/rootfs:ro
      - /var/run:/var/run:rw
      - /sys:/sys:ro
      - /var/lib/docker/:/var/lib/docker:ro
      - /dev/disk/:/dev/disk:ro
    command: run --server.http.listen-addr=0.0.0.0:12345 --storage.path=/var/lib/alloy/data /etc/alloy/config.alloy

The required volume mounts are:

/var/run/docker.sock: Docker socket for container discovery and API access
/: Host root filesystem (read-only) for system metrics
/var/run: Host runtime data (read-write) for accessing container state
/sys: Host system information (read-only) for cgroup and device metrics
/var/lib/docker/: Docker storage directory (read-only) for container metadata and layer information
/dev/disk/: Disk device information (read-only) for disk I/O metrics

Caution
Running in privileged mode grants the container access to all host devices. Only use privileged mode when necessary and ensure proper network isolation.

For a complete working example with Grafana and Prometheus, refer to the alloy-scenarios repository.

Kubernetes Deployment example

When you run Alloy in Kubernetes, deploy it as a DaemonSet to collect container metrics from each node.

The following example shows the required configuration for a DaemonSet:

apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: alloy
  namespace: monitoring
spec:
  selector:
    matchLabels:
      app: alloy
  template:
    metadata:
      labels:
        app: alloy
    spec:
      serviceAccountName: alloy
      hostNetwork: true
      hostPID: true
      containers:
        - name: alloy
          image: grafana/alloy:latest
          args:
            - run
            - /etc/alloy/config.alloy
            - --server.http.listen-addr=0.0.0.0:12345
            - --storage.path=/var/lib/alloy/data
          ports:
            - containerPort: 12345
              name: http-metrics
          securityContext:
            privileged: true
          volumeMounts:
            - name: config
              mountPath: /etc/alloy
            - name: rootfs
              mountPath: /rootfs
              readOnly: true
            - name: var-run
              mountPath: /var/run
            - name: sys
              mountPath: /sys
              readOnly: true
            - name: docker
              mountPath: /var/lib/docker
              readOnly: true
            - name: dev-disk
              mountPath: /dev/disk
              readOnly: true
      volumes:
        - name: config
          configMap:
            name: alloy-config
        - name: rootfs
          hostPath:
            path: /
        - name: var-run
          hostPath:
            path: /var/run
        - name: sys
          hostPath:
            path: /sys
        - name: docker
          hostPath:
            path: /var/lib/docker
        - name: dev-disk
          hostPath:
            path: /dev/disk

Key configuration requirements:

hostNetwork: true: Allows access to the host network stack
hostPID: true: Enables process-level metrics collection
privileged: true: Grants access to host resources
Volume mounts: Provide access to container runtime and system directories

Note
For container runtimes other than Docker, such as containerd or CRI-O, adjust the volume mounts and docker_host or containerd_host arguments accordingly.

Caution
Running containers with privileged access in Kubernetes has security implications. Consider using Pod Security Standards and RBAC to limit exposure, and only deploy to dedicated monitoring namespaces.

For more information about deploying Alloy on Kubernetes, refer to Deploy Grafana Alloy.

Compatible components

prometheus.exporter.cadvisor has exports that can be consumed by the following components:

Components that consume Targets

Note
Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.

prometheus.exporter.catchpoint

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

`prometheus.exporter.catchpoint`

EXPERIMENTAL: This is an experimental component. Experimental components are subject to frequent breaking changes, and may be removed with no equivalent replacement. To enable and use an experimental component, you must set the stability.level flag to experimental.

The prometheus.exporter.catchpoint component uses the catchpoint_exporter for collecting statistics from a Catchpoint account.

Usage

prometheus.exporter.catchpoint "<LABEL>" {
    port              = "<PORT>"
    verbose_logging   = <VERBOSE_LOGGING>
    webhook_path      = "<WEBHOOK_PATH>"
}

Arguments

You can use the following arguments with prometheus.exporter.catchpoint:

Name	Type	Description	Default	Required
`port`	`string`	Sets the port on which the exporter runs.	`"9090"`	no
`verbose_logging`	`bool`	Enables verbose logging to provide more detailed output for debugging purposes.	`false`	no
`webhook_path`	`string`	Defines the path where the exporter receives webhook data from Catchpoint	`"/catchpoint-webhook"`	no

Blocks

The prometheus.exporter.catchpoint component doesn’t support any blocks. You can configure this component with arguments.

Exported fields

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

Name	Type	Description
`targets`	`list(map(string))`	The targets that can be used to collect exporter metrics.

For example, the targets can either be passed to a discovery.relabel component to rewrite the targets’ label sets or to a prometheus.scrape component that collects the exposed metrics.

The exported targets use the configured in-memory traffic address specified by the run command.

Component health

prometheus.exporter.catchpoint is only reported as unhealthy if given an invalid configuration. In those cases, exported fields retain their last healthy values.

Debug information

prometheus.exporter.catchpoint doesn’t expose any component-specific debug information.

Debug metrics

prometheus.exporter.catchpoint doesn’t expose any component-specific debug metrics.

Example

This example uses a prometheus.scrape component to collect metrics from prometheus.exporter.catchpoint:

prometheus.exporter.catchpoint "example" {
  port             = "9090"
  verbose_logging  = false
  webhook_path     = "/catchpoint-webhook"
}

// Configure a prometheus.scrape component to collect catchpoint metrics.
prometheus.scrape "demo" {
  targets    = prometheus.exporter.catchpoint.example.targets
  forward_to = [prometheus.remote_write.demo.receiver]
}

prometheus.remote_write "demo" {
  endpoint {
    url = <PROMETHEUS_REMOTE_WRITE_URL>

    basic_auth {
      username = <USERNAME>
      password = <PASSWORD>
    }
  }
}

Replace the following:

<PROMETHEUS_REMOTE_WRITE_URL>: The URL of the Prometheus remote_write compatible server to send metrics to.
<USERNAME>: The username to use for authentication to the remote_write API.
<PASSWORD>: The password to use for authentication to the remote_write API.

Compatible components

prometheus.exporter.catchpoint has exports that can be consumed by the following components:

Components that consume Targets

Note
Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.

prometheus.exporter.cloudwatch

Mon, 13 Apr 2026 07:37:47 +0000

`prometheus.exporter.cloudwatch`

The prometheus.exporter.cloudwatch component embeds yet-another-cloudwatch-exporter, letting you collect Amazon CloudWatch metrics in a Prometheus-compatible format.

This component lets you scrape CloudWatch metrics in a set of configurations called jobs. There are two kinds of jobs: [discovery][] and [static][].

Authentication

Alloy must be running in an environment with access to AWS. The exporter uses the AWS SDK for Go and provides authentication via the AWS default credential chain. Regardless of the method used to acquire the credentials, some permissions are required for the exporter to work.

"tag:GetResources",
"cloudwatch:GetMetricData",
"cloudwatch:GetMetricStatistics",
"cloudwatch:ListMetrics"

The following IAM permissions are required for the Transit Gateway attachment (tgwa) metrics to work.

"ec2:DescribeTags",
"ec2:DescribeInstances",
"ec2:DescribeRegions",
"ec2:DescribeTransitGateway*"

The following IAM permission is required to discover tagged API Gateway REST APIs:

"apigateway:GET"

The following IAM permissions are required to discover tagged Database Migration Service (DMS) replication instances and tasks:

"dms:DescribeReplicationInstances",
"dms:DescribeReplicationTasks"

To use all of the integration features, use the following AWS IAM Policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "Stmt1674249227793",
      "Action": [
        "tag:GetResources",
        "cloudwatch:GetMetricData",
        "cloudwatch:GetMetricStatistics",
        "cloudwatch:ListMetrics",
        "ec2:DescribeTags",
        "ec2:DescribeInstances",
        "ec2:DescribeRegions",
        "ec2:DescribeTransitGateway*",
        "apigateway:GET",
        "dms:DescribeReplicationInstances",
        "dms:DescribeReplicationTasks"
      ],
      "Effect": "Allow",
      "Resource": "*"
    }
  ]
}

Usage

prometheus.exporter.cloudwatch "queues" {
    sts_region      = "us-east-2"
    discovery {
        type        = "AWS/SQS"
        regions     = ["us-east-2"]
        search_tags = {
            "scrape" = "true",
        }

        metric {
            name       = "NumberOfMessagesSent"
            statistics = ["Sum", "Average"]
            period     = "1m"
        }

        metric {
            name       = "NumberOfMessagesReceived"
            statistics = ["Sum", "Average"]
            period     = "1m"
        }
    }
}

Arguments

You can use the following arguments with prometheus.exporter.cloudwatch:

Name	Type	Description	Default	Required
`sts_region`	`string`	AWS region to use when calling STS for retrieving account information.		yes
`aws_sdk_version_v2`	`bool`	(Deprecated) When `false`, uses AWS SDK for Go v1 instead of v2.	`true`	no
`fips_disabled`	`bool`	Disable use of FIPS endpoints. Set ’true’ when running outside of USA regions.	`true`	no
`debug`	`bool`	Enable debug logging on CloudWatch exporter internals.	`false`	no
`discovery_exported_tags`	`map(list(string))`	List of tags (value) per service (key) to export in all metrics.	`{}`	no
`labels_to_snake_case`	`bool`	Output labels on metrics in snake case instead of camel case.	`false`	no

If you define the ["name", "type"] under "AWS/EC2" in the discovery_exported_tags argument, it exports the name and type tags and its values as labels in all metrics. This affects all discovery jobs.

Caution
Starting with Alloy v1.15, the aws_sdk_version_v2 argument is deprecated as AWS SDK for Go v1 is end-of-life since July 31, 2025. Remove this argument from your configuration to use AWS SDK for Go v2, which is the default.

Blocks

You can use the following blocks with prometheus.exporter.cloudwatch:

Name	Description	Required
`target`	Configures a blackbox target.	no

Note
The static, discovery, and custom_namespace blocks are marked as not required, but you must configure at least one static, discovery, or custom_namespace job.

`discovery`

The discovery block allows the component to scrape CloudWatch metrics with only the AWS service and a list of metrics under that service/namespace. Alloy finds AWS resources in the specified service, scrapes the metrics, labels them appropriately, and exports them to Prometheus. The following example configuration, shows you how to scrape CPU utilization and network traffic metrics from all AWS EC2 instances:

prometheus.exporter.cloudwatch "discover_instances" {
    sts_region = "us-east-2"

    discovery {
        type    = "AWS/EC2"
        regions = ["us-east-2"]

        metric {
            name       = "CPUUtilization"
            statistics = ["Average"]
            period     = "5m"
        }

        metric {
            name       = "NetworkPacketsIn"
            statistics = ["Average"]
            period     = "5m"
        }
    }
}

You can configure the discovery block one or multiple times to scrape metrics from different services or with different search_tags.

Name	Type	Description	Default	Required
`regions`	`list(string)`	List of AWS regions.		yes
`type`	`string`	CloudWatch service alias (`"alb"`, `"ec2"`, etc) or namespace name (`"AWS/EC2"`, `"AWS/S3"`, etc). Refer to supported-services for a complete list.		yes
`custom_tags`	`map(string)`	Custom tags to be added as a list of key / value pairs. When exported to Prometheus format, the label name follows the following format: `custom_tag_{key}`.	`{}`	no
`dimension_name_requirements`	`list(string)`	List of metric dimensions to query. Before querying metric values, the total list of metrics are filtered to only those that contain exactly this list of dimensions. If the list is empty or undefined, all dimension combinations are included.	`{}`	no
`delay`	`duration`	Delay the start time of the CloudWatch metrics query by this duration.	`0`	no
`period`	`duration`	Default period for metrics in this job.	`5m`	no
`length`	`duration`	Default length for metrics in this job.	Calculated based on `period`. Refer to period for details.	no
`nil_to_zero`	`bool`	When `true`, `NaN` metric values are converted to 0. Individual metrics can override this value in the [metric][] block.	`true`	no
`recently_active_only`	`bool`	Only return metrics that have been active in the last 3 hours.	`false`	no
`search_tags`	`map(string)`	List of key/value pairs to use for tag filtering. All must match. The value can be a regular expression.	`{}`	no
`add_cloudwatch_timestamp`	`bool`	When `true`, use the timestamp from CloudWatch instead of the scrape time.	`false`	no

`static`

The static block configures the component to scrape a specific set of CloudWatch metrics. The metrics need to be fully qualified with the following specifications:

namespace: For example, AWS/EC2, AWS/EBS, CoolApp if it were a custom metric, etc.
dimensions: CloudWatch identifies a metric by a set of dimensions, which are essentially label / value pairs. For example, all AWS/EC2 metrics are identified by the InstanceId dimension and the identifier itself.
metric: Metric name and statistics.

The following example configuration shows you how to scrape the same metrics in the discovery example, but for a specific AWS EC2 instance:

prometheus.exporter.cloudwatch "static_instances" {
    sts_region = "us-east-2"

    static "instances" {
        regions    = ["us-east-2"]
        namespace  = "AWS/EC2"
        dimensions = {
            "InstanceId" = "i01u29u12ue1u2c",
        }

        metric {
            name       = "CPUUsage"
            statistics = ["Sum", "Average"]
            period     = "1m"
        }
    }
}

As shown above, static blocks must be specified with a label, which translates to the name label in the exported metric.

static "<LABEL>" {
    regions    = ["us-east-2"]
    namespace  = "AWS/EC2"
    // ...
}

You can configure the static block one or multiple times to scrape metrics with different sets of dimensions.

Name	Type	Description	Default	Required
`dimensions`	`map(string)`	CloudWatch metric dimensions as a list of name / value pairs. Must uniquely define all metrics in this job.		yes
`namespace`	`string`	CloudWatch metric namespace.		yes
`regions`	`list(string)`	List of AWS regions.		yes
`custom_tags`	`map(string)`	Custom tags to be added as a list of key / value pairs. When exported to Prometheus format, the label name follows the following format: `custom_tag_{key}`.	`{}`	no
`nil_to_zero`	`bool`	When `true`, `NaN` metric values are converted to 0. Individual metrics can override this value in the [metric][] block.	`true`	no

All dimensions must be specified when scraping single metrics like the example above. For example, AWS/Logs metrics require Resource, Service, Class, and Type dimensions to be specified. The same applies to CloudWatch custom metrics, all dimensions attached to a metric when saved in CloudWatch are required.

`custom_namespace`

The custom_namespace block allows the component to scrape CloudWatch metrics from custom namespaces using only the namespace name and a list of metrics under that namespace. For example:

prometheus.exporter.cloudwatch "discover_instances" {
    sts_region = "eu-west-1"

    custom_namespace "customEC2Metrics" {
        namespace = "CustomEC2Metrics"
        regions   = ["us-east-1"]

        metric {
            name       = "cpu_usage_idle"
            statistics = ["Average"]
            period     = "5m"
        }

        metric {
            name       = "disk_free"
            statistics = ["Average"]
            period     = "5m"
        }
    }
}

You can configure the custom_namespace block multiple times to scrape metrics from different namespaces.

Name	Type	Description	Default	Required
`namespace`	`string`	CloudWatch metric namespace.		yes
`regions`	`list(string)`	List of AWS regions.		yes
`custom_tags`	`map(string)`	Custom tags to be added as a list of key/value pairs. When exported to Prometheus format, the label name follows the following format: `custom_tag_{key}`.	`{}`	no
`delay`	`duration`	Delay the start time of the CloudWatch metrics query by this duration.	`0`	no
`period`	`duration`	Default period for metrics in this job.	`5m`	no
`length`	`duration`	Default length for metrics in this job.	Calculated based on `period`. Refer to period for details.	no
`dimension_name_requirements`	`list(string)`	List of metric dimensions to query. Before querying metric values, the total list of metrics are filtered to only those that contain exactly this list of dimensions. If the list is empty or undefined, all dimension combinations are included.	`{}`	no
`nil_to_zero`	`bool`	When `true`, `NaN` metric values are converted to 0. Individual metrics can override this value in the [metric][] block.	`true`	no
`recently_active_only`	`bool`	Only return metrics that have been active in the last 3 hours.	`false`	no
`add_cloudwatch_timestamp`	`bool`	When `true`, use the timestamp from CloudWatch instead of the scrape time.	`false`	no

`metric`

Required

Represents an AWS Metric to scrape.

The metric block may be specified multiple times to define multiple target metrics. Refer to the View available metrics topic in the Amazon CloudWatch documentation for detailed metrics information.

Name	Type	Description	Default	Required
`name`	`string`	Metric name.		yes
`period`	`duration`	Refer to the period section below.	The value of `period` in the parent job.	no
`statistics`	`list(string)`	List of statistics to scrape. For example, `"Minimum"`, `"Maximum"`, etc.		yes
`add_cloudwatch_timestamp`	`bool`	When `true`, use the timestamp from CloudWatch instead of the scrape time.	The value of `add_cloudwatch_timestamp` in the parent job.	no
`length`	`duration`	Refer to the period section below.	The value of `length` in the parent job.	no
`nil_to_zero`	`bool`	When `true`, `NaN` metric values are converted to 0.	The value of `nil_to_zero` in the parent [static][] or [discovery][] block. `true` if not set in the parent block.	no

`period` and `length`

period controls primarily the width of the time bucket used for aggregating metrics collected from CloudWatch. length controls how far back in time CloudWatch metrics are considered during each Alloy scrape. If both settings are configured, the time parameters when calling CloudWatch APIs works as follows:

If, across multiple metrics under the same static or discovery job, there’s a different period or length, the minimum of all periods, and maximum of all lengths is configured.

On the other hand, if length isn’t configured, both period and length settings are calculated based on the required period configuration attribute.

If all metrics within a job (discovery or static) have the same period value configured, CloudWatch APIs are requested for metrics from the scrape time, to period seconds in the past. The values of these are exported to Prometheus.

On the other hand, if metrics with different periods are configured under an individual job, this works differently. First, two variables are calculated aggregating all periods: length, taking the maximum value of all periods, and the new period value, taking the minimum of all periods. Then, CloudWatch APIs are requested for metrics from now - length to now, aggregating each in samples for period seconds. For each metric, the most recent sample is exported to CloudWatch.

`role`

Represents an AWS IAM Role. If omitted, the AWS role that corresponds to the credentials configured in the environment is used.

Multiple roles can be useful when scraping metrics from different AWS accounts with a single pair of credentials. In this case, a different role is configured for Alloy to assume before calling AWS APIs. Therefore, the credentials configured in the system need permission to assume the target role. Refer to Granting a user permissions to switch roles in the AWS IAM documentation for more information about how to configure this.

Name	Type	Description	Default	Required
`external_id`	`string`	External ID used when calling STS AssumeRole API. Refer to the IAM User Guide for more information.	`""`	no
`role_arn`	`string`	AWS IAM Role ARN the exporter should assume to perform AWS API calls.		yes

`decoupled_scraping`

The decoupled_scraping block configures an optional feature that scrapes CloudWatch metrics in the background on a scheduled interval. When this feature is enabled, CloudWatch metrics are gathered asynchronously at the scheduled interval instead of synchronously when the CloudWatch component is scraped.

The decoupled scraping feature reduces the number of API requests sent to AWS. This feature also prevents component scrape timeouts when you gather high volumes of CloudWatch metrics.

Name	Type	Description	Default	Required
`enabled`	`bool`	Controls whether the decoupled scraping featured is enabled	false	no
`scrape_interval`	`string`	Controls how frequently to asynchronously gather new CloudWatch metrics	5m	no

Exported fields

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

Name	Type	Description
`targets`	`list(map(string))`	The targets that can be used to collect exporter metrics.

For example, the targets can either be passed to a discovery.relabel component to rewrite the targets’ label sets or to a prometheus.scrape component that collects the exposed metrics.

The exported targets use the configured in-memory traffic address specified by the run command.

Component health

prometheus.exporter.cloudwatch is only reported as unhealthy if given an invalid configuration. In those cases, exported fields retain their last healthy values.

Debug information

prometheus.exporter.cloudwatch doesn’t expose any component-specific debug information.

Debug metrics

prometheus.exporter.cloudwatch doesn’t expose any component-specific debug metrics.

Example

For detailed examples, refer to the [discovery][] and [static] sections.

Supported services in discovery jobs

The following AWS services are supported in cloudwatch_exporter discovery jobs. When you configure a discovery job, make sure the type field of each discovery_job matches the desired job namespace.

Namespace: /aws/sagemaker/Endpoints
Namespace: /aws/sagemaker/InferenceRecommendationsJobs
Namespace: /aws/sagemaker/ProcessingJobs
Namespace: /aws/sagemaker/TrainingJobs
Namespace: /aws/sagemaker/TransformJobs
Namespace: AmazonMWAA
Namespace: AWS/ACMPrivateCA
Namespace: AWS/AmazonMQ
Namespace: AWS/AOSS
Namespace: AWS/ApiGateway
Namespace: AWS/ApplicationELB
Namespace: AWS/AppRunner
Namespace: AWS/AppStream
Namespace: AWS/AppSync
Namespace: AWS/Athena
Namespace: AWS/AutoScaling
Namespace: AWS/Backup
Namespace: AWS/Bedrock
Namespace: AWS/Billing
Namespace: AWS/Cassandra
Namespace: AWS/CertificateManager
Namespace: AWS/ClientVPN
Namespace: AWS/CloudFront
Namespace: AWS/Cognito
Namespace: AWS/DataSync
Namespace: AWS/DDoSProtection
Namespace: AWS/DMS
Namespace: AWS/DocDB
Namespace: AWS/DX
Namespace: AWS/DynamoDB
Namespace: AWS/EBS
Namespace: AWS/EC2
Namespace: AWS/EC2CapacityReservations
Namespace: AWS/EC2Spot
Namespace: AWS/ECR
Namespace: AWS/ECS
Namespace: AWS/EFS
Namespace: AWS/ElastiCache
Namespace: AWS/ElasticBeanstalk
Namespace: AWS/ElasticMapReduce
Namespace: AWS/ELB
Namespace: AWS/EMRServerless
Namespace: AWS/ES
Namespace: AWS/Events
Namespace: AWS/Firehose
Namespace: AWS/FSx
Namespace: AWS/GameLift
Namespace: AWS/GatewayELB
Namespace: AWS/GlobalAccelerator
Namespace: AWS/IoT
Namespace: AWS/IPAM
Namespace: AWS/Kafka
Namespace: AWS/KafkaConnect
Namespace: AWS/Kinesis
Namespace: AWS/KinesisAnalytics
Namespace: AWS/KMS
Namespace: AWS/Lambda
Namespace: AWS/Logs
Namespace: AWS/MediaConnect
Namespace: AWS/MediaConvert
Namespace: AWS/MediaLive
Namespace: AWS/MediaPackage
Namespace: AWS/MediaTailor
Namespace: AWS/MemoryDB
Namespace: AWS/MWAA
Namespace: AWS/NATGateway
Namespace: AWS/Neptune
Namespace: AWS/Network Manager
Namespace: AWS/NetworkELB
Namespace: AWS/NetworkFirewall
Namespace: AWS/PrivateLinkEndpoints
Namespace: AWS/PrivateLinkServices
Namespace: AWS/Prometheus
Namespace: AWS/QLDB
Namespace: AWS/QuickSight
Namespace: AWS/RDS
Namespace: AWS/Redshift
Namespace: AWS/Route53
Namespace: AWS/Route53Resolver
Namespace: AWS/RUM
Namespace: AWS/S3
Namespace: AWS/SageMaker
Namespace: AWS/Sagemaker/ModelBuildingPipeline
Namespace: AWS/Scheduler
Namespace: AWS/SecretsManager
Namespace: AWS/SES
Namespace: AWS/SNS
Namespace: AWS/SQS
Namespace: AWS/States
Namespace: AWS/StorageGateway
Namespace: AWS/Timestream
Namespace: AWS/TransitGateway
Namespace: AWS/TrustedAdvisor
Namespace: AWS/Usage
Namespace: AWS/VpcLattice
Namespace: AWS/VPN
Namespace: AWS/WAFV2
Namespace: AWS/WorkSpaces
Namespace: ContainerInsights
Namespace: CWAgent
Namespace: ECS/ContainerInsights
Namespace: Glue

Compatible components

prometheus.exporter.cloudwatch has exports that can be consumed by the following components:

Components that consume Targets

Note
Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.

prometheus.exporter.consul

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

`prometheus.exporter.consul`

The prometheus.exporter.consul component embeds the consul_exporter for collecting metrics from a Consul installation.

Usage

prometheus.exporter.consul "<LABEL>" {
}

Arguments

You can use the following arguments with prometheus.exporter.consul:

Name	Type	Description	Default	Required
`allow_stale`	`bool`	Allows any Consul server (non-leader) to service a read.	`true`	no
`ca_file`	`string`	File path to a PEM-encoded certificate authority used to validate the authenticity of a server certificate.		no
`cert_file`	`string`	File path to a PEM-encoded certificate used with the private key to verify the exporter’s authenticity.		no
`concurrent_request_limit`	`string`	Limit the maximum number of concurrent requests to consul, 0 means no limit.		no
`generate_health_summary`	`bool`	Collects information about each registered service and exports `consul_catalog_service_node_healthy`.	`true`	no
`insecure_skip_verify`	`bool`	Disable TLS host verification.	`false`	no
`key_file`	`string`	File path to a PEM-encoded private key used with the certificate to verify the exporter’s authenticity.		no
`kv_filter`	`string`	Only store keys that match this regular expression pattern.	`".*"`	no
`kv_prefix`	`string`	Prefix under which to look for KV pairs.		no
`require_consistent`	`bool`	Forces the read to be fully consistent.		no
`server_name`	`string`	When provided, this overrides the hostname for the TLS certificate. It can be used to ensure that the certificate name matches the hostname you declare.		no
`server`	`string`	Address (host and port) of the Consul instance to connect to. This could be a local Alloy (localhost:8500), or the address of a Consul server.	`"http://localhost:8500"`	no
`timeout`	`duration`	Timeout on HTTP requests to consul.	`"500ms"`	no

Blocks

The prometheus.exporter.consul component doesn’t support any blocks. You can configure this component with arguments.

Exported fields

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

Name	Type	Description
`targets`	`list(map(string))`	The targets that can be used to collect exporter metrics.

For example, the targets can either be passed to a discovery.relabel component to rewrite the targets’ label sets or to a prometheus.scrape component that collects the exposed metrics.

The exported targets use the configured in-memory traffic address specified by the run command.

Component health

prometheus.exporter.consul is only reported as unhealthy if given an invalid configuration. In those cases, exported fields retain their last healthy values.

Debug information

prometheus.exporter.consul doesn’t expose any component-specific debug information.

Debug metrics

prometheus.exporter.consul doesn’t expose any component-specific debug metrics.

Example

The following example uses a prometheus.scrape component to collect metrics from prometheus.exporter.consul:

prometheus.exporter.consul "example" {
  server = "https://consul.example.com:8500"
}

// Configure a prometheus.scrape component to collect consul metrics.
prometheus.scrape "demo" {
  targets    = prometheus.exporter.consul.example.targets
  forward_to = [prometheus.remote_write.demo.receiver]
}

prometheus.remote_write "demo" {
  endpoint {
    url = "<PROMETHEUS_REMOTE_WRITE_URL>"

    basic_auth {
      username = "<USERNAME>"
      password = "<PASSWORD>"
    }
  }
}

Replace the following:

<PROMETHEUS_REMOTE_WRITE_URL>: The URL of the Prometheus remote_write compatible server to send metrics to.
<USERNAME>: The username to use for authentication to the remote_write API.
<PASSWORD>: The password to use for authentication to the remote_write API.

Compatible components

prometheus.exporter.consul has exports that can be consumed by the following components:

Components that consume Targets

Note
Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.

prometheus.exporter.databricks

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

`prometheus.exporter.databricks`

The prometheus.exporter.databricks component embeds the databricks_exporter for collecting billing, jobs, pipelines, and SQL warehouse metrics from Databricks System Tables via HTTP for Prometheus consumption.

Usage

prometheus.exporter.databricks "LABEL" {
    server_hostname     = "<DATABRICKS_SERVER_HOSTNAME>"
    warehouse_http_path = "<DATABRICKS_WAREHOUSE_HTTP_PATH>"
    client_id           = "<DATABRICKS_CLIENT_ID>"
    client_secret       = "<DATABRICKS_CLIENT_SECRET>"
}

Arguments

You can use the following arguments with prometheus.exporter.databricks:

Name	Type	Description	Default	Required
`client_id`	`string`	The OAuth2 Application ID or Client ID of your Service Principal.		yes
`client_secret`	`secret`	The OAuth2 Client Secret of your Service Principal.		yes
`server_hostname`	`string`	The Databricks workspace hostname, for example, `dbc-xxx.cloud.databricks.com`.		yes
`warehouse_http_path`	`string`	The HTTP path of the SQL Warehouse for example, `/sql/1.0/warehouses/abc123`.		yes
`billing_lookback`	`duration`	How far back to look for billing data.	`"24h"`	no
`collect_task_retries`	`bool`	Collect task retry metrics. Can cause high cardinality due to the `task_key` label.	`false`	no
`jobs_lookback`	`duration`	How far back to look for job runs.	`"3h"`	no
`pipelines_lookback`	`duration`	How far back to look for pipeline runs.	`"3h"`	no
`queries_lookback`	`duration`	How far back to look for SQL warehouse queries.	`"2h"`	no
`query_timeout`	`duration`	Timeout for individual SQL queries.	`"5m"`	no
`sla_threshold_seconds`	`int`	Duration threshold in seconds for job SLA miss detection.	`3600`	no

Lookback windows

The exporter queries Databricks System Tables using SQL with sliding time windows. Each scrape collects data from now - lookback to now:

billing_lookback: Queries system.billing.usage for DBU consumption and cost estimates. Databricks billing data typically has 24-48 hour lag.
jobs_lookback: Queries system.lakeflow.job_run_timeline for job run counts, durations, and status.
pipelines_lookback: Queries system.lakeflow.pipeline_event_log for DLT pipeline metrics.
queries_lookback: Queries system.query.history for SQL warehouse query metrics.

The lookback window should be at least 2x the scrape_interval to ensure data continuity between scrapes. For example, with a 10-minute scrape interval, use at least 20 minutes of lookback.

Blocks

The prometheus.exporter.databricks component doesn’t support any blocks. You can configure this component with arguments.

Exported fields

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

Name	Type	Description
`targets`	`list(map(string))`	The targets that can be used to collect exporter metrics.

For example, the targets can either be passed to a discovery.relabel component to rewrite the targets’ label sets or to a prometheus.scrape component that collects the exposed metrics.

The exported targets use the configured in-memory traffic address specified by the run command.

Component health

prometheus.exporter.databricks is only reported as unhealthy if given an invalid configuration. In those cases, exported fields retain their last healthy values.

Debug information

prometheus.exporter.databricks doesn’t expose any component-specific debug information.

Debug metrics

prometheus.exporter.databricks doesn’t expose any component-specific debug metrics.

Prerequisites

Before using this component, you need:

Databricks Workspace with Unity Catalog and System Tables enabled
Service Principal with OAuth2 M2M authentication configured
SQL Warehouse for querying System Tables and serverless is recommended for cost efficiency

Refer to the Databricks documentation for detailed OAuth2 M2M setup instructions.

Example

The following example uses a prometheus.scrape component to collect metrics from prometheus.exporter.databricks:

prometheus.exporter.databricks "example" {
  server_hostname     = "dbc-abc123-def456.cloud.databricks.com"
  warehouse_http_path = "/sql/1.0/warehouses/xyz789"
  client_id           = "my-service-principal-id"
  client_secret       = "my-service-principal-secret"
}

// Configure a prometheus.scrape component to collect databricks metrics.
prometheus.scrape "demo" {
  targets         = prometheus.exporter.databricks.example.targets
  forward_to      = [prometheus.remote_write.demo.receiver]
  scrape_interval = "10m"
  scrape_timeout  = "9m"
}

prometheus.remote_write "demo" {
  endpoint {
    url = "<PROMETHEUS_REMOTE_WRITE_URL>"

    basic_auth {
      username = "<USERNAME>"
      password = "<PASSWORD>"
    }
  }
}

Replace the following:

<PROMETHEUS_REMOTE_WRITE_URL>: The URL of the Prometheus remote_write compatible server to send metrics to.
<USERNAME>: The username to use for authentication to the remote_write API.
<PASSWORD>: The password to use for authentication to the remote_write API.

Tuning recommendations

scrape_interval: Use 10-30 minutes. The exporter queries Databricks System Tables which can be slow. Increase the scrape_interval to reduce your SQL Warehouse costs.
scrape_timeout: Must be less than scrape_interval. The exporter typically takes 90-120 seconds per scrape depending on data volume.
Lookback vs interval: The lookback windows should be at least 2x the scrape interval. The defaults, 3h for jobs and pipelines, and 2h for queries, work well with 10-30 minute scrape intervals.

High cardinality warning

The collect_task_retries flag adds task-level retry metrics which can significantly increase cardinality for workspaces with many jobs. Only enable this feature if you really need it.

Compatible components

prometheus.exporter.databricks has exports that can be consumed by the following components:

Components that consume Targets

Note
Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.

prometheus.exporter.dnsmasq

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

`prometheus.exporter.dnsmasq`

The prometheus.exporter.dnsmasq component embeds the dnsmasq_exporter for collecting statistics from a dnsmasq server.

Usage

prometheus.exporter.dnsmasq "<LABEL>" {
}

Arguments

You can use the following arguments with prometheus.exporter.dnsmasq:

Name	Type	Description	Default	Required
`address`	`string`	The address of the dnsmasq server.	`"localhost:53"`	no
`expose_leases`	`bool`	Expose dnsmasq leases as metrics (high cardinality).	`false`	no
`leases_file`	`string`	The path to the dnsmasq leases file.	`"/var/lib/misc/dnsmasq.leases"`	no

Blocks

The prometheus.exporter.dnsmasq component doesn’t support any blocks. You can configure this component with arguments.

Exported fields

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

Name	Type	Description
`targets`	`list(map(string))`	The targets that can be used to collect exporter metrics.

For example, the targets can either be passed to a discovery.relabel component to rewrite the targets’ label sets or to a prometheus.scrape component that collects the exposed metrics.

The exported targets use the configured in-memory traffic address specified by the run command.

Component health

prometheus.exporter.dnsmasq is only reported as unhealthy if given an invalid configuration. In those cases, exported fields retain their last healthy values.

Debug information

prometheus.exporter.dnsmasq doesn’t expose any component-specific debug information.

Debug metrics

prometheus.exporter.dnsmasq doesn’t expose any component-specific debug metrics.

Example

The following example uses a prometheus.scrape component to collect metrics from prometheus.exporter.dnsmasq:

prometheus.exporter.dnsmasq "example" {
  address = "localhost:53"
}

// Configure a prometheus.scrape component to collect github metrics.
prometheus.scrape "demo" {
  targets    = prometheus.exporter.dnsmasq.example.targets
  forward_to = [prometheus.remote_write.demo.receiver]
}

prometheus.remote_write "demo" {
  endpoint {
    url = "<PROMETHEUS_REMOTE_WRITE_URL>"

    basic_auth {
      username = "<USERNAME>"
      password = "<PASSWORD>"
    }
  }
}

Replace the following:

<PROMETHEUS_REMOTE_WRITE_URL>: The URL of the Prometheus remote_write compatible server to send metrics to.
<USERNAME>: The username to use for authentication to the remote_write API.
<PASSWORD>: The password to use for authentication to the remote_write API.

Compatible components

prometheus.exporter.dnsmasq has exports that can be consumed by the following components:

Components that consume Targets

Note
Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.

prometheus.exporter.elasticsearch

Mon, 13 Apr 2026 07:37:47 +0000

`prometheus.exporter.elasticsearch`

The prometheus.exporter.elasticsearch component embeds the elasticsearch_exporter for the collection of metrics from ElasticSearch servers.

Note
Currently, Alloy can only collect metrics from a single ElasticSearch server. However, the exporter can collect the metrics from all nodes through that server configured.

We strongly recommend that you configure a separate user for Alloy, and give it only the strictly mandatory security privileges necessary for monitoring your node. Refer to the Elasticsearch security privileges documentation for more information.

Usage

prometheus.exporter.elasticsearch "<LABEL>" {
    address = "<ELASTICSEARCH_ADDRESS>"
}

Arguments

You can use the following arguments with prometheus.exporter.elasticsearch:

Name	Type	Description	Default	Required
`address`	`string`	HTTP API address of an Elasticsearch node.	`"http://localhost:9200"`	no
`aliases`	`bool`	Include informational aliases metrics.		no
`all`	`bool`	Export stats for all nodes in the cluster. If used, this flag overrides the flag `node`.		no
`ca`	`string`	Path to PEM file that contains trusted Certificate Authorities for the Elasticsearch connection.		no
`client_cert`	`string`	Path to PEM file that contains the corresponding cert for the private key to connect to Elasticsearch.		no
`client_private_key`	`string`	Path to PEM file that contains the private key for client auth when connecting to Elasticsearch.		no
`cluster_settings`	`bool`	Export stats for cluster settings.		no
`clusterinfo_interval`	`duration`	Cluster info update interval for the cluster label.	`"5m"`	no
`data_stream`	`bool`	Export stats for Data Streams.		no
`indices_settings`	`bool`	Export stats for settings of all indices of the cluster.		no
`indices`	`bool`	Export stats for indices in the cluster.		no
`node`	`string`	Node’s name of which metrics should be exposed		no
`shards`	`bool`	Export stats for shards in the cluster (implies indices).		no
`slm`	`bool`	Export stats for SLM (Snapshot Lifecycle Management).		no
`snapshots`	`bool`	Export stats for the cluster snapshots.		no
`ssl_skip_verify`	`bool`	Skip SSL verification when connecting to Elasticsearch.		no
`timeout`	`duration`	Timeout for trying to get stats from Elasticsearch.	`"5s"`	no

Blocks

You can use the following block with prometheus.exporter.elasticsearch:

Name	Description	Required
`target`	Configures a blackbox target.	no

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

Exported fields

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

Name	Type	Description
`targets`	`list(map(string))`	The targets that can be used to collect exporter metrics.

For example, the targets can either be passed to a discovery.relabel component to rewrite the targets’ label sets or to a prometheus.scrape component that collects the exposed metrics.

The exported targets use the configured in-memory traffic address specified by the run command.

Component health

prometheus.exporter.elasticsearch is only reported as unhealthy if given an invalid configuration. In those cases, exported fields retain their last healthy values.

Debug information

prometheus.exporter.elasticsearch doesn’t expose any component-specific debug information.

Debug metrics

prometheus.exporter.elasticsearch doesn’t expose any component-specific debug metrics.

Example

This example uses a prometheus.scrape component to collect metrics from prometheus.exporter.elasticsearch:

prometheus.exporter.elasticsearch "example" {
  address = "http://localhost:9200"
  basic_auth {
    username = "<USERNAME>"
    password = "<PASSWORD>"
  }
}

// Configure a prometheus.scrape component to collect Elasticsearch metrics.
prometheus.scrape "demo" {
  targets    = prometheus.exporter.elasticsearch.example.targets
  forward_to = [prometheus.remote_write.demo.receiver]
}

prometheus.remote_write "demo" {
  endpoint {
    url = "<PROMETHEUS_REMOTE_WRITE_URL>"

    basic_auth {
      username = "<USERNAME>"
      password = "<PASSWORD>"
    }
  }
}

Replace the following:

<PROMETHEUS_REMOTE_WRITE_URL>: The URL of the Prometheus remote_write compatible server to send metrics to.
<USERNAME>: The username to use for authentication to the remote_write API.
<PASSWORD>: The password to use for authentication to the remote_write API.

Compatible components

prometheus.exporter.elasticsearch has exports that can be consumed by the following components:

Components that consume Targets

Note
Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.

prometheus.exporter.gcp

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

`prometheus.exporter.gcp`

The prometheus.exporter.gcp component embeds the stackdriver_exporter. You can use this component to collect GCP Cloud Monitoring (formerly stackdriver) metrics, translate them to Prometheus-compatible format, and remote write. The component supports all metrics available through the GCP monitoring API.

Metric names follow the template stackdriver_<monitored_resource>_<metric_type_prefix>_<metric_type>.

The following example shows a load balancing metric:

The metric has the following attributes:

monitored_resource = https_lb_rule
metric_type_prefix = loadbalancing.googleapis.com/
metric_type = https/backend_latencies

These attributes result in a final metric name of stackdriver_https_lb_rule_loadbalancing_googleapis_com_https_backend_latencies

Authentication

Alloy must be running in an environment with access to the GCP project it’s scraping. The exporter uses the Google Golang Client Library, which offers a variety of ways to provide credentials. Choose the option that works best for you.

After deciding how Alloy obtains credentials, ensure the account is set up with the IAM role roles/monitoring.viewer. Since the exporter gathers all of its data from GCP monitoring APIs, this is the only permission needed.

Usage

prometheus.exporter.gcp "pubsub" {
        project_ids = [
                "<PROJECT_ID_1>",
                "<PROJECT_ID_2>",
        ]

        metrics_prefixes = [
                "pubsub.googleapis.com/snapshot",
                "pubsub.googleapis.com/subscription/num_undelivered_messages",
                "pubsub.googleapis.com/subscription/oldest_unacked_message_age",
        ]
}

Arguments

You can use the following arguments with prometheus.exporter.gcp:

Name	Type	Description	Default	Required
`metrics_prefixes`	`list(string)`	One or more values from the supported GCP Metrics. These can be as targeted or loose as needed.		yes
`project_ids`	`list(string)`	Configure the GCP Projects to scrape for metrics.		yes
`drop_delegated_projects`	`bool`	When enabled drops metrics from attached projects and only fetches metrics from the explicitly configured `project_ids`.	`false`	no
`extra_filters`	`list(string)`	Used to refine the resources you would like to collect metrics from. Any string value within a filter string must be enclosed in escaped double-quotes. The structure for these filters is `<targeted_metric_prefix>:<filter_query>`.	`[]`	no
`gcp_client_timeout`	`duration`	Sets a timeout on the client used to make API calls to GCP. A single scrape can initiate numerous calls to GCP, so be mindful if you choose to override this value.	`"15s"`	no
`ingest_delay`	`bool`	When enabled, this automatically adjusts the time range used when querying for metrics backwards based on the metadata GCP has published for how long the data can take to be ingested.	`false`	no
`request_interval`	`duration`	The time range used when querying for metrics.	`"5m"`	no
`request_offset`	`duration`	When enabled this offsets the time range used when querying for metrics by a set amount.	`"0s"`	no

Note
If you are supplying a list of strings for the extra_filters argument, any string values within a particular filter string must be enclosed in escaped double quotes. For example, loadbalancing.googleapis.com:resource.labels.backend_target_name="sample-value" must be encoded as "loadbalancing.googleapis.com:resource.labels.backend_target_name=\"sample-value\"" in the Alloy configuration.

For extra_filters, the targeted_metric_prefix is used to ensure the filter is only applied to the metric_prefix(es) where it makes sense. It doesn’t explicitly have to match a value from metric_prefixes, but the targeted_metric_prefix must be at least a prefix to one or more metric_prefixes. The filter_query is applied to a final metrics API query when querying for metric data. The final query sent to the metrics API already includes filters for project and metric type. Each applicable filter_query is appended to the query with an AND. You can read more about the metric API filter options in the GCP documentation.

For request_interval, most of the time the default works perfectly fine. Most documented metrics include a comments of the form Sampled every X seconds. After sampling, data is not visible for up to Y seconds. As long as your request_interval is >= Y you should have no issues. Consider using ingest_delay if you would like this to be done programmatically or are gathering slower moving metrics.

For ingest_delay, you can find the values for this in documented metrics as After sampling, data is not visible for up to Y seconds. Since the GCP ingestion delay is an “at worst”, this is off by default to ensure data is gathered as soon as it’s available.

Blocks

The prometheus.exporter.gcp component doesn’t support any blocks. You can configure this component with arguments.

Exported fields

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

Name	Type	Description
`targets`	`list(map(string))`	The targets that can be used to collect exporter metrics.

For example, the targets can either be passed to a discovery.relabel component to rewrite the targets’ label sets or to a prometheus.scrape component that collects the exposed metrics.

The exported targets use the configured in-memory traffic address specified by the run command.

Component health

prometheus.exporter.gcp is only reported as unhealthy if given an invalid configuration. In those cases, exported fields retain their last healthy values.

Debug information

prometheus.exporter.gcp doesn’t expose any component-specific debug information.

Debug metrics

prometheus.exporter.gcp doesn’t expose any component-specific debug metrics.

Examples

prometheus.exporter.gcp "pubsub_full_config" {
        project_ids = [
                "foo",
                "bar",
        ]

        // Using pubsub metrics (https://cloud.google.com/monitoring/api/metrics_gcp/gcp-pubsub) as an example
        // all metrics.
        //   [
        //     "pubsub.googleapis.com/"
        //   ]
        // all snapshot specific metrics
        //   [
        //     "pubsub.googleapis.com/snapshot"
        //   ]
        // all snapshot specific metrics and a few subscription metrics
        metrics_prefixes = [
                "pubsub.googleapis.com/snapshot",
                "pubsub.googleapis.com/subscription/num_undelivered_messages",
                "pubsub.googleapis.com/subscription/oldest_unacked_message_age",
        ]

        // Given the above metrics_prefixes list, some examples of
        // targeted_metric_prefix option behavior with respect to the filter string
        // format <targeted_metric_prefix>:<filter_query> would be:
        //   pubsub.googleapis.com (apply to all defined prefixes)
        //   pubsub.googleapis.com/snapshot (apply to only snapshot metrics)
        //   pubsub.googleapis.com/subscription (apply to only subscription metrics)
        //   pubsub.googleapis.com/subscription/num_undelivered_messages (apply to only the specific subscription metric)
        extra_filters = [
                "pubsub.googleapis.com/subscription:resource.labels.subscription_id=monitoring.regex.full_match(\"my-subs-prefix.*\")",
        ]

        request_interval        = "5m"
        request_offset          = "0s"
        ingest_delay            = false
        drop_delegated_projects = false
        gcp_client_timeout      = "15s"
}

prometheus.exporter.gcp "lb_with_filter" {
        project_ids = [
                "foo",
                "bar",
        ]
        metrics_prefixes = [
                "loadbalancing.googleapis.com",
        ]
        extra_filters = [
                "loadbalancing.googleapis.com:resource.labels.backend_target_name=\"sample-value\"",
        ]
}

prometheus.exporter.gcp "lb_subset_with_filter" {
        project_ids = [
                "foo",
                "bar",
        ]
        metrics_prefixes = [
                "loadbalancing.googleapis.com/https/request_bytes_count",
                "loadbalancing.googleapis.com/https/total_latencies",
        ]
        extra_filters = [
                "loadbalancing.googleapis.com:resource.labels.backend_target_name=\"sample-value\"",
        ]
}

Compatible components

prometheus.exporter.gcp has exports that can be consumed by the following components:

Components that consume Targets

Note
Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.

prometheus.exporter.github

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

`prometheus.exporter.github`

The prometheus.exporter.github component embeds the github_exporter for collecting statistics from GitHub.

Usage

prometheus.exporter.github "<LABEL>" {
}

Arguments

You can use the following arguments with prometheus.exporter.github:

Name	Type	Description	Default	Required
`api_token_file`	`string`	File containing API token to use to authenticate against GitHub.		no
`api_token`	`secret`	API token to use to authenticate against GitHub.		no
`api_url`	`string`	The full URI of the GitHub API.	`"https://api.github.com"`	no
`github_app_id`	`number`	The GitHub App ID for authentication.		no
`github_app_installation_id`	`number`	The GitHub App installation ID for authentication.		no
`github_app_key_path`	`string`	Path to the GitHub App private key file.		no
`github_rate_limit`	`number`	Threshold for GitHub App rate limit to trigger re-authentication.	`15000`	no
`organizations`	`list(string)`	GitHub organizations for which to collect metrics.		no
`repositories`	`list(string)`	GitHub repositories for which to collect metrics.		no
`users`	`list(string)`	A list of GitHub users for which to collect metrics.		no

Authentication

GitHub uses an aggressive rate limit for unauthenticated requests based on IP address. To allow more API requests, we recommend that you configure either token or GitHub App authentication.

Token authentication: Set api_token or api_token_file with a personal access token or classic token.
GitHub App authentication: Set github_app_id, github_app_installation_id, and github_app_key_path to authenticate as a GitHub App.

When provided, api_token_file takes precedence over api_token.

You can’t use both token authentication and GitHub App authentication simultaneously.

Blocks

The prometheus.exporter.github component doesn’t support any blocks. You can configure this component with arguments.

Exported fields

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

Name	Type	Description
`targets`	`list(map(string))`	The targets that can be used to collect exporter metrics.

For example, the targets can either be passed to a discovery.relabel component to rewrite the targets’ label sets or to a prometheus.scrape component that collects the exposed metrics.

The exported targets use the configured in-memory traffic address specified by the run command.

Component health

prometheus.exporter.github is only reported as unhealthy if given an invalid configuration. In those cases, exported fields retain their last healthy values.

Debug information

prometheus.exporter.github doesn’t expose any component-specific debug information.

Debug metrics

prometheus.exporter.github doesn’t expose any component-specific debug metrics.

Examples

The following examples demonstrate token authentication and GitHub App authentication.

Token authentication

The following example uses a prometheus.scrape component to collect metrics from prometheus.exporter.github:

prometheus.exporter.github "example" {
  api_token_file = "/etc/github-api-token"
  repositories   = ["grafana/alloy"]
}

// Configure a prometheus.scrape component to collect github metrics.
prometheus.scrape "demo" {
  targets    = prometheus.exporter.github.example.targets
  forward_to = [prometheus.remote_write.demo.receiver]
}

prometheus.remote_write "demo" {
  endpoint {
    url = "<PROMETHEUS_REMOTE_WRITE_URL>"

    basic_auth {
      username = "<USERNAME>"
      password = "<PASSWORD>"
    }
  }
}

Replace the following:

<PROMETHEUS_REMOTE_WRITE_URL>: The URL of the Prometheus remote_write compatible server to send metrics to.
<USERNAME>: The username to use for authentication to the remote_write API.
<PASSWORD>: The password to use for authentication to the remote_write API.

GitHub App authentication

The following example uses GitHub App authentication to collect metrics:

prometheus.exporter.github "example" {
  repositories                 = ["grafana/alloy"]
  github_app_id                = 123456
  github_app_installation_id   = 789012
  github_app_key_path          = "/etc/github-app-key.pem"
}

// Configure a prometheus.scrape component to collect github metrics.
prometheus.scrape "demo" {
  targets    = prometheus.exporter.github.example.targets
  forward_to = [prometheus.remote_write.demo.receiver]
}

prometheus.remote_write "demo" {
  endpoint {
    url = "<PROMETHEUS_REMOTE_WRITE_URL>"

    basic_auth {
      username = "<USERNAME>"
      password = "<PASSWORD>"
    }
  }
}

Replace the following:

<PROMETHEUS_REMOTE_WRITE_URL>: The URL of the Prometheus remote_write compatible server to send metrics to.
<USERNAME>: The username to use for authentication to the remote_write API.
<PASSWORD>: The password to use for authentication to the remote_write API.

Compatible components

prometheus.exporter.github has exports that can be consumed by the following components:

Components that consume Targets

Note
Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.

prometheus.exporter.kafka

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

`prometheus.exporter.kafka`

The prometheus.exporter.kafka component embeds the kafka_exporter for collecting metrics from a Kafka server.

Usage

prometheus.exporter.kafka "<LABEL>" {
    kafka_uris = "<KAFKA_URI_LIST>"
}

Arguments

You can use the following arguments with prometheus.exporter.kafka:

Name	Type	Description	Default	Required
`kafka_uris`	`array(string)`	Address array (host:port) of Kafka server.		yes
`allow_auto_topic_creation`	`bool`	If true, the broker may auto-create topics that you requested which don’t already exist.		no
`allow_concurrency`	`bool`	If set to true, all scrapes trigger Kafka operations. Otherwise, they share results. WARNING: Disable this on large clusters.	`true`	no
`ca_file`	`string`	The optional certificate authority file for TLS client authentication.		no
`cert_file`	`string`	The optional certificate file for TLS client authentication.		no
`groups_exclude_regex`	`string`	Regex that determines which consumer groups to exclude.	`"^$"`	no
`groups_filter_regex`	`string`	Regex filter for consumer groups to be monitored.	`".*"`	no
`gssapi_kerberos_auth_type`	`string`	Kerberos auth type. Either `keytabAuth` or `userAuth`.		no
`gssapi_kerberos_config_path`	`string`	Kerberos configuration path.		no
`gssapi_key_tab_path`	`string`	Kerberos keytab file path.		no
`gssapi_realm`	`string`	Kerberos realm.		no
`gssapi_service_name`	`string`	Service name when using Kerberos Authorization		no
`insecure_skip_verify`	`bool`	If set to true, the server’s certificate isn’t checked for validity. This makes your HTTPS connections insecure.		no
`instance`	`string`	The`instance`label for metrics, default is the hostname:port of the first `kafka_uris`. You must manually provide the instance value if there is more than one string in `kafka_uris`.		no
`kafka_cluster_name`	`string`	Kafka cluster name.		no
`kafka_version`	`string`	Kafka broker version.	`"2.0.0"`	no
`key_file`	`string`	The optional key file for TLS client authentication.		no
`max_offsets`	`int`	The maximum number of offsets to store in the interpolation table for a partition.	`1000`	no
`metadata_refresh_interval`	`duration`	Metadata refresh interval.	`"1m"`	no
`offset_show_all`	`bool`	If true, the broker may auto-create topics that you requested which don’t already exist.	`true`	no
`prune_interval_seconds`	`int`	Deprecated (no-op), use `metadata_refresh_interval` instead.	`30`	no
`sasl_disable_pafx_fast`	`bool`	Configure the Kerberos client to not use PA_FX_FAST.		no
`sasl_mechanism`	`string`	The SASL SCRAM SHA algorithm SHA256 or SHA512 as mechanism.		no
`sasl_password`	`string`	SASL user password.		no
`sasl_username`	`string`	SASL user name.		no
`tls_server_name`	`string`	Used to verify the hostname on the returned certificates unless tls.insecure-skip-tls-verify is given. If you don’t provide the Kafka server name, the hostname is taken from the URL.		no
`topic_workers`	`int`	Minimum number of topics to monitor.	`100`	no
`topics_exclude_regex`	`string`	Regex that determines which topics to exclude.	`"^$"`	no
`topics_filter_regex`	`string`	Regex filter for topics to be monitored.	`".*"`	no
`use_sasl_handshake`	`bool`	Only set this to false if using a non-Kafka SASL proxy.	`true`	no
`use_sasl`	`bool`	Connect using SASL/PLAIN.		no
`use_tls`	`bool`	Connect using TLS.		no
`use_zookeeper_lag`	`bool`	If set to true, use a group from zookeeper.		no
`zookeeper_uris`	`array(string)`	Address array (hosts) of zookeeper server.		no

Blocks

The prometheus.exporter.kafka component doesn’t support any blocks. You can configure this component with arguments.

Exported fields

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

Name	Type	Description
`targets`	`list(map(string))`	The targets that can be used to collect exporter metrics.

For example, the targets can either be passed to a discovery.relabel component to rewrite the targets’ label sets or to a prometheus.scrape component that collects the exposed metrics.

The exported targets use the configured in-memory traffic address specified by the run command.

Component health

prometheus.exporter.kafka is only reported as unhealthy if given an invalid configuration. In those cases, exported fields retain their last healthy values.

Debug information

prometheus.exporter.kafka doesn’t expose any component-specific debug information.

Debug metrics

prometheus.exporter.kafka doesn’t expose any component-specific debug metrics.

Example

This example uses a prometheus.scrape component to collect metrics from prometheus.exporter.kafka:

prometheus.exporter.kafka "example" {
  kafka_uris = ["localhost:9200"]
}

// Configure a prometheus.scrape component to send metrics to.
prometheus.scrape "demo" {
  targets    = prometheus.exporter.kafka.example.targets
  forward_to = [prometheus.remote_write.demo.receiver]
}

prometheus.remote_write "demo" {
  endpoint {
    url = "<PROMETHEUS_REMOTE_WRITE_URL>"

    basic_auth {
      username = "<USERNAME>"
      password = "<PASSWORD>"
    }
  }
}

Replace the following:

<PROMETHEUS_REMOTE_WRITE_URL>: The URL of the Prometheus remote_write compatible server to send metrics to.
<USERNAME>: The username to use for authentication to the remote_write API.
<PASSWORD>: The password to use for authentication to the remote_write API.

Compatible components

prometheus.exporter.kafka has exports that can be consumed by the following components:

Components that consume Targets

Note
Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.

prometheus.exporter.memcached

Mon, 13 Apr 2026 07:37:47 +0000

`prometheus.exporter.memcached`

The prometheus.exporter.memcached component embeds the memcached_exporter for collecting metrics from a Memcached server.

Usage

prometheus.exporter.memcached "<LABEL>" {
}

Arguments

You can use the following arguments with prometheus.exporter.memcached:

Name	Type	Description	Default	Required
`address`	`string`	The Memcached server address.	`"localhost:11211"`	no
`timeout`	`duration`	The timeout for connecting to the Memcached server.	`"1s"`	no

Blocks

You can use the following block with prometheus.exporter.memcached:

Name	Description	Required
`target`	Configures a blackbox target.	no

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

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)

Exported fields

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

Name	Type	Description
`targets`	`list(map(string))`	The targets that can be used to collect exporter metrics.

For example, the targets can either be passed to a discovery.relabel component to rewrite the targets’ label sets or to a prometheus.scrape component that collects the exposed metrics.

The exported targets use the configured in-memory traffic address specified by the run command.

Component health

prometheus.exporter.memcached is only reported as unhealthy if given an invalid configuration. In those cases, exported fields retain their last healthy values.

Debug information

prometheus.exporter.memcached doesn’t expose any component-specific debug information.

Debug metrics

prometheus.exporter.memcached doesn’t expose any component-specific debug metrics.

Example

The following example uses a prometheus.exporter.memcached component to collect metrics from a Memcached server running locally, and scrapes the metrics using a prometheus.scrape component:

prometheus.exporter.memcached "example" {
  address = "localhost:13321"
  timeout = "5s"
}

prometheus.scrape "example" {
  targets    = prometheus.exporter.memcached.example.targets
  forward_to = [prometheus.remote_write.demo.receiver]
}

prometheus.remote_write "demo" {
  endpoint {
    url = "<PROMETHEUS_REMOTE_WRITE_URL>"

    basic_auth {
      username = "<USERNAME>"
      password = "<PASSWORD>"
    }
  }
}

Replace the following:

<PROMETHEUS_REMOTE_WRITE_URL>: The URL of the Prometheus remote_write compatible server to send metrics to.
<USERNAME>: The username to use for authentication to the remote_write API.
<PASSWORD>: The password to use for authentication to the remote_write API.

Compatible components

prometheus.exporter.memcached has exports that can be consumed by the following components:

Components that consume Targets

Note
Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.

prometheus.exporter.mongodb

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

`prometheus.exporter.mongodb`

The prometheus.exporter.mongodb component embeds the Percona mongodb_exporter.

Note
This exporter doesn’t collect metrics from multiple nodes. For this integration to work properly, you must connect each node of your MongoDB cluster to an Alloy instance.

We strongly recommend configuring a separate user for Alloy, giving it only the strictly mandatory security privileges necessary for monitoring your node. Refer to the Percona documentation for more information.

Usage

prometheus.exporter.mongodb "<LABEL>" {
    mongodb_uri = "<MONGODB_URI>"
}

Arguments

You can use the following arguments with prometheus.exporter.mongodb:

Name	Type	Description	Default	Required
`mongodb_uri`	`secret`	MongoDB node connection URI.		yes
`collect_all`	`bool`	Enables all collectors.	`true`	no
`compatible_mode`	`bool`	Enables metric names compatible with `mongodb_exporter` <v0.20.0.	`true`	no
`direct_connect`	`bool`	Whether or not a direct connect should be made. Direct connections aren’t valid if multiple hosts are specified or an SRV URI is used.	`false`	no
`discovering_mode`	`bool`	Whether or not to enable autodiscover collections.	`false`	no
`enable_coll_stats`	`bool`	Enables collecting collection statistics.	`false`	no
`enable_currentop_metrics`	`bool`	Enables collecting current operation metrics.	`false`	no
`enable_db_stats_free_storage`	`bool`	Enables collecting free storage statistics from `dbStats`.	`false`	no
`enable_db_stats`	`bool`	Enables collecting database statistics.	`false`	no
`enable_diagnostic_data`	`bool`	Enables collecting diagnostic data.	`false`	no
`enable_fcv`	`bool`	Enables collecting Feature Compatibility Version (FCV) metrics.	`false`	no
`enable_index_stats`	`bool`	Enables collecting index statistics.	`false`	no
`enable_pbm_metrics`	`bool`	Enables collecting Percona Backup for MongoDB (PBM) metrics.	`false`	no
`enable_profile`	`bool`	Enables collecting profile metrics.	`false`	no
`enable_replicaset_config`	`bool`	Enables collecting replica set configuration.	`false`	no
`enable_replicaset_status`	`bool`	Enables collecting replica set status.	`false`	no
`enable_shards`	`bool`	Enables collecting sharding information.	`false`	no
`enable_top_metrics`	`bool`	Enables collecting top metrics.	`false`	no

MongoDB node connection URI must be in the Standard Connection String Format

Blocks

The prometheus.exporter.mongodb component doesn’t support any blocks. You can configure this component with arguments.

Exported fields

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

Name	Type	Description
`targets`	`list(map(string))`	The targets that can be used to collect exporter metrics.

For example, the targets can either be passed to a discovery.relabel component to rewrite the targets’ label sets or to a prometheus.scrape component that collects the exposed metrics.

The exported targets use the configured in-memory traffic address specified by the run command.

Component health

prometheus.exporter.mongodb is only reported as unhealthy if given an invalid configuration. In those cases, exported fields retain their last healthy values.

Debug information

prometheus.exporter.mongodb doesn’t expose any component-specific debug information.

Debug metrics

prometheus.exporter.mongodb doesn’t expose any component-specific debug metrics.

Example

The following example uses a prometheus.scrape component to collect metrics from prometheus.exporter.mongodb:

prometheus.exporter.mongodb "example" {
  mongodb_uri = "mongodb://127.0.0.1:27017"
}

// Configure a prometheus.scrape component to collect MongoDB metrics.
prometheus.scrape "demo" {
  targets    = prometheus.exporter.mongodb.example.targets
  forward_to = [ prometheus.remote_write.default.receiver ]
}

prometheus.remote_write "default" {
  endpoint {
    url = "<PROMETHEUS_REMOTE_WRITE_URL>"
  }
}

Replace the following:

<PROMETHEUS_REMOTE_WRITE_URL>: The URL of the Prometheus remote_write compatible server to send metrics to.

Compatible components

prometheus.exporter.mongodb has exports that can be consumed by the following components:

Components that consume Targets

Note
Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.

prometheus.exporter.mssql

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

`prometheus.exporter.mssql`

The prometheus.exporter.mssql component embeds the sql_exporter for collecting stats from a Microsoft SQL Server and exposing them as Prometheus metrics.

Usage

prometheus.exporter.mssql "<LABEL>" {
    connection_string = "<CONNECTION_STRING>"
}

Arguments

You can use the following arguments with prometheus.exporter.mssql:

Name	Type	Description	Default	Required
`connection_string`	`secret`	The connection string used to connect to an Microsoft SQL Server.		yes
`connection_name`	`string`	The name of the connection, used as a label in uptime metrics.	`""`	no
`max_idle_connections`	`int`	Maximum number of idle connections to any one target.	`3`	no
`max_open_connections`	`int`	Maximum number of open connections to any one target.	`3`	no
`timeout`	`duration`	The query timeout in seconds.	`"10s"`	no
`query_config`	`string`	MSSQL query to Prometheus metric configuration as an inline string.		no

The sql_exporter examples show the format of the connection_string argument:

sqlserver://<USERNAME>:<PASSWORD>@<SQLMI_ENDPOINT>.database.windows.net:1433?encrypt=true&hostNameInCertificate=%2A.<SQL_MI_DOMAIN>.database.windows.net&trustservercertificate=true

Note
If your username or password contain special characters, you must URL encode the characters in the connection_string argument. For more information, refer to the Data Source Names section in the sql_exporter documentation

The connection_name parameter allows uptime metrics. Refer to the sql_exporter target.name setting.

If specified, the query_config argument must be a YAML document as string defining which MSSQL queries map to custom Prometheus metrics. query_config is typically loaded by using the exports of another component. For example,

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

Refer to sql_exporter for details on how to create a configuration.

Authentication

By default, the <USERNAME> and <PASSWORD> used within the connection_string argument corresponds to a SQL Server username and password.

If Alloy is running in the same Windows domain as the SQL Server, then you can use the parameter authenticator=winsspi within the connection_string to authenticate without any additional credentials.

sqlserver://@<HOST>:<PORT>?authenticator=winsspi

If you want to use Windows credentials to authenticate, instead of SQL Server credentials, you can use the parameter authenticator=ntlm within the connection_string. The <USERNAME> and <PASSWORD> then corresponds to a Windows username and password. You must use a URL encoded backslash, %5C, when you prefix the Windows domain to the username.

sqlserver://<DOMAIN>%5C<USERNAME>:<PASSWORD>@<HOST>:<PORT>?authenticator=ntlm

Blocks

The prometheus.exporter.mssql component doesn’t support any blocks. You can configure this component with arguments.

Exported fields

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

Name	Type	Description
`targets`	`list(map(string))`	The targets that can be used to collect exporter metrics.

For example, the targets can either be passed to a discovery.relabel component to rewrite the targets’ label sets or to a prometheus.scrape component that collects the exposed metrics.

The exported targets use the configured in-memory traffic address specified by the run command.

Component health

prometheus.exporter.mssql is only reported as unhealthy if given an invalid configuration. In those cases, exported fields retain their last healthy values.

Debug information

prometheus.exporter.mssql doesn’t expose any component-specific debug information.

Debug metrics

prometheus.exporter.mssql doesn’t expose any component-specific debug metrics.

Example

This example uses a prometheus.scrape component to collect metrics from prometheus.exporter.mssql:

prometheus.exporter.mssql "example" {
  connection_string = "sqlserver://user:pass@localhost:1433"
}

// Configure a prometheus.scrape component to collect mssql metrics.
prometheus.scrape "demo" {
  targets    = prometheus.exporter.mssql.example.targets
  forward_to = [prometheus.remote_write.demo.receiver]
}

prometheus.remote_write "demo" {
  endpoint {
    url = "<PROMETHEUS_REMOTE_WRITE_URL>"

    basic_auth {
      username = "<USERNAME>"
      password = "<PASSWORD>"
    }
  }
}

Replace the following:

<PROMETHEUS_REMOTE_WRITE_URL>: The URL of the Prometheus remote_write compatible server to send metrics to.
<USERNAME>: The username to use for authentication to the remote_write API.
<PASSWORD>: The password to use for authentication to the remote_write API.

Custom metrics

You can use the optional query_config parameter to retrieve custom Prometheus metrics for a MSSQL instance.

If this is defined, the new configuration is used to query your MSSQL instance and create whatever Prometheus metrics are defined. If you want additional metrics on top of the default metrics, the default configuration must be used as a base.

The default configuration used by this integration is as follows:

collector_name: mssql_standard

metrics:
  - metric_name: mssql_local_time_seconds
    type: gauge
    help: 'Local time in seconds since epoch (Unix time).'
    values: [unix_time]
    query: |
      SELECT DATEDIFF(second, '19700101', GETUTCDATE()) AS unix_time
  - metric_name: mssql_connections
    type: gauge
    help: 'Number of active connections.'
    key_labels:
      - db
    values: [count]
    query: |
      SELECT DB_NAME(sp.dbid) AS db, COUNT(sp.spid) AS count
      FROM sys.sysprocesses sp
      GROUP BY DB_NAME(sp.dbid)
  #
  # Collected from sys.dm_os_performance_counters
  #
  - metric_name: mssql_deadlocks_total
    type: counter
    help: 'Number of lock requests that resulted in a deadlock.'
    values: [cntr_value]
    query: |
      SELECT cntr_value
      FROM sys.dm_os_performance_counters WITH (NOLOCK)
      WHERE counter_name = 'Number of Deadlocks/sec' AND instance_name = '_Total'
  - metric_name: mssql_user_errors_total
    type: counter
    help: 'Number of user errors.'
    values: [cntr_value]
    query: |
      SELECT cntr_value
      FROM sys.dm_os_performance_counters WITH (NOLOCK)
      WHERE counter_name = 'Errors/sec' AND instance_name = 'User Errors'
  - metric_name: mssql_kill_connection_errors_total
    type: counter
    help: 'Number of severe errors that caused SQL Server to kill the connection.'
    values: [cntr_value]
    query: |
      SELECT cntr_value
      FROM sys.dm_os_performance_counters WITH (NOLOCK)
      WHERE counter_name = 'Errors/sec' AND instance_name = 'Kill Connection Errors'
  - metric_name: mssql_page_life_expectancy_seconds
    type: gauge
    help: 'The minimum number of seconds a page will stay in the buffer pool on this node without references.'
    values: [cntr_value]
    query: |
      SELECT top(1) cntr_value
      FROM sys.dm_os_performance_counters WITH (NOLOCK)
      WHERE counter_name = 'Page life expectancy'
  - metric_name: mssql_batch_requests_total
    type: counter
    help: 'Number of command batches received.'
    values: [cntr_value]
    query: |
      SELECT cntr_value
      FROM sys.dm_os_performance_counters WITH (NOLOCK)
      WHERE counter_name = 'Batch Requests/sec'
  - metric_name: mssql_log_growths_total
    type: counter
    help: 'Number of times the transaction log has been expanded, per database.'
    key_labels:
      - db
    values: [cntr_value]
    query: |
      SELECT rtrim(instance_name) AS db, cntr_value
      FROM sys.dm_os_performance_counters WITH (NOLOCK)
      WHERE counter_name = 'Log Growths' AND instance_name <> '_Total'
  - metric_name: mssql_buffer_cache_hit_ratio
    type: gauge
    help: 'Ratio of requests that hit the buffer cache'
    values: [BufferCacheHitRatio]
    query: |
      SELECT (a.cntr_value * 1.0 / b.cntr_value) * 100.0 as BufferCacheHitRatio
      FROM sys.dm_os_performance_counters  a
      JOIN  (SELECT cntr_value, OBJECT_NAME
          FROM sys.dm_os_performance_counters
          WHERE counter_name = 'Buffer cache hit ratio base'
              AND OBJECT_NAME = 'SQLServer:Buffer Manager') b ON  a.OBJECT_NAME = b.OBJECT_NAME
      WHERE a.counter_name = 'Buffer cache hit ratio'
      AND a.OBJECT_NAME = 'SQLServer:Buffer Manager'

  - metric_name: mssql_checkpoint_pages_sec
    type: gauge
    help: 'Checkpoint Pages Per Second'
    values: [cntr_value]
    query: |
      SELECT cntr_value
      FROM sys.dm_os_performance_counters
      WHERE [counter_name] = 'Checkpoint pages/sec'
  #
  # Collected from sys.dm_io_virtual_file_stats
  #
  - metric_name: mssql_io_stall_seconds_total
    type: counter
    help: 'Stall time in seconds per database and I/O operation.'
    key_labels:
      - db
    value_label: operation
    values:
      - read
      - write
    query_ref: mssql_io_stall

  #
  # Collected from sys.dm_os_process_memory
  #
  - metric_name: mssql_resident_memory_bytes
    type: gauge
    help: 'SQL Server resident memory size (AKA working set).'
    values: [resident_memory_bytes]
    query_ref: mssql_process_memory

  - metric_name: mssql_virtual_memory_bytes
    type: gauge
    help: 'SQL Server committed virtual memory size.'
    values: [virtual_memory_bytes]
    query_ref: mssql_process_memory

  - metric_name: mssql_available_commit_memory_bytes
    type: gauge
    help: 'SQL Server available to be committed memory size.'
    values: [available_commit_limit_bytes]
    query_ref: mssql_process_memory

  - metric_name: mssql_memory_utilization_percentage
    type: gauge
    help: 'The percentage of committed memory that is in the working set.'
    values: [memory_utilization_percentage]
    query_ref: mssql_process_memory

  - metric_name: mssql_page_fault_count_total
    type: counter
    help: 'The number of page faults that were incurred by the SQL Server process.'
    values: [page_fault_count]
    query_ref: mssql_process_memory

  #
  # Collected from sys.dm_os_sys_info
  #
  - metric_name: mssql_server_total_memory_bytes
    type: gauge
    help: 'SQL Server committed memory in the memory manager.'
    values: [committed_memory_bytes]
    query_ref: mssql_os_sys_info

  - metric_name: mssql_server_target_memory_bytes
    type: gauge
    help: 'SQL Server target committed memory set for the memory manager.'
    values: [committed_memory_target_bytes]
    query_ref: mssql_os_sys_info

  #
  # Collected from sys.dm_os_sys_memory
  #
  - metric_name: mssql_os_memory
    type: gauge
    help: 'OS physical memory, used and available.'
    value_label: 'state'
    values: [used, available]
    query: |
      SELECT
        (total_physical_memory_kb - available_physical_memory_kb) * 1024 AS used,
        available_physical_memory_kb * 1024 AS available
      FROM sys.dm_os_sys_memory
  - metric_name: mssql_os_page_file
    type: gauge
    help: 'OS page file, used and available.'
    value_label: 'state'
    values: [used, available]
    query: |
      SELECT
        (total_page_file_kb - available_page_file_kb) * 1024 AS used,
        available_page_file_kb * 1024 AS available
      FROM sys.dm_os_sys_memory
queries:
  # Populates `mssql_io_stall` and `mssql_io_stall_total`
  - query_name: mssql_io_stall
    query: |
      SELECT
        cast(DB_Name(a.database_id) as varchar) AS [db],
        sum(io_stall_read_ms) / 1000.0 AS [read],
        sum(io_stall_write_ms) / 1000.0 AS [write]
      FROM
        sys.dm_io_virtual_file_stats(null, null) a
      INNER JOIN sys.master_files b ON a.database_id = b.database_id AND a.file_id = b.file_id
      GROUP BY a.database_id
  # Populates `mssql_resident_memory_bytes`, `mssql_virtual_memory_bytes`, mssql_available_commit_memory_bytes,
  # and `mssql_memory_utilization_percentage`, and `mssql_page_fault_count_total`
  - query_name: mssql_process_memory
    query: |
      SELECT
        physical_memory_in_use_kb * 1024 AS resident_memory_bytes,
        virtual_address_space_committed_kb * 1024 AS virtual_memory_bytes,
        available_commit_limit_kb * 1024 AS available_commit_limit_bytes,
        memory_utilization_percentage,
        page_fault_count
      FROM sys.dm_os_process_memory
  # Populates `mssql_server_total_memory_bytes` and `mssql_server_target_memory_bytes`.
  - query_name: mssql_os_sys_info
    query: |
      SELECT
        committed_kb * 1024 AS committed_memory_bytes,
        committed_target_kb * 1024 AS committed_memory_target_bytes
      FROM sys.dm_os_sys_info

Compatible components

prometheus.exporter.mssql has exports that can be consumed by the following components:

Components that consume Targets

Note
Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.

prometheus.exporter.mysql

Mon, 13 Apr 2026 07:37:47 +0000

`prometheus.exporter.mysql`

The prometheus.exporter.mysql component embeds the mysqld_exporter for collecting stats from a MySQL server.

Usage

prometheus.exporter.mysql "<LABEL>" {
    data_source_name = "<DATA_SOURCE_NAME>"
}

Arguments

You can use the following arguments with prometheus.exporter.mysql:

Name	Type	Description	Default	Required
`data_source_name`	`secret`	Data Source Name for the MySQL server to connect to.		yes
`disable_collectors`	`list(string)`	A list of collectors to disable from the default set.		no
`enable_collectors`	`list(string)`	A list of collectors to enable on top of the default set.		no
`lock_wait_timeout`	`int`	Timeout, in seconds, to acquire a metadata lock.	`2`	no
`log_slow_filter`	`bool`	Used to avoid queries from scrapes being logged in the slow query log.	`false`	no
`set_collectors`	`list(string)`	A list of collectors to run. Fully overrides the default set.		no

Set a lock_wait_timeout on the connection to avoid potentially long wait times for metadata locks. For more information, refer to the lock_wait_timeout in the MySQL documentation.

Note
log_slow_filter isn’t supported by Oracle MySQL.

Blocks

You can use the following blocks with prometheus.exporter.mysql:

Name	Description	Required
`target`	Configures a blackbox target.	no

`heartbeat`

Name	Type	Description	Default	Required
`database`	`string`	Database to collect heartbeat data from.	`"heartbeat"`	no
`table`	`string`	Table to collect heartbeat data from.	`"heartbeat"`	no
`utc`	`bool`	Use UTC for timestamps of the current server. `pt-heartbeat` is called with `--utc`.	`false`	no

`info_schema.processlist`

Name	Type	Description	Default	Required
`min_time`	`int`	Minimum time a thread must be in each state to be counted.	`0`	no
`processes_by_host`	`bool`	Enable collecting the number of processes by host.	`true`	no
`processes_by_user`	`bool`	Enable collecting the number of processes by user.	`true`	no

`info_schema.tables`

Name	Type	Description	Default	Required
`info_schema_tables_databases`	`string`	Regular expression to match databases to collect table stats for.	`"*"`	no

`mysql.user`

Name	Type	Description	Default	Required
`privileges`	`bool`	Enable collecting user privileges from `mysql.user`.	`false`	no

`perf_schema.eventsstatements`

Name	Type	Description	Default	Required
`limit`	`int`	Limit the number of events statements digests, in descending order by `last_seen`.	`250`	no
`text_limit`	`int`	Maximum length of the normalized statement text.	`120`	no
`time_limit`	`int`	Limit how old, in seconds, the `last_seen` events statements can be.	`86400`	no

`perf_schema.file_instances`

Name	Type	Description	Default	Required
`filter`	`string`	Regular expression to select rows in `performance_schema.file_summary_by_instance`.	`".*"`	no
`remove_prefix`	`string`	Prefix to trim away from `file_name`.	`"/var/lib/mysql"`	no

Refer to the MySQL documentation for more detailed information about the tables used in perf_schema_file_instances_filter and perf_schema_file_instances_remove_prefix.

`perf_schema.memory_events`

Name	Type	Description	Default	Required
`remove_prefix`	`string`	Prefix to trim away from `performance_schema.memory_summary_global_by_event_name`.	`"memory/"`	no

Supported Collectors

The full list of supported collectors is:

Name	Description	Enabled by default
`global_status`	Collect metrics from `SHOW GLOBAL STATUS`.	yes
`global_variables`	Collect metrics from `SHOW GLOBAL VARIABLES`.	yes
`info_schema.innodb_cmpmem`	Collect metrics from `information_schema.innodb_cmpmem`.	yes
`info_schema.innodb_metric`s	Collect metrics from `information_schema.innodb_metrics`.	yes
`info_schema.query_response_time`	Collect query response time distribution if `query_response_time_stats` is ON.	yes
`slave_status`	Scrape information from `SHOW SLAVE STATUS`.	yes
`auto_increment.columns`	Collect `auto_increment` columns and max values from `information_schema`.	no
`binlog_size`	Collect the current size of all registered `binlog` files.	no
`engine_innodb_status`	Collect metrics from `SHOW ENGINE INNODB STATUS`.	no
`engine_tokudb_status`	Collect metrics from `SHOW ENGINE TOKUDB STATUS`.	no
`heartbeat`	Collect metrics from heartbeat database and tables.	no
`info_schema.clientstats`	If running with userstat=1, enable to collect client statistics.	no
`info_schema.innodb_tablespaces`	Collect metrics from `information_schema.innodb_sys_tablespaces`.	no
`info_schema.processlist`	Collect current thread state counts from the `information_schema.processlist`.	no
`info_schema.replica_host`	Collect metrics from `information_schema.replica_host_status`.	no
`info_schema.schemastats`	If running with userstat=1, enable to collect schema statistics.	no
`info_schema.tables`	Collect metrics from `information_schema.tables`.	no
`info_schema.tablestats`	If running with userstat=1, enable to collect table statistics.	no
`info_schema.userstats`	If running with userstat=1, enable to collect user statistics.	no
`mysql.user`	Collect data from `mysql.user`.	no
`perf_schema.eventsstatements`	Collect metrics from `performance_schema.events_statements_summary_by_digest`.	no
`perf_schema.eventsstatementssum`	Collect metrics of grand sums from `performance_schema.events_statements_summary_by_digest`.	no
`perf_schema.eventswaits`	Collect metrics from `performance_schema.events_waits_summary_global_by_event_name`.	no
`perf_schema.file_events`	Collect metrics from `performance_schema.file_summary_by_event_name`.	no
`perf_schema.file_instances`	Collect metrics from `performance_schema.file_summary_by_instance`.	no
`perf_schema.indexiowaits`	Collect metrics from `performance_schema.table_io_waits_summary_by_index_usage`.	no
`perf_schema.memory_events`	Collect metrics from `performance_schema.memory_summary_global_by_event_name`.	no
`perf_schema.replication_applier_status_by_worker`	Collect metrics from `performance_schema.replication_applier_status_by_worker`.	no
`perf_schema.replication_group_member_stats`	Collect metrics from `performance_schema.replication_group_member_stats`.	no
`perf_schema.replication_group_members`	Collect metrics from `performance_schema.replication_group_members`.	no
`perf_schema.tableiowaits`	Collect metrics from `performance_schema.table_io_waits_summary_by_table`.	no
`perf_schema.tablelocks`	Collect metrics from `performance_schema.table_lock_waits_summary_by_table`.	no
`slave_hosts`	Scrape information from `SHOW SLAVE HOSTS`.	no

Exported fields

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

Name	Type	Description
`targets`	`list(map(string))`	The targets that can be used to collect exporter metrics.

For example, the targets can either be passed to a discovery.relabel component to rewrite the targets’ label sets or to a prometheus.scrape component that collects the exposed metrics.

The exported targets use the configured in-memory traffic address specified by the run command.

Component health

prometheus.exporter.mysql is only reported as unhealthy if given an invalid configuration. In those cases, exported fields retain their last healthy values.

Debug information

prometheus.exporter.mysql doesn’t expose any component-specific debug information.

Debug metrics

prometheus.exporter.mysql doesn’t expose any component-specific debug metrics.

Example

The following example uses a prometheus.scrape component to collect metrics from prometheus.exporter.mysql:

prometheus.exporter.mysql "example" {
  data_source_name  = "root@(server-a:3306)/"
  enable_collectors = ["heartbeat", "mysql.user"]
}

// Configure a prometheus.scrape component to collect mysql metrics.
prometheus.scrape "demo" {
  targets    = prometheus.exporter.mysql.example.targets
  forward_to = [prometheus.remote_write.demo.receiver]
}

prometheus.remote_write "demo" {
  endpoint {
    url = "<PROMETHEUS_REMOTE_WRITE_URL>"

    basic_auth {
      username = "<USERNAME>"
      password = "<PASSWORD>"
    }
  }
}

Replace the following:

<PROMETHEUS_REMOTE_WRITE_URL>: The URL of the Prometheus remote_write compatible server to send metrics to.
<USERNAME>: The username to use for authentication to the remote_write API.
<PASSWORD>: The password to use for authentication to the remote_write API.

Compatible components

prometheus.exporter.mysql has exports that can be consumed by the following components:

Components that consume Targets

Note
Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.

prometheus.exporter.oracledb

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

`prometheus.exporter.oracledb`

The prometheus.exporter.oracledb component embeds oracledb_exporter for collecting statistics from an OracleDB server.

Ensure you have the following:

Oracle Instant Client Basic installed on the system running Alloy
Appropriate environment variables configured for Oracle Client libraries

Oracle instant client basic

When you run the standalone binary, you must install the Oracle Instant Client Basic for your operating system. The exporter only requires the basic version.

Note
You must also provide Oracle Instant Client Basic when you run Alloy in Docker or Kubernetes. The prometheus.exporter.oracledb component relies on Oracle Instant Client libraries that are available in the container image or host environment.

Environment variables

Set the following environment variables for Oracle Client library access:

Linux: Set LD_LIBRARY_PATH to the Oracle Instant Client library directory
macOS (ARM): Set DYLD_LIBRARY_PATH to the Oracle Instant Client library directory
ORACLE_BASE (optional): Base directory for Oracle installations
ORACLE_HOME (optional): Location of the Oracle Instant Client installation
TNS_ADMIN (optional): Location of your Oracle wallet directory when using wallet authentication

Database user permissions

The database user specified in the connection string must have permissions to query Oracle system views. The user requires the SELECT_CATALOG_ROLE role, or SELECT privilege on specific system views.

Refer to the Oracle AI Database Metrics Exporter Installation guide for the complete list of required permissions.

Usage

prometheus.exporter.oracledb "<LABEL>" {
    connection_string = "<CONNECTION_STRING>"
}

Arguments

You can use the following arguments with prometheus.exporter.oracledb:

Name	Type	Description	Default	Required
`connection_string`	`secret`	The connection string used to connect to an Oracle Database.		yes
`custom_metrics`	`list(string)`	The paths to the custom metrics files. (TOML format)		no
`default_metrics`	`string`	The path to the default metrics file. (TOML format)		no
`max_idle_conns`	`int`	Number of maximum idle connections in the connection pool.	`0`	no
`max_open_conns`	`int`	Number of maximum open connections in the connection pool.	`10`	no
`password`	`secret`	The password to use for authentication to the Oracle Database.		no
`query_timeout`	`int`	The query timeout in seconds.	`5`	no
`username`	`string`	The username to use for authentication to the Oracle Database.		no

Refer to the oracledb_exporter repository for examples of TOML metrics files.

For backward compatibility, you can still provide the username and password arguments in the connection_string argument:

oracle://user:pass@host:port/service_name[?OPTION1=VALUE1[&OPTIONn=VALUEn]...]

If the connection_string argument doesn’t contain the username and password, you must provide the username and password arguments. In this case, the URL must have the format:

host:port/service_name[?OPTION1=VALUE1[&OPTIONn=VALUEn]...]

Blocks

The prometheus.exporter.oracledb component doesn’t support any blocks. You can configure this component with arguments.

Exported fields

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

Name	Type	Description
`targets`	`list(map(string))`	The targets that can be used to collect exporter metrics.

For example, the targets can either be passed to a discovery.relabel component to rewrite the targets’ label sets or to a prometheus.scrape component that collects the exposed metrics.

The exported targets use the configured in-memory traffic address specified by the run command.

Component health

prometheus.exporter.oracledb is only reported as unhealthy if given an invalid configuration. In those cases, exported fields retain their last healthy values.

Debug information

prometheus.exporter.oracledb doesn’t expose any component-specific debug information.

Debug metrics

prometheus.exporter.oracledb doesn’t expose any component-specific debug metrics.

Example

The following example uses a prometheus.scrape component to collect metrics from prometheus.exporter.oracledb:

prometheus.exporter.oracledb "example" {
  connection_string = "localhost:1521/orcl.localnet"
  username = "<DB_USERNAME>"
  password = "<DB_PASSWORD>"
}

// Configure a prometheus.scrape component to collect oracledb metrics.
prometheus.scrape "demo" {
  targets    = prometheus.exporter.oracledb.example.targets
  forward_to = [prometheus.remote_write.demo.receiver]
}

prometheus.remote_write "demo" {
  endpoint {
    url = "<PROMETHEUS_REMOTE_WRITE_URL>"

    basic_auth {
      username = "<USERNAME>"
      password = "<PASSWORD>"
    }
  }
}

Replace the following:

<DB_USERNAME>: The database username
<DB_PASSWORD>: The password for the database user
<PROMETHEUS_REMOTE_WRITE_URL>: The URL of the Prometheus remote_write compatible server to send metrics to.
<USERNAME>: The username to use for authentication to the remote_write API.
<PASSWORD>: The password to use for authentication to the remote_write API.

Compatible components

prometheus.exporter.oracledb has exports that can be consumed by the following components:

Components that consume Targets

Note
Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.

prometheus.exporter.postgres

Mon, 13 Apr 2026 07:37:47 +0000

`prometheus.exporter.postgres`

The prometheus.exporter.postgres component embeds the postgres_exporter for collecting metrics from a PostgreSQL database.

You can specify multiple prometheus.exporter.postgres components by giving them different labels.

Usage

prometheus.exporter.postgres "<LABEL>" {
    data_source_names = "<DATA_SOURCE_NAMES_LIST>"
}

Arguments

You can use the following arguments with prometheus.exporter.postgres:

Name	Type	Description	Default	Required
`data_source_names`	`list(secret)`	Specifies the PostgreSQL servers to connect to.		yes
`custom_queries_config_path`	`string`	Path to YAML file containing custom queries to expose as metrics.	`""`	no
`disable_default_metrics`	`bool`	When `true`, only exposes metrics supplied from `custom_queries_config_path`.	`false`	no
`disable_settings_metrics`	`bool`	Disables collection of metrics from `pg_settings`.	`false`	no
`enabled_collectors`	`list(string)`	List of collectors to enable. Refer to the information below for more detail.	`[]`	no

Refer to the PostgreSQL documentation for more information about the format of the connection strings in data_source_names.

Refer to the examples for the custom_queries_config_path file in the postgres_exporter repository.

Note
There are a number of environment variables that aren’t recommended for use, as they will affect all prometheus.exporter.postgres components. Refer to the postgres_exporter repository for a full list of environment variables.

The prometheus.exporter.postgres component configures the embedded postgres_exporter to run with a collection timeout of 10 seconds.

By default, the same set of metrics is enabled as in the upstream postgres_exporter. If custom_queries_config_path is set, additional metrics defined in the given configuration file will be exposed. If disable_default_metrics is set to true, only the metrics defined in the custom_queries_config_path file will be exposed.

A subset of metrics collectors can be controlled by setting the enabled_collectors argument. The following collectors are available for selection:

buffercache_summary
database_wraparound
database
locks
long_running_transactions
postmaster
process_idle
replication_slot
replication
stat_activity_autovacuum
stat_bgwriter
stat_checkpointer - Only supported in PostgreSQL 17 and later
stat_database
stat_progress_vacuum
stat_statements
stat_user_tables
stat_wal_receiver
statio_user_indexes
statio_user_tables
wal
xlog_location

By default, the following collectors are enabled:

database
locks
replication_slot
replication
roles
stat_bgwriter
stat_database
stat_progress_vacuum
stat_user_tables
statio_user_tables
wal

Note
Due to a limitation of the upstream exporter, when multiple data_source_names are used, the collectors that are controlled via the enabled_collectors argument is only applied to the first data source in the list.

Blocks

You can use the following block with prometheus.exporter.postgres:

Name	Description	Required
`target`	Configures a blackbox target.	no

`autodiscovery`

The autodiscovery block configures discovery of databases, outside of any specified in data_source_names.

The following arguments are supported:

Name	Type	Description	Default	Required
`database_allowlist`	`list(string)`	List of databases to filter for, meaning only these databases will be scraped.		no
`database_denylist`	`list(string)`	List of databases to filter out, meaning all other databases will be scraped.		no
`enabled`	`bool`	Whether to automatically discover other databases.	`false`	no

If enabled is set to true and no allowlist or denylist is specified, the exporter scrapes from all databases.

If autodiscovery is disabled, neither database_allowlist nor database_denylist has any effect.

`stat_statements`

The stat_statements block configures the selection of both the query ID and the full SQL statement. This configuration takes effect only when the stat_statements collector is enabled.

The following arguments are supported:

Name	Type	Description	Default	Required
`exclude_databases`	`list(string)`	Comma-separated list of database names to exclude.	`[]`	no
`exclude_users`	`list(string)`	Comma-separated list of user names to exclude.	`[]`	no
`include_query`	`bool`	Enable the selection of query ID and SQL statement.	`false`	no
`limit`	`number`	Maximum number of statements to fetch.	`100`	no
`query_length`	`number`	Maximum length of the statement query text.	`120`	no

Exported fields

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

Name	Type	Description
`targets`	`list(map(string))`	The targets that can be used to collect exporter metrics.

For example, the targets can either be passed to a discovery.relabel component to rewrite the targets’ label sets or to a prometheus.scrape component that collects the exposed metrics.

The exported targets use the configured in-memory traffic address specified by the run command.

Component health

prometheus.exporter.postgres is only reported as unhealthy if given an invalid configuration.

Debug information

prometheus.exporter.postgres doesn’t expose any component-specific debug information.

Debug metrics

prometheus.exporter.postgres doesn’t expose any component-specific debug metrics.

Examples

Collect metrics from a PostgreSQL server

The following example uses a prometheus.exporter.postgres component to collect metrics from a PostgreSQL server running locally with all default settings:

// Because no autodiscovery is defined, this will only scrape the 'database_name' database, as defined
// in the DSN below.
prometheus.exporter.postgres "example" {
  data_source_names = ["postgresql://username:password@localhost:5432/database_name?sslmode=disable"]
}

prometheus.scrape "default" {
  targets    = prometheus.exporter.postgres.example.targets
  forward_to = [prometheus.remote_write.demo.receiver]
}

prometheus.remote_write "demo" {
  endpoint {
    url = "<PROMETHEUS_REMOTE_WRITE_URL>"

    basic_auth {
      username = "<USERNAME>"
      password = "<PASSWORD>"
    }
  }
}

Replace the following:

<PROMETHEUS_REMOTE_WRITE_URL>: The URL of the Prometheus remote_write compatible server to send metrics to.
<USERNAME>: The username to use for authentication to the remote_write API.
<PASSWORD>: The password to use for authentication to the remote_write API.

Collect custom metrics from an allowlisted set of databases

The following example uses a prometheus.exporter.postgres component to collect custom metrics from a set of specific databases, replacing default metrics with custom metrics derived from queries in /etc/alloy/custom-postgres-metrics.yaml:

prometheus.exporter.postgres "example" {
  data_source_names = ["postgresql://username:password@localhost:5432/database_name?sslmode=disable"]

  // This block configures autodiscovery to check for databases outside of the 'database_name' db
  // specified in the DSN above. The database_allowlist field means that only the 'frontend_app' and 'backend_app'
  // databases will be scraped.
  autodiscovery {
    enabled            = true
    database_allowlist = ["frontend_app", "backend_app"]
  }

  disable_default_metrics    = true
  custom_queries_config_path = "/etc/alloy/custom-postgres-metrics.yaml"
}

prometheus.scrape "default" {
  targets    = prometheus.exporter.postgres.example.targets
  forward_to = [prometheus.remote_write.demo.receiver]
}

prometheus.remote_write "demo" {
  endpoint {
    url = "<PROMETHEUS_REMOTE_WRITE_URL>"

    basic_auth {
      username = "<USERNAME>"
      password = "<PASSWORD>"
    }
  }
}

Replace the following:

<PROMETHEUS_REMOTE_WRITE_URL>: The URL of the Prometheus remote_write compatible server to send metrics to.
<USERNAME>: The username to use for authentication to the remote_write API.
<PASSWORD>: The password to use for authentication to the remote_write API.

Collect metrics from all databases except for a denylisted database

This example uses a prometheus.exporter.postgres component to collect custom metrics from all databases except for the secrets database.

prometheus.exporter.postgres "example" {
  data_source_names = ["postgresql://username:password@localhost:5432/database_name?sslmode=disable"]

  // The database_denylist field will filter out those databases from the list of databases to scrape,
  // meaning that all databases *except* these will be scraped.
  //
  // In this example it will scrape all databases except for the one named 'secrets'.
  autodiscovery {
    enabled           = true
    database_denylist = ["secrets"]
  }
}

prometheus.scrape "default" {
  targets    = prometheus.exporter.postgres.example.targets
  forward_to = [prometheus.remote_write.demo.receiver]
}

prometheus.remote_write "demo" {
  endpoint {
    url = "<PROMETHEUS_REMOTE_WRITE_URL>"

    basic_auth {
      username = "<USERNAME>"
      password = "<PASSWORD>"
    }
  }
}

Escape special characters in postgres url

If your PostgreSQL connection string includes special characters for e.g. password (@, :, /, etc.), you should wrap the password using encoding.url_encode.

prometheus.exporter.postgres "example" {
  data_source_names = [
    "postgresql://username:" + encoding.url_encode("p@ss/w:ord!") + "@localhost:5432/dbname?sslmode=disable"
  ]
}

This ensures the DSN remains valid and correctly parsed.

Replace the following:

<PROMETHEUS_REMOTE_WRITE_URL>: The URL of the Prometheus remote_write compatible server to send metrics to.
<USERNAME>: The username to use for authentication to the remote_write API.
<PASSWORD>: The password to use for authentication to the remote_write API.

Compatible components

prometheus.exporter.postgres has exports that can be consumed by the following components:

Components that consume Targets

Note
Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.

prometheus.exporter.process

Mon, 13 Apr 2026 07:37:47 +0000

`prometheus.exporter.process`

The prometheus.exporter.process component embeds the process_exporter for collecting process stats from /proc.

Note
We do not recommend using this exporter with clustering enabled.

The default instance label set by this exporter is the hostname of the machine running Alloy. Alloy clustering uses consistent hashing to distribute targets across the instances. This requires the discovered targets to be the same and have the same labels across all cluster instances.

If you do need to use this component in a cluster, use a dedicated prometheus.scrape component that’s used to scrape this exporter and doesn’t have clustering enabled. Alternatively, use discovery.relabel to set the instance label to a value that is the same across all cluster instances.

Usage

prometheus.exporter.process "<LABEL>" {
}

Arguments

You can use the following arguments with prometheus.exporter.process:

Name	Type	Description	Default	Required
`gather_smaps`	`bool`	Gather metrics from the smaps file for a process.	`true`	no
`procfs_path`	`string`	The procfs mount point.	`"/proc"`	no
`recheck_on_scrape`	`bool`	Recheck process names on each scrape.	`false`	no
`remove_empty_groups`	`bool`	Forget process groups with no processes.	`false`	no
`track_children`	`bool`	Whether to track a process’ children.	`true`	no
`track_threads`	`bool`	Report metrics for a process’ individual threads.	`true`	no

If you set remove_empty_groups to the default, false, the process “groups” created by the matcher blocks continue to report metrics even after the processes in that group have stopped running. This ensures you can see when a process count drops to zero, but it can cause unbounded growth in reported metrics and memory usage if your matcher generates dynamic group names, for example, using specific PIDs. The reporting continues until Alloy is restarted.

When you set remove_empty_groups to true, process groups are forgotten and stop reporting metrics as soon as they contain no running processes. Grafana recommends that you set remove_empty_groups to true if your name argument utilizes unique identifiers like .PID or .StartTime.

For example, when you set remove_empty_groups to false and the name argument for a matcher block utilizes the .PID of a process, the matcher creates a new process group for every new process instance. The old process groups continue to report metrics with values of 0, even though no running processes are associated with them, leading to high cardinality. Set remove_empty_groups to true to remove the old groups, and prevent the high cardinality.

Blocks

You can use the following block with prometheus.exporter.process:

Name	Description	Required
`target`	Configures a blackbox target.	no

`matcher`

Each matcher block configuration can match multiple processes, which are tracked as a single process “group.”

Name	Type	Description	Default	Required
`cmdline`	`list(string)`	A list of regular expressions applied to the `argv` of the process.		no
`comm`	`list(string)`	A list of strings that match the base executable name for a process, truncated to 15 characters.		no
`exe`	`list(string)`	A list of strings that match `argv[0]` for a process.		no
`name`	`string`	The name to use for identifying the process group name in the metric.	`"{{.ExeBase}}"`	no

The name argument can use the following template variables. By default it uses the base path of the executable:

{{.Comm}}: Basename of the original executable from /proc/<pid>/stat.
{{.ExeBase}}: Basename of the executable from argv[0].
{{.ExeFull}}: Fully qualified path of the executable.
{{.Username}}: Username of the effective user.
{{.Matches}}: Map containing all regular expression capture groups resulting from matching a process with the cmdline rule group.
{{.PID}}: PID of the process. Note that the PID is copied from the first executable found.
{{.StartTime}}: The start time of the process. This is useful when combined with PID as PIDS get reused over time.
{{.Cgroups}}: The cgroups, if supported, of the process (/proc/self/cgroup). This is particularly useful for identifying to which container a process belongs.

Note
Using PID or StartTime is discouraged, as it’s almost never what you want, and is likely to result in high cardinality metrics.

The value that’s used for matching comm list elements is derived from reading the second field of /proc/<pid>/stat, stripped of parens.

For values in exe, if there are no slashes, only the basename of argv[0] needs to match. Otherwise, the name must be an exact match. For example, "postgres" may match any PostgreSQL binary, but /usr/local/bin/postgres only matches a PostgreSQL process with that exact path. If any of the strings match, the process is tracked.

Each regular expression in cmdline must match the corresponding argv for the process to be tracked. The first element that is matched is argv[1]. Regular expression captures are added to the .Matches map for use in the name.

Exported fields

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

Name	Type	Description
`targets`	`list(map(string))`	The targets that can be used to collect exporter metrics.

For example, the targets can either be passed to a discovery.relabel component to rewrite the targets’ label sets or to a prometheus.scrape component that collects the exposed metrics.

The exported targets use the configured in-memory traffic address specified by the run command.

Component health

prometheus.exporter.process is only reported as unhealthy if given an invalid configuration. In those cases, exported fields retain their last healthy values.

Debug information

prometheus.exporter.process doesn’t expose any component-specific debug information.

Debug metrics

prometheus.exporter.process doesn’t expose any component-specific debug metrics.

Example

This example uses a prometheus.scrape component to collect metrics from prometheus.exporter.process:

prometheus.exporter.process "example" {
  track_children = false

  matcher {
    comm = ["alloy"]
  }
}

// Configure a prometheus.scrape component to collect process_exporter metrics.
prometheus.scrape "demo" {
  targets    = prometheus.exporter.process.example.targets
  forward_to = [prometheus.remote_write.demo.receiver]
}

prometheus.remote_write "demo" {
  endpoint {
    url = "<PROMETHEUS_REMOTE_WRITE_URL>"

    basic_auth {
      username = "<USERNAME>"
      password = "<PASSWORD>"
    }
  }
}

Replace the following:

<PROMETHEUS_REMOTE_WRITE_URL>: The URL of the Prometheus remote_write compatible server to send metrics to.
<USERNAME>: The username to use for authentication to the remote_write API.
<PASSWORD>: The password to use for authentication to the remote_write API.

Compatible components

prometheus.exporter.process has exports that can be consumed by the following components:

Components that consume Targets

Note
Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.

prometheus.exporter.redis

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

`prometheus.exporter.redis`

The prometheus.exporter.redis component embeds the redis_exporter for collecting metrics from a Redis database.

Usage

prometheus.exporter.redis "<LABEL>" {
    redis_addr = "<REDIS_ADDRESS>"
}

Arguments

You can use the following arguments with prometheus.exporter.redis:

Name	Type	Description	Default	Required
`redis_addr`	`string`	Address (host and port) of the Redis instance to connect to.		yes
`check_key_groups_batch_size`	`int`	Check key or key groups batch size hint for the underlying SCAN.	`10000`	no
`check_key_groups`	`list(string)`	List of Lua regular expressions (regex) for grouping keys.		no
`check_keys`	`list(string)`	List of key-patterns to export value and length/size, searched for with SCAN.		no
`check_single_keys`	`list(string)`	List of single keys to export value and length/size.		no
`check_single_streams`	`list(string)`	List of single streams to export info about streams, groups, and consumers.		no
`check_streams`	`list(string)`	List of stream-patterns to export info about streams, groups, and consumers to search for with SCAN.		no
`config_command`	`string`	What to use for the CONFIG command.	`"CONFIG"`	no
`connection_timeout`	`duration`	Timeout for connection to Redis instance (in Golang duration format).	`"15s"`	no
`count_keys`	`list(string)`	List of individual keys to export counts for.		no
`export_client_list`	`bool`	Whether to scrape Client List specific metrics.		no
`export_client_port`	`bool`	Whether to include the client’s port when exporting the client list.		no
`export_key_values`	`bool`	Whether to export key values as labels when using `check_keys` or `check_single_keys`.	`true`	no
`incl_system_metrics`	`bool`	Whether to include system metrics. For example `redis_total_system_memory_bytes`.		no
`is_cluster`	`bool`	Whether the connection is to a Redis cluster.		no
`is_tile38`	`bool`	Whether to scrape Tile38-specific metrics.		no
`max_distinct_key_groups`	`int`	The maximum number of distinct key groups with the most memory utilization to present as distinct metrics per database.	`100`	no
`namespace`	`string`	Namespace for the metrics.	`"redis"`	no
`ping_on_connect`	`bool`	Whether to ping the Redis instance after connecting.		no
`redis_metrics_only`	`bool`	Whether to just export metrics or to also export go runtime metrics.		no
`redis_password_file`	`string`	Path of a file containing a password.		no
`redis_password_map_file`	`string`	Path of a JSON file containing a map of Redis URIs to passwords.		no
`redis_password`	`secret`	Password of the Redis instance.		no
`redis_user`	`string`	User name to use for authentication. Redis ACL for Redis 6.0 and newer.		no
`script_path`	`string`	Path to Lua Redis script for collecting extra metrics.		no
`script_paths`	`list(string)`	List of paths to Lua Redis scripts for collecting extra metrics.		no
`set_client_name`	`bool`	Whether to set client name to `redis_exporter`.	`true`	no
`skip_tls_verification`	`bool`	Whether to skip TLS verification.		no
`tls_ca_cert_file`	`string`	Name of the CA certificate file (including full path) if the server requires TLS client authentication.		no
`tls_client_cert_file`	`string`	Name of the client certificate file (including full path) if the server requires TLS client authentication.		no
`tls_client_key_file`	`string`	Name of the client key file (including full path) if the server requires TLS client authentication.		no

If redis_password_file is defined, it takes precedence over redis_password.

When check_key_groups isn’t set, no key groups are made.

The check_key_groups_batch_size argument name reflects key groups for backwards compatibility, but applies to both key and key groups.

The script_path argument may also be specified as a comma-separated string of paths, though it’s encouraged to use script_paths when using multiple Lua scripts.

Any leftover key groups beyond max_distinct_key_groups are aggregated in the ‘overflow’ bucket.

The is_cluster argument must be set to true when connecting to a Redis cluster and using either of the check_keys and check_single_keys arguments.

Note
Setting export_client_port increases the cardinality of all Redis metrics.

Blocks

The prometheus.exporter.redis component doesn’t support any blocks. You can configure this component with arguments.

Exported fields

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

Name	Type	Description
`targets`	`list(map(string))`	The targets that can be used to collect exporter metrics.

For example, the targets can either be passed to a discovery.relabel component to rewrite the targets’ label sets or to a prometheus.scrape component that collects the exposed metrics.

The exported targets use the configured in-memory traffic address specified by the run command.

Component health

prometheus.exporter.redis is only reported as unhealthy if given an invalid configuration. In those cases, exported fields retain their last healthy values.

Debug information

prometheus.exporter.redis doesn’t expose any component-specific debug information.

Debug metrics

prometheus.exporter.redis doesn’t expose any component-specific debug metrics.

Example

This example uses a prometheus.scrape component to collect metrics from prometheus.exporter.redis:

prometheus.exporter.redis "example" {
  redis_addr = "localhost:6379"
}

// Configure a prometheus.scrape component to collect Redis metrics.
prometheus.scrape "demo" {
  targets    = prometheus.exporter.redis.example.targets
  forward_to = [prometheus.remote_write.demo.receiver]
}

prometheus.remote_write "demo" {
  endpoint {
    url = "<PROMETHEUS_REMOTE_WRITE_URL>"

    basic_auth {
      username = "<USERNAME>"
      password = "<PASSWORD>"
    }
  }
}

Replace the following:

<PROMETHEUS_REMOTE_WRITE_URL>: The URL of the Prometheus remote_write compatible server to send metrics to.
<USERNAME>: The username to use for authentication to the remote_write API.
<PASSWORD>: The password to use for authentication to the remote_write API.

Compatible components

prometheus.exporter.redis has exports that can be consumed by the following components:

Components that consume Targets

Note
Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.

prometheus.exporter.self

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

`prometheus.exporter.self`

The prometheus.exporter.self component collects and exposes metrics about Alloy itself.

Note
We do not recommend using this exporter with clustering enabled.

The default instance label set by this exporter is the hostname of the machine running Alloy. Alloy clustering uses consistent hashing to distribute targets across the instances. This requires the discovered targets to be the same and have the same labels across all cluster instances.

If you do need to use this component in a cluster, use a dedicated prometheus.scrape component that’s used to scrape this exporter and doesn’t have clustering enabled. Alternatively, use discovery.relabel to set the instance label to a value that is the same across all cluster instances.

Usage

prometheus.exporter.self "<LABEL>" {
}

Arguments

The prometheus.exporter.self component doesn’t support any arguments.

Blocks

The prometheus.exporter.self component doesn’t support any blocks.

Exported fields

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

Name	Type	Description
`targets`	`list(map(string))`	The targets that can be used to collect exporter metrics.

For example, the targets can either be passed to a discovery.relabel component to rewrite the targets’ label sets or to a prometheus.scrape component that collects the exposed metrics.

The exported targets use the configured in-memory traffic address specified by the run command.

Component health

prometheus.exporter.self is only reported as unhealthy if given an invalid configuration.

Debug information

prometheus.exporter.self doesn’t expose any component-specific debug information.

Debug metrics

prometheus.exporter.self doesn’t expose any component-specific debug metrics.

Example

The following example uses a prometheus.scrape component to collect metrics from prometheus.exporter.self:

prometheus.exporter.self "example" {}

// Configure a prometheus.scrape component to collect Alloy metrics.
prometheus.scrape "demo" {
  targets    = prometheus.exporter.self.example.targets
  forward_to = [prometheus.remote_write.demo.receiver]
}

prometheus.remote_write "demo" {
  endpoint {
    url = "<PROMETHEUS_REMOTE_WRITE_URL>"

    basic_auth {
      username = "<USERNAME>"
      password = "<PASSWORD>"
    }
  }
}

Replace the following:

<PROMETHEUS_REMOTE_WRITE_URL>: The URL of the Prometheus remote_write compatible server to send metrics to.
<USERNAME>: The username to use for authentication to the remote_write API.
<PASSWORD>: The password to use for authentication to the remote_write API.

Compatible components

prometheus.exporter.self has exports that can be consumed by the following components:

Components that consume Targets

Note
Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.

prometheus.exporter.snmp

Mon, 13 Apr 2026 07:37:47 +0000

`prometheus.exporter.snmp`

The prometheus.exporter.snmp component embeds the snmp_exporter. The snmp_exporter lets you collect SNMP data and expose them as Prometheus metrics.

Note
prometheus.exporter.snmp uses the latest configuration introduced in version v0.29.0 of the Prometheus snmp_exporter.

Usage

prometheus.exporter.snmp "<LABEL>" {
  config_file = "<SNMP_CONFIG_FILE_PATH>"

  target "<TARGET_NAME>" {
    address = "<TARGET_ADDRESS>"
  }
}

prometheus.exporter.snmp "<LABEL>" {
  config_file = "<SNMP_CONFIG_FILE_PATH>"
  targets     = <TARGET_LIST>
}

Arguments

You can use the following arguments with prometheus.exporter.snmp:

Name	Type	Description	Default	Required
`concurrency`	`int`	SNMP exporter concurrency.	`1`	no
`config_file`	`string`	SNMP configuration file defining custom modules.		no
`config_merge_strategy`	`string`	A strategy defining how `config` or `config_file` contents merge with the embedded SNMP config. Can be `replace` or `merge`.	`"replace"`	no
`config`	`string` or `secret`	SNMP configuration as inline string.		no
`targets`	`list(map(string))`	SNMP targets.		no

The config_file argument points to a YAML file defining which snmp_exporter modules to use. Refer to snmp_exporter for details on how to generate a configuration file.

The config argument must be a YAML document as string defining which SNMP modules and authorizations to use. config is typically loaded by using the exports of another component. For example,

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

Set config_merge_strategy to merge to add additional configuration to the embedded SNMP configuration. For example, if you need to add a few custom auth settings without regenerating the whole configuration.

The targets argument is an alternative to the [target][] block. This is useful when SNMP targets are supplied by another component. The following labels can be set to a target:

name: The name of the target (required).
address or __address__: The address of SNMP device (required).
module: SNMP modules to use for polling, separated by comma.
auth: The SNMP authentication profile to use.
walk_params: The configuration to use for this target.

Any other labels defined are added to the scraped metrics.

Blocks

You can use the following blocks with prometheus.exporter.snmp:

Name	Description	Required
`target`	Configures a blackbox target.	no

`target`

The target block defines an individual SNMP target. The target block may be specified multiple times to define multiple targets. The label of the block is required and is used in the target’s job label.

Name	Type	Description	Default	Required
`address`	`string`	The address of SNMP device.		yes
`auth`	`string`	SNMP authentication profile to use.	`""`	no
`labels`	`map(string)`	Map of labels to apply to all metrics captured from the target.	`""`	no
`module`	`string`	SNMP modules to use for polling, separated by comma.	`""`	no
`snmp_context`	`string`	Override the `context_name` parameter in the SNMP configuration file.	`""`	no
`walk_params`	`string`	Config to use for this target.	`""`	no

`walk_param`

The walk_param block defines an individual SNMP connection profile that can be used to override default SNMP settings. The walk_param block may be specified multiple times to define multiple SNMP connection profiles.

Name	Type	Description	Default	Required
`max_repetitions`	`int`	How many objects to request with GET/GETBULK.	`25`	no
`name`	`string`	Name of the module to override.		no
`retries`	`int`	How many times to retry a failed request.	`3`	no
`timeout`	`duration`	Timeout for each individual SNMP request.		no

Exported fields

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

Name	Type	Description
`targets`	`list(map(string))`	The targets that can be used to collect exporter metrics.

For example, the targets can either be passed to a discovery.relabel component to rewrite the targets’ label sets or to a prometheus.scrape component that collects the exposed metrics.

The exported targets use the configured in-memory traffic address specified by the run command.

Component health

prometheus.exporter.snmp is only reported as unhealthy if given an invalid configuration. In those cases, exported fields retain their last healthy values.

Debug information

prometheus.exporter.snmp doesn’t expose any component-specific debug information.

Debug metrics

prometheus.exporter.snmp doesn’t expose any component-specific debug metrics.

Example

The following example uses a prometheus.scrape component to collect metrics from prometheus.exporter.snmp:

prometheus.exporter.snmp "example" {
    config_file = "snmp_modules.yml"

    target "network_switch_1" {
        address     = "192.168.1.2"
        module      = "system,if_mib"
        walk_params = "public"
        labels = {
            "env" = "dev",
        }
    }

    target "network_router_2" {
        address     = "192.168.1.3"
        module      = "system,if_mib,mikrotik"
        walk_params = "private"
    }

    walk_param "private" {
        retries = "2"
    }

    walk_param "public" {
        retries = "2"
    }
}

// Configure a prometheus.scrape component to collect SNMP metrics.
prometheus.scrape "demo" {
    targets    = prometheus.exporter.snmp.example.targets
    forward_to = [ /* ... */ ]
}

The following example uses an embedded configuration with secrets:

local.file "snmp_config" {
    filename  = "snmp_modules.yml"
    is_secret = true
}

prometheus.exporter.snmp "example" {
    config = local.file.snmp_config.content

    target "network_switch_1" {
        address     = "192.168.1.2"
        module      = "system,if_mib"
        walk_params = "public"
    }

    target "network_router_2" {
        address     = "192.168.1.3"
        module      = "system,if_mib,mikrotik"
        walk_params = "private"
    }

    walk_param "private" {
        retries = "2"
    }

    walk_param "public" {
        retries = "2"
    }
}

// Configure a prometheus.scrape component to collect SNMP metrics.
prometheus.scrape "demo" {
    targets    = prometheus.exporter.snmp.example.targets
    forward_to = [prometheus.remote_write.demo.receiver]
}

prometheus.remote_write "demo" {
    endpoint {
        url = "<PROMETHEUS_REMOTE_WRITE_URL>"

        basic_auth {
            username = "<USERNAME>"
            password = "<PASSWORD>"
        }
    }
}

Replace the following:

<PROMETHEUS_REMOTE_WRITE_URL>: The URL of the Prometheus remote_write compatible server to send metrics to.
<USERNAME>: The username to use for authentication to the remote_write API.
<PASSWORD>: The password to use for authentication to the remote_write API.

The following example uses the alternative way to pass targets:

prometheus.exporter.snmp "example" {
    config_file = "snmp_modules.yml"

    targets = [
        {
            "name"        = "network_switch_1",
            "address"     = "192.168.1.2",
            "module"      = "system,if_mib",
            "walk_params" = "public",
            "env"         = "dev",
        },
        {
            "name"        = "network_router_2",
            "address"     = "192.168.1.3",
            "module"      = "system,if_mib,mikrotik",
            "walk_params" = "private",
        },
    ]

    walk_param "private" {
        retries = "2"
    }

    walk_param "public" {
        retries = "2"
    }
}

// Configure a prometheus.scrape component to collect SNMP metrics.
prometheus.scrape "demo" {
    targets    = prometheus.exporter.snmp.example.targets
    forward_to = [ /* ... */ ]
}

The following example uses the local.file component to read targets from a YAML file and send them to the prometheus.exporter.snmp component:

local.file "targets" {
  filename = "targets.yml"
}

prometheus.exporter.snmp "example" {
    config_file = "snmp_modules.yml"

    targets = encoding.from_yaml(local.file.targets.content)

    walk_param "private" {
        retries = "2"
    }

    walk_param "public" {
        retries = "2"
    }
}

// Configure a prometheus.scrape component to collect SNMP metrics.
prometheus.scrape "demo" {
    targets    = prometheus.exporter.snmp.example.targets
    forward_to = [ /* ... */ ]
}

The YAML file in this example looks like this:

- name: t1
  address: localhost:161
  module: default
  auth: public_v2
- name: t2
  address: localhost:161
  module: default
  auth: public_v2

The following example uses the discovery.file component to send targets to the prometheus.exporter.snmp component:

discovery.file "example" {
  files = ["targets.yml"]
}

prometheus.exporter.snmp "example" {
  config_file = "snmp_modules.yml"
  targets = discovery.file.example.targets
}

// Configure a prometheus.scrape component to collect SNMP metrics.
prometheus.scrape "demo" {
    targets    = prometheus.exporter.snmp.example.targets
    forward_to = [ /* ... */ ]
}

The YAML file in this example looks like this:

- targets:
  - localhost:161
  labels:
    name: t1
    module: default
    auth: public_v2
- targets:
  - localhost:161
  labels:
    name: t2
    module: default
    auth: public_v2

Compatible components

prometheus.exporter.snmp has exports that can be consumed by the following components:

Components that consume Targets

Note
Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.

prometheus.exporter.snowflake

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

`prometheus.exporter.snowflake`

The prometheus.exporter.snowflake component embeds the snowflake_exporter for collecting warehouse, database, table, and replication statistics from a Snowflake account via HTTP for Prometheus consumption.

Usage

You can use the prometheus.exporter.snowflake component with password or RSA authentication.

Password Authentication

prometheus.exporter.snowflake "LABEL" {
    account_name = "<SNOWFLAKE_ACCOUNT_NAME>"
    username =     "<USERNAME>"
    password =     "<PASSWORD>"
    warehouse =    "<VIRTUAL_WAREHOUSE>"
}

RSA Authentication

prometheus.exporter.snowflake "LABEL" {
    account_name =         "<SNOWFLAKE_ACCOUNT_NAME>"
    username =             "<USERNAME>"
    private_key_path =     "<RSA_PRIVATE_KEY_PATH>"
    private_key_password = "<RSA_PRIVATE_KEY_PASSWORD>"
    warehouse =            "<VIRTUAL_WAREHOUSE>"
}

Arguments

You can use the following arguments with prometheus.exporter.snowflake:

Name	Type	Description	Default	Required
`account_name`	`string`	The account to collect metrics from.		yes
`username`	`string`	The username for the user used when querying metrics.		yes
`warehouse`	`string`	The warehouse to use when querying metrics.		yes
`enable_tracing`	`bool`	Whether to have the snowflake database driver provide trace logging.	`false`	no
`exclude_deleted_tables`	`bool`	Whether to exclude deleted tables when querying table storage metrics.	`false`	no
`password`	`secret`	The password for the user used when querying metrics (required for password authentication).		no
`private_key_password`	`secret`	The password for the user’s RSA private key (required for encrypted RSA key-pair authentication).		no
`private_key_path`	`secret`	The path to the user’s RSA private key file (required for RSA key-pair authentication).		no
`role`	`string`	The role to use when querying metrics.	`"ACCOUNTADMIN"`	no

One of password or private_key_path must be specified to authenticate. Users with an encrypted private key will also need to provide a private_key_password.

Blocks

The prometheus.exporter.snowflake component doesn’t support any blocks. You can configure this component with arguments.

Exported fields

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

Name	Type	Description
`targets`	`list(map(string))`	The targets that can be used to collect exporter metrics.

For example, the targets can either be passed to a discovery.relabel component to rewrite the targets’ label sets or to a prometheus.scrape component that collects the exposed metrics.

The exported targets use the configured in-memory traffic address specified by the run command.

Component health

prometheus.exporter.snowflake is only reported as unhealthy if given an invalid configuration. In those cases, exported fields retain their last healthy values.

Debug information

prometheus.exporter.snowflake doesn’t expose any component-specific debug information.

Debug metrics

prometheus.exporter.snowflake doesn’t expose any component-specific debug metrics.

Example

The following example uses a prometheus.scrape component to collect metrics from prometheus.exporter.snowflake:

prometheus.exporter.snowflake "example" {
  account_name = "XXXXXXX-YYYYYYY"
  username     = "grafana"
  password     = "snowflake"
  warehouse    = "examples"
}

// Configure a prometheus.scrape component to collect snowflake metrics.
prometheus.scrape "demo" {
  targets    = prometheus.exporter.snowflake.example.targets
  forward_to = [prometheus.remote_write.demo.receiver]
}

prometheus.remote_write "demo" {
  endpoint {
    url = "<PROMETHEUS_REMOTE_WRITE_URL>"

    basic_auth {
      username = "<USERNAME>"
      password = "<PASSWORD>"
    }
  }
}

Replace the following:

<PROMETHEUS_REMOTE_WRITE_URL>: The URL of the Prometheus remote_write compatible server to send metrics to.
<USERNAME>: The username to use for authentication to the remote_write API.
<PASSWORD>: The password to use for authentication to the remote_write API.

Compatible components

prometheus.exporter.snowflake has exports that can be consumed by the following components:

Components that consume Targets

Note
Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.

prometheus.exporter.squid

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

`prometheus.exporter.squid`

The prometheus.exporter.squid component embeds the squid_exporter for collecting metrics from a squid instance.

Usage

prometheus.exporter.squid "<LABEL>" {
    address = "<SQUID_ADDRESS>"
}

Arguments

You can use the following arguments with prometheus.exporter.squid:

Name	Type	Description	Required
`address`	`string`	The squid address to collect metrics from.	yes
`password`	`secret`	The password for the user used when querying metrics.	no
`username`	`string`	The username for the user used when querying metrics.	no

Blocks

The prometheus.exporter.squid component doesn’t support any blocks. You can configure this component with arguments.

Exported fields

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

Name	Type	Description
`targets`	`list(map(string))`	The targets that can be used to collect exporter metrics.

For example, the targets can either be passed to a discovery.relabel component to rewrite the targets’ label sets or to a prometheus.scrape component that collects the exposed metrics.

The exported targets use the configured in-memory traffic address specified by the run command.

Component health

prometheus.exporter.squid is only reported as unhealthy if given an invalid configuration. In those cases, exported fields retain their last healthy values.

Debug information

prometheus.exporter.squid doesn’t expose any component-specific debug information.

Debug metrics

prometheus.exporter.squid doesn’t expose any component-specific debug metrics.

Example

This example uses a prometheus.scrape component to collect metrics from prometheus.exporter.squid:

prometheus.exporter.squid "example" {
  address = "localhost:3128"
}

// Configure a prometheus.scrape component to collect squid metrics.
prometheus.scrape "demo" {
  targets    = prometheus.exporter.squid.example.targets
  forward_to = [prometheus.remote_write.demo.receiver]
}

prometheus.remote_write "demo" {
  endpoint {
    url = "<PROMETHEUS_REMOTE_WRITE_URL>"

    basic_auth {
      username = "<USERNAME>"
      password = "<PASSWORD>"
    }
  }
}

Replace the following:

<PROMETHEUS_REMOTE_WRITE_URL>: The URL of the Prometheus remote_write compatible server to send metrics to.
<USERNAME>: The username to use for authentication to the remote_write API.
<PASSWORD>: The password to use for authentication to the remote_write API.

Compatible components

prometheus.exporter.squid has exports that can be consumed by the following components:

Components that consume Targets

Note
Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.

prometheus.exporter.static

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

`prometheus.exporter.static`

EXPERIMENTAL: This is an experimental component. Experimental components are subject to frequent breaking changes, and may be removed with no equivalent replacement. To enable and use an experimental component, you must set the stability.level flag to experimental.

prometheus.exporter.static loads metrics from text specified in Prometheus exposition format and exposes them for scraping.

You can specify multiple prometheus.exporter.static components by giving them different labels.

Usage

prometheus.exporter.static "<LABEL>" {
}

Arguments

You can use the following argument with prometheus.exporter.static:

Name	Type	Description	Default	Required
`text`	`string`	Text in Prometheus exposition format.	`""`	no

Exported fields

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

Name	Type	Description
`targets`	`list(map(string))`	The targets that can be used to collect exporter metrics.

For example, the targets can either be passed to a discovery.relabel component to rewrite the targets’ label sets or to a prometheus.scrape component that collects the exposed metrics.

The exported targets use the configured in-memory traffic address specified by the run command.

Component health

prometheus.exporter.static is only reported as unhealthy if given an invalid configuration. In those cases, exported fields retain their last healthy values.

Debug information

prometheus.exporter.static doesn’t expose any component-specific debug information.

Debug metrics

prometheus.exporter.static doesn’t expose any component-specific debug metrics.

Example

This example uses a prometheus.scrape component to collect metrics from prometheus.exporter.static:

prometheus.exporter.static "demo" {
    text = `
# HELP http_requests_total The total number of HTTP requests.
# TYPE http_requests_total counter
http_requests_total{method="post",code="200"} 1027
http_requests_total{method="post",code="400"}    3

# HELP http_request_duration_seconds A histogram of the request duration.
# TYPE http_request_duration_seconds histogram
http_request_duration_seconds_bucket{le="0.05"} 24054
http_request_duration_seconds_bucket{le="0.1"} 33444
http_request_duration_seconds_bucket{le="0.2"} 100392
http_request_duration_seconds_bucket{le="0.5"} 129389
http_request_duration_seconds_bucket{le="1"} 133988
http_request_duration_seconds_bucket{le="+Inf"} 144320
http_request_duration_seconds_sum 53423
http_request_duration_seconds_count 144320
    `
}

// Configure a prometheus.scrape component to collect static metrics.
prometheus.scrape "demo" {
  targets    = prometheus.exporter.static.demo.targets
  forward_to = [prometheus.remote_write.demo.receiver]
}

prometheus.remote_write "demo" {
  endpoint {
    url = "<PROMETHEUS_REMOTE_WRITE_URL>"

    basic_auth {
      username = "<USERNAME>"
      password = "<PASSWORD>"
    }
  }
}

Replace the following:

<PROMETHEUS_REMOTE_WRITE_URL>: The URL of the Prometheus remote_write compatible server to send metrics to.
<USERNAME>: The username to use for authentication to the remote_write API.
<PASSWORD>: The password to use for authentication to the remote_write API.

Compatible components

prometheus.exporter.static has exports that can be consumed by the following components:

Components that consume Targets

Note
Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.

prometheus.exporter.statsd

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

`prometheus.exporter.statsd`

The prometheus.exporter.statsd component embeds the statsd_exporter for collecting StatsD-style metrics and exporting them as Prometheus metrics.

Usage

prometheus.exporter.statsd "<LABEL>" {
}

Arguments

You can use the following arguments with prometheus.exporter.statsd:

Name	Type	Description	Default	Required
`cache_size`	`int`	Maximum size of your metric mapping cache. Relies on least recently used replacement policy if max size is reached.	`1000`	no
`cache_type`	`string`	Metric mapping cache type. Valid options are “lru” and “random”.	`"lru"`	no
`event_flush_interval`	`string`	Maximum time between event queue flushes.	`"200ms"`	no
`event_flush_threshold`	`int`	Number of events to hold in queue before flushing.	`1000`	no
`event_queue_size`	`int`	Size of internal queue for processing events.	`10000`	no
`listen_tcp`	`string`	The TCP address on which to receive statsd metric lines. Use `""` to disable it.	`":9125"`	no
`listen_udp`	`string`	The UDP address on which to receive statsd metric lines. Use `""` to disable it.	`":9125"`	no
`listen_unixgram`	`string`	The Unixgram socket path to receive statsd metric lines in datagram. Use `""` to disable it.		no
`mapping_config_path`	`string`	The path to a YAML mapping file used to translate specific dot-separated StatsD metrics into labeled Prometheus metrics.		no
`parse_dogstatsd_tags`	`bool`	Parse DogStatsd style tags.	`true`	no
`parse_influxdb_tags`	`bool`	Parse InfluxDB style tags.	`true`	no
`parse_librato_tags`	`bool`	Parse Librato style tags.	`true`	no
`parse_signalfx_tags`	`bool`	Parse SignalFX style tags.	`true`	no
`read_buffer`	`int`	Size (in bytes) of the operating system’s transmit read buffer associated with the UDP or Unixgram connection.		no
`relay_addr`	`string`	Relay address configuration (UDP endpoint in the format ‘host:port’).		no
`relay_packet_length`	`int`	Maximum relay output packet length to avoid fragmentation.	`1400`	no
`unix_socket_mode`	`string`	The permission mode of the Unix socket.	`"755"`	no

At least one of listen_udp, listen_tcp, or listen_unixgram should be enabled. Refer to the statsd_exporter documentation more information about the mapping config file. Make sure the kernel parameter net.core.rmem_max is set to a value greater than the value specified in read_buffer.

Blocks

The prometheus.exporter.statsd component doesn’t support any blocks. You can configure this component with arguments.

Exported fields

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

Name	Type	Description
`targets`	`list(map(string))`	The targets that can be used to collect exporter metrics.

For example, the targets can either be passed to a discovery.relabel component to rewrite the targets’ label sets or to a prometheus.scrape component that collects the exposed metrics.

The exported targets use the configured in-memory traffic address specified by the run command.

Component health

prometheus.exporter.statsd is only reported as unhealthy if given an invalid configuration. In those cases, exported fields retain their last healthy values.

Debug information

prometheus.exporter.statsd doesn’t expose any component-specific debug information.

Debug metrics

prometheus.exporter.statsd doesn’t expose any component-specific debug metrics.

Example

The following example uses a prometheus.scrape component to collect metrics from prometheus.exporter.statsd:

prometheus.exporter.statsd "example" {
  listen_udp            = ""
  listen_tcp            = ":9125"
  listen_unixgram       = ""
  unix_socket_mode      = "755"
  mapping_config_path   = "mapTest.yaml"
  read_buffer           = 1
  cache_size            = 1000
  cache_type            = "lru"
  event_queue_size      = 10000
  event_flush_threshold = 1000
  event_flush_interval  = "200ms"
  parse_dogstatsd_tags  = true
  parse_influxdb_tags   = true
  parse_librato_tags    = true
  parse_signalfx_tags   = true
}

// Configure a prometheus.scrape component to collect statsd metrics.
prometheus.scrape "demo" {
  targets    = prometheus.exporter.statsd.example.targets
  forward_to = [prometheus.remote_write.demo.receiver]
}

prometheus.remote_write "demo" {
  endpoint {
    url = "<PROMETHEUS_REMOTE_WRITE_URL>"

    basic_auth {
      username = "<USERNAME>"
      password = "<PASSWORD>"
    }
  }
}

Replace the following:

<PROMETHEUS_REMOTE_WRITE_URL>: The URL of the Prometheus remote_write compatible server to send metrics to.
<USERNAME>: The username to use for authentication to the remote_write API.
<PASSWORD>: The password to use for authentication to the remote_write API.

Compatible components

prometheus.exporter.statsd has exports that can be consumed by the following components:

Components that consume Targets

Note
Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.

prometheus.exporter.unix

Mon, 13 Apr 2026 07:37:47 +0000

`prometheus.exporter.unix`

The prometheus.exporter.unix component uses the node_exporter to expose a wide variety of hardware and OS metrics for Unix-based systems.

The node_exporter itself is comprised of various collectors, which you can enable and disable. For more information on collectors, refer to the collectors-list section.

You can specify multiple prometheus.exporter.unix components by giving them different labels.

Note
We do not recommend using this exporter with clustering enabled.

The default instance label set by this exporter is the hostname of the machine running Alloy. Alloy clustering uses consistent hashing to distribute targets across the instances. This requires the discovered targets to be the same and have the same labels across all cluster instances.

If you do need to use this component in a cluster, use a dedicated prometheus.scrape component that’s used to scrape this exporter and doesn’t have clustering enabled. Alternatively, use discovery.relabel to set the instance label to a value that is the same across all cluster instances.

Usage

prometheus.exporter.unix "<LABEL>" {
}

Arguments

You can use the following arguments with prometheus.exporter.unix:

Name	Type	Description	Default	Required
`disable_collectors`	`list(string)`	Collectors to disable.	`[]`	no
`enable_collectors`	`list(string)`	Collectors to enable.	`[]`	no
`include_exporter_metrics`	`bool`	Whether metrics about the exporter itself should be reported.	`false`	no
`procfs_path`	`string`	The procfs mount point.	`"/proc"`	no
`rootfs_path`	`string`	Specify a prefix for accessing the host filesystem.	`"/"`	no
`set_collectors`	`list(string)`	Overrides the default set of enabled collectors with the collectors listed.		no
`sysfs_path`	`string`	The sysfs mount point.	`"/sys"`	no
`udev_data_path`	`string`	The udev data path.	`"/run/udev/data"`	no

set_collectors defines a hand-picked list of enabled-by-default collectors. If set, anything not provided in that list is disabled by default. Refer to the Collectors list for the default set of enabled collectors for each supported operating system.

enable_collectors enables more collectors over the default set, or on top of the ones provided in set_collectors.

disable_collectors extends the default set of disabled collectors. If there are conflicts, it takes precedence over enable_collectors.

Blocks

You can use the following blocks with prometheus.exporter.unix:

Name	Description	Required
`target`	Configures a blackbox target.	no

`arp`

Name	Type	Description	Default	Required
`device_exclude`	`string`	Regular expression of devices to exclude for `arp` collector. Mutually exclusive with `device_include`.		no
`device_include`	`string`	Regular expression of devices to include for `arp` collector. Mutually exclusive with `device_exclude`.		no
`netlink`	`boolean`	Use netlink to gather ARP stats instead of `/proc/net/arp`.	`false`	no

It is recommended to set netlink to true on systems with InfiniBand or other non-Ethernet devices.

`bcache`

Name	Type	Description	Default	Required
`priority_stats`	`boolean`	Enable exposing of expensive `bcache` priority stats.	false	no

`cpu`

Name	Type	Description	Default	Required
`bugs_include`	`string`	Regular expression of `bugs` field in `cpu` info to filter.		no
`flags_include`	`string`	Regular expression of `flags` field in `cpu` info to filter.		no
`guest`	`boolean`	Enable the `node_cpu_guest_seconds_total` metric.	false	no
`info`	`boolean`	Enable the `cpu_info` metric for the `cpu` collector.	false	no

`disk`

Name	Type	Description	Default	Required
`device_exclude`	`string`	Regular expression of devices to exclude for `diskstats`.	`"^(ram\|loop\|fd\|(h\|s\|v\|xv)d[a-z]\|nvme\\d+n\\d+p)\\d+$"`	no
`device_include`	`string`	Regular expression of devices to include for `diskstats`. If set, `device_exclude` is ignored.		no

`ethtool`

Name	Type	Description	Default	Required
`device_exclude`	`string`	Regular expression of `ethtool` devices to exclude. Mutually exclusive with `device_include`.		no
`device_include`	`string`	Regular expression of `ethtool` devices to include. Mutually exclusive with `device_exclude`.		no
`metrics_include`	`string`	Regular expression of `ethtool` stats to include.	`.*`	no

`filesystem`

The default values vary by the operating system Alloy runs on.

Name	Type	Description	Default	Required
`fs_types_exclude`	`string`	Regular expression of filesystem types to ignore for filesystem collector.	see below	no
`mount_points_exclude`	`string`	Regular expression of mount points to ignore for filesystem collector.	see below	no
`mount_timeout`	`duration`	How long to wait for a mount to respond before marking it as stale.	`"5s"`	no

fs_types_exclude defaults to the following regular expression string:

linux

osx

bsd

^(autofs|binfmt_misc|bpf|cgroup2?|configfs|debugfs|devpts|devtmpfs|fusectl|hugetlbfs|iso9660|mqueue|nsfs|overlay|proc|procfs|pstore|rpc_pipefs|securityfs|selinuxfs|squashfs|sysfs|tracefs)$

^(autofs|devfs)$

^devfs$

mount_points_exclude defaults to the following regular expression string:

linux

osx

bsd

^/(dev|proc|run/credentials/.+|sys|var/lib/docker/.+)($|/)

^/(dev)($|/)

^/(dev)($|/)

`hwmon`

Name	Type	Description	Default	Required
`chip_include`	`string`	Regular expression of `hwmon` chip to include. Mutually exclusive to `chip-exclude`.		no
`chip_exclude`	`string`	Regular expression of `hwmon` chip to exclude. Mutually exclusive to `chip-include`.		no

`ipvs`

Name	Type	Description	Default	Required
`backend_labels`	`list(string)`	Array of IPVS backend stats labels.	`[local_address, local_port, remote_address, remote_port, proto, local_mark]`	no

`netclass`

Name	Type	Description	Default	Required
`ignore_invalid_speed_device`	`boolean`	Ignore net devices with invalid speed values.	`false`	no
`ignored_devices`	`string`	Regular expression of net devices to ignore for `netclass` collector.	`"^$"`	no

`netdev`

Name	Type	Description	Default	Required
`address_info`	`boolean`	Enable collecting address-info for every device.	`false`	no
`device_exclude`	`string`	Regular expression of net devices to exclude. Mutually exclusive with `device_include`.		no
`device_include`	`string`	Regular expression of net devices to include. Mutually exclusive with `device_exclude`.		no

`netstat`

Name	Type	Description	Default	Required
`fields`	`string`	Regular expression of fields to return for `netstat` collector.	see below	no

fields defaults to the following regular expression string:

"^(.*_(InErrors|InErrs)|Ip_Forwarding|Ip(6|Ext)_(InOctets|OutOctets)|Icmp6?_(InMsgs|OutMsgs)|TcpExt_(Listen.*|Syncookies.*|TCPSynRetrans|TCPTimeouts)|Tcp_(ActiveOpens|InSegs|OutSegs|OutRsts|PassiveOpens|RetransSegs|CurrEstab)|Udp6?_(InDatagrams|OutDatagrams|NoPorts|RcvbufErrors|SndbufErrors))$"

`ntp`

Name	Type	Description	Default	Required
`ip_ttl`	`int`	TTL to use while sending NTP query.	`1`	no
`local_offset_tolerance`	`duration`	Offset between local clock and local NTPD time to tolerate.	`"1ms"`	no
`max_distance`	`duration`	Max accumulated distance to the root.	`"3466080us"`	no
`protocol_version`	`int`	NTP protocol version.	`4`	no
`server_is_local`	`boolean`	Certifies that the server address isn’t a public NTP server.	`false`	no
`server`	`string`	NTP server to use for the collector.	`"127.0.0.1"`	no

`perf`

Name	Type	Description	Default	Required
`cache_profilers`	`list(string)`	`Perf` cache profilers that should be collected.		no
`cpus`	`string`	List of CPUs from which `perf` metrics should be collected.		no
`disable_cache_profilers`	`boolean`	Disable `perf` cache profilers.	`false`	no
`disable_hardware_profilers`	`boolean`	Disable `perf` hardware profilers.	`false`	no
`disable_software_profilers`	`boolean`	Disable `perf` software profilers.	`false`	no
`hardware_profilers`	`list(string)`	`Perf` hardware profilers that should be collected.		no
`software_profilers`	`list(string)`	`Perf` software profilers that should be collected.		no
`tracepoint`	`list(string)`	Array of `perf` tracepoints that should be collected.		no

`powersupply`

Name	Type	Description	Default	Required
`ignored_supplies`	`string`	Regular expression of power supplies to ignore for the `powersupplyclass` collector.	`"^$"`	no

`runit`

Name	Type	Description	Default	Required
`service_dir`	`string`	Path to `runit` service directory.	`"/etc/service"`	no

`supervisord`

Name	Type	Description	Default	Required
`url`	`string`	XML RPC endpoint for the `supervisord` collector.	`"http://localhost:9001/RPC2"`	no

Setting SUPERVISORD_URL in the environment overrides the default value. An explicit value in the block takes precedence over the environment variable.

`sysctl`

Name	Type	Description	Default	Required
`include`	`list(string)`	Numeric `sysctl` values to expose.	`[]`	no
`include_info`	`list(string)`	String `sysctl` values to expose.	`[]`	no

`systemd`

Name	Type	Description	Default	Required
`enable_restarts`	`boolean`	Enables service unit metric `service_restart_total`	`false`	no
`start_time`	`boolean`	Enables service unit metric `unit_start_time_seconds`	`false`	no
`task_metrics`	`boolean`	Enables service unit task metrics `unit_tasks_current` and `unit_tasks_max.`	`false`	no
`unit_exclude`	`string`	Regular expression of systemd units to exclude. Units must both match include and not match exclude to be collected.	`".+\\.(automount\|device\|mount\|scope\|slice)"`	no
`unit_include`	`string`	Regular expression of systemd units to include. Units must both match include and not match exclude to be collected.	`".+"`	no

`tapestats`

Name	Type	Description	Default	Required
`ignored_devices`	`string`	Regular expression of `tapestats` devices to ignore.	`"^$"`	no

`textfile`

Name	Type	Description	Default	Required
`directory`	`string`	Directory to read `*.prom` files from for the `textfile` collector.		no

`vmstat`

Name	Type	Description	Default	Required
`fields`	`string`	Regular expression of fields to return for the `vmstat` collector.	`"^(oom_kill\|pgpg\|pswp\|pg.fault)."`	no

Exported fields

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

Name	Type	Description
`targets`	`list(map(string))`	The targets that can be used to collect exporter metrics.

For example, the targets can either be passed to a discovery.relabel component to rewrite the targets’ label sets or to a prometheus.scrape component that collects the exposed metrics.

The exported targets use the configured in-memory traffic address specified by the run command.

Component health

prometheus.exporter.unix is only reported as unhealthy if given an invalid configuration. In those cases, exported fields retain their last healthy values.

Debug information

prometheus.exporter.unix doesn’t expose any component-specific debug information.

Debug metrics

prometheus.exporter.unix doesn’t expose any component-specific debug metrics.

Collectors list

The following table lists the available collectors that node_exporter brings bundled in. Some collectors only work on specific operating systems. Enabling a collector that’s not supported by the host operating system where Alloy is running is a no-op.

You can choose to enable a subset of collectors to limit the amount of metrics exposed by the prometheus.exporter.unix component, or disable collectors that are expensive to run.

Name	Description	OS	Enabled by default
`arp`	Exposes ARP statistics from `/proc/net/arp` or via netlink.	Linux	yes
`bcache`	Exposes bcache statistics from `/sys/fs/bcache`.	Linux	yes
`bonding`	Exposes the number of configured and active slaves of Linux bonding interfaces.	Linux	yes
`boottime`	Exposes system boot time derived from the `kern.boottime sysctl`.	Darwin, Dragonfly, FreeBSD, NetBSD, OpenBSD, Oracle Solaris	yes
`btrfs`	Exposes statistics on btrfs.	Linux	yes
`buddyinfo`	Exposes statistics of memory fragments as reported by `/proc/buddyinfo`.	Linux	no
`conntrack`	Shows conntrack statistics. Does nothing if no `/proc/sys/net/netfilter/` is present.	Linux	yes
`cpu`	Exposes CPU statistics.	Darwin, Dragonfly, FreeBSD, Linux, Oracle Solaris, NetBSD	yes
`cpufreq`	Exposes CPU frequency statistics.	Linux, Oracle Solaris	yes
`devstat`	Exposes device statistics.	Dragonfly, FreeBSD	no
`diskstats`	Exposes disk I/O statistics.	Darwin, Linux, OpenBSD	yes
`dmi`	Exposes DMI information.	Linux	yes
`drbd`	Exposes Distributed Replicated Block Device statistics (to version 8.4).	Linux	no
`drm`	Exposes GPU card info from `/sys/class/drm/card?/device`.	Linux	no
`edac`	Exposes error detection and correction statistics.	Linux	yes
`entropy`	Exposes available entropy.	Linux	yes
`ethtool`	Exposes ethtool stats.	Linux	no
`exec`	Exposes execution statistics.	Dragonfly, FreeBSD	yes
`fibrechannel`	Exposes FibreChannel statistics.	Linux	yes
`filefd`	Exposes file descriptor statistics from `/proc/sys/fs/file-nr`.	Linux	yes
`filesystem`	Exposes filesystem statistics, such as disk space used.	Darwin, Dragonfly, FreeBSD, Linux, OpenBSD	yes
`hwmon`	Exposes hardware monitoring and sensor data from `/sys/class/hwmon`.	Linux	yes
`infiniband`	Exposes network statistics specific to InfiniBand and Intel OmniPath configurations.	Linux	yes
`interrupts`	Exposes detailed interrupts statistics.	Linux, OpenBSD	no
`ipvs`	Exposes IPVS status from `/proc/net/ip_vs` and stats from `/proc/net/ip_vs_stats`.	Linux	yes
`ksmd`	Exposes kernel and system statistics from `/sys/kernel/mm/ksm`.	Linux	no
`lnstat`	Exposes Linux network cache stats.	Linux	no
`loadavg`	Exposes load average.	Darwin, Dragonfly, FreeBSD, Linux, NetBSD, OpenBSD, Oracle Solaris	yes
`logind`	Exposes session counts from logind.	Linux	no
`mdadm`	Exposes statistics about devices in `/proc/mdstat`. Does nothing if no `/proc/mdstat` is present.	Linux	yes
`meminfo_numa`	Exposes memory statistics from `/proc/meminfo_numa`.	Linux	no
`meminfo`	Exposes memory statistics.	Darwin, Dragonfly, FreeBSD, Linux, OpenBSD, NetBSD	yes
`mountstats`	Exposes filesystem statistics from `/proc/self/mountstats`. Exposes detailed NFS client statistics.	Linux	no
`netclass`	Exposes network interface info from `/sys/class/net`.	Linux	yes
`netdev`	Exposes network interface statistics such as bytes transferred.	Darwin, Dragonfly, FreeBSD, Linux, OpenBSD	yes
`netisr`	Exposes netisr statistics.	FreeBSD	yes
`netstat`	Exposes network statistics from `/proc/net/netstat`. This is the same information as `netstat -s`.	Linux	yes
`network_route`	Exposes network route statistics.	Linux	no
`nfs`	Exposes NFS client statistics from `/proc/net/rpc/nfs`. This is the same information as `nfsstat -c`.	Linux	yes
`nfsd`	Exposes NFS kernel server statistics from `/proc/net/rpc/nfsd`. This is the same information as `nfsstat -s`.	Linux	yes
`ntp`	Exposes local NTP daemon health to check time.	any	no
`nvme`	Exposes NVMe statistics.	Linux	yes
`os`	Exposes os-release information.	Linux	yes
`perf`	Exposes perf based metric. Warning: Metrics are dependent on kernel configuration and settings.	Linux	no
`powersupplyclass`	Collects information on power supplies.	any	yes
`pressure`	Exposes pressure stall statistics from `/proc/pressure/`.	Linux kernel 4.20+ or CONFIG_PSI	yes
`processes`	Exposes aggregate process statistics from /proc.	Linux	no
`qdisc`	Exposes queuing discipline statistics.	Linux	no
`rapl`	Exposes various statistics from `/sys/class/powercap`.	Linux	yes
`runit`	Exposes service status from runit.	any	no
`schedstat`	Exposes task scheduler statistics from `/proc/schedstat`.	Linux	yes
`sockstat`	Exposes various statistics from `/proc/net/sockstat`.	Linux	yes
`softirqs`	Exposes detailed softirq statistics from `/proc/softirqs`.	Linux	no
`softnet`	Exposes statistics from `/proc/net/softnet_stat`.	Linux	yes
`stat`	Exposes various statistics from `/proc/stat`. This includes boot time, forks and interrupts.	Linux	yes
`supervisord`	Exposes service status from supervisord.	any	no
`sysctl`	Expose sysctl values from `/proc/sys`.	Linux	no
`systemd`	Exposes service and system status from systemd.	Linux	no
`tapestats`	Exposes tape device stats.	Linux	yes
`tcpstat`	Exposes TCP connection status information from `/proc/net/tcp` and `/proc/net/tcp6`. Warning: The current version has potential performance issues in high load situations.	Linux	no
`textfile`	Collects metrics from files in a directory matching the filename pattern `*.prom`. The files must use text-based exposition formats.	any	yes
`thermal_zone`	Exposes thermal zone & cooling device statistics from `/sys/class/thermal`.	Linux	yes
`thermal`	Exposes thermal statistics.	Darwin	yes
`time`	Exposes the current system time.	any	yes
`timex`	Exposes selected `adjtimex(2)` system call stats.	Linux	yes
`udp_queues`	Exposes UDP total lengths of the `rx_queue` and `tx_queue` from `/proc/net/udp` and `/proc/net/udp6`.	Linux	yes
`uname`	Exposes system information as provided by the uname system call.	Darwin, FreeBSD, Linux, OpenBSD, NetBSD	yes
`vmstat`	Exposes statistics from `/proc/vmstat`.	Linux	yes
`wifi`	Exposes WiFi device and station statistics.	Linux	no
`xfs`	Exposes XFS runtime statistics.	Linux kernel 4.4+	yes
`zfs`	Exposes ZFS performance statistics.	Linux, Oracle Solaris	yes
`zoneinfo`	Exposes zone stats.	Linux	no

Run on Docker/Kubernetes

When running Alloy in a Docker container, you need to bind mount the filesystem, procfs, and sysfs from the host machine, as well as set the corresponding arguments for the component to work.

You may also need to add capabilities such as SYS_TIME and make sure that Alloy is running with elevated privileges for some of the collectors to work properly.

Example

This example uses a prometheus.scrape component to collect metrics from prometheus.exporter.unix:

prometheus.exporter.unix "demo" { }

// Configure a prometheus.scrape component to collect unix metrics.
prometheus.scrape "demo" {
  targets    = prometheus.exporter.unix.demo.targets
  forward_to = [prometheus.remote_write.demo.receiver]
}

prometheus.remote_write "demo" {
  endpoint {
    url = "<PROMETHEUS_REMOTE_WRITE_URL>"

    basic_auth {
      username = "<USERNAME>"
      password = "<PASSWORD>"
    }
  }
}

Replace the following:

<PROMETHEUS_REMOTE_WRITE_URL>: The URL of the Prometheus remote_write compatible server to send metrics to.
<USERNAME>: The username to use for authentication to the remote_write API.
<PASSWORD>: The password to use for authentication to the remote_write API.

Compatible components

prometheus.exporter.unix has exports that can be consumed by the following components:

Components that consume Targets

Note
Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.

prometheus.exporter.windows

Mon, 13 Apr 2026 07:37:47 +0000

`prometheus.exporter.windows`

The prometheus.exporter.windows component embeds the windows_exporter which exposes a wide variety of hardware and OS metrics for Windows-based systems.

The windows_exporter itself comprises various collectors, which you can enable and disable as needed. For more information on collectors, refer to the collectors-list section.

Note
The blacklist and whitelist configuration arguments are deprecated but remain available for backwards compatibility. Use the include and exclude arguments instead.

Note
We do not recommend using this exporter with clustering enabled.

The default instance label set by this exporter is the hostname of the machine running Alloy. Alloy clustering uses consistent hashing to distribute targets across the instances. This requires the discovered targets to be the same and have the same labels across all cluster instances.

If you do need to use this component in a cluster, use a dedicated prometheus.scrape component that’s used to scrape this exporter and doesn’t have clustering enabled. Alternatively, use discovery.relabel to set the instance label to a value that is the same across all cluster instances.

Usage

prometheus.exporter.windows "<LABEL>" {
}

Arguments

You can use the following arguments with prometheus.exporter.windows:

Name	Type	Description	Default	Required
`enabled_collectors`	`list(string)`	List of collectors to enable.	`["cpu","logical_disk","net","os","service","system"]`	no

enabled_collectors defines a hand-picked list of collectors to enable by default. If you set this argument, the component disables any collectors not in the list. Refer to the Collectors list for the default set.

Caution
To use any of the configuration blocks below, you must add the corresponding collector name to the enabled_collectors list. For example, to use the dns block, you must include "dns" in your enabled_collectors list. A block has no effect unless you enable its collector.

Blocks

You can use the following blocks with prometheus.exporter.windows. Each block only takes effect if you include its corresponding collector in enabled_collectors.

Name	Description	Required
`target`	Configures a blackbox target.	no

Caution
The text_file block is deprecated as of Alloy v1.11.0. Use the textfile block to configure the textfile collector.

Note
The msmq block is deprecated as of Alloy v1.9.0. You can still include this block in your configuration files, but it has no effect.

`dfsr`

Name	Type	Description	Default	Required
`sources_enabled`	`list(string)`	A list of DFSR `Perflib` sources to use.	`["connection","folder","volume"]`	no

`dns`

Name	Type	Description	Default	Required
`enabled_list`	`list(string)`	A list of collectors to use.	`["metrics", "wmi_stats"]`	no

`exchange`

Name	Type	Description	Default	Required
`enabled_list`	`list(string)`	A list of collectors to use.	`["ADAccessProcesses", "TransportQueues", "HttpProxy", "ActiveSync", "AvailabilityService", "OutlookWebAccess", "Autodiscover", "WorkloadManagement", "RpcClientAccess", "MapiHttpEmsmdb"]`	no

`filetime`

Name	Type	Description	Default	Required
`file_patterns`	`list(string)`	A list of glob patterns that match files to monitor.	`[]`	no

`iis`

Name	Type	Description	Default	Required
`app_exclude`	`string`	Regular expression of applications to ignore.	`"^$"`	no
`app_include`	`string`	Regular expression of applications to report on.	`"^.+$"`	no
`site_exclude`	`string`	Regular expression of sites to ignore.	`"^$"`	no
`site_include`	`string`	Regular expression of sites to report on.	`"^.+$"`	no

The component wraps user-supplied app_exclude, app_include, site_exclude, and site_include strings in a regular expression.

`logical_disk`

Name	Type	Description	Default	Required
`enabled_list`	`list(string)`	A list of collectors to use.	`["metrics"]`	no
`exclude`	`string`	Regular expression of volumes to exclude.	`"^$"`	no
`include`	`string`	Regular expression of volumes to include.	`"^.+$"`	no

The collectors specified by enabled_list can include the following:

metrics
bitlocker_status

The component includes volume names that match the regular expression specified by include and don’t match the regular expression specified by exclude.

The component wraps user-supplied exclude and include strings in a regular expression.

`mscluster`

Name	Type	Description	Default	Required
`enabled_list`	`list(string)`	A list of collectors to use.	`["cluster","network","node","resource","resourcegroup"]`	no

The collectors specified by enabled_list can include the following:

cluster
network
node
resource
resourcegroup

For example, you can set enabled_list to ["cluster"].

`mssql`

Name	Type	Description	Default	Required
`enabled_classes`	`list(string)`	A list of MSSQL WMI classes to use.	`["accessmethods", "availreplica", "bufman", "databases", "dbreplica", "genstats", "info", "locks", "memmgr", "sqlerrors", "sqlstats", "transactions", "waitstats"]`	no

`net`

Name	Type	Description	Default	Required
`enabled_list`	`list(string)`	A list of collectors to use.	`["metrics", "nic_info"]`	no
`exclude`	`string`	Regular expression of NICs to exclude.	`"^$"`	no
`include`	`string`	Regular expression of NICs to include.	`"^.+$"`	no

The collectors specified by enabled_list can include the following:

metrics
nic_info

The component includes NIC names that match the regular expression specified by include and don’t match the regular expression specified by exclude.

The component wraps user-supplied exclude and include strings in a regular expression.

`network`

Name	Type	Description	Default	Required
`exclude`	`string`	Regular expression of NICs to exclude.	`"^$"`	no
`include`	`string`	Regular expression of NICs to include.	`"^.+$"`	no

The component includes NIC names that match the regular expression specified by include and don’t match the regular expression specified by exclude.

The component wraps user-supplied exclude and include strings in a regular expression.

`netframework`

Name	Type	Description	Default	Required
`enabled_list`	`list(string)`	A list of collectors to use.	`["clrexceptions","clrinterop","clrjit","clrloading","clrlocksandthreads","clrmemory","clrremoting","clrsecurity"]`	no

The collectors specified by enabled_list can include the following:

clrexceptions
clrinterop
clrjit
clrloading
clrlocksandthreads
clrmemory
clrremoting
clrsecurity

For example, you can set enabled_list to ["clrjit"].

`performancecounter`

Name	Type	Description	Default	Required
`objects`	`string`	YAML string representing the counters to monitor.	`""`	no

The objects field accepts a YAML string that satisfies the schema in the exporter’s documentation for the performancecounter collector. You can construct this directly in Alloy syntax with raw Alloy syntax strings, but the best way to configure this collector is to use a local.file component.

local.file "counters" {
  filename = "/etc/alloy/performance_counters.yaml"
}

prometheus.exporter.windows "default" {
  ...

  performancecounter {
    objects = local.file.counters.content
  }

  ...
}

The performance_counters.yaml file should be a YAML file that represents an array of objects matching the schema in the documentation, like the example below.

# Monitor Memory performance counters
- name: memory
  object: "Memory"
  counters:
    - name: "Cache Faults/sec"
      type: "counter"  # Use 'counter' for cumulative/rate metrics
    - name: "Available Bytes"
      type: "gauge"    # Use 'gauge' for point-in-time values

# Monitor Processor performance counters
- name: processor
  object: "Processor"
  instances: ["_Total"]  # Optional: filter to specific instances
  counters:
    - name: "% Processor Time"
      type: "gauge"
    - name: "Interrupts/sec"
      type: "counter"

`physical_disk`

Name	Type	Description	Default	Required
`exclude`	`string`	Regular expression of physical disk to exclude.	`"^$"`	no
`include`	`string`	Regular expression of physical disk to include.	`"^.+$"`	no

The component wraps user-supplied exclude and include strings in a regular expression.

`printer`

Name	Type	Description	Default	Required
`exclude`	`string`	Regular expression of printer to exclude.	`"^$"`	no
`include`	`string`	Regular expression of printer to include.	`"^.+$"`	no

The component includes printers that match the regular expression specified by include and don’t match the regular expression specified by exclude.

The component wraps user-supplied exclude and include strings in a regular expression.

`process`

Name	Type	Description	Default	Required
`counter_version`	`int`	Version of the process collector to use.	`0`	no
`enable_iis_worker_process`	`bool`	Enable IIS worker process name queries.	`false`	no
`exclude`	`string`	Regular expression of processes to exclude.	`"^$"`	no
`include`	`string`	Regular expression of processes to include.	`"^.+$"`	no

The counter_version may be 0, 1, or 2.

A value of 1 uses the Windows Process performance counters through the registry API.
A value of 2 uses the Windows Process V2 performance counters through the Performance Data Helper (PDH) API. These counters are available starting in Windows 11.
A value of 0 checks if Process V2 counters are available and falls back to Process counters if they aren’t.

The component includes processes that match the regular expression specified by include and don’t match the regular expression specified by exclude.

The component wraps user-supplied exclude and include strings in a regular expression.

The upstream collector warns that enable_iis_worker_process may leak memory. Use with caution.

`scheduled_task`

Name	Type	Description	Default	Required
`exclude`	`string`	Regular expression of tasks to exclude.	`"^$"`	no
`include`	`string`	Regular expression of tasks to include.	`"^.+$"`	no

The component includes tasks that match the regular expression specified by include and don’t match the regular expression specified by exclude.

The component wraps user-supplied exclude and include strings in a regular expression.

`service`

Name	Type	Description	Default	Required
`exclude`	`string`	Regular expression of services to exclude.	`"^$"`	no
`include`	`string`	Regular expression of services to include.	`"^.+$"`	no

The component includes services that match the regular expression specified by include and don’t match the regular expression specified by exclude.

The component wraps user-supplied exclude and include strings in a regular expression.

Note
The use_api, where_clause, and enable_v2_collector attributes are deprecated as of Alloy v1.9.0. You can still include these attributes in your configuration files, but they have no effect.

`smb`

Name	Type	Description	Default	Required
`enabled_list`	`list(string)`	Deprecated (no-op), a list of collectors to use.	`[]`	no

The collectors specified by enabled_list can include the following:

ServerShares

For example, you can set enabled_list to ["ServerShares"].

`smb_client`

Name	Type	Description	Default	Required
`enabled_list`	`list(string)`	Deprecated (no-op), a list of collectors to use.	`[]`	no

The collectors specified by enabled_list can include the following:

ClientShares

For example, you can set enabled_list to ["ClientShares"].

`smtp`

Name	Type	Description	Default	Required
`exclude`	`string`	Regular expression of virtual servers to ignore.	`"^$"`	no
`include`	`string`	Regular expression of virtual servers to include.	`"^.+$"`	no

The component includes server names that match the regular expression specified by include and don’t match the regular expression specified by exclude.

The component wraps user-supplied exclude and include strings in a regular expression.

`tcp`

Name	Type	Description	Default	Required
`enabled_list`	`list(string)`	A list of collectors to use.	`["metrics","connections_state"]`	no

The collectors specified by enabled_list can include the following:

connections_state
metrics

For example, you can set enabled_list to ["metrics"].

`textfile`

Name	Type	Description	Default	Required
`directories`	`list(string)`	The list of directories containing files to ingest.	see below	no
`text_file_directory`	`string`	Deprecated. The directory containing files to ingest.		no

By default, directories contains the textfile_inputs directory in the Alloy installation directory. For example, if you install Alloy in C:\Program Files\GrafanaLabs\Alloy\, the default is ["C:\Program Files\GrafanaLabs\Alloy\textfile_inputs"].

The deprecated text_file_directory attribute accepts a comma-separated string of directories. If you set both text_file_directory and directories, the component combines them into a single list.

For backwards compatibility, you can also use the deprecated text_file block to configure the textfile collector. If you configure both blocks, the component combines the distinct directory values from each.

The component only reads files with the .prom extension inside the specified directories.

Note
The .prom files must end with an empty line feed for the component to recognize and read them.

`text_file` (Deprecated: use `textfile` instead)

Name	Type	Description	Default	Required
`directories`	`list(string)`	The list of directories containing files to ingest.	see below	no
`text_file_directory`	`string`	Deprecated. The directory containing files to ingest.		no

This block is deprecated. Use the textfile block instead.

If you configure both text_file and textfile blocks, the component combines the distinct directory values from each.

The component only reads files with the .prom extension inside the specified directories.

Note
The .prom files must end with an empty line feed for the component to recognize and read them.

`update`

Name	Type	Description	Default	Required
`online`	`bool`	Whether to search for updates online.	`false`	no
`scrape_interval`	`duration`	How frequently to scrape Windows Update information.	`6h`	no

Exported fields

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

Name	Type	Description
`targets`	`list(map(string))`	The targets that can be used to collect exporter metrics.

For example, the targets can either be passed to a discovery.relabel component to rewrite the targets’ label sets or to a prometheus.scrape component that collects the exposed metrics.

The exported targets use the configured in-memory traffic address specified by the run command.

Component health

prometheus.exporter.windows reports as unhealthy only when you provide an invalid configuration. In those cases, exported fields retain their last healthy values.

Debug information

prometheus.exporter.windows doesn’t expose any component-specific debug information.

Debug metrics

prometheus.exporter.windows doesn’t expose any component-specific debug metrics.

Wrap regular expression strings

Some collector blocks such as scheduled_task accept a regular expression as a string argument. prometheus.exporter.windows prefixes some regular expression string arguments with ^(?: and suffixes them with )$. For example, if a user sets an exclude argument to ".*", Alloy sets it to "^(?:.*)$".

To find out if the component wraps a particular regular expression argument, refer to the collector block documentation.

Note
The wrapping may change the behaviour of your regular expression. For example, the e.* regular expression would normally match both the “service” and “email” strings. However, ^(?:e.*)$ would only match “email”.

Collectors list

The following table lists the available collectors in windows_exporter. Some collectors only work on specific operating systems. If you enable a collector that the host OS doesn’t support, it has no effect.

You can enable a subset of collectors to limit the amount of metrics that the prometheus.exporter.windows component exposes, or disable collectors that are expensive to run.

Name	Description	Enabled by default
`ad`	Active Directory Domain Services
`adcs`	Active Directory Certificate Services
`adfs`	Active Directory Federation Services
`cache`	Cache metrics
`cpu`	CPU usage	Yes
`cpu_info`	CPU Information
`container`	Container metrics
`dfsr`	DFSR metrics
`dhcp`	DHCP Server
`dns`	DNS Server
`exchange`	Exchange metrics
`filetime`	File modification time metrics
`fsrmquota`	Microsoft File Server Resource Manager (FSRM) Quotas collector
`gpu`	GPU usage and memory consumption
`hyperv`	Hyper-V hosts
`iis`	IIS sites and applications
`logical_disk`	Logical disks, disk I/O	Yes
`memory`	Memory usage metrics
`mscluster`	MSCluster metrics
`msmq`	MSMQ queues
`mssql`	SQL Server Performance Objects metrics
`netframework`	.NET Framework metrics
`net`	Network interface I/O	Yes
`os`	OS metrics (memory, processes, users)	Yes
`pagefile`	Pagefile metrics
`performancecounter`	Performance Counter metrics
`physical_disk`	Physical disks
`printer`	Printer metrics
`process`	Per-process metrics
`remote_fx`	RemoteFX protocol (RDP) metrics
`scheduled_task`	Scheduled Tasks metrics
`service`	Service state metrics	Yes
`smb`	SMB Server shares
`smb_client`	SMB Client shares
`smtp`	IIS SMTP Server
`system`	System calls	Yes
`tcp`	TCP connections
`time`	Windows Time Service
`thermalzone`	Thermal information
`terminal_services`	Terminal services (RDS)
`textfile`	Read Prometheus metrics from a text file
`udp`	UDP connections
`update`	Windows Update service metrics
`vmware`	Performance counters installed by the VMware Guest agent

Refer to the linked documentation on each collector for more information on reported metrics, configuration settings and usage examples.

Caution
Certain collectors cause Alloy to crash if you use them without the required infrastructure. These include but aren’t limited to mscluster, VMware, nps, dns, msmq, ad, hyperv, and scheduled_task.

The cs and logon collectors are deprecated and removed from the exporter. You can still configure these collectors, but they have no effect.

Example

The following example uses a prometheus.scrape component to collect metrics from prometheus.exporter.windows:

prometheus.exporter.windows "default" { }

// Configure a prometheus.scrape component to collect windows metrics.
prometheus.scrape "example" {
  targets    = prometheus.exporter.windows.default.targets
  forward_to = [prometheus.remote_write.demo.receiver]
}

prometheus.remote_write "demo" {
  endpoint {
    url = "<PROMETHEUS_REMOTE_WRITE_URL>"

    basic_auth {
      username = "<USERNAME>"
      password = "<PASSWORD>"
    }
  }
}

The following example shows you how to enable additional collectors and configure them:

prometheus.exporter.windows "advanced" {
  // Enable additional collectors beyond the default set
  enabled_collectors = [
    "cpu", "logical_disk", "net", "os", "service", "system",  // defaults
    "dns", "iis", "process", "scheduled_task"                 // additional
  ]

  // Configure DNS collector settings
  dns {
    enabled_list = ["metrics", "wmi_stats"]
  }

  // Configure IIS collector settings
  iis {
    site_include = "^(Default Web Site|Production)$"
    app_exclude  = "^$"
  }

  // Configure process collector settings
  process {
    include = "^(chrome|firefox|notepad).*"
    exclude = "^$"
  }
}

prometheus.scrape "advanced_example" {
  targets    = prometheus.exporter.windows.advanced.targets
  forward_to = [prometheus.remote_write.demo.receiver]
}

Replace the following:

<PROMETHEUS_REMOTE_WRITE_URL>: The URL of the Prometheus remote_write compatible server to send metrics to.
<USERNAME>: The username to use for authentication to the remote_write API.
<PASSWORD>: The password to use for authentication to the remote_write API.

Compatible components

prometheus.exporter.windows has exports that can be consumed by the following components:

Components that consume Targets

Note
Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.

prometheus.operator.podmonitors

Mon, 13 Apr 2026 07:37:47 +0000

`prometheus.operator.podmonitors`

prometheus.operator.podmonitors discovers PodMonitor resources in your Kubernetes cluster and scrapes the targets they reference. This component performs three main functions:

Discover PodMonitor resources from your Kubernetes cluster.
Discover Pods in your cluster that match those PodMonitors.
Scrape metrics from those Pods, and forward them to a receiver.

The default configuration assumes Alloy is running inside a Kubernetes cluster, and uses the in-cluster configuration to access the Kubernetes API. You can run it from outside the cluster by supplying connection info in the client block, but network level access to Pods is required to scrape metrics from them.

PodMonitors may reference secrets for authenticating to targets to scrape them. In these cases, the secrets are loaded and refreshed only when the PodMonitor is updated or when this component refreshes its internal state, which happens on a 5-minute refresh cycle.

Usage

prometheus.operator.podmonitors "<LABEL>" {
    forward_to = <RECEIVER_LIST>
}

Arguments

You can use the following arguments with prometheus.operator.podmonitors:

Name	Type	Description	Default	Required
`forward_to`	`list(MetricsReceiver)`	List of receivers to send scraped metrics to.		yes
`namespaces`	`list(string)`	List of namespaces to search for PodMonitor resources. If not specified, all namespaces are searched.		no
`informer_sync_timeout`	`duration`	Timeout for initial sync of PodMonitor resources.	`"1m"`	no

Blocks

You can use the following blocks with prometheus.operator.podmonitors:

Name	Description	Required
`target`	Configures a blackbox target.	no

`client`

The client block configures the Kubernetes client used to discover PodMonitors. If the client block isn’t provided, the default in-cluster configuration with the service account of the running Alloy Pod is used.

The following arguments are supported:

Name	Type	Description	Default	Required
`api_server`	`string`	URL of the Kubernetes API server.		no
`kubeconfig_file`	`string`	Path of the `kubeconfig` file to use for connecting to Kubernetes.		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
`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

At most, one of the following can be provided:

[authorization][authorization] block
[basic_auth][basic_auth] block
[bearer_token_file][client] argument
[bearer_token][client] argument
[oauth2][oauth2] 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`

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)

`clustering`

Name	Type	Description	Default	Required
`enabled`	`bool`	Enables sharing targets with other cluster nodes.	`false`	yes

When Alloy is using clustering, and enabled is set to true, then this component instance opts-in to participating in the cluster to distribute scrape load between all cluster nodes.

Clustering assumes that all cluster nodes are running with the same configuration file, and that all prometheus.operator.podmonitors components that have opted-in to using clustering, over the course of a scrape interval have the same configuration.

All prometheus.operator.podmonitors components instances opting in to clustering use target labels and a consistent hashing algorithm to determine ownership for each of the targets between the cluster peers. Then, each peer only scrapes the subset of targets that it’s responsible for, so that the scrape load is distributed. When a node joins or leaves the cluster, every peer recalculates ownership and continues scraping with the new target set. This performs better than hashmod sharding where all nodes have to be re-distributed, as only 1/N of the target’s ownership is transferred, but is eventually consistent (rather than fully consistent like hashmod sharding is).

If Alloy is not running in clustered mode, then the block is a no-op, and prometheus.operator.podmonitors scrapes every target it receives in its arguments.

`rule`

The rule block configures relabeling rules to apply to discovered scrape targets. The drop and keep actions filter targets, not individual metrics. To filter or relabel metrics after scraping, use a prometheus.relabel component.

The rule block contains the definition of any relabeling rules that can be applied to an input metric. If more than one rule block is defined, the transformations are applied in top-down order.

The following arguments can be used to configure a rule. All arguments are optional. Omitted fields take their default values.

Name	Type	Description	Default	Required
`action`	`string`	The relabeling action to perform.	replace	no
`modulus`	`uint`	A positive integer used to calculate the modulus of the hashed source label values.		no
`regex`	`string`	A valid RE2 expression with support for parenthesized capture groups. Used to match the extracted value from the combination of the `source_label` and `separator` fields or filter labels during the `labelkeep/labeldrop/labelmap` actions.	`(.*)`	no
`replacement`	`string`	The value against which a regular expression replace is performed, if the regular expression matches the extracted value. Supports previously captured groups.	`"$1"`	no
`separator`	`string`	The separator used to concatenate the values present in `source_labels`.	;	no
`source_labels`	`list(string)`	The list of labels whose values are to be selected. Their content is concatenated using the `separator` and matched against `regex`.		no
`target_label`	`string`	Label to which the resulting value will be written to.		no

You can use the following actions:

drop - Drops metrics where regex matches the string extracted using the source_labels and separator.
dropequal - Drop targets for which the concatenated source_labels do match target_label.
hashmod - Hashes the concatenated labels, calculates its modulo modulus and writes the result to the target_label.
keep - Keeps metrics where regex matches the string extracted using the source_labels and separator.
keepequal - Drop targets for which the concatenated source_labels don’t match target_label.
labeldrop - Matches regex against all label names. Any labels that match are removed from the metric’s label set.
labelkeep - Matches regex against all label names. Any labels that don’t match are removed from the metric’s label set.
labelmap - Matches regex against all label names. Any labels that match are renamed according to the contents of the replacement field.
lowercase - Sets target_label to the lowercase form of the concatenated source_labels.
replace - Matches regex to the concatenated labels. If there’s a match, it replaces the content of the target_label using the contents of the replacement field.
uppercase - Sets target_label to the uppercase form of the concatenated source_labels.

Note
The regular expression capture groups can be referred to using either the $CAPTURE_GROUP_NUMBER or ${CAPTURE_GROUP_NUMBER} notation.

`scrape`

Name	Type	Description	Default	Required
`default_sample_limit`	`int`	The default maximum samples per scrape. Used as the default if the target resource doesn’t provide a sample limit.		no
`default_scrape_interval`	`duration`	The default interval between scraping targets. Used as the default if the target resource doesn’t provide a scrape interval.	`1m`	no
`default_scrape_timeout`	`duration`	The default timeout for scrape requests. Used as the default if the target resource doesn’t provide a scrape timeout.	`10s`	no
`enable_type_and_unit_labels`	`bool`	(Experimental) Whether the metric type and unit should be added as labels to scraped metrics.	`false`	no
`honor_metadata`	`bool`	(Experimental) Indicates whether to send metric metadata to downstream components.	`false`	no
`scrape_native_histograms`	`bool`	Whether to scrape native histograms from targets.	`false`	no

EXPERIMENTAL: The honor_metadata and enable_type_and_unit_labels arguments are experimental features.

If you enable the honor_metadata argument, resource consumption may increase, particularly if you ingest many metrics with different names. Some downstream components aren’t compatible with Prometheus metadata. The following components are compatible:

otelcol.receiver.prometheus

prometheus.remote_write only when configured for Remote Write v2.

prometheus.write_queue

When enable_type_and_unit_labels argument is enabled and available from the scrape, the metric type and unit are added as labels to each scraped sample. This provides additional schema information about metrics directly in the label set. This feature doesn’t require downstream components to support Remote Write v2.

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.

`selector`

The selector block describes a Kubernetes label selector for PodMonitors.

The following arguments are supported:

Name	Type	Description	Default	Required
`match_labels`	`map(string)`	Label keys and values used to discover resources.	`{}`	no

When the match_labels argument is empty, all PodMonitor resources are matched.

`match_expression`

The match_expression block describes a Kubernetes label matcher expression for PodMonitors discovery.

The following arguments are supported:

Name	Type	Description	Required
`key`	`string`	The label name to match against.	yes
`operator`	`string`	The operator to use when matching.	yes
`values`	`list(string)`	The values used when matching.	no

The operator argument must be one of the following strings:

"In"
"NotIn"
"Exists"
"DoesNotExist"

If there are multiple match_expressions blocks inside of a selector block, they’re combined together with AND clauses.

Exported fields

prometheus.operator.podmonitors doesn’t export any fields. It forwards all metrics it scrapes to the receiver configured with the forward_to argument.

Component health

prometheus.operator.podmonitors is reported as unhealthy when given an invalid configuration, Prometheus components fail to initialize, or the connection to the Kubernetes API couldn’t be established properly.

Debug information

prometheus.operator.podmonitors reports the status of the last scrape for each configured scrape job on the component’s debug endpoint, including discovered labels, and the last scrape time.

It also exposes some debug information for each PodMonitor it has discovered, including any errors found while reconciling the scrape configuration from the PodMonitor.

Debug metrics

prometheus.operator.podmonitors doesn’t expose any component-specific debug metrics.

Example

The following example discovers all PodMonitors in your cluster, and forwards collected metrics to a prometheus.remote_write component.

prometheus.remote_write "staging" {
  // Send metrics to a locally running Mimir.
  endpoint {
    url = "http://mimir:9009/api/v1/push"

    basic_auth {
      username = "example-user"
      password = "example-password"
    }
  }
}

prometheus.operator.podmonitors "pods" {
    forward_to = [prometheus.remote_write.staging.receiver]
}

The following example limits discovered PodMonitors to ones with the label team=ops in a specific namespace: my-app.

prometheus.operator.podmonitors "pods" {
    forward_to = [prometheus.remote_write.staging.receiver]
    namespaces = ["my-app"]
    selector {
        match_expression {
            key = "team"
            operator = "In"
            values = ["ops"]
        }
    }
}

The following example applies additional relabel rules to discovered targets to filter by hostname. This may be useful if running Alloy as a DaemonSet.

prometheus.operator.podmonitors "pods" {
    forward_to = [prometheus.remote_write.staging.receiver]
    rule {
      action = "keep"
      regex = sys.env("<HOSTNAME>")
      source_labels = ["__meta_kubernetes_pod_node_name"]
    }
}

Compatible components

prometheus.operator.podmonitors can accept arguments from the following components:

Components that export Prometheus MetricsReceiver

Note
Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.

prometheus.operator.probes

Mon, 13 Apr 2026 07:37:47 +0000

`prometheus.operator.probes`

prometheus.operator.probes discovers Probe resources in your Kubernetes cluster and scrapes the targets they reference. This component performs three main functions:

Discover Probe resources from your Kubernetes cluster.
Discover targets or ingresses that match those Probes.
Scrape metrics from those endpoints, and forward them to a receiver.

Probes may reference secrets for authenticating to targets to scrape them. In these cases, the secrets are loaded and refreshed only when the Probe is updated or when this component refreshes its’ internal state, which happens on a 5-minute refresh cycle.

Usage

prometheus.operator.probes "<LABEL>" {
    forward_to = <RECEIVER_LIST>
}

Arguments

You can use the following arguments with prometheus.operator.probes:

Name	Type	Description	Default	Required
`forward_to`	`list(MetricsReceiver)`	List of receivers to send scraped metrics to.		yes
`informer_sync_timeout`	`duration`	Timeout for initial sync of Probe resources.	`"1m"`	no
`namespaces`	`list(string)`	List of namespaces to search for Probe resources. If not specified, all namespaces are searched.		no

Blocks

You can use the following blocks with prometheus.operator.probes:

Name	Description	Required
`target`	Configures a blackbox target.	no

`client`

The client block configures the Kubernetes client used to discover Probes. If the client block isn’t provided, the default in-cluster configuration with the service account of the running Alloy Pod is used.

The following arguments are supported:

Name	Type	Description	Default	Required
`api_server`	`string`	URL of the Kubernetes API server.		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
`kubeconfig_file`	`string`	Path of the `kubeconfig` file to use for connecting to Kubernetes.		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

At most, one of the following can be provided:

[authorization][authorization] block
[basic_auth][basic_auth] block
[bearer_token_file][client] argument
[bearer_token][client] argument
[oauth2][oauth2] 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.

`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)

`clustering`

Name	Type	Description	Default	Required
`enabled`	`bool`	Enables sharing targets with other cluster nodes.	`false`	yes

When Alloy is running in clustered mode, and enabled is set to true, then this component instance opts-in to participating in the cluster to distribute scrape load between all cluster nodes.

Clustering assumes that all cluster nodes are running with the same configuration file, and that all prometheus.operator.probes components that have opted-in to using clustering, over the course of a scrape interval have the same configuration.

All prometheus.operator.probes components instances opting in to clustering use target labels and a consistent hashing algorithm to determine ownership for each of the targets between the cluster peers. Then, each peer only scrapes the subset of targets that it’s responsible for, so that the scrape load is distributed. When a node joins or leaves the cluster, every peer recalculates ownership and continues scraping with the new target set. This performs better than hashmod sharding where all nodes have to be re-distributed, as only 1/N of the target’s ownership is transferred, but is eventually consistent (rather than fully consistent like hashmod sharding is).

If Alloy is not running in clustered mode, then the block is a no-op, and prometheus.operator.probes scrapes every target it receives in its arguments.

`rule`

The rule block contains the definition of any relabeling rules that can be applied to an input metric. If more than one rule block is defined, the transformations are applied in top-down order.

The following arguments can be used to configure a rule. All arguments are optional. Omitted fields take their default values.

Name	Type	Description	Default	Required
`action`	`string`	The relabeling action to perform.	replace	no
`modulus`	`uint`	A positive integer used to calculate the modulus of the hashed source label values.		no
`regex`	`string`	A valid RE2 expression with support for parenthesized capture groups. Used to match the extracted value from the combination of the `source_label` and `separator` fields or filter labels during the `labelkeep/labeldrop/labelmap` actions.	`(.*)`	no
`replacement`	`string`	The value against which a regular expression replace is performed, if the regular expression matches the extracted value. Supports previously captured groups.	`"$1"`	no
`separator`	`string`	The separator used to concatenate the values present in `source_labels`.	;	no
`source_labels`	`list(string)`	The list of labels whose values are to be selected. Their content is concatenated using the `separator` and matched against `regex`.		no
`target_label`	`string`	Label to which the resulting value will be written to.		no

You can use the following actions:

drop - Drops metrics where regex matches the string extracted using the source_labels and separator.
dropequal - Drop targets for which the concatenated source_labels do match target_label.
hashmod - Hashes the concatenated labels, calculates its modulo modulus and writes the result to the target_label.
keep - Keeps metrics where regex matches the string extracted using the source_labels and separator.
keepequal - Drop targets for which the concatenated source_labels don’t match target_label.
labeldrop - Matches regex against all label names. Any labels that match are removed from the metric’s label set.
labelkeep - Matches regex against all label names. Any labels that don’t match are removed from the metric’s label set.
labelmap - Matches regex against all label names. Any labels that match are renamed according to the contents of the replacement field.
lowercase - Sets target_label to the lowercase form of the concatenated source_labels.
replace - Matches regex to the concatenated labels. If there’s a match, it replaces the content of the target_label using the contents of the replacement field.
uppercase - Sets target_label to the uppercase form of the concatenated source_labels.

Note
The regular expression capture groups can be referred to using either the $CAPTURE_GROUP_NUMBER or ${CAPTURE_GROUP_NUMBER} notation.

`scrape`

Name	Type	Description	Default	Required
`default_sample_limit`	`int`	The default maximum samples per scrape. Used as the default if the target resource doesn’t provide a sample limit.		no
`default_scrape_interval`	`duration`	The default interval between scraping targets. Used as the default if the target resource doesn’t provide a scrape interval.	`1m`	no
`default_scrape_timeout`	`duration`	The default timeout for scrape requests. Used as the default if the target resource doesn’t provide a scrape timeout.	`10s`	no
`enable_type_and_unit_labels`	`bool`	(Experimental) Whether the metric type and unit should be added as labels to scraped metrics.	`false`	no
`honor_metadata`	`bool`	(Experimental) Indicates whether to send metric metadata to downstream components.	`false`	no
`scrape_native_histograms`	`bool`	Whether to scrape native histograms from targets.	`false`	no

EXPERIMENTAL: The honor_metadata and enable_type_and_unit_labels arguments are experimental features.

If you enable the honor_metadata argument, resource consumption may increase, particularly if you ingest many metrics with different names. Some downstream components aren’t compatible with Prometheus metadata. The following components are compatible:

otelcol.receiver.prometheus

prometheus.remote_write only when configured for Remote Write v2.

prometheus.write_queue

When enable_type_and_unit_labels argument is enabled and available from the scrape, the metric type and unit are added as labels to each scraped sample. This provides additional schema information about metrics directly in the label set. This feature doesn’t require downstream components to support Remote Write v2.

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.

`selector`

The selector block describes a Kubernetes label selector for Probes.

The following arguments are supported:

Name	Type	Description	Default	Required
`match_labels`	`map(string)`	Label keys and values used to discover resources.	`{}`	no

When the match_labels argument is empty, all Probe resources are matched.

`match_expression`

The match_expression block describes a Kubernetes label matcher expression for Probes discovery.

The following arguments are supported:

Name	Type	Description	Required
`key`	`string`	The label name to match against.	yes
`operator`	`string`	The operator to use when matching.	yes
`values`	`list(string)`	The values used when matching.	no

The operator argument must be one of the following strings:

"In"
"NotIn"
"Exists"
"DoesNotExist"

If there are multiple match_expressions blocks inside of a selector block, they’re combined together with AND clauses.

Exported fields

prometheus.operator.probes doesn’t export any fields. It forwards all metrics it scrapes to the receivers configured with the forward_to argument.

Component health

prometheus.operator.probes is reported as unhealthy when given an invalid configuration, Prometheus components fail to initialize, or the connection to the Kubernetes API couldn’t be established properly.

Debug information

prometheus.operator.probes reports the status of the last scrape for each configured scrape job on the component’s debug endpoint, including discovered labels, and the last scrape time.

It also exposes some debug information for each Probe it has discovered, including any errors found while reconciling the scrape configuration from the Probe.

Debug metrics

prometheus.operator.probes doesn’t expose any component-specific debug metrics.

Example

The following example discovers all Probes in your cluster, and forwards collected metrics to a prometheus.remote_write component.

prometheus.remote_write "staging" {
  // Send metrics to a locally running Mimir.
  endpoint {
    url = "http://mimir:9009/api/v1/push"

    basic_auth {
      username = "example-user"
      password = "example-password"
    }
  }
}

prometheus.operator.probes "pods" {
    forward_to = [prometheus.remote_write.staging.receiver]
}

The following example limits discovered Probes to ones with the label team=ops in a specific namespace: my-app.

prometheus.operator.probes "pods" {
    forward_to = [prometheus.remote_write.staging.receiver]
    namespaces = ["my-app"]
    selector {
        match_expression {
            key = "team"
            operator = "In"
            values = ["ops"]
        }
    }
}

The following example applies additional relabel rules to discovered targets to filter by hostname. This may be useful if running Alloy as a DaemonSet.

prometheus.operator.probes "probes" {
    forward_to = [prometheus.remote_write.staging.receiver]
    rule {
      action = "keep"
      regex = sys.env("HOSTNAME")
      source_labels = ["__meta_kubernetes_pod_node_name"]
    }
}

Compatible components

prometheus.operator.probes can accept arguments from the following components:

Components that export Prometheus MetricsReceiver

Note
Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.

prometheus.operator.scrapeconfigs

Mon, 13 Apr 2026 07:37:47 +0000

`prometheus.operator.scrapeconfigs`

EXPERIMENTAL: This is an experimental component. Experimental components are subject to frequent breaking changes, and may be removed with no equivalent replacement. To enable and use an experimental component, you must set the stability.level flag to experimental.

prometheus.operator.scrapeconfigs discovers ScrapeConfig resources in your Kubernetes cluster and scrapes the targets they reference. This component performs two main functions:

Discover ScrapeConfig resources from your Kubernetes cluster.
Scrape metrics from the targets, and forward them to a receiver.

The default configuration assumes Alloy is running inside a Kubernetes cluster, and uses the in-cluster configuration to access the Kubernetes API. You can run Alloy from outside the cluster by supplying connection info in the client block, but network level access to scrapeconfigs is required to scrape metrics from them.

scrapeconfigs may reference secrets for authenticating to targets to scrape them. In these cases, the secrets are loaded and refreshed only when the ScrapeConfig is updated or when this component refreshes its internal state, which happens on a 5-minute refresh cycle.

Service Discovery Methods

ScrapeConfig resources support multiple service discovery mechanisms:

Static Configuration

Static configurations define a fixed list of targets to scrape. This is useful when targets are known in advance and don’t change frequently.

HTTP Service Discovery

HTTP service discovery allows dynamic target discovery by querying an HTTP endpoint that returns target information in JSON format. The endpoint is polled at regular intervals to discover new targets or remove stale ones. This is particularly useful for:

Dynamic environments where targets are frequently added or removed
Integration with external service registries
Custom service discovery implementations

The HTTP endpoint returns a JSON array of target groups, where each target group contains:

targets: Array of host:port combinations to scrape
labels: Optional labels to apply to all targets in the group

Example JSON response:

[
  {
    "targets": ["service1.example.com:8080", "service2.example.com:8080"],
    "labels": {
      "job": "web-servers",
      "env": "production"
    }
  },
  {
    "targets": ["db1.example.com:9090"],
    "labels": {
      "job": "databases",
      "env": "production"
    }
  }
]

Usage

prometheus.operator.scrapeconfigs "<LABEL>" {
    forward_to = <RECEIVER_LIST>
}

Arguments

You can use the following arguments with prometheus.operator.scrapeconfigs:

Name	Type	Description	Default	Required
`forward_to`	`list(MetricsReceiver)`	List of receivers to send scraped metrics to.		yes
`informer_sync_timeout`	`duration`	Timeout for initial sync of ScrapeConfig resources.	`"1m"`	no
`namespaces`	`list(string)`	List of namespaces to search for ScrapeConfig resources. If not specified, all namespaces are searched.		no

Blocks

You can use the following blocks with prometheus.operator.scrapeconfigs:

Name	Description	Required
`target`	Configures a blackbox target.	no

`client`

The client block configures the Kubernetes client used to discover scrapeconfigs. If the client block isn’t provided, the default in-cluster configuration with the service account of the running Alloy Pod is used.

The following arguments are supported:

Name	Type	Description	Default	Required
`api_server`	`string`	URL of the Kubernetes API server.		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
`kubeconfig_file`	`string`	Path of the `kubeconfig` file to use for connecting to Kubernetes.		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

At most, one of the following can be provided:

[authorization][authorization] block
[basic_auth][basic_auth] block
[bearer_token][client] argument
[bearer_token_file][client] argument
[oauth2][oauth2] 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.

`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)

`clustering`

Name	Type	Description	Default	Required
`enabled`	`bool`	Enables sharing targets with other cluster nodes.	`false`	yes

When Alloy is using clustering, and enabled is set to true, then this component instance opts-in to participating in the cluster to distribute scrape load between all cluster nodes.

Clustering assumes that all cluster nodes are running with the same configuration file, and that all prometheus.operator.scrapeconfigs components that have opted-in to using clustering, over the course of a scrape interval have the same configuration.

All prometheus.operator.scrapeconfigs components instances opting in to clustering use target labels and a consistent hashing algorithm to determine ownership for each of the targets between the cluster peers. Then, each peer only scrapes the subset of targets that it is responsible for, so that the scrape load is distributed. When a node joins or leaves the cluster, every peer recalculates ownership and continues scraping with the new target set. This performs better than hashmod sharding where all nodes have to be re-distributed, as only 1/N of the target’s ownership is transferred, but is eventually consistent (rather than fully consistent like hashmod sharding is).

If Alloy is not running in clustered mode, then the block is a no-op, and prometheus.operator.scrapeconfigs scrapes every target it receives in its arguments.

`rule`

The rule block contains the definition of any relabeling rules that can be applied to an input metric. If more than one rule block is defined, the transformations are applied in top-down order.

The following arguments can be used to configure a rule. All arguments are optional. Omitted fields take their default values.

Name	Type	Description	Default	Required
`action`	`string`	The relabeling action to perform.	replace	no
`modulus`	`uint`	A positive integer used to calculate the modulus of the hashed source label values.		no
`regex`	`string`	A valid RE2 expression with support for parenthesized capture groups. Used to match the extracted value from the combination of the `source_label` and `separator` fields or filter labels during the `labelkeep/labeldrop/labelmap` actions.	`(.*)`	no
`replacement`	`string`	The value against which a regular expression replace is performed, if the regular expression matches the extracted value. Supports previously captured groups.	`"$1"`	no
`separator`	`string`	The separator used to concatenate the values present in `source_labels`.	;	no
`source_labels`	`list(string)`	The list of labels whose values are to be selected. Their content is concatenated using the `separator` and matched against `regex`.		no
`target_label`	`string`	Label to which the resulting value will be written to.		no

You can use the following actions:

drop - Drops metrics where regex matches the string extracted using the source_labels and separator.
dropequal - Drop targets for which the concatenated source_labels do match target_label.
hashmod - Hashes the concatenated labels, calculates its modulo modulus and writes the result to the target_label.
keep - Keeps metrics where regex matches the string extracted using the source_labels and separator.
keepequal - Drop targets for which the concatenated source_labels don’t match target_label.
labeldrop - Matches regex against all label names. Any labels that match are removed from the metric’s label set.
labelkeep - Matches regex against all label names. Any labels that don’t match are removed from the metric’s label set.
labelmap - Matches regex against all label names. Any labels that match are renamed according to the contents of the replacement field.
lowercase - Sets target_label to the lowercase form of the concatenated source_labels.
replace - Matches regex to the concatenated labels. If there’s a match, it replaces the content of the target_label using the contents of the replacement field.
uppercase - Sets target_label to the uppercase form of the concatenated source_labels.

Note
The regular expression capture groups can be referred to using either the $CAPTURE_GROUP_NUMBER or ${CAPTURE_GROUP_NUMBER} notation.

`scrape`

Name	Type	Description	Default	Required
`default_sample_limit`	`int`	The default maximum samples per scrape. Used as the default if the target resource doesn’t provide a sample limit.		no
`default_scrape_interval`	`duration`	The default interval between scraping targets. Used as the default if the target resource doesn’t provide a scrape interval.	`1m`	no
`default_scrape_timeout`	`duration`	The default timeout for scrape requests. Used as the default if the target resource doesn’t provide a scrape timeout.	`10s`	no
`enable_type_and_unit_labels`	`bool`	(Experimental) Whether the metric type and unit should be added as labels to scraped metrics.	`false`	no
`honor_metadata`	`bool`	(Experimental) Indicates whether to send metric metadata to downstream components.	`false`	no
`scrape_native_histograms`	`bool`	Whether to scrape native histograms from targets.	`false`	no

EXPERIMENTAL: The honor_metadata and enable_type_and_unit_labels arguments are experimental features.

If you enable the honor_metadata argument, resource consumption may increase, particularly if you ingest many metrics with different names. Some downstream components aren’t compatible with Prometheus metadata. The following components are compatible:

otelcol.receiver.prometheus

prometheus.remote_write only when configured for Remote Write v2.

prometheus.write_queue

When enable_type_and_unit_labels argument is enabled and available from the scrape, the metric type and unit are added as labels to each scraped sample. This provides additional schema information about metrics directly in the label set. This feature doesn’t require downstream components to support Remote Write v2.

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.

`selector`

The selector block describes a Kubernetes label selector for scrapeconfigs.

The following arguments are supported:

Name	Type	Description	Default	Required
`match_labels`	`map(string)`	Label keys and values used to discover resources.	`{}`	no

When the match_labels argument is empty, all ScrapeConfig resources will be matched.

`match_expression`

The match_expression block describes a Kubernetes label matcher expression for scrapeconfigs discovery.

The following arguments are supported:

Name	Type	Description	Required
`key`	`string`	The label name to match against.	yes
`operator`	`string`	The operator to use when matching.	yes
`values`	`list(string)`	The values used when matching.	no

The operator argument must be one of the following strings:

"In"
"NotIn"
"Exists"
"DoesNotExist"

If there are multiple match_expressions blocks inside of a selector block, they are combined together with AND clauses.

Exported fields

prometheus.operator.scrapeconfigs doesn’t export any fields. It forwards all metrics it scrapes to the receiver configures with the forward_to argument.

Component health

prometheus.operator.scrapeconfigs is reported as unhealthy when given an invalid configuration, Prometheus components fail to initialize, or the connection to the Kubernetes API could not be established properly.

Debug information

prometheus.operator.scrapeconfigs reports the status of the last scrape for each configured scrape job on the component’s debug endpoint, including discovered labels, and the last scrape time.

It also exposes some debug information for each ScrapeConfig it has discovered, including any errors found while reconciling the scrape configuration from the ScrapeConfig.

Debug metrics

prometheus.operator.scrapeconfigs doesn’t expose any component-specific debug metrics.

Example

This example discovers all scrapeconfigs in your cluster, and forwards collected metrics to a prometheus.remote_write component.

prometheus.remote_write "staging" {
  // Send metrics to a locally running Mimir.
  endpoint {
    url = "http://mimir:9009/api/v1/push"

    basic_auth {
      username = "example-user"
      password = "example-password"
    }
  }
}

prometheus.operator.scrapeconfigs "scrapeconfigs" {
    forward_to = [prometheus.remote_write.staging.receiver]
}

This example limits the discovered scrapeconfigs to ones with the label team=ops in a specific namespace: my-app.

prometheus.operator.scrapeconfigs "scrapeconfigs" {
    forward_to = [prometheus.remote_write.staging.receiver]
    namespaces = ["my-app"]
    selector {
        match_expression {
            key = "team"
            operator = "In"
            values = ["ops"]
        }
    }
}

Static Configuration Example

This example shows a ScrapeConfig resource using static target discovery:

apiVersion: monitoring.coreos.com/v1alpha1
kind: ScrapeConfig
metadata:
  name: static-targets
  namespace: monitoring
spec:
  staticConfigs:
  - targets:
    - "web-server-1.example.com:8080"
    - "web-server-2.example.com:8080"
    labels:
      job: "web-servers"
      env: "production"
  metricsPath: /metrics
  scrapeInterval: 30s

HTTP Service Discovery Example

This example shows a ScrapeConfig resource using HTTP service discovery:

apiVersion: monitoring.coreos.com/v1alpha1
kind: ScrapeConfig
metadata:
  name: http-discovery
  namespace: monitoring
spec:
  httpSDConfigs:
  - url: "http://service-registry.internal:8080/discover"
    refreshInterval: 60s
  metricsPath: /metrics
  scrapeInterval: 30s
  scrapeTimeout: 10s

The HTTP endpoint (http://service-registry.internal:8080/discover) returns JSON in this format:

[
  {
    "targets": [
      "api-server-1.example.com:8080",
      "api-server-2.example.com:8080"
    ],
    "labels": {
      "service": "api",
      "version": "v1.2.3"
    }
  },
  {
    "targets": [
      "worker-1.example.com:9090",
      "worker-2.example.com:9090"
    ],
    "labels": {
      "service": "worker",
      "version": "v2.1.0"
    }
  }
]

Extra Metric Labels

prometheus.operator.scrapeconfigs adds the following extra labels to all metrics scraped for ScrapeConfig objects.

Label	Description
`__meta_kubernetes_scrapeconfig_namespace`	Namespace of the ScrapeConfig object
`__meta_kubernetes_scrapeconfig_name`	Name of the ScrapeConfig object

Compatible components

prometheus.operator.scrapeconfigs can accept arguments from the following components:

Components that export Prometheus MetricsReceiver

Note
Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.

prometheus.operator.servicemonitors

Mon, 13 Apr 2026 07:37:47 +0000

`prometheus.operator.servicemonitors`

prometheus.operator.servicemonitors discovers ServiceMonitor resources in your Kubernetes cluster and scrapes the targets they reference. This component performs three main functions:

Discover ServiceMonitor resources from your Kubernetes cluster.
Discover Services and Endpoints in your cluster that match those ServiceMonitors.
Scrape metrics from those Endpoints, and forward them to a receiver.

ServiceMonitors may reference secrets for authenticating to targets to scrape them. In these cases, the secrets are loaded and refreshed only when the ServiceMonitor is updated or when this component refreshes its’ internal state, which happens on a 5-minute refresh cycle.

Usage

prometheus.operator.servicemonitors "<LABEL>" {
    forward_to = <RECEIVER_LIST>
}

Arguments

You can use the following arguments with prometheus.operator.servicemonitors:

Name	Type	Description	Default	Required
`forward_to`	`list(MetricsReceiver)`	List of receivers to send scraped metrics to.		yes
`informer_sync_timeout`	`duration`	Timeout for initial sync of ServiceMonitor resources.	`"1m"`	no
`kubernetes_role`	`string`	The Kubernetes role used for discovery. Supports `endpoints` or `endpointslice`.	`"endpoints"`	no
`namespaces`	`list(string)`	List of namespaces to search for ServiceMonitor resources. If not specified, all namespaces are searched.		no

Blocks

You can use the following blocks with prometheus.operator.servicemonitors:

Name	Description	Required
`target`	Configures a blackbox target.	no

`client`

The client block configures the Kubernetes client used to discover ServiceMonitors. If the client block isn’t provided, the default in-cluster configuration with the service account of the running Alloy Pod is used.

The following arguments are supported:

Name	Type	Description	Default	Required
`api_server`	`string`	URL of the Kubernetes API server.		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
`kubeconfig_file`	`string`	Path of the `kubeconfig` file to use for connecting to Kubernetes.		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

At most, one of the following can be provided:

[authorization][authorization] block
[basic_auth][basic_auth] block
[bearer_token_file][client] argument
[bearer_token][client] argument
[oauth2][oauth2] 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.

`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)

`clustering`

Name	Type	Description	Default	Required
`enabled`	`bool`	Enables sharing targets with other cluster nodes.	`false`	yes

When Alloy is using clustering, and enabled is set to true, then this component instance opts-in to participating in the cluster to distribute scrape load between all cluster nodes.

Clustering assumes that all cluster nodes are running with the same configuration file, and that all prometheus.operator.servicemonitors components that have opted-in to using clustering, over the course of a scrape interval have the same configuration.

All prometheus.operator.servicemonitors components instances opting in to clustering use target labels and a consistent hashing algorithm to determine ownership for each of the targets between the cluster peers. Then, each peer only scrapes the subset of targets that it’s responsible for, so that the scrape load is distributed. When a node joins or leaves the cluster, every peer recalculates ownership and continues scraping with the new target set. This performs better than hashmod sharding where all nodes have to be re-distributed, as only 1/N of the target’s ownership is transferred, but is eventually consistent (rather than fully consistent like hashmod sharding is).

If Alloy is not running in clustered mode, then the block is a no-op, and prometheus.operator.servicemonitors scrapes every target it receives in its arguments.

`rule`

The rule block contains the definition of any relabeling rules that can be applied to an input metric. If more than one rule block is defined, the transformations are applied in top-down order.

The following arguments can be used to configure a rule. All arguments are optional. Omitted fields take their default values.

Name	Type	Description	Default	Required
`action`	`string`	The relabeling action to perform.	replace	no
`modulus`	`uint`	A positive integer used to calculate the modulus of the hashed source label values.		no
`regex`	`string`	A valid RE2 expression with support for parenthesized capture groups. Used to match the extracted value from the combination of the `source_label` and `separator` fields or filter labels during the `labelkeep/labeldrop/labelmap` actions.	`(.*)`	no
`replacement`	`string`	The value against which a regular expression replace is performed, if the regular expression matches the extracted value. Supports previously captured groups.	`"$1"`	no
`separator`	`string`	The separator used to concatenate the values present in `source_labels`.	;	no
`source_labels`	`list(string)`	The list of labels whose values are to be selected. Their content is concatenated using the `separator` and matched against `regex`.		no
`target_label`	`string`	Label to which the resulting value will be written to.		no

You can use the following actions:

drop - Drops metrics where regex matches the string extracted using the source_labels and separator.
dropequal - Drop targets for which the concatenated source_labels do match target_label.
hashmod - Hashes the concatenated labels, calculates its modulo modulus and writes the result to the target_label.
keep - Keeps metrics where regex matches the string extracted using the source_labels and separator.
keepequal - Drop targets for which the concatenated source_labels don’t match target_label.
labeldrop - Matches regex against all label names. Any labels that match are removed from the metric’s label set.
labelkeep - Matches regex against all label names. Any labels that don’t match are removed from the metric’s label set.
labelmap - Matches regex against all label names. Any labels that match are renamed according to the contents of the replacement field.
lowercase - Sets target_label to the lowercase form of the concatenated source_labels.
replace - Matches regex to the concatenated labels. If there’s a match, it replaces the content of the target_label using the contents of the replacement field.
uppercase - Sets target_label to the uppercase form of the concatenated source_labels.

Note
The regular expression capture groups can be referred to using either the $CAPTURE_GROUP_NUMBER or ${CAPTURE_GROUP_NUMBER} notation.

`scrape`

Name	Type	Description	Default	Required
`default_sample_limit`	`int`	The default maximum samples per scrape. Used as the default if the target resource doesn’t provide a sample limit.		no
`default_scrape_interval`	`duration`	The default interval between scraping targets. Used as the default if the target resource doesn’t provide a scrape interval.	`1m`	no
`default_scrape_timeout`	`duration`	The default timeout for scrape requests. Used as the default if the target resource doesn’t provide a scrape timeout.	`10s`	no
`enable_type_and_unit_labels`	`bool`	(Experimental) Whether the metric type and unit should be added as labels to scraped metrics.	`false`	no
`honor_metadata`	`bool`	(Experimental) Indicates whether to send metric metadata to downstream components.	`false`	no
`scrape_native_histograms`	`bool`	Whether to scrape native histograms from targets.	`false`	no

EXPERIMENTAL: The honor_metadata and enable_type_and_unit_labels arguments are experimental features.

If you enable the honor_metadata argument, resource consumption may increase, particularly if you ingest many metrics with different names. Some downstream components aren’t compatible with Prometheus metadata. The following components are compatible:

otelcol.receiver.prometheus

prometheus.remote_write only when configured for Remote Write v2.

prometheus.write_queue

When enable_type_and_unit_labels argument is enabled and available from the scrape, the metric type and unit are added as labels to each scraped sample. This provides additional schema information about metrics directly in the label set. This feature doesn’t require downstream components to support Remote Write v2.

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.

`selector`

The selector block describes a Kubernetes label selector for ServiceMonitors.

The following arguments are supported:

Name	Type	Description	Default	Required
`match_labels`	`map(string)`	Label keys and values used to discover resources.	`{}`	no

When the match_labels argument is empty, all ServiceMonitor resources are matched.

`match_expression`

The match_expression block describes a Kubernetes label matcher expression for ServiceMonitors discovery.

The following arguments are supported:

Name	Type	Description	Required
`key`	`string`	The label name to match against.	yes
`operator`	`string`	The operator to use when matching.	yes
`values`	`list(string)`	The values used when matching.	no

The operator argument must be one of the following strings:

"In"
"NotIn"
"Exists"
"DoesNotExist"

If there are multiple match_expressions blocks inside of a selector block, they’re combined together with AND clauses.

Exported fields

prometheus.operator.servicemonitors doesn’t export any fields. It forwards all metrics it scrapes to the receiver configures with the forward_to argument.

Component health

prometheus.operator.servicemonitors is reported as unhealthy when given an invalid configuration, Prometheus components fail to initialize, or the connection to the Kubernetes API couldn’t be established properly.

Debug information

prometheus.operator.servicemonitors reports the status of the last scrape for each configured scrape job on the component’s debug endpoint, including discovered labels, and the last scrape time.

It also exposes some debug information for each ServiceMonitor it has discovered, including any errors found while reconciling the scrape configuration from the ServiceMonitor.

Debug metrics

prometheus.operator.servicemonitors doesn’t expose any component-specific debug metrics.

Example

The following example discovers all ServiceMonitors in your cluster, and forwards collected metrics to a prometheus.remote_write component.

prometheus.remote_write "staging" {
  // Send metrics to a locally running Mimir.
  endpoint {
    url = "http://mimir:9009/api/v1/push"

    basic_auth {
      username = "example-user"
      password = "example-password"
    }
  }
}

prometheus.operator.servicemonitors "services" {
    forward_to = [prometheus.remote_write.staging.receiver]
}

The following example limits discovered ServiceMonitors to ones with the label team=ops in a specific namespace: my-app.

prometheus.operator.servicemonitors "services" {
    forward_to = [prometheus.remote_write.staging.receiver]
    namespaces = ["my-app"]
    selector {
        match_expression {
            key = "team"
            operator = "In"
            values = ["ops"]
        }
    }
}

The following example applies additional relabel rules to discovered targets to filter by hostname. This may be useful if running Alloy as a DaemonSet.

prometheus.operator.servicemonitors "services" {
    forward_to = [prometheus.remote_write.staging.receiver]
    rule {
      action = "keep"
      regex = sys.env("HOSTNAME")
      source_labels = ["__meta_kubernetes_pod_node_name"]
    }
}

Compatible components

prometheus.operator.servicemonitors can accept arguments from the following components:

Components that export Prometheus MetricsReceiver

Note
Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.

prometheus.receive_http

Mon, 13 Apr 2026 07:37:47 +0000

`prometheus.receive_http`

prometheus.receive_http listens for HTTP requests containing Prometheus metric samples and forwards them to other components capable of receiving metrics.

The HTTP API exposed is compatible with Prometheus remote_write API. This means that other prometheus.remote_write components can be used as a client and send requests to prometheus.receive_http which enables using Alloy as a proxy for Prometheus metrics.

Usage

prometheus.receive_http "<LABEL>" {
  http {
    listen_address = "<LISTEN_ADDRESS>"
    listen_port = <PORT>
  }
  forward_to = <RECEIVER_LIST>
}

The component starts an HTTP server supporting the following endpoint:

POST /api/v1/metrics/write: Sends metrics to the component, which in turn is forwarded to the receivers as configured in forward_to argument. The request format must be compatible with the Prometheus remote_write API and can use either the v1 or v2 format. One way to send valid requests to this component is to use another Alloy with a prometheus.remote_write component.

Arguments

You can use the following arguments with prometheus.receive_http:

Name	Type	Description	Default	Required
`forward_to`	`list(MetricsReceiver)`	List of receivers to send metrics to.		yes
`accepted_remote_write_protobuf_messages`	`list(string)`	Accepted remote write protobuf message types.	`["prometheus.WriteRequest"]`	no
`append_metadata`	`bool`	Pass metric metadata to downstream components.	`false`	no
`enable_type_and_unit_labels`	`bool`	Add the metric type and unit as labels to the metric.	`false`	no

EXPERIMENTAL: The append_metadata, enable_type_and_unit_labels, and using "io.prometheus.write.v2.Request" in accepted_remote_write_protobuf_messages are experimental features.

The append_metadata and enable_type_and_unit_labels arguments only apply to remote write v2 payloads and only when metadata is included in those payloads. Enabling support for remote write v2 payloads requires that "io.prometheus.write.v2.Request" is included in accepted_remote_write_protobuf_messages. Remote write v1 payloads (accepted_remote_write_protobuf_messages = ["prometheus.WriteRequest"]) cannot support these features.

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.

Blocks

You can use the following blocks with prometheus.receive_http:

Name	Description	Required
`target`	Configures a blackbox target.	no

`http`

The http block configures the HTTP server.

You can use the following arguments to configure the http block. Any omitted fields take their default values.

Name	Type	Description	Default	Required
`conn_limit`	`int`	Maximum number of simultaneous HTTP connections. Defaults to no limit.	`0`	no
`listen_address`	`string`	Network address on which the server listens for new connections. Defaults to accepting all incoming connections.	`""`	no
`listen_port`	`int`	Port number on which the server listens for new connections.	`8080`	no
`server_idle_timeout`	`duration`	Idle timeout for HTTP server.	`"120s"`	no
`server_read_timeout`	`duration`	Read timeout for HTTP server.	`"30s"`	no
`server_write_timeout`	`duration`	Write timeout for HTTP server.	`"30s"`	no

`tls`

The tls block configures TLS for the HTTP server.

Name	Type	Description	Default	Required
`cert_pem`	`string`	PEM data of the server TLS certificate.	`""`	no
`cert_file`	`string`	Path to the server TLS certificate on disk.	`""`	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
`key_file`	`string`	Path to the server TLS key on disk.	`""`	no
`key_pem`	`secret`	PEM data of the server TLS key.	`""`	no

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

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.

Exported fields

prometheus.receive_http doesn’t export any fields.

Component health

prometheus.receive_http is reported as unhealthy if it’s given an invalid configuration.

Debug metrics

The following are some of the metrics that are exposed when this component is used. The metrics include labels such as status_code where relevant, which can be used to measure request success rates.

prometheus_fanout_latency (histogram): Write latency for sending metrics to other components.
prometheus_forwarded_samples_total (counter): Total number of samples sent to downstream components.
prometheus_receive_http_request_duration_seconds (histogram): Time (in seconds) spent serving HTTP requests.
prometheus_receive_http_request_message_bytes (histogram): Size (in bytes) of messages received in the request.
prometheus_receive_http_response_message_bytes (histogram): Size (in bytes) of messages sent in response.
prometheus_receive_http_tcp_connections (gauge): Current number of accepted TCP connections.

Example

Receive metrics over HTTP

The following example creates a prometheus.receive_http component which starts an HTTP server listening on port 9999 on all network interfaces. The server receives metrics and forwards them to a prometheus.remote_write component which writes these metrics to the specified HTTP endpoint.

// Receives metrics over HTTP
prometheus.receive_http "api" {
  http {
    listen_address = "0.0.0.0"
    listen_port = 9999
  }
  forward_to = [prometheus.remote_write.local.receiver]
}

// Send metrics to a locally running Mimir.
prometheus.remote_write "local" {
  endpoint {
    url = "http://mimir:9009/api/v1/push"

    basic_auth {
      username = "example-user"
      password = "example-password"
    }
  }
}

Proxy metrics

To send metrics to the prometheus.receive_http component defined in the previous example, another Alloy can run with the following configuration:

// Collects metrics of localhost:12345
prometheus.scrape "self" {
  targets = [
    {"__address__" = "localhost:12345", "job" = "alloy"},
  ]
  forward_to = [prometheus.remote_write.local.receiver]
}

// Writes metrics to localhost:9999/api/v1/metrics/write - e.g. served by
// the prometheus.receive_http component from the example above.
prometheus.remote_write "local" {
  endpoint {
    url = "http://localhost:9999/api/v1/metrics/write"
  }
}

Technical details

prometheus.receive_http uses snappy for compression.

Compatible components

prometheus.receive_http can accept arguments from the following components:

Components that export Prometheus MetricsReceiver

Note
Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.

prometheus.relabel

Mon, 13 Apr 2026 07:37:47 +0000

`prometheus.relabel`

Prometheus metrics follow the OpenMetrics format. Each time series is uniquely identified by its metric name, plus optional key-value pairs called labels. Each sample represents a datapoint in the time series and contains a value and an optional timestamp.

<metric name>{<label_1>=<label_val_1>, <label_2>=<label_val_2> ...} <value> [timestamp]

The prometheus.relabel component rewrites the label set of each metric passed along to the exported receiver by applying one or more relabeling rules. If no rules are defined or applicable to some metrics, then those metrics are forwarded as-is to each receiver passed in the component’s arguments. If no labels remain after the relabeling rules are applied, then the metric is dropped.

The most common use of prometheus.relabel is to filter Prometheus metrics or standardize the label set that’s passed to one or more downstream receivers. The rule blocks are applied to the label set of each metric in order of their appearance in the configuration file. The configured rules can be retrieved by calling the function in the rules export field.

You can specify multiple prometheus.relabel components by giving them different labels.

Usage

prometheus.relabel "<LABEL>" {
  forward_to = <RECEIVER_LIST>

  rule {
    ...
  }

  ...
}

Arguments

You can use the following arguments with prometheus.relabel:

Name	Type	Description	Default	Required
`forward_to`	`list(MetricsReceiver)`	Where the metrics should be forwarded to, after relabeling takes place.		yes
`max_cache_size`	`int`	The maximum number of elements to hold in the relabeling cache.	`100000`	no

Blocks

You can use the following block with prometheus.relabel:

Name	Description	Required
`target`	Configures a blackbox target.	no

`rule`

The rule block contains the definition of any relabeling rules that can be applied to an input metric. If more than one rule block is defined, the transformations are applied in top-down order.

The following arguments can be used to configure a rule. All arguments are optional. Omitted fields take their default values.

Name	Type	Description	Default	Required
`action`	`string`	The relabeling action to perform.	replace	no
`modulus`	`uint`	A positive integer used to calculate the modulus of the hashed source label values.		no
`regex`	`string`	A valid RE2 expression with support for parenthesized capture groups. Used to match the extracted value from the combination of the `source_label` and `separator` fields or filter labels during the `labelkeep/labeldrop/labelmap` actions.	`(.*)`	no
`replacement`	`string`	The value against which a regular expression replace is performed, if the regular expression matches the extracted value. Supports previously captured groups.	`"$1"`	no
`separator`	`string`	The separator used to concatenate the values present in `source_labels`.	;	no
`source_labels`	`list(string)`	The list of labels whose values are to be selected. Their content is concatenated using the `separator` and matched against `regex`.		no
`target_label`	`string`	Label to which the resulting value will be written to.		no

You can use the following actions:

drop - Drops metrics where regex matches the string extracted using the source_labels and separator.
dropequal - Drop targets for which the concatenated source_labels do match target_label.
hashmod - Hashes the concatenated labels, calculates its modulo modulus and writes the result to the target_label.
keep - Keeps metrics where regex matches the string extracted using the source_labels and separator.
keepequal - Drop targets for which the concatenated source_labels don’t match target_label.
labeldrop - Matches regex against all label names. Any labels that match are removed from the metric’s label set.
labelkeep - Matches regex against all label names. Any labels that don’t match are removed from the metric’s label set.
labelmap - Matches regex against all label names. Any labels that match are renamed according to the contents of the replacement field.
lowercase - Sets target_label to the lowercase form of the concatenated source_labels.
replace - Matches regex to the concatenated labels. If there’s a match, it replaces the content of the target_label using the contents of the replacement field.
uppercase - Sets target_label to the uppercase form of the concatenated source_labels.

Note
The regular expression capture groups can be referred to using either the $CAPTURE_GROUP_NUMBER or ${CAPTURE_GROUP_NUMBER} notation.

Exported fields

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

Name	Type	Description
`receiver`	`MetricsReceiver`	The input receiver where samples are sent to be relabeled.
`rules`	`RelabelRules`	The currently configured relabeling rules.

Component health

prometheus.relabel is only reported as unhealthy if given an invalid configuration. In those cases, exported fields are kept at their last healthy values.

Debug information

prometheus.relabel doesn’t expose any component-specific debug information.

Debug metrics

prometheus_fanout_latency (histogram): Write latency for sending to direct and indirect components.
prometheus_forwarded_samples_total (counter): Total number of samples sent to downstream components.
prometheus_relabel_cache_hits (counter): Total number of cache hits.
prometheus_relabel_cache_misses (counter): Total number of cache misses.
prometheus_relabel_cache_size (gauge): Total size of relabel cache.
prometheus_relabel_metrics_processed (counter): Total number of metrics processed.
prometheus_relabel_metrics_written (counter): Total number of metrics written.

Example

The following example shows how the prometheus.relabel component applies relabel rules to the incoming metrics, and forwards the results to prometheus.remote_write.onprem.receiver:

prometheus.relabel "keep_backend_only" {
  forward_to = [prometheus.remote_write.onprem.receiver]

  rule {
    action        = "replace"
    source_labels = ["__address__", "instance"]
    separator     = "/"
    target_label  = "host"
  }
  rule {
    action        = "keep"
    source_labels = ["app"]
    regex         = "backend"
  }
  rule {
    action = "labeldrop"
    regex  = "instance"
  }
}

metric_a{__address__ = "localhost", instance = "development", app = "frontend"} 10
metric_a{__address__ = "localhost", instance = "development", app = "backend"}  2
metric_a{__address__ = "cluster_a", instance = "production",  app = "frontend"} 7
metric_a{__address__ = "cluster_a", instance = "production",  app = "backend"}  9
metric_a{__address__ = "cluster_b", instance = "production",  app = "database"} 4

After applying the first rule, the replace action populates a new label named host by concatenating the contents of the __address__ and instance labels, separated by a slash /.

metric_a{host = "localhost/development", __address__ = "localhost", instance = "development", app = "frontend"} 10
metric_a{host = "localhost/development", __address__ = "localhost", instance = "development", app = "backend"}  2
metric_a{host = "cluster_a/production",  __address__ = "cluster_a", instance = "production",  app = "frontend"} 7
metric_a{host = "cluster_a/production",  __address__ = "cluster_a", instance = "production",  app = "backend"}  9
metric_a{host = "cluster_b/production",  __address__ = "cluster_a", instance = "production",  app = "database"} 4

On the second relabeling rule, the keep action only keeps the metrics whose app label matches regex, dropping everything else, so the list of metrics is trimmed down to:

metric_a{host = "localhost/development", __address__ = "localhost", instance = "development", app = "backend"}  2
metric_a{host = "cluster_a/production",  __address__ = "cluster_a", instance = "production",  app = "backend"}  9

The third and final relabeling rule which uses the labeldrop action removes the instance label from the set of labels.

So in this case, the initial set of metrics passed to the exported receiver is:

metric_a{host = "localhost/development", __address__ = "localhost", app = "backend"}  2
metric_a{host = "cluster_a/production",  __address__ = "cluster_a", app = "backend"}  9

The two resulting metrics are then propagated to each receiver defined in the forward_to argument.

Compatible components

prometheus.relabel can accept arguments from the following components:

Components that export Prometheus MetricsReceiver

prometheus.relabel has exports that can be consumed by the following components:

Components that consume Prometheus MetricsReceiver

Note
Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.

prometheus.remote_write

Mon, 13 Apr 2026 07:37:47 +0000

`prometheus.remote_write`

prometheus.remote_write collects metrics sent from other components into a Write-Ahead Log (WAL) and forwards them over the network to a series of user-supplied endpoints. Metrics are sent over the network using the Prometheus Remote Write protocol.

You can specify multiple prometheus.remote_write components by giving them different labels.

Usage

prometheus.remote_write "<LABEL>" {
  endpoint {
    url = "<REMOTE_WRITE_URL>"

    ...
  }

  ...
}

Arguments

You can use the following argument with prometheus.remote_write:

Name	Type	Description	Default	Required
`external_labels`	`map(string)`	Labels to add to metrics sent over the network.		no

Blocks

You can use the following blocks with prometheus.remote_write:

Name	Description	Required
`target`	Configures a blackbox target.	no

`endpoint`

The endpoint block describes a single location to send metrics to. You can define multiple endpoint blocks to send metrics to multiple locations.

The following arguments are supported:

Name	Type	Description	Default	Required
`url`	`string`	Full URL to send metrics to.		yes
`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.	`false`	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
`headers`	`map(string)`	Extra headers to deliver with the request.		no
`name`	`string`	Optional name to identify the endpoint in metrics.		no
`no_proxy`	`string`	Comma-separated list of IP addresses, CIDR notations, and domain names to exclude from proxying.		no
`protobuf_message`	`string`	Protobuf message format to use for remote write. Must be `prometheus.WriteRequest` or experimental `io.prometheus.write.v2.Request`.	`"prometheus.WriteRequest"`	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
`remote_timeout`	`duration`	Timeout for requests made to the URL.	`"30s"`	no
`send_exemplars`	`bool`	Whether exemplars should be sent.	`true`	no
`send_native_histograms`	`bool`	Whether native histograms should be sent.	`false`	no

At most, one of the following can be provided:

[authorization][authorization] block
[azuread][azuread] block
[basic_auth][basic_auth] block
bearer_token_file argument
bearer_token argument
[oauth2][oauth2] block
[sigv4][sigv4] block

When multiple endpoint blocks are provided, metrics are concurrently sent to all configured locations. Each endpoint has a queue which is used to read metrics from the WAL and queue them for sending. The queue_config block can be used to customize the behavior of the queue.

Endpoints can be named for easier identification in debug metrics using the name argument. If the name argument isn’t provided, a name is generated based on a hash of the endpoint settings.

When send_native_histograms is true, native Prometheus histogram samples sent to prometheus.remote_write are forwarded to the configured endpoint. If the endpoint doesn’t support receiving native histogram samples, pushing metrics fails.

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.

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

`azuread`

Name	Type	Description	Default	Required
`cloud`	`string`	The Azure Cloud.	`"AzurePublic"`	no

The supported values for cloud are:

"AzurePublic"
"AzureChina"
"AzureGovernment"

`managed_identity`

Required

Name	Type	Description	Default	Required
`client_id`	`string`	Client ID of the managed identity used to authenticate.		yes

client_id should be a valid UUID in one of the supported formats:

xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
urn:uuid:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Microsoft encoding: {xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}
Raw hex encoding: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

`oauth`

Required

Name	Type	Description	Required
`client_id`	`string`	The client ID of the Azure Active Directory application that’s being used to authenticate.	yes
`client_secret`	`secret`	The client secret of the Azure Active Directory application that’s being used to authenticate.	yes
`tenant_id`	`string`	The tenant ID of the Azure Active Directory application that’s being used to authenticate.	yes

`sdk`

Required

This block configures Azure SDK authentication.

Name	Type	Description	Default	Required
`tenant_id`	`string`	The tenant ID of the Azure Active Directory application that’s being used to authenticate.		yes

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

`metadata_config`

Name	Type	Description	Default	Required
`max_samples_per_send`	`number`	Maximum number of metadata samples to send to the endpoint at once.	`2000`	no
`send_interval`	`duration`	How frequently metric metadata is sent to the endpoint.	`"1m"`	no
`send`	`bool`	Controls whether metric metadata is sent to the endpoint.	`true`	no

`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)

`queue_config`

Name	Type	Description	Default	Required
`batch_send_deadline`	`duration`	Maximum time samples wait in the buffer before sending.	`"5s"`	no
`capacity`	`number`	Number of samples to buffer per shard.	`10000`	no
`max_backoff`	`duration`	Maximum retry delay.	`"5s"`	no
`max_samples_per_send`	`number`	Maximum number of samples per send.	`2000`	no
`max_shards`	`number`	Maximum number of concurrent shards sending samples to the endpoint.	`50`	no
`min_backoff`	`duration`	Initial retry delay. The backoff time gets doubled for each retry.	`"30ms"`	no
`min_shards`	`number`	Minimum amount of concurrent shards sending samples to the endpoint.	`1`	no
`retry_on_http_429`	`bool`	Retry when an HTTP 429 status code is received.	`true`	no
`sample_age_limit`	`duration`	Maximum age of samples to send.	`"0s"`	no

Each queue then manages a number of concurrent shards which is responsible for sending a fraction of data to their respective endpoints. The number of shards is automatically raised if samples aren’t being sent to the endpoint quickly enough. The range of permitted shards can be configured with the min_shards and max_shards arguments. Refer to Tune max_shards for more information about how to configure max_shards.

Each shard has a buffer of samples it keeps in memory, controlled with the capacity argument. New metrics aren’t read from the WAL unless there is at least one shard that’s not at maximum capacity.

The buffer of a shard is flushed and sent to the endpoint either after the shard reaches the number of samples specified by max_samples_per_send or the duration specified by batch_send_deadline has elapsed since the last flush for that shard.

Shards retry requests which fail due to a recoverable error. An error is recoverable if the server responds with an HTTP 5xx status code. The delay between retries can be customized with the min_backoff and max_backoff arguments.

The retry_on_http_429 argument specifies whether HTTP 429 status code responses should be treated as recoverable errors. Other HTTP 4xx status code responses are never considered recoverable errors. When retry_on_http_429 is enabled, Retry-After response headers from the servers are honored.

The sample_age_limit argument specifies the maximum age of samples to send. Any samples older than the limit are dropped and won’t be sent to the remote storage. The default value is 0s, which means that all samples are sent (feature is disabled).

`sigv4`

Name	Type	Description	Required
`access_key`	`string`	AWS API access key.	no
`profile`	`string`	Named AWS profile used to authenticate.	no
`region`	`string`	AWS region.	no
`role_arn`	`string`	AWS Role ARN, an alternative to using AWS API keys.	no
`secret_key`	`secret`	AWS API secret key.	no

If region is left blank, the region from the default credentials chain is used.

If access_key is left blank, the environment variable AWS_ACCESS_KEY_ID is used.

If secret_key is left blank, the environment variable AWS_SECRET_ACCESS_KEY is used.

`write_relabel_config`

The write_relabel_config block contains the definition of any relabeling rules that can be applied to an input metric. If more than one write_relabel_config block is defined, the transformations are applied in top-down order.

The following arguments can be used to configure a write_relabel_config. All arguments are optional. Omitted fields take their default values.

Name	Type	Description	Default	Required
`action`	`string`	The relabeling action to perform.	replace	no
`modulus`	`uint`	A positive integer used to calculate the modulus of the hashed source label values.		no
`regex`	`string`	A valid RE2 expression with support for parenthesized capture groups. Used to match the extracted value from the combination of the `source_label` and `separator` fields or filter labels during the `labelkeep/labeldrop/labelmap` actions.	`(.*)`	no
`replacement`	`string`	The value against which a regular expression replace is performed, if the regular expression matches the extracted value. Supports previously captured groups.	`"$1"`	no
`separator`	`string`	The separator used to concatenate the values present in `source_labels`.	;	no
`source_labels`	`list(string)`	The list of labels whose values are to be selected. Their content is concatenated using the `separator` and matched against `regex`.		no
`target_label`	`string`	Label to which the resulting value will be written to.		no

You can use the following actions:

drop: Drops metrics where regex matches the string extracted using the source_labels and separator.
dropequal: Drop targets for which the concatenated source_labels do match target_label.
hashmod: Hashes the concatenated labels, calculates its modulo modulus and writes the result to the target_label.
keep: Keeps metrics where regex matches the string extracted using the source_labels and separator.
keepequal: Drop targets for which the concatenated source_labels don’t match target_label.
labeldrop: Matches regex against all label names. Any labels that match are removed from the metric’s label set.
labelkeep: Matches regex against all label names. Any labels that don’t match are removed from the metric’s label set.
labelmap: Matches regex against all label names. Any labels that match are renamed according to the contents of the replacement field.
lowercase: Sets target_label to the lowercase form of the concatenated source_labels.
replace: Matches regex to the concatenated labels. If there’s a match, it replaces the content of the target_label using the contents of the replacement field.
uppercase: Sets target_label to the uppercase form of the concatenated source_labels.

Note
The regular expression capture groups can be referred to using either the $CAPTURE_GROUP_NUMBER or ${CAPTURE_GROUP_NUMBER} notation.

`wal`

The wal block customizes the Write-Ahead Log (WAL) used to temporarily store metrics before they’re sent to the configured set of endpoints.

Name	Type	Description	Default	Required
`truncate_frequency`	`duration`	How frequently to clean up the WAL.	`"2h"`	no
`min_keepalive_time`	`duration`	Minimum time to keep data in the WAL before it can be removed.	`"5m"`	no
`max_keepalive_time`	`duration`	Maximum time to keep data in the WAL before removing it.	`"8h"`	no

The WAL serves two primary purposes:

Buffer unsent metrics in case of intermittent network issues.
Populate in-memory cache after a process restart.

The WAL is located inside a component-specific directory relative to the storage path Alloy is configured to use. Refer to the run documentation for information about how to change the storage path.

The truncate_frequency argument configures how often to clean up the WAL. Every time the truncate_frequency period elapses, the lower two-thirds of data is removed from the WAL and is no longer available for sending.

When a WAL clean-up starts, the lowest successfully sent timestamp is used to determine how much data is safe to remove from the WAL. The min_keepalive_time and max_keepalive_time control the permitted age range of data in the WAL. Samples aren’t removed until they’re at least as old as min_keepalive_time, and samples are forcibly removed if they’re older than max_keepalive_time.

Exported fields

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

Name	Type	Description
`receiver`	`MetricsReceiver`	A value which other components can use to send metrics to.

Component health

prometheus.remote_write is only reported as unhealthy if given an invalid configuration. In those cases, exported fields are kept at their last healthy values.

Debug information

prometheus.remote_write doesn’t expose any component-specific debug information.

Debug metrics

prometheus_remote_storage_bytes_total (counter): Total number of bytes of data sent by queues after compression.
prometheus_remote_storage_enqueue_retries_total (counter): Total number of times enqueue has failed because a shard’s queue was full.
prometheus_remote_storage_exemplars_dropped_total (counter): Total number of exemplars which were dropped after being read from the WAL before being sent to remote_write because of an unknown reference ID.
prometheus_remote_storage_exemplars_failed_total (counter): Total number of exemplars that failed to send to remote storage due to non-recoverable errors.
prometheus_remote_storage_exemplars_in_total (counter): Exemplars read into remote storage.
prometheus_remote_storage_exemplars_pending (gauge): The number of exemplars pending in shards to be sent to remote storage.
prometheus_remote_storage_exemplars_retried_total (counter): Total number of exemplars that failed to send to remote storage but were retried due to recoverable errors.
prometheus_remote_storage_exemplars_total (counter): Total number of exemplars sent to remote storage.
prometheus_remote_storage_max_samples_per_send (gauge): The maximum number of samples each shard is allowed to send in a single request.
prometheus_remote_storage_metadata_bytes_total (counter): Total number of bytes of metadata sent by queues after compression.
prometheus_remote_storage_metadata_failed_total (counter): Total number of metadata entries that failed to send to remote storage due to non-recoverable errors.
prometheus_remote_storage_metadata_retried_total (counter): Total number of metadata entries that failed to send to remote storage but were retried due to recoverable errors.
prometheus_remote_storage_metadata_total (counter): Total number of metadata entries sent to remote storage.
prometheus_remote_storage_queue_highest_sent_timestamp_seconds (gauge): Unix timestamp of the latest WAL sample successfully sent by a queue.
prometheus_remote_storage_samples_dropped_total (counter): Total number of samples which were dropped after being read from the WAL before being sent to remote_write because of an unknown reference ID.
prometheus_remote_storage_samples_failed_total (counter): Total number of samples that failed to send to remote storage due to non-recoverable errors.
prometheus_remote_storage_samples_in_total (counter): Samples read into remote storage.
prometheus_remote_storage_samples_pending (gauge): The number of samples pending in shards to be sent to remote storage.
prometheus_remote_storage_samples_retries_total (counter): Total number of samples that failed to send to remote storage but were retried due to recoverable errors.
prometheus_remote_storage_samples_total (counter): Total number of samples sent to remote storage.
prometheus_remote_storage_sent_batch_duration_seconds (histogram): Duration of send calls to remote storage.
prometheus_remote_storage_shard_capacity (gauge): The capacity of shards within a given queue.
prometheus_remote_storage_shards_desired (gauge): The number of shards a queue wants to run to be able to keep up with the amount of incoming metrics.
prometheus_remote_storage_shards_max (gauge): The maximum number of a shards a queue is allowed to run.
prometheus_remote_storage_shards_min (gauge): The minimum number of shards a queue is allowed to run.
prometheus_remote_storage_shards (gauge): The number of shards used for concurrent delivery of metrics to an endpoint.
prometheus_remote_write_wal_exemplars_appended_total (counter): Total number of exemplars appended to the WAL.
prometheus_remote_write_wal_out_of_order_samples_total (counter): Total number of out of order samples ingestion failed attempts.
prometheus_remote_write_wal_metadata_updates_total (counter): Total number of metadata updates sent through the WAL.
prometheus_remote_write_wal_samples_appended_total (counter): Total number of samples appended to the WAL.
prometheus_remote_write_wal_storage_active_series (gauge): Current number of active series being tracked by the WAL.
prometheus_remote_write_wal_storage_created_series_total (counter): Total number of created series appended to the WAL.
prometheus_remote_write_wal_storage_deleted_series (gauge): Current number of series marked for deletion from memory.
prometheus_remote_write_wal_storage_removed_series_total (counter): Total number of series removed from the WAL.

Examples

The following examples show you how to create prometheus.remote_write components that send metrics to different destinations.

Send metrics to a local Mimir instance

You can create a prometheus.remote_write component that sends your metrics to a local Mimir instance:

prometheus.remote_write "staging" {
  // Send metrics to a locally running Mimir.
  endpoint {
    url = "http://mimir:9009/api/v1/push"

    basic_auth {
      username = "example-user"
      password = "example-password"
    }
  }
}

// Configure a prometheus.scrape component to send metrics to
// prometheus.remote_write component.
prometheus.scrape "demo" {
  targets = [
    // Collect metrics from the default HTTP listen address.
    {"__address__" = "127.0.0.1:12345"},
  ]
  forward_to = [prometheus.remote_write.staging.receiver]
}

Send metrics to a Mimir instance with a tenant specified

You can create a prometheus.remote_write component that sends your metrics to a specific tenant within the Mimir instance. This is useful when your Mimir instance is using more than one tenant:

prometheus.remote_write "staging" {
  // Send metrics to a Mimir instance
  endpoint {
    url = "http://mimir:9009/api/v1/push"

    headers = {
      "X-Scope-OrgID" = "staging",
    }
  }
}

Experimental: Send metrics using Remote Write v2 protocol

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.

You can configure prometheus.remote_write to use the Remote Write v2 protocol if your endpoint supports it:

prometheus.remote_write "v2_example" {
  endpoint {
    url = "http://mimir:9009/api/v1/push"
    protobuf_message = "io.prometheus.write.v2.Request"
  }
}

Send metrics to a managed service

You can create a prometheus.remote_write component that sends your metrics to a managed service, for example, Grafana Cloud. The Prometheus username and the Grafana Cloud API Key are injected in this example through environment variables.

prometheus.remote_write "default" {
  endpoint {
    url = "https://prometheus-xxx.grafana.net/api/prom/push"
      basic_auth {
        username = sys.env("PROMETHEUS_USERNAME")
        password = sys.env("GRAFANA_CLOUD_API_KEY")
      }
  }
}

Troubleshooting

Out of order errors

You may sometimes see an “out of order” error in the Alloy log files. This means that Alloy sent a metric sample that has an older timestamp than a sample that the database already ingested. If your database is Mimir, the exact name of the Mimir error is err-mimir-sample-out-of-order.

The most common cause for this error is that there is more than one Alloy instance scraping the same target. To troubleshoot, take the following steps in order:

If you use clustering, check if the number of Alloy instances changed at the time the error was logged. This is the only situation in which it’s normal to experience an out of order error. The error would only happen for a short period, until the cluster stabilizes and all Alloy instances have a new list of targets. Since the time duration for the cluster to stabilize is expected to be much shorter than the scrape interval, this isn’t a real problem. If the out of order error you see isn’t related to scaling of clustered collectors, it must be investigated.
Check if there are active Alloy instances which shouldn’t be running. There may be an older Alloy instance that wasn’t shut down before a new one was started.
Inspect the configuration to see if there could be multiple Alloy instances which scrape the same target.
Inspect the WAL to see which Alloy instance sent those metric samples. The WAL is located in a directory set by the run command --storage.path argument. You can use Promtool to inspect it and find out which metric series were sent by this Alloy instance since the last WAL truncation event. For example:
text
```
./promtool tsdb dump --match='{__name__="otelcol_connector_spanmetrics_duration_seconds_bucket", http_method="GET", job="ExampleJobName"}' /path/to/wal/
```

Technical details

prometheus.remote_write uses snappy for compression.

Any labels that start with __ are removed before sending to the endpoint.

Data retention

The prometheus.remote_write component uses a Write Ahead Log (WAL) to prevent data loss during network outages. The component buffers the received metrics in a WAL for each configured endpoint. The queue shards can use the WAL after the network outage is resolved and flush the buffered metrics to the endpoints.

The WAL records metrics in 128 MB files called segments. To avoid having a WAL that grows on-disk indefinitely, the component truncates its segments on a set interval.

On each truncation, the WAL deletes references to series that are no longer present and also checkpoints roughly the oldest two thirds of the segments (rounded down to the nearest integer) written to it since the last truncation period. A checkpoint means that the WAL only keeps track of the unique identifier for each existing metrics series, and can no longer use the samples for remote writing. If that data hasn’t yet been pushed to the remote endpoint, it’s lost.

This behavior dictates the data retention for the prometheus.remote_write component. It also means that it’s impossible to directly correlate data retention directly to the data age itself, as the truncation logic works on segments, not the samples themselves. This makes data retention less predictable when the component receives a non-consistent rate of data.

The WAL block contains some configurable parameters that can be used to control the tradeoff between memory usage, disk usage, and data retention.

The truncate_frequency or wal_truncate_frequency parameter configures the interval at which truncations happen. A lower value leads to reduced memory usage, but also provides less resiliency to long outages.

When a WAL clean-up starts, the most recently successfully sent timestamp is used to determine how much data is safe to remove from the WAL. The min_keepalive_time or min_wal_time controls the minimum age of samples considered for removal. No samples more recent than min_keepalive_time are removed. The max_keepalive_time or max_wal_time controls the maximum age of samples that can be kept in the WAL. Samples older than max_keepalive_time are forcibly removed.

Extended `remote_write` outages

When the remote write endpoint is unreachable over a period of time, the most recent successfully sent timestamp isn’t updated. The min_keepalive_time and max_keepalive_time arguments control the age range of data kept in the WAL.

If the remote write outage is longer than the max_keepalive_time parameter, then the WAL is truncated, and the oldest data is lost.

Intermittent `remote_write` outages

If the remote write endpoint is intermittently reachable, the most recent successfully sent timestamp is updated whenever the connection is successful. A successful connection updates the series’ comparison with min_keepalive_time and triggers a truncation on the next truncate_frequency interval which checkpoints two thirds of the segments (rounded down to the nearest integer) written since the previous truncation.

Falling behind

If the queue shards can’t flush data quickly enough to keep up-to-date with the most recent data buffered in the WAL, the component is “falling behind”. It’s not unusual for the component to temporarily fall behind 2 or 3 scrape intervals. If the component falls behind more than one third of the data written since the last truncate interval, it’s possible for the truncate loop to checkpoint data before being pushed to the remote_write endpoint.

Tune `max_shards`

The queue_config block allows you to configure max_shards. The max_shards is the maximum number of concurrent shards sending samples to the Prometheus-compatible remote write endpoint. For each shard, a single remote write request can send up to max_samples_per_send samples.

Alloy tries not to use too many shards, but if the queue falls behind, the remote write component increases the number of shards up to max_shards to increase throughput. A high number of shards may potentially overwhelm the remote endpoint or increase Alloy memory utilization. For this reason, it’s important to tune max_shards to a reasonable value that’s good enough to keep up with the backlog of data to send to the remote endpoint without overwhelming it.

The maximum throughput that Alloy can achieve when remote writing is equal to max_shards * max_samples_per_send * <1 / average write request latency>. For example, running Alloy with the default configuration of 50 max_shards and 2000 max_samples_per_send, and assuming the average latency of a remote write request is 500ms, the maximum throughput achievable is about 50 * 2000 * (1s / 500ms) = 200K samples / s.

The default max_shards configuration is good for most use cases, especially if each Alloy instance scrapes up to 1 million active series. However, if you run Alloy at a large scale and each instance scrapes more than 1 million series, we recommend increasing the value of max_shards.

Alloy exposes a few metrics that you can use to monitor the remote write shards:

prometheus_remote_storage_shards_desired (gauge): The number of shards a queue wants to run to keep up with the number of incoming metrics.
prometheus_remote_storage_shards_max (gauge): The maximum number of shards a queue is allowed to run.
prometheus_remote_storage_shards_min (gauge): The minimum number of shards a queue is allowed to run.
prometheus_remote_storage_shards (gauge): The number of shards used for concurrent delivery of metrics to an endpoint.

If you’re already running Alloy, a rule of thumb is to set max_shards to 4x shard utilization. Using the metrics explained above, you can run the following PromQL instant query to compute the suggested max_shards value for each remote write endpoint url:

clamp_min(
    (
        # Calculate the 90th percentile desired shards over the last seven-day period.
        # If you're running Alloy for less than seven days, then
        # reduce the [7d] period to cover only the time range since when you deployed it.
        ceil(quantile_over_time(0.9, prometheus_remote_storage_shards_desired[7d]))

        # Add room for spikes.
        * 4
    ),
    # We recommend setting max_shards to a value of no less than 50, as in the default configuration.
    50
)

If you aren’t running Alloy yet, we recommend running it with the default max_shards and then using the PromQL instant query mentioned above to compute the recommended max_shards.

WAL corruption

WAL corruption can occur when Alloy unexpectedly stops while the latest WAL segments are still being written to disk. For example, the host computer has a general disk failure and crashes before you can stop Alloy and other running services. When you restart Alloy, it verifies the WAL, removing any corrupt segments it finds. Sometimes, this repair is unsuccessful, and you must manually delete the corrupted WAL to continue. If the WAL becomes corrupted, Alloy writes error messages such as err="failed to find segment for index" to the log file.

Note
Deleting a WAL segment or a WAL file permanently deletes the stored WAL data.

To delete the corrupted WAL:

Stop Alloy.
Find and delete the contents of the wal directory.

By default the wal directory is a subdirectory of the data-alloy directory located in the Alloy working directory. The WAL data directory may be different than the default depending on the path specified by the command line flag --storage-path.

Note
There is one wal directory per prometheus.remote_write component.
Start Alloy and verify that the WAL is working correctly.

Compatible components

prometheus.remote_write has exports that can be consumed by the following components:

Components that consume Prometheus MetricsReceiver

Note
Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.

prometheus.scrape

Mon, 13 Apr 2026 07:37:47 +0000

`prometheus.scrape`

prometheus.scrape configures a Prometheus scraping job for a given set of targets. The scraped metrics are forwarded to the list of receivers passed in forward_to.

You can specify multiple prometheus.scrape components by giving them different labels.

Usage

prometheus.scrape "<LABEL>" {
  targets    = <TARGET_LIST>
  forward_to = <RECEIVER_LIST>
}

Arguments

The component configures and starts a new scrape job to scrape all the input targets. The list of arguments that can be used to configure the block is presented below.

The scrape job name defaults to the component’s unique identifier.

One of the following can be provided:

[authorization][authorization] block
[basic_auth][basic_auth] block
bearer_token_file argument
bearer_token argument
[oauth2][oauth2] block

If conflicting attributes are passed, for example, defining both a bearer_token and bearer_token_file or configuring both basic_auth and oauth2 at the same time, the component reports an error.

You can use the following arguments with prometheus.scrape:

Name	Type	Description	Default	Required
`forward_to`	`list(MetricsReceiver)`	List of receivers to send scraped metrics to.		yes
`targets`	`list(map(string))`	List of targets to scrape.		yes
`bearer_token_file`	`string`	File containing a bearer token to authenticate with.		no
`bearer_token`	`secret`	Bearer token to authenticate with.		no
`body_size_limit`	`int`	An uncompressed response body larger than this many bytes causes the scrape to fail. 0 means no limit.		no
`convert_classic_histograms_to_nhcb`	`bool`	Whether to convert classic histograms to native histograms with custom buckets (NHCB).	`false`	no
`enable_compression`	`bool`	Whether compression is enabled for the scrape.	`true`	no
`enable_http2`	`bool`	Whether HTTP2 is supported for requests.	`true`	no
`enable_protobuf_negotiation`	`bool`	Deprecated: use `scrape_protocols` instead.	`false`	no
`enable_type_and_unit_labels`	`bool`	(Experimental) Whether the metric type and unit should be added as labels to scraped metrics.	`false`	no
`extra_metrics`	`bool`	Whether extra metrics should be generated for scrape targets.	`false`	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
`honor_labels`	`bool`	Indicator whether the scraped metrics should remain unmodified.	`false`	no
`honor_timestamps`	`bool`	Indicator whether the scraped timestamps should be respected.	`true`	no
`honor_metadata`	`bool`	(Experimental) Indicates whether to send metric metadata to downstream components.	`false`	no
`job_name`	`string`	The value to use for the job label if not already set.	component name	no
`label_limit`	`uint`	More than this many labels post metric-relabeling causes the scrape to fail.		no
`label_name_length_limit`	`uint`	More than this label name length post metric-relabeling causes the scrape to fail.		no
`label_value_length_limit`	`uint`	More than this label value length post metric-relabeling causes the scrape to fail.		no
`metric_name_escaping_scheme`	`string`	The escaping scheme to use for metric names. See below for available values.	`"underscores"`	no
`metric_name_validation_scheme`	`string`	The validation scheme to use for metric names. See below for available values.	`"legacy"`	no
`metrics_path`	`string`	The HTTP resource path on which to fetch metrics from targets.	`"/metrics"`	no
`native_histogram_bucket_limit`	`uint`	Native histogram buckets will be merged to stay within this limit. Disabled when set to zero.	`0`	no
`native_histogram_min_bucket_factor`	`float64`	If the growth from one bucket to the next is smaller than this, buckets will be merged. Disabled when set to zero.	`0`	no
`no_proxy`	`string`	Comma-separated list of IP addresses, CIDR notations, and domain names to exclude from proxying.		no
`params`	`map(list(string))`	A set of query parameters with which the target is scraped.		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
`sample_limit`	`uint`	More than this many samples post metric-relabeling causes the scrape to fail		no
`scheme`	`string`	The URL protocol scheme used to fetch metrics from targets.		no
`scrape_classic_histograms`	`bool`	Whether to scrape a classic histogram that’s also exposed as a native histogram.	`false`	no
`scrape_failure_log_file`	`string`	File to which scrape failures are logged.	`""`	no
`scrape_fallback_protocol`	`string`	The fallback protocol to use if the target does not provide a valid Content-Type header. See below for available values.	`PrometheusText0_0_4`	no
`scrape_interval`	`duration`	How frequently to scrape the targets of this scrape configuration.	`"60s"`	no
`scrape_native_histograms`	`bool`	Whether to scrape native histograms. Currently, cannot be updated at runtime.	`false`	no
`scrape_protocols`	`list(string)`	The protocols to negotiate during a scrape, in order of preference. See below for available values.	`["OpenMetricsText1.0.0", "OpenMetricsText0.0.1", "PrometheusText1.0.0", "PrometheusText0.0.4"]`	no
`scrape_timeout`	`duration`	The timeout for scraping targets of this configuration.	`"10s"`	no
`target_limit`	`uint`	More than this many targets after the target relabeling causes the scrapes to fail.		no
`track_timestamps_staleness`	`bool`	Indicator whether to track the staleness of the scraped timestamps.	`false`	no

EXPERIMENTAL: The honor_metadata argument is an experimental feature. If you enable this argument, resource consumption may increase, particularly if you ingest many metrics with different names. Some downstream components aren’t compatible with Prometheus metadata. The following components are compatible:

otelcol.receiver.prometheus

prometheus.remote_write only when configured for Remote Write v2.

prometheus.write_queue

EXPERIMENTAL: The enable_type_and_unit_labels argument is an experimental feature. When enabled and available from the scrape, the metric type and unit are added as labels to each scraped sample. This provides additional schema information about metrics directly in the label set. This feature doesn’t require downstream components to support Remote Write v2.

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 scrape_protocols controls the preferred order of protocols to negotiate during a scrape. The following values are supported:

OpenMetricsText0.0.1
OpenMetricsText1.0.0
PrometheusProto
PrometheusText0.0.4
PrometheusText1.0.0

You can also use the scrape_fallback_protocol argument to specify a fallback protocol to use if the target does not provide a valid Content-Type header.

If you were using the deprecated enable_protobuf_negotiation argument, switch to using scrape_protocols = ["PrometheusProto", "OpenMetricsText1.0.0", "OpenMetricsText0.0.1", "PrometheusText0.0.4"] instead.

For now, native histograms are only available through the Prometheus Protobuf exposition format. To scrape native histograms, scrape_native_histograms must be set to true and the first item in scrape_protocols must be PrometheusProto.

The default value for scrape_protocols changes to ["PrometheusProto", "OpenMetricsText1.0.0", "OpenMetricsText0.0.1", "PrometheusText1.0.0", "PrometheusText0.0.4"] when scrape_native_histograms is set to true.

The metric_name_validation_scheme controls how metric names are validated. The following values are supported:

"utf8" - Uses UTF-8 validation scheme.
"legacy" - Uses legacy validation scheme which was default in Prometheus v2 (default).

The metric_name_escaping_scheme controls how metric names are escaped. The following values are supported:

"allow-utf-8" - Allows UTF-8 characters in metric names. No escaping is required. (default when validation scheme is “utf8”)
"underscores" - Replaces all legacy-invalid characters with underscores (default when validation scheme is “legacy”)
"dots" - Replaces all legacy-invalid characters with dots except that dots are converted to _dot_ and pre-existing underscores are converted to __.
"values" - Prepends the name with U__ and replaces all invalid characters with the unicode value, surrounded by underscores. Single underscores are replaced with double underscores.

Note: metric_name_escaping_scheme cannot be set to "allow-utf-8" while metric_name_validation_scheme is not set to "utf8".

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.

track_timestamps_staleness controls whether Prometheus tracks staleness of metrics with an explicit timestamp present in scraped data.

An “explicit timestamp” is an optional timestamp in the Prometheus metrics exposition format. For example, this sample has a timestamp of 1395066363000:
text
```
http_requests_total{method="post",code="200"} 1027 1395066363000
```
If track_timestamps_staleness is set to true, a staleness marker will be inserted when a metric is no longer present or the target is down.
A “staleness marker” is just a sample with a specific NaN value which is reserved for internal use by Prometheus.
We recommend you set track_timestamps_staleness to true if the database where metrics are written to has enabled out of order ingestion.
If track_timestamps_staleness is set to false, samples with explicit timestamps will only be labeled as stale after a certain time period, which in Prometheus is 5 minutes by default.

Blocks

You can use the following blocks with prometheus.scrape:

Name	Description	Required
`target`	Configures a blackbox target.	no

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

`clustering`

Name	Type	Description	Default	Required
`enabled`	`bool`	Enables sharing targets with other cluster nodes.	`false`	yes

When Alloy is using clustering, and enabled is set to true, then this prometheus.scrape component instance opts-in to participating in the cluster to distribute scrape load between all cluster nodes.

Clustering assumes that all cluster nodes are running with the same configuration file, have access to the same service discovery APIs, and that all prometheus.scrape components that have opted-in to using clustering, over the course of a scrape interval, are converging on the same target set from upstream components in their targets argument.

All prometheus.scrape components instances opting in to clustering use target labels and a consistent hashing algorithm to determine ownership for each of the targets between the cluster peers. Then, each peer only scrapes the subset of targets that it’s responsible for, so that the scrape load is distributed. When a node joins or leaves the cluster, every peer recalculates ownership and continues scraping with the new target set. This performs better than hashmod sharding where all nodes have to be re-distributed, as only 1/N of the targets ownership is transferred, but is eventually consistent (rather than fully consistent like hashmod sharding is).

If Alloy is not running in clustered mode, then the block is a no-op and prometheus.scrape scrapes every target it receives in its arguments.

`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)

Exported fields

prometheus.scrape doesn’t export any fields that can be referenced by other components.

Component health

prometheus.scrape is only reported as unhealthy if given an invalid configuration.

Debug information

prometheus.scrape reports the status of the last scrape for each configured scrape job on the component’s debug endpoint.

Debug metrics

prometheus_fanout_latency (histogram): Write latency for sending to direct and indirect components.
prometheus_forwarded_samples_total (counter): Total number of samples sent to downstream components.
prometheus_scrape_targets_gauge (gauge): Number of targets this component is configured to scrape.

Scraping behavior

The prometheus.scrape component borrows the scraping behavior of Prometheus. Prometheus, and by extent this component, uses a pull model for scraping metrics from a given set of targets. Each scrape target is defined as a set of key-value pairs called labels. The set of targets can either be static, or dynamically provided periodically by a service discovery component such as discovery.kubernetes. The special label __address__ must always be present and corresponds to the <host>:<port> that’s used for the scrape request.

By default, the scrape job tries to scrape all available targets’ /metrics endpoints using HTTP, with a scrape interval of 1 minute and scrape timeout of 10 seconds. The metrics path, protocol scheme, scrape interval and timeout, query parameters, as well as any other settings can be configured using the component’s arguments.

If a target is hosted at the in-memory traffic address specified by the run command, prometheus.scrape scrapes the metrics in-memory, bypassing the network.

The scrape job expects the metrics exposed by the endpoint to follow the OpenMetrics format. All metrics are then propagated to each receiver listed in the component’s forward_to argument.

Labels coming from targets, that start with a double underscore __ are treated as internal, and are removed prior to scraping.

The prometheus.scrape component regards a scrape as successful if it responded with an HTTP 200 OK status code and returned a body of valid metrics.

If the scrape request fails, the component’s debug UI section contains more detailed information about the failure, the last successful scrape, as well as the labels last used for scraping.

The following labels are automatically injected to the scraped time series and can help pin down a scrape target.

Label	Description
job	The configured job name that the target belongs to. Defaults to the fully formed component name.
instance	The `__address__` or `<host>:<port>` of the scrape target’s URL.

Similarly, these metrics that record the behavior of the scrape targets are also automatically available.

Metric Name	Description
`scrape_body_size_bytes`	The uncompressed size of the most recent scrape response, if successful. Scrapes failing because the `body_size_limit` is exceeded report -1, other scrape failures report 0.
`scrape_duration_seconds`	Duration of the scrape in seconds.
`scrape_sample_limit`	The configured sample limit for a target. Useful for measuring how close a target was to reaching the sample limit using `scrape_samples_post_metric_relabeling / (scrape_sample_limit > 0)`
`scrape_samples_post_metric_relabeling`	The number of samples remaining after metric relabeling was applied.
`scrape_samples_scraped`	The number of samples the target exposed.
`scrape_series_added`	The approximate number of new series in this scrape.
`scrape_timeout_seconds`	The configured scrape timeout for a target. Useful for measuring how close a target was to timing out using `scrape_duration_seconds / scrape_timeout_seconds`
`up`	1 if the instance is healthy and reachable, or 0 if the scrape failed.

The up metric is particularly useful for monitoring and alerting on the health of a scrape job. It’s set to 0 in case anything goes wrong with the scrape target, either because it’s not reachable, because the connection times out while scraping, or because the samples from the target couldn’t be processed. When the target is behaving normally, the up metric is set to 1.

To enable scraping of Prometheus’ native histograms over gRPC, the scrape_protocols should specify PrometheusProto as the first protocol to negotiate, for example:

prometheus.scrape "prometheus" {
  ...
  scrape_native_histograms = true
  scrape_protocols = ["PrometheusProto", "OpenMetricsText1.0.0", "OpenMetricsText0.0.1", "PrometheusText0.0.4"]
}

Thescrape_classic_histograms argument controls whether the component should also scrape the ‘classic’ histogram equivalent of a native histogram, if it’s present. It’s an equivalent to the always_scrape_classic_histograms argument in Prometheus v3.

Example

Set up scrape jobs for `blackbox exporter` targets

The following example sets up the scrape job with certain attributes (scrape endpoint, scrape interval, query parameters) and lets it scrape two instances of the blackbox exporter. The exposed metrics are sent over to the provided list of receivers, as defined by other components.

prometheus.scrape "blackbox_scraper" {
  targets = [
    {"__address__" = "blackbox-exporter:9115", "instance" = "one"},
    {"__address__" = "blackbox-exporter:9116", "instance" = "two"},
  ]

  forward_to = [prometheus.remote_write.grafanacloud.receiver, prometheus.remote_write.onprem.receiver]

  scrape_interval = "10s"
  params          = { "target" = ["grafana.com"], "module" = ["http_2xx"] }
  metrics_path    = "/probe"
}

The endpoints that are being scraped every 10 seconds are:

http://blackbox-exporter:9115/probe?target=grafana.com&module=http_2xx
http://blackbox-exporter:9116/probe?target=grafana.com&module=http_2xx

Authentication with the Kubernetes API server

The following example shows you how to authenticate with the Kubernetes API server.

prometheus.scrape "kubelet" {
        scheme = "https"
        tls_config {
            server_name = "kubernetes"
            ca_file = "/var/run/secrets/kubernetes.io/serviceaccount/ca.crt"
            insecure_skip_verify = false
        }
        bearer_token_file = "/var/run/secrets/kubernetes.io/serviceaccount/token"
}

Technical details

prometheus.scrape supports gzip compression.

The following special labels can change the behavior of prometheus.scrape:

__address__: The name of the label that holds the <host>:<port> address of a scrape target.
__metrics_path__: The name of the label that holds the path on which to scrape a target.
__param_<name>: A prefix for labels that provide URL parameters <name> used to scrape a target.
__scheme__: the name of the label that holds the protocol scheme (http, https) on which to scrape a target.
__scrape_interval__: The name of the label that holds the scrape interval used to scrape a target.
__scrape_timeout__: The name of the label that holds the scrape timeout used to scrape a target.

Special labels added after a scrape

__name__: The label name indicating the metric name of a timeseries.
instance: The label name used for the instance label.
job: The label name indicating the job from which a timeseries was scraped.

Compatible components

prometheus.scrape can accept arguments from the following components:

Components that export Targets
Components that export Prometheus MetricsReceiver

Note
Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.

prometheus.write.queue

Mon, 13 Apr 2026 07:37:47 +0000

`prometheus.write.queue`

EXPERIMENTAL: This is an experimental component. Experimental components are subject to frequent breaking changes, and may be removed with no equivalent replacement. To enable and use an experimental component, you must set the stability.level flag to experimental.

prometheus.write.queue collects metrics sent from other components into a Write-Ahead Log (WAL) and forwards them over the network to a series of user-supplied endpoints. Metrics are sent over the network using the Prometheus Remote Write protocol.

Note
Starting with Alloy v1.14, prometheus.write.queue is deprecated. It will be removed in a future release. Use prometheus.remote_write instead.

You can specify multiple prometheus.write.queue components by giving them different labels.

Usage

prometheus.write.queue "<LABEL>" {
  endpoint "default" {
    url = "<REMOTE_WRITE_URL>"

    ...
  }

  ...
}

Arguments

You can use the following argument with prometheus.write.queue:

Name	Type	Description	Default	Required
`ttl`	`duration`	How long the samples can be queued for before they’re discarded.	`"2h"`	no

Blocks

You can use the following blocks with prometheus.write.queue:

Name	Description	Required
`target`	Configures a blackbox target.	no

`endpoint`

The endpoint block describes a single location to send metrics to. Multiple endpoint blocks can be provided to send metrics to multiple locations. Each endpoint has its own WAL folder.

The following arguments are supported:

Name	Type	Description	Default	Required
`url`	`string`	Full URL to send metrics to.		yes
`batch_count`	`uint`	How many series to queue in each queue.	`1000`	no
`bearer_token`	`secret`	Bearer token to authenticate with.		no
`enable_round_robin`	`bool`	Use round robin load balancing when there are multiple IPs for a given endpoint.	`false`	no
`external_labels`	`map(string)`	Labels to add to metrics sent over the network.		no
`flush_interval`	`duration`	How long to wait until sending if `batch_count` isn’t triggered.	`"1s"`	no
`headers`	`map(secret)`	Custom HTTP headers to add to all requests sent to the server.		no
`max_retry_attempts`	`uint`	Maximum number of retries before dropping the batch.	`0`	no
`metadata_cache_enabled`	`bool`	Enables an LRU cache for tracking Metadata to support sparse metadata sending.	`false`	no
`metadata_cache_size`	`uint`	Maximum number of metadata entries to keep in cache to track what has been sent.	`1000`	no
`protobuf_message`	`string`	Protobuf message format to use for remote write.	`"prometheus.WriteRequest"`	no
`proxy_url`	`string`	URL of the HTTP proxy to use for requests.		no
`proxy_from_environment`	`bool`	Whether to read proxy configuration from environment variables.	`false`	no
`proxy_connect_headers`	`map(secret)`	HTTP headers to send to proxies during CONNECT requests.		no
`retry_backoff`	`duration`	How long to wait between retries.	`"1s"`	no
`write_timeout`	`duration`	Timeout for requests made to the URL.	`"30s"`	no

protobuf_message must be prometheus.WriteRequest or io.prometheus.write.v2.Request. These values represent prometheus remote write protocol versions 1 and 2.

‘metadata_cache_enabled’ and metadata_cache_size are only relevant when using io.prometheus.write.v2.Request, and is intended to reduce the frequency of metadata sending to reduce overall network traffic. A larger cache_size will consume more memory, but if you are sending many different metrics will also reduce how frequently metadata is sent with samples.

`basic_auth`

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

`tls_config`

Name	Type	Description	Required
`ca_pem`	`string`	CA PEM-encoded text to validate the server with.	no
`cert_pem`	`string`	Certificate PEM-encoded text for client authentication.	no
`insecure_skip_verify`	`bool`	Disables validation of the server certificate.	no
`key_pem`	`secret`	Key PEM-encoded text for client authentication.	no

`parallelism`

Name	Type	Description	Default	Required
`allowed_network_error_fraction`	`float`	The allowed error rate before scaling down. For example `0.50` allows 50% error rate.	`0.50`	no
`desired_check_interval`	`duration`	The length of time between checking for desired connections.	`"5s"`	no
`desired_connections_lookback`	`duration`	The length of time that previous desired connections are kept for determining desired connections.	`"5m"`	no
`drift_scale_down`	`duration`	The minimum amount of time between the timestamps of incoming signals and outgoing signals before decreasing desired connections.	`"30s"`	no
`drift_scale_up`	`duration`	The maximum amount of time between the timestamps of incoming signals and outgoing signals before increasing desired connections.	`"60s"`	no
`max_connections`	`uint`	The maximum number of desired connections.	`50`	no
`min_connections`	`uint`	The minimum number of desired connections.	`2`	no
`network_flush_interval`	`duration`	The length of time that network successes and failures are kept for determining desired connections.	`"1m"`	no

Parallelism determines when to scale up or down the number of desired connections.

The drift between the incoming and outgoing timestamps determines whether to increase or decrease the desired connections. The value stays the same if the drift is between drift_scale_up_seconds and drift_scale_down_seconds.

Network successes and failures are recorded and kept in memory. This data helps determine the nature of the drift. For example, if the drift is increasing and the network failures are increasing, the desired connections shouldn’t increase because that would increase the load on the endpoint.

The desired_check_interval prevents connection flapping. Each time a desired connection is calculated, the connection is added to a lookback buffer. Before increasing or decreasing the desired connections, prometheus.write.queue chooses the highest value in the lookback buffer. For example, for the past 5 minutes, the desired connections have been: [2,1,1]. The check determines that the desired connections are 1, and the number of desired connections won’t change because the value 2 is still in the lookback buffer. On the next check, the desired connections are [1,1,1]. Since the 2 value has expired, the desired connections change to 1. In general, the system is fast to increase and slow to decrease the desired connections.

`persistence`

The persistence block describes how often and at what limits to write to disk. Persistence settings are shared for each endpoint.

The following arguments are supported:

Name	Type	Description	Default	Required
`batch_interval`	`duration`	How often to batch signals to disk if `max_signals_to_batch` isn’t reached.	`"5s"`	no
`max_signals_to_batch`	`uint`	The maximum number of signals before they’re batched to disk.	`10000`	no

Exported fields

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

Name	Type	Description
`receiver`	`MetricsReceiver`	A value that other components can use to send metrics to.

Component health

prometheus.write.queue is only reported as unhealthy if given an invalid configuration. In those cases, exported fields are kept at their last healthy values.

Debug information

prometheus.write.queue doesn’t expose any component-specific debug information.

Debug metrics

The following metrics are provided for backward compatibility. They generally behave the same, but there are likely edge cases where they differ.

prometheus_remote_storage_metadata_failed_total (counter): Total number of metadata entries that failed to send to remote storage due to non-recoverable errors.
prometheus_remote_storage_metadata_retried_total (counter): Total number of metadata entries that failed to send to remote storage but were retried due to recoverable errors.
prometheus_remote_storage_metadata_total (counter): Total number of metadata entries sent to remote storage.
prometheus_remote_storage_queue_highest_sent_timestamp_seconds (gauge): Unix timestamp of the latest WAL sample successfully sent by a queue.
prometheus_remote_storage_highest_timestamp_in_seconds TODO

prometheus_remote_storage_samples_failed_total (counter): Total number of samples that failed to send to remote storage due to non-recoverable errors.

prometheus_remote_storage_samples_retried_total (counter): Total number of samples that failed to send to remote storage but were retried due to recoverable errors.
prometheus_remote_storage_samples_total (counter): Total number of samples sent to remote storage.
prometheus_remote_storage_sent_batch_duration_seconds (histogram): Duration of send calls to remote storage.

prometheus_remote_storage_bytes_total (counter): Total number of bytes of data sent by queues after compression.
prometheus_remote_storage_sent_bytes_total (counter): Total number of bytes of data sent by queues after compression. (same as prometheus_remote_storage_bytes_total)
prometheus_remote_storage_sent_batch_duration_seconds (histogram): Duration of send calls to remote storage.
prometheus_remote_storage_shards_max (gauge): The maximum number of a shards a queue is allowed to run.
prometheus_remote_storage_shards_min (gauge): The minimum number of shards a queue is allowed to run.
prometheus_remote_storage_shards (gauge): The number of shards used for concurrent delivery of metrics to an endpoint.

Metrics that are new to prometheus.write.queue. These are highly subject to change.

alloy_queue_metadata_network_sent_total (counter): Number of metadata sent successfully.
alloy_queue_metadata_serializer_errors_total (counter): Number of errors for metadata written to serializer.
alloy_queue_metadata_serializer_incoming_signals_total (counter): Total number of metadata written to serialization.
alloy_queue_metadata_network_failed_total (counter): Number of metadata failed.
alloy_queue_metadata_network_duration_seconds (histogram): Duration writing metadata to endpoint.
alloy_queue_metadata_network_errors_total (counter): Number of errors writing metadata to network.
alloy_queue_metadata_network_retried_429_total (counter): Number of metadata retried due to status code 429.
alloy_queue_metadata_network_retried_5xx_total (counter): Number of metadata retried due to status code 5xx.
alloy_queue_metadata_network_retried_total (counter): Number of metadata retried due to network issues.
alloy_queue_series_network_failed_total (counter): Number of series failed.
alloy_queue_series_network_duration_seconds (histogram): Duration writing series to endpoint.
alloy_queue_series_network_errors_total (counter): Number of errors writing series to network.
alloy_queue_series_network_retried_429_total (counter): Number of series retried due to status code 429.
alloy_queue_series_network_retried_5xx_total (counter): Number of series retried due to status code 5xx.
alloy_queue_series_network_retried_total (counter): Number of series retried due to network issues.
alloy_queue_series_network_sent_total (counter): Number of series sent successfully.
alloy_queue_series_network_timestamp_seconds (gauge): Highest timestamp written to an endpoint.
alloy_queue_series_serializer_errors_total (counter): Number of errors for series written to serializer.
alloy_queue_series_serializer_incoming_signals_total (counter): Total number of series written to serialization.
alloy_queue_series_serializer_incoming_exemplars_total (counter): Total number of exemplars written to serialization.
alloy_queue_series_serializer_incoming_timestamp_seconds (gauge): Highest timestamp of incoming series.
alloy_queue_series_disk_compressed_bytes_read_total (counter): Total number of compressed bytes read from disk.
alloy_queue_series_disk_compressed_bytes_written_total (counter): Total number of compressed bytes written to disk.
alloy_queue_series_disk_uncompressed_bytes_read_total (counter): Total number of uncompressed bytes read from disk.
alloy_queue_series_disk_uncompressed_bytes_written_total (counter): Total number of uncompressed bytes written to disk.
alloy_queue_series_file_id_written (gauge): Current file id written, file id being a numeric number.
alloy_queue_series_file_id_read (gauge): Current file id read, file id being a numeric number.

Examples

The following examples show you how to create prometheus.write.queue components that send metrics to different destinations.

Send metrics to a local Mimir instance

You can create a prometheus.write.queue component that sends your metrics to a local Mimir instance:

prometheus.write.queue "staging" {
  // Send metrics to a locally running Mimir.
  endpoint "mimir" {
    url = "http://mimir:9009/api/v1/push"

    basic_auth {
      username = "example-user"
      password = "example-password"
    }
  }
}

// Configure a prometheus.scrape component to send metrics to
// prometheus.write.queue component.
prometheus.scrape "demo" {
  targets = [
    // Collect metrics from the default HTTP listen address.
    {"__address__" = "127.0.0.1:12345"},
  ]
  forward_to = [prometheus.write.queue.staging.receiver]
}

Technical details

prometheus.write.queue uses zstd for compression. prometheus.write.queue sends native histograms by default. Any labels that start with __ will be removed before sending to the endpoint.

Data retention

Data is written to disk in blocks utilizing zstd compression. These blocks are read on startup and resent if they’re still within the TTL. Any data that hasn’t been written to disk, or that’s in the network queues is lost if Alloy is restarted.

Retries

prometheus.write.queue retries sending data if the following errors or HTTP status codes are returned:

Network errors.
HTTP 429 errors.
HTTP 5XX errors.

prometheus.write.queue won’t retry sending data if any other unsuccessful status codes are returned.

Memory

prometheus.write.queue is meant to be memory efficient. You can adjust the max_signals_to_batch, parallelism, and batch_size to control how much memory is used. A higher max_signals_to_batch allows for more efficient disk compression. A higher parallelism allows more parallel writes, and batch_size allows more data sent at one time. This can allow greater throughput at the cost of more memory on both Alloy and the endpoint. The defaults are suitable for most common usages.

Compatible components

prometheus.write.queue has exports that can be consumed by the following components:

Components that consume Prometheus MetricsReceiver

Note
Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.

prometheus on Grafana Labs

prometheus.echo

prometheus.echo

Usage

Arguments

Blocks

Exported fields

Component health

Debug information

Debug metrics

Example

Example with OpenMetrics format

Compatible components

prometheus.enrich

prometheus.enrich

Usage

Arguments

Blocks

Exports

Debug information

Debug metrics

Example

Enrich metrics from prometheus.scrape

Enrich metrics from prometheus.receive_http

Compatible components

prometheus.exporter.apache

prometheus.exporter.apache

Usage

Arguments

Blocks

Exported fields

Component health

Debug information

Debug metrics

Example

Compatible components

prometheus.exporter.azure

prometheus.exporter.azure

Authentication

Usage

Arguments

Blocks

Exported fields

Component health

Debug information

Debug metrics

Examples

Compatible components

prometheus.exporter.blackbox

prometheus.exporter.blackbox

Usage

Arguments

Blocks

target

Exported fields

Component health

Debug information

Debug metrics

Examples

Collect metrics using a blackbox exporter configuration file

Collect metrics using an embedded configuration

Collect metrics from a dynamic set of targets

Set instance label to target URL

Compatible components

prometheus.exporter.cadvisor

prometheus.exporter.cadvisor

Usage

Arguments

Blocks

Exported fields

Component health

Debug information

Debug metrics

Examples

Component configuration

Docker deployment example

Kubernetes Deployment example

Compatible components

prometheus.exporter.catchpoint

prometheus.exporter.catchpoint

`prometheus.echo`

`prometheus.enrich`

Enrich metrics from `prometheus.scrape`

Enrich metrics from `prometheus.receive_http`

`prometheus.exporter.apache`

`prometheus.exporter.azure`

`prometheus.exporter.blackbox`

`target`

`prometheus.exporter.cadvisor`

`prometheus.exporter.catchpoint`

`prometheus.exporter.cloudwatch`

`discovery`

`static`

`custom_namespace`

`metric`

`period` and `length`

`role`

`decoupled_scraping`

`prometheus.exporter.consul`

`prometheus.exporter.databricks`

`prometheus.exporter.dnsmasq`

`prometheus.exporter.elasticsearch`