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

# `prometheus.exporter.process`

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

> Note
> 
> We do not recommend using this exporter with [clustering](../../../../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.

## Usage

Alloy ![Copy code to clipboard](/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 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`:

No valid configuration blocks found.

### `matcher`

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

Expand table

| 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/&lt;pid&gt;/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.

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](../../../../get-started/component_controller/#in-memory-traffic) address specified by the [run command](../../../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`](../prometheus.scrape/) component to collect metrics from `prometheus.exporter.process`:

Alloy ![Copy code to clipboard](/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](../../../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.