Categorygithub.com/prometheus/procfs
modulepackage
0.15.1
Repository: https://github.com/prometheus/procfs.git
Documentation: pkg.go.dev
Versions
1
Dependencies
19
Dependents
498
Files
8.4k SLOC

# README

procfs

This package provides functions to retrieve system, kernel, and process metrics from the pseudo-filesystems /proc and /sys.

WARNING: This package is a work in progress. Its API may still break in backwards-incompatible ways without warnings. Use it at your own risk.

Go Reference CircleCI Go Report Card

Usage

The procfs library is organized by packages based on whether the gathered data is coming from /proc, /sys, or both. Each package contains an FS type which represents the path to either /proc, /sys, or both. For example, cpu statistics are gathered from /proc/stat and are available via the root procfs package. First, the proc filesystem mount point is initialized, and then the stat information is read.

fs, err := procfs.NewFS("/proc")
stats, err := fs.Stat()

Some sub-packages such as blockdevice, require access to both the proc and sys filesystems.

    fs, err := blockdevice.NewFS("/proc", "/sys")
    stats, err := fs.ProcDiskstats()

Package Organization

The packages in this project are organized according to (1) whether the data comes from the /proc or /sys filesystem and (2) the type of information being retrieved. For example, most process information can be gathered from the functions in the root procfs package. Information about block devices such as disk drives is available in the blockdevices sub-package.

Building and Testing

The procfs library is intended to be built as part of another application, so there are no distributable binaries.
However, most of the API includes unit tests which can be run with make test.

Updating Test Fixtures

The procfs library includes a set of test fixtures which include many example files from the /proc and /sys filesystems. These fixtures are included as a ttar file which is extracted automatically during testing. To add/update the test fixtures, first ensure the fixtures directory is up to date by removing the existing directory and then extracting the ttar file using make fixtures/.unpacked or just make test.

rm -rf testdata/fixtures
make test

Next, make the required changes to the extracted files in the fixtures directory. When the changes are complete, run make update_fixtures to create a new fixtures.ttar file based on the updated fixtures directory. And finally, verify the changes using git diff testdata/fixtures.ttar.

# Packages

Package bcache provides access to statistics exposed by the bcache (Linux block cache).
Package btrfs provides access to statistics exposed by Btrfs filesystems.
Package nfs implements parsing of /proc/net/rpc/nfsd.
Package sysfs provides functions to retrieve system and kernel metrics from the pseudo-filesystem sys.
Package xfs provides access to statistics exposed by the XFS filesystem.

# Functions

AllProcs returns a list of all currently available processes under /proc.
AllThreads returns a list of all currently available threads under /proc/PID.
GetMounts retrieves mountinfo information from `/proc/self/mountinfo`.
GetProcMounts retrieves mountinfo information from a processes' `/proc/<pid>/mountinfo`.
NewDefaultFS returns a new proc FS mounted under the default proc mountPoint.
NewFS returns a new proc FS mounted under the given proc mountPoint.
NewProc returns a process for the given pid under /proc.
NewStat returns information about current cpu/process statistics.
NewTLSStat reads the tls_stat statistics.
NewXfrmStat reads the xfrm_stat statistics.
Self returns a process for the current process read via /proc/self.

# Constants

completed entry (ha valid).
Don't answer this addresses.
Obsoleted: Want to use a netmask (only for proxy entries).
permanent entry.
Publish entry.
Has requested trailers.
DefaultMountPoint is the common mount point of the proc filesystem.

# Variables

# Structs

ARPEntry contains a single row of the columnar data represented in /proc/net/arp.
A BuddyInfo is the details parsed from /proc/buddyinfo.
Cgroup models one line from /proc/[pid]/cgroup.
CgroupSummary models one line from /proc/cgroups.
A ConntrackStatEntry represents one line from net/stat/nf_conntrack and contains netfilter conntrack statistics at one CPU core.
CPUInfo contains general information about a system CPU found in /proc/cpuinfo.
CPUStat shows how much time the cpu spend in various stages.
Crypto holds info parsed from /proc/crypto.
FS represents the pseudo-filesystem sys, which provides an interface to kernel data structures.
Fscacheinfo represents fscache statistics.
InotifyInfo represents a single inotify line in the fdinfo file.
Interrupt represents a single interrupt line.
IPVSBackendStatus holds current metrics of one virtual / real address pair.
IPVSStats holds IPVS statistics, as exposed by the kernel in `/proc/net/ip_vs_stats`.
KernelRandom contains information about to the kernel's random number generator.
LoadAvg represents an entry in /proc/loadavg.
MDStat holds info parsed from /proc/mdstat.
Meminfo represents memory statistics.
A Mount is a device mount parsed from /proc/[pid]/mountstats.
A MountInfo is a type that describes the details, options for each mount, parsed from /proc/self/mountinfo.
A MountStatsNFS is a MountStats implementation for NFSv3 and v4 mounts.
Namespace represents a single namespace of a process.
NetDevLine is single line parsed from /proc/net/dev or /proc/[pid]/net/dev.
This contains generic data structures for both udp and tcp sockets.
NetProtocolCapabilities contains a list of capabilities for each protocol.
NetProtocolStatLine contains a single line parsed from /proc/net/protocols.
A NetRouteLine represents one line from net/route.
A NetSockstat contains the output of /proc/net/sockstat{,6} for IPv4 or IPv6, respectively.
A NetSockstatProtocol contains statistics about a given socket protocol.
NetStat contains statistics for all the counters from one file.
NetUNIX holds the data read from /proc/net/unix.
NetUNIXLine represents a line of /proc/net/unix.
A NFSBytesStats contains statistics about the number of bytes read and written by an NFS client to and from an NFS server.
A NFSEventsStats contains statistics about NFS event occurrences.
A NFSOperationStats contains statistics for a single operation.
A NFSTransportStats contains statistics for the NFS mount RPC requests and responses.
Proc provides information about a running process.
ProcFDInfo contains represents file descriptor information.
ProcIO models the content of /proc/<pid>/io.
ProcLimits represents the soft limits for each of the process's resource limits.
ProcMap contains the process memory-mappings of the process read from `/proc/[pid]/maps`.
ProcMapPermissions contains permission settings read from `/proc/[pid]/maps`.
ProcNetstat models the content of /proc/<pid>/net/netstat.
ProcSchedstat contains the values from `/proc/<pid>/schedstat`.
ProcSnmp models the content of /proc/<pid>/net/snmp.
ProcSnmp6 models the content of /proc/<pid>/net/snmp6.
ProcStat provides status information about the process, read from /proc/[pid]/stat.
ProcStatus provides status information about the process, read from /proc/[pid]/status.
PSILine is a single line of values as returned by `/proc/pressure/*`.
PSIStats represent pressure stall information from /proc/pressure/* "Some" indicates the share of time in which at least some tasks are stalled.
Schedstat contains scheduler statistics from /proc/schedstat See https://www.kernel.org/doc/Documentation/scheduler/sched-stats.txt for a detailed description of what these numbers mean.
SchedstatCPU contains the values from one "cpu<N>" line.
Slab represents a slab pool in the kernel.
SlabInfo represents info for all slabs.
Softirqs represents the softirq statistics.
SoftIRQStat represent the softirq statistics as exported in the procfs stat file.
SoftnetStat contains a single row of data from /proc/net/softnet_stat.
Stat represents kernel/system statistics.
Swap represents an entry in /proc/swaps.
TLSStat struct represents data in /proc/net/tls_stat.
The VM interface is described at https://www.kernel.org/doc/Documentation/sysctl/vm.txt Each setting is exposed as a single file.
Wireless models the content of /proc/net/wireless.
XfrmStat models the contents of /proc/net/xfrm_stat.
Zoneinfo holds info parsed from /proc/zoneinfo.

# Interfaces

A MountStats is a type which contains detailed statistics for a specific type of Mount.

# Type aliases

Interrupts models the content of /proc/interrupts.
Namespaces contains all of the namespaces that the process is contained in.
NetDev is parsed from /proc/net/dev or /proc/[pid]/net/dev.
This contains generic data structures for both udp and tcp sockets.
NetProtocolStats stores the contents from /proc/net/protocols.
NetUNIXFlags is the type of the flags field.
NetUNIXState is the type of the state field.
NetUNIXType is the type of the type field.
ProcFDInfos represents a list of ProcFDInfo structs.
Procs represents a list of Proc structs.