README.md
1# procfs
2
3This package provides functions to retrieve system, kernel, and process
4metrics from the pseudo-filesystems /proc and /sys.
5
6*WARNING*: This package is a work in progress. Its API may still break in
7backwards-incompatible ways without warnings. Use it at your own risk.
8
9[](https://godoc.org/github.com/prometheus/procfs)
10[](https://travis-ci.org/prometheus/procfs)
11[](https://goreportcard.com/report/github.com/prometheus/procfs)
12
13## Usage
14
15The procfs library is organized by packages based on whether the gathered data is coming from
16/proc, /sys, or both. Each package contains an `FS` type which represents the path to either /proc,
17/sys, or both. For example, cpu statistics are gathered from
18`/proc/stat` and are available via the root procfs package. First, the proc filesystem mount
19point is initialized, and then the stat information is read.
20
21```go
22fs, err := procfs.NewFS("/proc")
23stats, err := fs.Stat()
24```
25
26Some sub-packages such as `blockdevice`, require access to both the proc and sys filesystems.
27
28```go
29 fs, err := blockdevice.NewFS("/proc", "/sys")
30 stats, err := fs.ProcDiskstats()
31```
32
33## Package Organization
34
35The packages in this project are organized according to (1) whether the data comes from the `/proc` or
36`/sys` filesystem and (2) the type of information being retrieved. For example, most process information
37can be gathered from the functions in the root `procfs` package. Information about block devices such as disk drives
38is available in the `blockdevices` sub-package.
39
40## Building and Testing
41
42The procfs library is intended to be built as part of another application, so there are no distributable binaries.
43However, most of the API includes unit tests which can be run with `make test`.
44
45### Updating Test Fixtures
46
47The procfs library includes a set of test fixtures which include many example files from
48the `/proc` and `/sys` filesystems. These fixtures are included as a [ttar](https://github.com/ideaship/ttar) file
49which is extracted automatically during testing. To add/update the test fixtures, first
50ensure the `fixtures` directory is up to date by removing the existing directory and then
51extracting the ttar file using `make fixtures/.unpacked` or just `make test`.
52
53```bash
54rm -rf fixtures
55make test
56```
57
58Next, make the required changes to the extracted files in the `fixtures` directory. When
59the changes are complete, run `make update_fixtures` to create a new `fixtures.ttar` file
60based on the updated `fixtures` directory. And finally, verify the changes using
61`git diff fixtures.ttar`.
62
){kind=link}
){kind=link}