Documentation Grafana Cloud Instrument and send data Grafana Alloy Reference Components prometheus prometheus.exporter.process

prometheus.exporter.process

The prometheus.exporter.process component embeds the process_exporter to collect process stats from /proc.

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

Usage

Alloy Copy

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

Arguments

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

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:

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:

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.

Exported fields

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:

Alloy Copy

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