The linux-perf package

[Tags:bsd3, library, program]

This library is for parsing, representing in Haskell and pretty printing the data file output of the Linux perf command. The perf command provides performance profiling information for applications running under the Linux operating system. This information includes hardware performance counters and kernel tracepoints.

Modern CPUs can provide information about the runtime behaviour of software through so-called hardware performance counters Recent versions of the Linux kernel (since 2.6.31) provide a generic interface to low-level events for running processes. This includes access to hardware counters but also a wide array of software events such as page faults, scheduling activity and system calls. A userspace tool called perf is built on top of the kernel interface, which provides a convenient way to record and view events for running processes.

The perf tool has many sub-commands which do a variety of things, but in general it has two main purposes:

1. Recording events.

2. Displaying events.

The perf record command records information about performance events in a file called (by default) It is a binary file format which is basically a memory dump of the data structures used to record event information. The file has two main parts:

1. A header which describes the layout of information in the file (section sizes, etcetera) and common information about events in the second part of the file (an encoding of event types and their names).

2. The payload of the file which is a sequence of event records.

Each event field has a header which says what general type of event it is plus information about the size of its body.

There are nine types of event:

1. PERF_RECORD_MMAP: memory map event.

2. PERF_RECORD_LOST: an unknown event.

3. PERF_RECORD_COMM: maps a command name string to a process and thread ID.

4. PERF_RECORD_EXIT: process exit.



7. PERF_RECORD_FORK: process creation.


9. PERF_RECORD_SAMPLE: a sample of an actual hardware counter or a software event.

The PERF_RECORD_SAMPLE events (samples) are the most interesting ones in terms of program profiling. The other events seem to be mostly useful for keeping track of process technicalities. Samples are timestamped with an unsigned 64 bit word, which records elapsed nanoseconds since some point in time (system running time, based on the kernel scheduler clock). Samples have themselves a type which is defined in the file header and linked to the sample by an integer identifier.

Below is an example program which reads a file and prints out the number of events that it contains.

module Main where

import Profiling.Linux.Perf (readPerfData)
import Profiling.Linux.Perf.Types (PerfData (..))
import System.Environment (getArgs)

main :: IO ()
main = do
   args <- getArgs
   case args of
      [] -> return ()
      (file:_) -> do
         perfData <- readPerfData file
         print $ length $ perfData_events perfData

[Skip to Readme]


Versions 0.3
Dependencies base (==4.*), binary (>=0.5 && <0.7), bytestring (>=0.9), containers (>=0.4 && <0.6), directory (>=1.1 && <2), filepath (>=1.2 && <2), ghc-events (>=0.4.2), linux-perf (>=0.2), mtl (==2.*), pretty (==1.*), process (==1.1.*), unix (>=2.5 && <2.7) [details]
License BSD3
Author Simon Marlow, Bernie Pope, Mikolaj Konarski, Duncan Coutts
Maintainer Bernie Pope <>
Category Development, GHC, Debug, Profiling, Trace
Home page
Bug tracker
Source repository head: git clone git://
Uploaded Sat Nov 3 10:14:13 UTC 2012 by MikolajKonarski
Distributions NixOS:0.3
Downloads 403 total (4 in the last 30 days)
0 []
Status Docs uploaded by user
Build status unknown [no reports yet]
Hackage Matrix CI




Maintainer's Corner

For package maintainers and hackage trustees

Readme for linux-perf

Readme for linux-perf-0.3


linux-perf is a library for parsing, representing in Haskell and pretty-printing the data file output of the Linux 'perf' command (Linux performance counters).

License and Copyright

linux-perf is distributed as open source software under the terms of the BSD License (see the file LICENSE in the top directory).

Authors: Simon Marlow, Bernie Pope, Mikolaj Konarski, Duncan Coutts, copyright 2010, 2011, 2012.

Contact information

Email Bernie Pope:


Building and installing

linux-perf uses the cabal infrastructure for configuring, building and installation. It needs access to the header files from the Linux kernel source distribution (one that is sufficiently recent to support the performance counters tool).

To build and install:

cabal install --extra-include-dirs=/path/to/linux/headers/

To clean:

cabal clean

To test:

dump-perf test/ | less

For longer examples see