go-papi provides a Go interface to PAPI, the Performance Application Programming Interface. PAPI provides convenient access to hardware performance counters, primarily those provided by the CPU but with others (e.g., various networks) also available.

As the PAPI(3) man page explains, the PAPI API is split into "high level" and "low level" functions, with the former being simpler to use but less flexible and the latter providing finer-grained control over the sets of data measured and reported.

Installation is a bit of a pain, as the new go tool doesn't yet handle custom Makefiles such as the one go-papi requires. (This requirement is due to some of go-papi's source files being generated automatically by a Perl script.)

First, download go-papi into your Go build tree without automatically building/installing it:

go get -d -v github.com/lanl/go-papi

Set the PAPI_INCDIR environment variable to the directory containing papi.h. Also, ensure that the directory containing libpapi.so is listed in your LD_LIBRARY_PATH.

Next, switch to the go-papi directory and build/test/install the package:

cd $GOROOT/src/pkg/github.com/lanl/go-papi
make
make check
make install

It is then safe to do a make clean to remove all of the byproducts of the installation process.

Pre-built documentation for the core part of the go-papi API is available online at http://godoc.org/github.com/lanl/go-papi. Unfortunately, the online documentation omits descriptions of all constants, variables, etc. that are generated during the build process, specifically the list of PAPI events (papi-event.go), event modifiers (papi-emod.go), and error values (papi-errno.go).

Once you install go-papi, you can view the complete go-papi API with godoc, for example by running

godoc -http=:6060 -index

to start a local Web server then viewing the documentation at http://localhost:6060/pkg/github.com/lanl/go-papi/ in your favorite browser.

For code examples, take a look at the *_test.go files in the go-papi source distribution. papi_hl_test.go utilizes PAPI's high-level API; papi_ll_test.go utilizes PAPI's low-level API; and papi_test.go utilizes a few miscellaneous functions.

BSD-ish with a "modifications must be indicated" clause. See http://github.com/lanl/go-papi/blob/master/LICENSE.md for the full text.

Triad National Security, LLC (Triad) owns the copyright to go-papi, a component of the LANL Go Suite (identified internally as LA-CC-11-056).

Scott Pakin, pakin@lanl.gov