---
title: "prometheus.exporter.process | Grafana Cloud documentation"
description: "Learn about prometheus.exporter.process"
---

> For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt).

# `prometheus.exporter.process`

The `prometheus.exporter.process` component embeds the [`process_exporter`](https://github.com/ncabatoff/process-exporter) to collect process stats from `/proc`.

> Note
> 
> We do not recommend using this exporter with [clustering](https://grafana.com/docs/grafana-cloud/send-data/alloy/get-started/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.process` component only works on Linux systems. On other operating systems, Alloy writes a warning to the logs and the component doesn’t collect process metrics.

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

## Usage

Alloy ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

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

## Arguments

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

Expand table

| Name                  | Type     | Description                                                                                         | Default   | Required |
|-----------------------|----------|-----------------------------------------------------------------------------------------------------|-----------|----------|
| `gather_smaps`        | `bool`   | Gather proportional memory metrics for a process from the smaps files.                              | `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`   | Remove process groups that contain no processes.                                                    | `false`   | no       |
| `track_children`      | `bool`   | Track children of a tracked process in the same group, unless a child belongs to a different group. | `true`    | no       |
| `track_threads`       | `bool`   | Report metrics for each thread name in addition to each group name.                                 | `true`    | no       |

If you set `remove_empty_groups` to the default, `false`, the process “groups” that the `matcher` blocks create 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 based on specific PIDs. The reporting continues until you restart Alloy.

When you set `remove_empty_groups` to `true`, the component drops a process group and stops reporting metrics for it when the group contains no running processes. Grafana recommends that you set `remove_empty_groups` to `true` if your `name` argument uses unique identifiers like `.PID` or `.StartTime`.

For example, if you set `remove_empty_groups` to `false` and the `name` argument for a `matcher` block uses the `.PID` of a process, the `matcher` creates a separate process group for every process instance. Groups whose processes have exited continue to report metrics with values of 0, which leads to high cardinality. Set `remove_empty_groups` to `true` so the component removes those groups and prevents the high cardinality.

The component sets the `instance` label on its exported targets to the `HOSTNAME` environment variable. If `HOSTNAME` isn’t set, the component uses the operating system hostname, or `unknown` if it can’t determine one.

## Blocks

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

No valid configuration blocks found.

### `matcher`

Each `matcher` block can match multiple processes, which the component tracks as a single process “group.”

You can use the following arguments with the `matcher` block:

Expand table

| Name      | Type           | Description                                                                                      | Default          | Required |
|-----------|----------------|--------------------------------------------------------------------------------------------------|------------------|----------|
| `cmdline` | `list(string)` | A list of regular expressions, each matched against the corresponding element of `argv`.         |                  | 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 the process group in metrics.                                                | `"{{.ExeBase}}"` | no       |

Each `matcher` block must set at least one of `cmdline`, `comm`, or `exe`. If you set none of them, the component fails with an invalid configuration error.

The component derives the value for matching `comm` list elements from the second field of `/proc/<pid>/stat`, with the parentheses removed.

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 component tracks the process.

The component matches each regular expression in `cmdline` against the corresponding element of `argv`, starting at `argv[1]`. The first regular expression matches `argv[1]`, the second matches `argv[2]`, and so on. Every regular expression must match its corresponding element before the component tracks the process. The component adds named regular expression captures, for example `(?P<version>[0-9]+)`, to the `.Matches` map for use in `name`.

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}}`: A map of the named capture groups from the `cmdline` regular expressions.
- `{{.PID}}`: PID of the process. The component copies the PID from the first executable found.
- `{{.StartTime}}`: The start time of the process. This is useful with `PID`, because PIDs get reused over time.
- `{{.Cgroups}}`: The cgroups of the process, from `/proc/self/cgroup`, if supported. This is particularly useful for identifying which container a process belongs to.

> Note
> 
> Avoid `PID` and `StartTime`. They’re almost never what you want, and they’re likely to result in high cardinality metrics.

## Exported fields

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

Expand table

| 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](https://grafana.com/docs/grafana-cloud/send-data/alloy/get-started/component_controller/#in-memory-traffic) address specified by the [run command](https://grafana.com/docs/grafana-cloud/send-data/alloy/reference/cli/run/).

## 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`](https://grafana.com/docs/grafana-cloud/send-data/alloy/reference/components/prometheus/prometheus.scrape) component to collect metrics from `prometheus.exporter.process`:

Alloy ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

```alloy
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](https://grafana.com/docs/grafana-cloud/send-data/alloy/reference/compatibility/#targets-consumers)

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