README.md
1# procfs
2
3This procfs 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, /sys, or both. For example, current cpu statistics are gathered from
17`/proc/stat` and are available via the root procfs package. First, the proc filesystem mount
18point is initialized, and then the stat information is read.
19
20```go
21fs, err := procfs.NewFS("/proc")
22stats, err := fs.Stat()
23```
24
25Some sub-packages such as `blockdevice`, require access to both the proc and sys filesystems.
26
27```go
28 fs, err := blockdevice.NewFS("/proc", "/sys")
29 stats, err := fs.ProcDiskstats()
30```
31
32## Building and Testing
33
34The procfs library is normally built as part of another application. However, when making
35changes to the library, the `make test` command can be used to run the API test suite.
36
37### Updating Test Fixtures
38
39The procfs library includes a set of test fixtures which include many example files from
40the `/proc` and `/sys` filesystems. These fixtures are included as a [ttar](https://github.com/ideaship/ttar) file
41which is extracted automatically during testing. To add/update the test fixtures, first
42ensure the `fixtures` directory is up to date by removing the existing directory and then
43extracting the ttar file using `make fixtures/.unpacked` or just `make test`.
44
45```bash
46rm -rf fixtures
47make test
48```
49
50Next, make the required changes to the extracted files in the `fixtures` directory. When
51the changes are complete, run `make update_fixtures` to create a new `fixtures.ttar` file
52based on the updated `fixtures` directory. And finally, verify the changes using
53`git diff fixtures.ttar`.
54
){kind=link}
){kind=link}