procstat

package
v1.32.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 9, 2024 License: MIT Imports: 27 Imported by: 187

README

Procstat Input Plugin

The procstat plugin can be used to monitor the system resource usage of one or more processes. The procstat_lookup metric displays the query information, specifically the number of PIDs returned on a search

Processes can be selected for monitoring using one of several methods:

  • pidfile
  • exe
  • pattern
  • user
  • systemd_unit
  • cgroup
  • supervisor_unit
  • win_service

Global configuration options

In addition to the plugin-specific configuration settings, plugins support additional global and plugin configuration settings. These settings are used to modify metrics, tags, and field or create aliases and configure ordering, etc. See the CONFIGURATION.md for more details.

Configuration

# Monitor process cpu and memory usage
[[inputs.procstat]]
  ## PID file to monitor process
  pid_file = "/var/run/nginx.pid"
  ## executable name (ie, pgrep <exe>)
  # exe = "nginx"
  ## pattern as argument for pgrep (ie, pgrep -f <pattern>)
  # pattern = "nginx"
  ## user as argument for pgrep (ie, pgrep -u <user>)
  # user = "nginx"
  ## Systemd unit name, supports globs when include_systemd_children is set to true
  # systemd_unit = "nginx.service"
  # include_systemd_children = false
  ## CGroup name or path, supports globs
  # cgroup = "systemd/system.slice/nginx.service"
  ## Supervisor service names of hypervisorctl management
  # supervisor_units = ["webserver", "proxy"]

  ## Windows service name
  # win_service = ""

  ## override for process_name
  ## This is optional; default is sourced from /proc/<pid>/status
  # process_name = "bar"

  ## Field name prefix
  # prefix = ""

  ## Mode to use when calculating CPU usage. Can be one of 'solaris' or 'irix'.
  # mode = "irix"

  ## Add the given information tag instead of a field
  ## This allows to create unique metrics/series when collecting processes with
  ## otherwise identical tags. However, please be careful as this can easily
  ## result in a large number of series, especially with short-lived processes,
  ## creating high cardinality at the output.
  ## Available options are:
  ##   cmdline   -- full commandline
  ##   pid       -- ID of the process
  ##   ppid      -- ID of the process' parent
  ##   status    -- state of the process
  ##   user      -- username owning the process
  ## socket only options:
  ##   protocol  -- protocol type of the process socket
  ##   state     -- state of the process socket
  ##   src       -- source address of the process socket (non-unix sockets)
  ##   src_port  -- source port of the process socket (non-unix sockets)
  ##   dest      -- destination address of the process socket (non-unix sockets)
  ##   dest_port -- destination port of the process socket (non-unix sockets)
  ##   name      -- name of the process socket (unix sockets only)
  # tag_with = []

  ## Properties to collect
  ## Available options are
  ##   cpu     -- CPU usage statistics
  ##   limits  -- set resource limits
  ##   memory  -- memory usage statistics
  ##   mmap    -- mapped memory usage statistics (caution: can cause high load)
  ##   sockets -- socket statistics for protocols in 'socket_protocols'
  # properties = ["cpu", "limits", "memory", "mmap"]

  ## Protocol filter for the sockets property
  ## Available options are
  ##   all  -- all of the protocols below
  ##   tcp4 -- TCP socket statistics for IPv4
  ##   tcp6 -- TCP socket statistics for IPv6
  ##   udp4 -- UDP socket statistics for IPv4
  ##   udp6 -- UDP socket statistics for IPv6
  ##   unix -- Unix socket statistics
  # socket_protocols = ["all"]

  ## Method to use when finding process IDs.  Can be one of 'pgrep', or
  ## 'native'.  The pgrep finder calls the pgrep executable in the PATH while
  ## the native finder performs the search directly in a manor dependent on the
  ## platform.  Default is 'pgrep'
  # pid_finder = "pgrep"

  ## New-style filtering configuration (multiple filter sections are allowed)
  # [[inputs.procstat.filter]]
  #    ## Name of the filter added as 'filter' tag
  #    name = "shell"
  #
  #    ## Service filters, only one is allowed
  #    ## Systemd unit names (wildcards are supported)
  #    # systemd_units = []
  #    ## CGroup name or path (wildcards are supported)
  #    # cgroups = []
  #    ## Supervisor service names of hypervisorctl management
  #    # supervisor_units = []
  #    ## Windows service names
  #    # win_service = []
  #
  #    ## Process filters, multiple are allowed
  #    ## Regular expressions to use for matching against the full command
  #    # patterns = ['.*']
  #    ## List of users owning the process (wildcards are supported)
  #    # users = ['*']
  #    ## List of executable paths of the process (wildcards are supported)
  #    # executables = ['*']
  #    ## List of process names (wildcards are supported)
  #    # process_names = ['*']
  #    ## Recursion depth for determining children of the matched processes
  #    ## A negative value means all children with infinite depth
  #    # recursion_depth = 0
Windows support

Preliminary support for Windows has been added, however you may prefer using the win_perf_counters input plugin as a more mature alternative.

Darwin specifics

If you use this plugin with supervisor_units and pattern on Darwin, you have to use the pgrep finder as the underlying library relies on pgrep.

Permissions

Some files or directories may require elevated permissions. As such a user may need to provide telegraf with higher levels of permissions to access and produce metrics.

Metrics

For descriptions of these tags and fields, consider reading one of the following:

Below are an example set of tags and fields:

  • procstat
    • tags:
      • pid (if requested)
      • cmdline (if requested)
      • process_name
      • pidfile (when defined)
      • exe (when defined)
      • pattern (when defined)
      • user (when selected)
      • systemd_unit (when defined)
      • cgroup (when defined)
      • cgroup_full (when cgroup or systemd_unit is used with glob)
      • supervisor_unit (when defined)
      • win_service (when defined)
    • fields:
      • child_major_faults (int)
      • child_minor_faults (int)
      • created_at (int) [epoch in nanoseconds]
      • cpu_time (int)
      • cpu_time_iowait (float) (zero for all OSes except Linux)
      • cpu_time_system (float)
      • cpu_time_user (float)
      • cpu_usage (float)
      • disk_read_bytes (int, Linux only, telegraf may need to be ran as root)
      • disk_write_bytes (int, Linux only, telegraf may need to be ran as root)
      • involuntary_context_switches (int)
      • major_faults (int)
      • memory_anonymous (int)
      • memory_private_clean (int)
      • memory_private_dirty (int)
      • memory_pss (int)
      • memory_referenced (int)
      • memory_rss (int)
      • memory_shared_clean (int)
      • memory_shared_dirty (int)
      • memory_size (int)
      • memory_swap (int)
      • memory_usage (float)
      • memory_vms (int)
      • minor_faults (int)
      • nice_priority (int)
      • num_fds (int, telegraf may need to be ran as root)
      • num_threads (int)
      • pid (int)
      • ppid (int)
      • status (string)
      • read_bytes (int, telegraf may need to be ran as root)
      • read_count (int, telegraf may need to be ran as root)
      • realtime_priority (int)
      • rlimit_cpu_time_hard (int)
      • rlimit_cpu_time_soft (int)
      • rlimit_file_locks_hard (int)
      • rlimit_file_locks_soft (int)
      • rlimit_memory_data_hard (int)
      • rlimit_memory_data_soft (int)
      • rlimit_memory_locked_hard (int)
      • rlimit_memory_locked_soft (int)
      • rlimit_memory_rss_hard (int)
      • rlimit_memory_rss_soft (int)
      • rlimit_memory_stack_hard (int)
      • rlimit_memory_stack_soft (int)
      • rlimit_memory_vms_hard (int)
      • rlimit_memory_vms_soft (int)
      • rlimit_nice_priority_hard (int)
      • rlimit_nice_priority_soft (int)
      • rlimit_num_fds_hard (int)
      • rlimit_num_fds_soft (int)
      • rlimit_realtime_priority_hard (int)
      • rlimit_realtime_priority_soft (int)
      • rlimit_signals_pending_hard (int)
      • rlimit_signals_pending_soft (int)
      • signals_pending (int)
      • voluntary_context_switches (int)
      • write_bytes (int, telegraf may need to be ran as root)
      • write_count (int, telegraf may need to be ran as root)
  • procstat_lookup
    • tags:
      • exe
      • pid_finder
      • pid_file
      • pattern
      • prefix
      • user
      • systemd_unit
      • cgroup
      • supervisor_unit
      • win_service
      • result
    • fields:
      • pid_count (int)
      • running (int)
      • result_code (int, success = 0, lookup_error = 1)
  • procstat_socket (if configured, Linux only)
    • tags:
      • pid (if requested)
      • protocol (if requested)
      • cmdline (if requested)
      • process_name
      • pidfile (when defined)
      • exe (when defined)
      • pattern (when defined)
      • user (when selected)
      • systemd_unit (when defined)
      • cgroup (when defined)
      • cgroup_full (when cgroup or systemd_unit is used with glob)
      • supervisor_unit (when defined)
      • win_service (when defined)
    • fields:
      • protocol
      • state
      • pid
      • src
      • src_port (tcp and udp sockets only)
      • dest (tcp and udp sockets only)
      • dest_port (tcp and udp sockets only)
      • bytes_received (tcp sockets only)
      • bytes_sent (tcp sockets only)
      • lost (tcp sockets only)
      • retransmits (tcp sockets only)
      • rx_queue
      • tx_queue
      • inode (unix sockets only)

NOTE: Resource limit > 2147483647 will be reported as 2147483647.

Example Output

procstat_lookup,host=prash-laptop,pattern=influxd,pid_finder=pgrep,result=success pid_count=1i,running=1i,result_code=0i 1582089700000000000
procstat,host=prash-laptop,pattern=influxd,process_name=influxd,user=root involuntary_context_switches=151496i,child_minor_faults=1061i,child_major_faults=8i,cpu_time_user=2564.81,pid=32025i,major_faults=8609i,created_at=1580107536000000000i,voluntary_context_switches=1058996i,cpu_time_system=616.98,memory_swap=0i,memory_locked=0i,memory_usage=1.7797634601593018,num_threads=18i,cpu_time_iowait=0,memory_rss=148643840i,memory_vms=1435688960i,memory_data=0i,memory_stack=0i,minor_faults=1856550i 1582089700000000000
procstat_socket,host=prash-laptop,process_name=browser,protocol=tcp4 bytes_received=826987i,bytes_sent=32869i,dest="192.168.0.2",dest_port=443i,lost=0i,pid=32025i,retransmits=0i,rx_queue=0i,src="192.168.0.1",src_port=52106i,state="established",tx_queue=0i 1582089700000000000

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Filter added in v1.31.0 

type Filter struct {
	Name            string          `toml:"name"`
	PidFiles        []string        `toml:"pid_files"`
	SystemdUnits    []string        `toml:"systemd_units"`
	SupervisorUnits []string        `toml:"supervisor_units"`
	WinService      []string        `toml:"win_services"`
	CGroups         []string        `toml:"cgroups"`
	Patterns        []string        `toml:"patterns"`
	Users           []string        `toml:"users"`
	Executables     []string        `toml:"executables"`
	ProcessNames    []string        `toml:"process_names"`
	RecursionDepth  int             `toml:"recursion_depth"`
	Log             telegraf.Logger `toml:"-"`
	// contains filtered or unexported fields
}

func (*Filter) ApplyFilter added in v1.31.0 

func (f *Filter) ApplyFilter() ([]processGroup, error)

func (*Filter) Init added in v1.31.0 

func (f *Filter) Init() error

type NativeFinder added in v1.14.0 

type NativeFinder struct{}

NativeFinder uses gopsutil to find processes

func (*NativeFinder) Children added in v1.29.0 

func (pg *NativeFinder) Children(pid PID) ([]PID, error)

Children matches children pids on the command line when the process was executed

func (*NativeFinder) FastProcessList added in v1.14.5 

func (pg *NativeFinder) FastProcessList() ([]*process.Process, error)

func (*NativeFinder) FullPattern added in v1.14.0 

func (pg *NativeFinder) FullPattern(pattern string) ([]PID, error)

FullPattern matches on the command line when the process was executed

func (*NativeFinder) Pattern added in v1.14.0 

func (pg *NativeFinder) Pattern(pattern string) ([]PID, error)

Pattern matches on the process name

func (*NativeFinder) PidFile added in v1.14.0 

func (pg *NativeFinder) PidFile(path string) ([]PID, error)

PidFile returns the pid from the pid file given.

func (*NativeFinder) UID added in v1.18.0 

func (pg *NativeFinder) UID(user string) ([]PID, error)

Uid will return all pids for the given user

type PID added in v1.14.0 

type PID int32

type PIDFinder added in v1.14.0 

type PIDFinder interface {
	PidFile(path string) ([]PID, error)
	Pattern(pattern string) ([]PID, error)
	UID(user string) ([]PID, error)
	FullPattern(path string) ([]PID, error)
	Children(pid PID) ([]PID, error)
}

type Pgrep added in v1.14.0 

type Pgrep struct {
	// contains filtered or unexported fields
}

Implementation of PIDGatherer that execs pgrep to find processes

func (*Pgrep) Children added in v1.29.0 

func (pg *Pgrep) Children(pid PID) ([]PID, error)

func (*Pgrep) FullPattern added in v1.14.0 

func (pg *Pgrep) FullPattern(pattern string) ([]PID, error)

func (*Pgrep) Pattern added in v1.14.0 

func (pg *Pgrep) Pattern(pattern string) ([]PID, error)

func (*Pgrep) PidFile added in v1.14.0 

func (pg *Pgrep) PidFile(path string) ([]PID, error)

func (*Pgrep) UID added in v1.18.0 

func (pg *Pgrep) UID(user string) ([]PID, error)

type PidsTags added in v1.20.0 

type PidsTags struct {
	PIDs []PID
	Tags map[string]string
}

type Proc added in v1.14.0 

type Proc struct {
	*process.Process
	// contains filtered or unexported fields
}

func (*Proc) Metrics added in v1.32.0 

func (p *Proc) Metrics(prefix string, cfg *collectionConfig, t time.Time) ([]telegraf.Metric, error)

Add metrics a single Process

func (*Proc) PID added in v1.14.0 

func (p *Proc) PID() PID

func (*Proc) SetTag added in v1.29.0 

func (p *Proc) SetTag(k, v string)

type Process added in v1.14.0 

type Process interface {
	PID() PID
	Name() (string, error)
	SetTag(string, string)
	MemoryMaps(bool) (*[]process.MemoryMapsStat, error)
	Metrics(string, *collectionConfig, time.Time) ([]telegraf.Metric, error)
}

type Procstat 

type Procstat struct {
	PidFinder              string          `toml:"pid_finder"`
	PidFile                string          `toml:"pid_file"`
	Exe                    string          `toml:"exe"`
	Pattern                string          `toml:"pattern"`
	Prefix                 string          `toml:"prefix"`
	CmdLineTag             bool            `toml:"cmdline_tag" deprecated:"1.29.0;1.40.0;use 'tag_with' instead"`
	ProcessName            string          `toml:"process_name"`
	User                   string          `toml:"user"`
	SystemdUnit            string          `toml:"systemd_unit"`
	SupervisorUnit         []string        `toml:"supervisor_unit" deprecated:"1.29.0;1.40.0;use 'supervisor_units' instead"`
	SupervisorUnits        []string        `toml:"supervisor_units"`
	IncludeSystemdChildren bool            `toml:"include_systemd_children"`
	CGroup                 string          `toml:"cgroup"`
	PidTag                 bool            `toml:"pid_tag" deprecated:"1.29.0;1.40.0;use 'tag_with' instead"`
	WinService             string          `toml:"win_service"`
	Mode                   string          `toml:"mode"`
	Properties             []string        `toml:"properties"`
	SocketProtocols        []string        `toml:"socket_protocols"`
	TagWith                []string        `toml:"tag_with"`
	Filter                 []Filter        `toml:"filter"`
	Log                    telegraf.Logger `toml:"-"`
	// contains filtered or unexported fields
}

func (*Procstat) Gather 

func (p *Procstat) Gather(acc telegraf.Accumulator) error

func (*Procstat) Init added in v1.17.1 

func (p *Procstat) Init() error

func (*Procstat) SampleConfig 

func (*Procstat) SampleConfig() string

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.