Proc Utilities¶
Helper functions for querying process and system information from the /proc contents. Fetching information this way provides huge performance benefits over lookups via system utilities (ps, netstat, etc). For instance, resolving connections this way cuts the runtime by around 90% verses the alternatives. These functions may not work on all platforms (only Linux?).
The method for reading these files (and a little code) are borrowed from psutil, which was written by Jay Loden, Dave Daeschler, Giampaolo Rodola’ and is under the BSD license.
These functions are not being vended to stem users. They may change in the future, use them at your own risk.
Changed in version 1.3.0: Dropped the get_* prefix from several function names. The old names still work, but are deprecated aliases.
Module Overview:
is_available - checks if proc utilities can be used on this system
system_start_time - unix timestamp for when the system started
physical_memory - memory available on this system
cwd - provides the current working directory for a process
uid - provides the user id a process is running under
memory_usage - provides the memory usage of a process
stats - queries statistics about a process
file_descriptors_used - number of file descriptors used by a process
connections - provides the connections made by a process
-
stem.util.proc.
Stat
(enum)¶ Types of data available via the
stats()
function.Stat
Description
COMMAND
command name under which the process is running
CPU_UTIME
total user time spent on the process
CPU_STIME
total system time spent on the process
START_TIME
when this process began, in unix time
-
stem.util.proc.
is_available
[source]¶ Checks if proc information is available on this platform.
- Returns
True if proc contents exist on this platform, False otherwise
-
stem.util.proc.
system_start_time
[source]¶ Provides the unix time (seconds since epoch) when the system started.
- Returns
float for the unix time of when the system started
- Raises
IOError if it can’t be determined
-
stem.util.proc.
physical_memory
[source]¶ Provides the total physical memory on the system in bytes.
- Returns
int for the bytes of physical memory this system has
- Raises
IOError if it can’t be determined
-
stem.util.proc.
cwd
(pid)[source]¶ Provides the current working directory for the given process.
- Parameters
pid (int) – process id of the process to be queried
- Returns
str with the path of the working directory for the process
- Raises
IOError if it can’t be determined
-
stem.util.proc.
uid
(pid)[source]¶ Provides the user ID the given process is running under.
- Parameters
pid (int) – process id of the process to be queried
- Returns
int with the user id for the owner of the process
- Raises
IOError if it can’t be determined
-
stem.util.proc.
memory_usage
(pid)[source]¶ Provides the memory usage in bytes for the given process.
- Parameters
pid (int) – process id of the process to be queried
- Returns
tuple of two ints with the memory usage of the process, of the form (resident_size, virtual_size)
- Raises
IOError if it can’t be determined
-
stem.util.proc.
stats
(pid, *stat_types)[source]¶ Provides process specific information. See the
Stat
enum for valid options.- Parameters
pid (int) – process id of the process to be queried
stat_types (Stat) – information to be provided back
- Returns
tuple with all of the requested statistics as strings
- Raises
IOError if it can’t be determined
-
stem.util.proc.
file_descriptors_used
(pid)[source]¶ Provides the number of file descriptors currently being used by a process.
New in version 1.3.0.
- Parameters
pid (int) – process id of the process to be queried
- Returns
int of the number of file descriptors used
- Raises
IOError if it can’t be determined
-
stem.util.proc.
connections
(pid=None, user=None)[source]¶ Queries connections from the proc contents. This matches netstat, lsof, and friends but is much faster. If no pid or user are provided this provides all present connections.
- Parameters
pid (int) – pid to provide connections for
user (str) – username to look up connections for
- Returns
list of
Connection
instances- Raises
IOError if it can’t be determined
-
stem.util.proc.
get_system_start_time
¶ Provides the unix time (seconds since epoch) when the system started.
- Returns
float for the unix time of when the system started
- Raises
IOError if it can’t be determined
-
stem.util.proc.
get_physical_memory
¶ Provides the total physical memory on the system in bytes.
- Returns
int for the bytes of physical memory this system has
- Raises
IOError if it can’t be determined
-
stem.util.proc.
get_cwd
(pid)¶ Provides the current working directory for the given process.
- Parameters
pid (int) – process id of the process to be queried
- Returns
str with the path of the working directory for the process
- Raises
IOError if it can’t be determined
-
stem.util.proc.
get_uid
(pid)¶ Provides the user ID the given process is running under.
- Parameters
pid (int) – process id of the process to be queried
- Returns
int with the user id for the owner of the process
- Raises
IOError if it can’t be determined
-
stem.util.proc.
get_memory_usage
(pid)¶ Provides the memory usage in bytes for the given process.
- Parameters
pid (int) – process id of the process to be queried
- Returns
tuple of two ints with the memory usage of the process, of the form (resident_size, virtual_size)
- Raises
IOError if it can’t be determined
-
stem.util.proc.
get_stats
(pid, *stat_types)¶ Provides process specific information. See the
Stat
enum for valid options.- Parameters
pid (int) – process id of the process to be queried
stat_types (Stat) – information to be provided back
- Returns
tuple with all of the requested statistics as strings
- Raises
IOError if it can’t be determined
-
stem.util.proc.
get_connections
(pid=None, user=None)¶ Queries connections from the proc contents. This matches netstat, lsof, and friends but is much faster. If no pid or user are provided this provides all present connections.
- Parameters
pid (int) – pid to provide connections for
user (str) – username to look up connections for
- Returns
list of
Connection
instances- Raises
IOError if it can’t be determined