Sysdig Documentation

Include/Exclude Processes

In addition to filtering data by container, it is also possible to filter independently by process. Broadly speaking, this refinement helps ensure that relevant data is reported while noise is reduced. More specifically, use cases for process filtering may include: 

  • Wanting to alert reliably whenever a given process goes down.  The total number of processes can exceed the reporting limit; when that happens, some processes are not reported. In this case, an unreported process could be misinterpreted as being "down." Specify a filter for 30-40 processes to guarantee that they will always be reported.

  • Wanting to limit the number of noisy but inessential processes being reported, for example: sed, awk, grep, and similar tools that may be used infrequently.

  • Wanting to prioritize workload-specific processes, perhaps from integrated applications such as NGINX, Supervisord or PHP-FPM.

Note

Note that you can report on processes and containers independently; the including/excluding of one does not affect the including/excluding of the other.

Prerequisites_Processes

This feature requires the following Sysdig  component versions: 

  • Sysdig agent version 0.91 or higher

  • For on-premises installations: version 3.2.0.2540 or higher

Understand Process Filtering Behavior

By default, processes are reported according to internal criteria such as resource usage (CPU/memory/file and net IO) and container count.

If you choose to enable process filtering, processes in the include list will be given preference over other internal criteria.

Processes are filtered based on a standard priority filter description already used in Sysdig yaml files. It is comprised of -include and -exclude statements which are matched in order, with evaluation ceasing with the first matched statement. Statements are considered matched if EACH of the conditions in the statement is met.

Use Process Filtering

Edit dragent.yaml per the following patterns to implement the filtering you need.

Process Condition Parameters and Rules

The process: condition parameters and rules are described below.

Table 1. The process: Condition Parameters

Name

Value

Description

app_checks_always_send:

true/false

Legacy config that causes the agent to emit any process with app check. With process filtering, this translates to an extra "include" clause at the head of the process filter which matches a process with any app check, thereby overriding any exclusions. Still subject to limit.

flush_filter:

Definition of process filter to be used if flush_filter_enabled == true. Defaults to -include all

flush_filter_enabled:

true/false

Defaults to false (default process reporting behavior). Set to true to use the rest of the process filtering options.

limit:

N (chosen number)

Defines the approximate limit of processes to emit to the backend, within 10 processes or so. Default is 250 processes.

top_n_per_container:

N (chosen number)

Defines how many of the top processes per resource category per emitted container to report after included processes. Still subject to limit. Defaults to 1.

top_n_per_host:

N (chosen number)

Defines how many of the top processes per resource category per host are reported before included processes. Still subject to limit. Defaults to 1.



Rules

  • container.image: my_container_image  Validates whether the container image associated with the process is a wild card match of the provided image name

  • container.name: my_container_name  Validates whether the container name associated with the process is a wild card match of the provided image name

  • container.label.XYZ: value  Validates whether the label XYZ of the container associated with the process is a wildcard match of the provided value

  • process.name: my_process_name  Validates whether the name of the process is a wild card match of the provided value

  • process.cmdline: value  Checks whether the executable name of a process contains the specified value, or any argument to the process is a wildcard match of the provided value

  • appcheck.match: value  Checks whether the process has any appcheck which is a wildcard match of the given value

  • all  Matches all processes, but does not whitelist them, nor does it blacklist them. If no filter is provided, the default is -include all. However, if a filter is provided and no match is made otherwise, then all unmatched processes will be blacklisted. In most cases, the definition of a process filter should end with -include: all.

Examples

Block All Processes from a Container

Block all processes from a given container. No processes from some_container_name will be reported.

process:
  flush_filter:
  - exclude:
      container.name: "some_container_name"
  - include:
      allprocess:   flush_filter: - exclude: container.name: "some_container_name" - include: all

Prioritize Processes from a Container

Send all processes from a given container at high priority.

process:
  flush_filter:
    - include:
        container.name: "some_container_name"
    - include:
        all

Prioritize "java" Processes

Send all processes that contain 'java" in the name at high priority.

process:
  flush_filter:
    - include:
        process.name: "*java*"
    - include:
        all

Prioritize "java" Processes from a Particular Container

Send processes containing "java" from a given container at high priority.

process:
  flush_filter:
    - include:
       container.name: "some_container_name"
       process.name: "*java*"
    - include
        all

Prioritize "java" Processes not in a Particular Container

Send all processes that contain "java" in the name that are not in container some_container_nane.

process:
  flush_filter:
    - exclude:
        container.name: "some_container_name"
    - include:
        process.name: "*java*"
    - include:
        all

Prioritize "java" Processes even from an Excluded Container

Send all processes containing "java" in the name. If a process does not contain "java" in the name and if the container within which the process runs is named  some_container_name,  then exclude it.

Note that each include/exclude rule is handled sequentially and hierarchically so that even if the container is excluded, it can still report "java" processes.

flush_filter:
   - include:
       process.name: "*java*"
   - exclude:
      container.name: "some_container_name"
   - include:
      all

Prioritize "java" Processes and "sql" Processes from Different Containers

Send java processes from one container and sql processes from another at high priority.

process:
  flush_filter:
    - include:
       container.name: "java_container_name"
       process.name: "*java*"
    - include
       container.name: "sql_container_name"
       process.name: "*sql*"
    - include
        all

Report ONLY Processes in a Particular Container

Only send processes running in a container with a given label.

process:
  flush_filter:
     - include:
 =container.label.report_processes_from_this_container_example_label: true
     - exclude:
         all