Version: v1.28.1 Latest Latest

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

Go to latest
Published: Sep 12, 2023 License: MIT Imports: 16 Imported by: 176


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
  • 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 for more details.


# Monitor process cpu and memory usage
  ## PID file to monitor process
  pid_file = "/var/run/"
  ## 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"

  ## 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 = ""

  ## When true add the full cmdline as a tag.
  # cmdline_tag = false

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

  ## Add the PID as a tag instead of as a field.  When collecting multiple
  ## processes with otherwise matching tags this setting should be enabled to
  ## ensure each process has a unique identity.
  ## Enabling this option may result in a large number of series, especially
  ## when processes have a short lifetime.
  # pid_tag = false

  ## 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"
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.


  • procstat
    • tags:
      • pid (when pid_tag is true)
      • cmdline (when 'cmdline_tag' is true)
      • 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)
      • win_service (when defined)
    • fields:
      • child_major_faults (int)
      • child_minor_faults (int)
      • created_at (int) [epoch in nanoseconds]
      • cpu_time (int)
      • cpu_time_guest (float)
      • cpu_time_guest_nice (float)
      • cpu_time_idle (float)
      • cpu_time_iowait (float)
      • cpu_time_irq (float)
      • cpu_time_nice (float)
      • cpu_time_soft_irq (float)
      • cpu_time_steal (float)
      • cpu_time_system (float)
      • cpu_time_user (float)
      • cpu_usage (float)
      • 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
      • win_service
      • result
    • fields:
      • pid_count (int)
      • running (int)
      • result_code (int, success = 0, lookup_error = 1)

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,cpu_time_idle=0,cpu_time_irq=0,cpu_time_guest=0,pid=32025i,major_faults=8609i,created_at=1580107536000000000i,voluntary_context_switches=1058996i,cpu_time_system=616.98,cpu_time_steal=0,cpu_time_guest_nice=0,memory_swap=0i,memory_locked=0i,memory_usage=1.7797634601593018,num_threads=18i,cpu_time_nice=0,cpu_time_iowait=0,cpu_time_soft_irq=0,memory_rss=148643840i,memory_vms=1435688960i,memory_data=0i,memory_stack=0i,minor_faults=1856550i 1582089700000000000




This section is empty.


This section is empty.


This section is empty.


type NativeFinder added in v1.14.0

type NativeFinder struct {

NativeFinder uses gopsutil to find processes

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)

func NewNativeFinder added in v1.14.0

func NewNativeFinder() (PIDFinder, error)

NewNativeFinder ...

func NewPgrep added in v1.14.0

func NewPgrep() (PIDFinder, 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) 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 {
	Tags map[string]string
	Err  error

type Proc added in v1.14.0

type Proc struct {
	// contains filtered or unexported fields

func (*Proc) PID added in v1.14.0

func (p *Proc) PID() PID

func (*Proc) Percent added in v1.14.0

func (p *Proc) Percent(_ time.Duration) (float64, error)

func (*Proc) Tags added in v1.14.0

func (p *Proc) Tags() map[string]string

func (*Proc) Username added in v1.14.0

func (p *Proc) Username() (string, error)

type Process added in v1.14.0

type Process interface {
	Tags() map[string]string

	PageFaults() (*process.PageFaultsStat, error)
	IOCounters() (*process.IOCountersStat, error)
	MemoryInfo() (*process.MemoryInfoStat, error)
	MemoryMaps(bool) (*[]process.MemoryMapsStat, error)
	Name() (string, error)
	Cmdline() (string, error)
	NumCtxSwitches() (*process.NumCtxSwitchesStat, error)
	NumFDs() (int32, error)
	NumThreads() (int32, error)
	Percent(interval time.Duration) (float64, error)
	MemoryPercent() (float32, error)
	Times() (*cpu.TimesStat, error)
	RlimitUsage(bool) ([]process.RlimitStat, error)
	Username() (string, error)
	CreateTime() (int64, error)
	Ppid() (int32, error)
	Status() ([]string, error)

func NewProc added in v1.14.0

func NewProc(pid PID) (Process, error)

type Procstat

type Procstat struct {
	PidFinder              string `toml:"pid_finder"`
	PidFile                string `toml:"pid_file"`
	Exe                    string
	Pattern                string
	Prefix                 string
	CmdLineTag             bool `toml:"cmdline_tag"`
	ProcessName            string
	User                   string
	SystemdUnit            string `toml:"systemd_unit"`
	IncludeSystemdChildren bool   `toml:"include_systemd_children"`
	CGroup                 string `toml:"cgroup"`
	PidTag                 bool
	WinService             string `toml:"win_service"`
	Mode                   string
	// 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

func (*Procstat) SimpleFindPids added in v1.20.0

func (p *Procstat) SimpleFindPids(f PIDFinder) ([]PID, map[string]string, error)

Get matching PIDs and their initial tags

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL