Menu

Caution

Grafana Alloy is the new name for our distribution of the OTel collector. Grafana Agent has been deprecated and is in Long-Term Support (LTS) through October 31, 2025. Grafana Agent will reach an End-of-Life (EOL) on November 1, 2025. Read more about why we recommend migrating to Grafana Alloy.

Important: This documentation is about an older version. It's relevant only to the release noted, many of the features and functions have been updated or replaced. Please view the current version.

Open source

discovery.process

BETA: This is a beta component. Beta components are subject to breaking changes, and may be replaced with equivalent functionality that cover the same use case.

discovery.process discovers processes running on the local Linux OS.

Note

To use the discovery.process component you must run Grafana Agent Flow as root and inside host PID namespace.

Usage

river
discovery.process "LABEL" {

}

Arguments

The following arguments are supported:

NameTypeDescriptionDefaultRequired
joinlist(map(string))Join external targets to discovered processes targets based on __container_id__ label.no
refresh_intervaldurationHow often to sync targets.“60s”no

Targets joining

If join is specified, discovery.process will join the discovered processes based on the __container_id__ label.

For example, if join is specified as follows:

json
[
  {
    "pod": "pod-1",
    "__container_id__": "container-1"
  },
  {
    "pod": "pod-2",
    "__container_id__": "container-2"
  }
]

And the discovered processes are:

json
[
  {
    "__process_pid__": "1",
    "__container_id__": "container-1"
  },
  {
    "__process_pid__": "2"
  }
]

The resulting targets are:

json
[
  {
    "__container_id__": "container-1",
    "__process_pid__": "1",
    "pod": "pod-1"
  },
  {
    "__process_pid__": "2"
  },
  {
    "__container_id__": "container-1",
    "pod": "pod-1"
  },
  {
    "__container_id__": "container-2",
    "pod": "pod-2"
  }
]

Blocks

The following blocks are supported inside the definition of discovery.process:

HierarchyBlockDescriptionRequired
discover_configdiscover_configConfigures which process metadata to discover.no

discover_config block

The discover_config block describes which process metadata to discover.

The following arguments are supported:

NameTypeDescriptionDefaultRequired
exeboolA flag to enable discovering __meta_process_exe label.trueno
cwdboolA flag to enable discovering __meta_process_cwd label.trueno
commandlineboolA flag to enable discovering __meta_process_commandline label.trueno
uidboolA flag to enable discovering __meta_process_uid: label.trueno
usernameboolA flag to enable discovering __meta_process_username: label.trueno
container_idboolA flag to enable discovering __container_id__ label.trueno

Exported fields

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

NameTypeDescription
targetslist(map(string))The set of processes discovered on the local Linux OS.

Each target includes the following labels:

  • __process_pid__: The process PID.
  • __meta_process_exe: The process executable path. Taken from /proc/<pid>/exe.
  • __meta_process_cwd: The process current working directory. Taken from /proc/<pid>/cwd.
  • __meta_process_commandline: The process command line. Taken from /proc/<pid>/cmdline.
  • __meta_process_uid: The process UID. Taken from /proc/<pid>/status.
  • __meta_process_username: The process username. Taken from __meta_process_uid and os/user/LookupID.
  • __container_id__: The container ID. Taken from /proc/<pid>/cgroup. If the process is not running in a container, this label is not set.

Component health

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

Debug information

discovery.process does not expose any component-specific debug information.

Debug metrics

discovery.process does not expose any component-specific debug metrics.

Examples

Example discovering processes on the local host

river
discovery.process "all" {
  refresh_interval = "60s"
  discover_config {
    cwd = true
    exe = true
    commandline = true
    username = true
    uid = true
    container_id = true
  }
}

Example discovering processes on the local host and joining with discovery.kubernetes

river
discovery.kubernetes "pyroscope_kubernetes" {
  selectors {
    field = "spec.nodeName=" + env("HOSTNAME")
    role = "pod"
  }
  role = "pod"
}

discovery.process "all" {
  join = discovery.kubernetes.pyroscope_kubernetes.targets
  refresh_interval = "60s"
  discover_config {
    cwd = true
    exe = true
    commandline = true
    username = true
    uid = true
    container_id = true
  }
}

Compatible components

discovery.process can accept arguments from the following components:

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

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.