Menu
Grafana Cloud

discovery.process

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

Note

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

Usage

alloy
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

alloy
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

alloy
discovery.kubernetes "pyroscope_kubernetes" {
  selectors {
    field = "spec.nodeName=" + sys.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.