linux-perf.cabal

Name:                linux-perf
Version:             0.3
Synopsis:            Read files generated by perf on Linux
Homepage:            http://code.haskell.org/linux-perf
License:             BSD3
License-file:        LICENSE
Data-files:          LICENSE, README.md, README.ghc-events-perf.md,
                     from_linux-perf-users.md, Profiling/Linux/Perf/perf_file.h
Author:              Simon Marlow, Bernie Pope, Mikolaj Konarski, Duncan Coutts
Maintainer:          Bernie Pope <florbitous@gmail.com>
Stability:           Experimental
homepage:            https://github.com/bjpop/haskell-linux-perf
bug-reports:         https://github.com/bjpop/haskell-linux-perf/issues
category:            Development, GHC, Debug, Profiling, Trace
Build-type:          Simple
Cabal-version:       >=1.10
Description:
 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
 <http://en.wikipedia.org/wiki/Hardware_performance_counter>.
 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) @perf.data@.
 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.
 .
    5. @PERF_RECORD_THROTTLE@:
 .
    6. @PERF_RECORD_UNTHROTTLE@:
 .
    7. @PERF_RECORD_FORK@: process creation.
 .
    8. @PERF_RECORD_READ@:
 .
    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 @perf.data@ 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

source-repository head
  type:            git
  location:        git://github.com/bjpop/haskell-linux-perf.git

Library
  -- Modules exported by the library.
  Exposed-modules: Profiling.Linux.Perf,
                   Profiling.Linux.Perf.Types,
                   Profiling.Linux.Perf.Parse,
                   Profiling.Linux.Perf.Pretty

  -- Packages needed in order to build this package.
  Build-depends: base==4.*,
                 binary >= 0.5 && < 0.8,
                 mtl==2.*,
                 bytestring >= 0.9,
                 pretty >= 1 && < 2,
                 containers >= 0.4 && < 0.6

  include-dirs: Profiling/Linux/Perf

  default-language: Haskell2010

  -- Modules not exported by this package.
  -- Other-modules:

  -- Extra tools (e.g. alex, hsc2hs, ...) needed to build the source.
  -- Build-tools:

Executable dump-perf {
  Main-is: dump-perf.hs
  hs-source-dirs: dump-perf
  Build-depends: linux-perf>=0.2,
                 base==4.*,
                 bytestring >= 0.9
  default-language: Haskell2010
  ghc-options:   -rtsopts
}

Executable ghc-events-perf-record {
  Main-is: ghc-events-perf-record.hs
  hs-source-dirs: ghc-events-perf
  Build-depends: base==4.*,
                 unix >= 2.5 && < 2.8,
                 directory >= 1.1 && < 2,
                 filepath >= 1.2 && < 2
  default-language: Haskell2010
  ghc-options:   -rtsopts
  ghc-options:   -Wall -fwarn-orphans -fwarn-tabs -fwarn-incomplete-uni-patterns -fwarn-incomplete-record-updates -fwarn-monomorphism-restriction -fwarn-unrecognised-pragmas
  ghc-options:   -fno-warn-auto-orphans -fno-warn-implicit-prelude
}

Executable ghc-events-perf-sync {
  Main-is: ghc-events-perf-sync.hs
  hs-source-dirs: ghc-events-perf
  Build-depends: base==4.*,
                 ghc-events >= 0.4.2,
                 containers >= 0.4 && < 0.6,
                 process >= 1.1.0.0
  default-language: Haskell2010
  ghc-options:   -rtsopts
  ghc-options:   -Wall -fwarn-orphans -fwarn-tabs -fwarn-incomplete-uni-patterns -fwarn-incomplete-record-updates -fwarn-monomorphism-restriction -fwarn-unrecognised-pragmas
  ghc-options:   -fno-warn-auto-orphans -fno-warn-implicit-prelude
}

Executable ghc-events-perf {
  Main-is: ghc-events-perf.hs
  hs-source-dirs: ghc-events-perf
  Build-depends: base==4.*,
                 filepath >= 1.2 && < 2,
                 process >= 1.1.0.0,
                 unix >= 2.5 && < 2.8
  default-language: Haskell2010
  ghc-options:   -Wall -fwarn-orphans -fwarn-tabs -fwarn-incomplete-uni-patterns -fwarn-incomplete-record-updates -fwarn-monomorphism-restriction -fwarn-unrecognised-pragmas
  ghc-options:   -fno-warn-auto-orphans -fno-warn-implicit-prelude
}

Executable count-events {
  Main-is: count-events.hs
  hs-source-dirs: test
  Build-depends: linux-perf>=0.2,
                 base==4.*
  default-language: Haskell2010
}