| 1 | # procfs
|
|---|
| 2 |
|
|---|
| 3 | This package provides functions to retrieve system, kernel, and process
|
|---|
| 4 | metrics from the pseudo-filesystems /proc and /sys.
|
|---|
| 5 |
|
|---|
| 6 | *WARNING*: This package is a work in progress. Its API may still break in
|
|---|
| 7 | backwards-incompatible ways without warnings. Use it at your own risk.
|
|---|
| 8 |
|
|---|
| 9 | [](https://pkg.go.dev/github.com/prometheus/procfs)
|
|---|
| 10 | [](https://circleci.com/gh/prometheus/procfs/tree/master)
|
|---|
| 11 | [](https://goreportcard.com/report/github.com/prometheus/procfs)
|
|---|
| 12 |
|
|---|
| 13 | ## Usage
|
|---|
| 14 |
|
|---|
| 15 | The 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
|
|---|
| 19 | point is initialized, and then the stat information is read.
|
|---|
| 20 |
|
|---|
| 21 | ```go
|
|---|
| 22 | fs, err := procfs.NewFS("/proc")
|
|---|
| 23 | stats, err := fs.Stat()
|
|---|
| 24 | ```
|
|---|
| 25 |
|
|---|
| 26 | Some 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 |
|
|---|
| 35 | The 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
|
|---|
| 37 | can be gathered from the functions in the root `procfs` package. Information about block devices such as disk drives
|
|---|
| 38 | is available in the `blockdevices` sub-package.
|
|---|
| 39 |
|
|---|
| 40 | ## Building and Testing
|
|---|
| 41 |
|
|---|
| 42 | The procfs library is intended to be built as part of another application, so there are no distributable binaries.
|
|---|
| 43 | However, most of the API includes unit tests which can be run with `make test`.
|
|---|
| 44 |
|
|---|
| 45 | ### Updating Test Fixtures
|
|---|
| 46 |
|
|---|
| 47 | The procfs library includes a set of test fixtures which include many example files from
|
|---|
| 48 | the `/proc` and `/sys` filesystems. These fixtures are included as a [ttar](https://github.com/ideaship/ttar) file
|
|---|
| 49 | which is extracted automatically during testing. To add/update the test fixtures, first
|
|---|
| 50 | ensure the `fixtures` directory is up to date by removing the existing directory and then
|
|---|
| 51 | extracting the ttar file using `make fixtures/.unpacked` or just `make test`.
|
|---|
| 52 |
|
|---|
| 53 | ```bash
|
|---|
| 54 | rm -rf fixtures
|
|---|
| 55 | make test
|
|---|
| 56 | ```
|
|---|
| 57 |
|
|---|
| 58 | Next, make the required changes to the extracted files in the `fixtures` directory. When
|
|---|
| 59 | the changes are complete, run `make update_fixtures` to create a new `fixtures.ttar` file
|
|---|
| 60 | based on the updated `fixtures` directory. And finally, verify the changes using
|
|---|
| 61 | `git diff fixtures.ttar`.
|
|---|
